Starts browse.

Sintaxe:

Notas:

1. DATASET is also accepted, but FILE is preferred.
2. GTEQ cannot be used with the RBA option.
3. KEYLENGTH is required with SYSID for a KSDS browse. KEYLENGTH should not be specified for a direct browse of either an ESDS (use the RBA option) or an RRDS (use the RRN option).
4. DSIDERR is equivalent to FILENOTFOUND.

Descrição:

STARTBR specifies the record in a file, on a local or a remote system, where you want to start a browse operation.
No records are read until a READNEXT or a READPREV command is executed.

A browse operation can be one of the following:

• A direct browse of a KSDS by record key.
• A direct browse of an ESDS by relative byte address (RBA).
• A direct browse of an RRDS by relative record number (RRN).
• A browse of a KSDS using an alternative index path.
• A browse of an ESDS using an alternative index path.
  In this case, an ESDS is browsed by key in the same way as a KSDS.
  You should be aware that some of the options that are not valid for a direct ESDS browse are valid for an alternative index browse.
  Details are given in the option descriptions.

  The options that are specified on the STARTBR command define the characteristics that apply throughout the subsequent browse operation.
  Specifically, if GENERIC or GTEQ are specified, they are used not only when determining the starting point of the browse, but also whenever the value of RIDFLD is changed before issuing a READNEXT command.

Opções

EQUAL
• Specifies that the search is satisfied only by a record that has the same key (complete or generic) as that which is specified in the RIDFLD option.
• This option is the default for a direct ESDS browse.

FILE(name)
• Specifies the name of the CICS file that is to be browsed.
• The name must be alphanumeric, up to eight characters long, and the file must be currently BROWSABLE (see INQUIRE FILE).
• If a remote SYSID is specified, the underlying file is assumed to reside on a remote system, irrespective of whether the name exists in the local File Definitions (FD).
• Otherwise, the FD entry is used to determine whether the underlying file is on a local or a remote system.

GENERIC
• Specifies that the search key is a generic key whose length is specified in the KEYLENGTH option.
• Use this option only with a KSDS or RRDS, or a KSDS or ESDS through an alternative index path.
• The search is satisfied on finding a record whose key has the same starting characters (generic key) as those that are specified in the RIDFLD option.

GTEQ
• Specifies that if the search for a record that has the same key (complete or generic) as that which is specified in the RIDFLD option is unsuccessful, the first record that has a greater key satisfies the search.
• This option is the default for directly browsing a KSDS or RRDS.
• It is not valid when directly browsing an ESDS, although it can be used when browsing an ESDS through an alternative path index.

KEYLENGTH(data-value)
• Specifies, as a 16-bit binary value, the length of the key that is supplied in the RIDFLD option.
• If KEYLENGTH is omitted, and both GENERIC and SYSID are also omitted, CICS obtains the length of the key if the file is local, or gets it from the KeyLen attribute that is in the FD entry, if the file is remote.
• If either GENERIC or SYSID is present, KEYLENGTH is required; the length cannot be taken from the FD entry.
• See KEYLENGTH and RIDFLD for more information about using this option.
• You can specify KEYLENGTH for a direct browse of a KSDS or a browse of either a KSDS or an ESDS through an alternative path index.
• KEYLENGTH should not be specified for a direct browse of either an ESDS (use the RBA option) or an RRDS (use the RRN option).
• If a specified KEYLENGTH value differs from the length that is defined for the underlying file and the operation is not generic, the INVREQ condition occurs.
• INVREQ also occurs if you specify GENERIC, and the KEYLENGTH value is not less than that which is specified in the File Definitions (FD) (see above).
• If KEYLENGTH(0) is used for positioning on the first record in the file, the GTEQ option must also be specified; otherwise, the NOTFND condition occurs.

Nota:
• GTEQ is the default for browse operations on either a KSDS or an ESDS through an alternative path index.
• Also, it cannot be used with the RBA option.

RBA
• Specifies that the record identification field that is supplied in the RIDFLD option contains a relative byte address.
• Use this option only when browsing an ESDS directly.
• The RBA option should not be present if the record identification field that is supplied in the RIDFLD option contains either a key (use the KEYLENGTH option) or a relative record number (use the RRN option).

REQID(data-value)
• Specifies, as a 16-bit binary value, a unique request identifier for the browse; it is used to control multiple browse operations on a file.
• If this option is not specified, a default value of zero is assumed.

RIDFLD(data-area)
• Specifies the record identification field.
• The contents can be a key, a relative byte address, or a relative record number.
• For a relative byte address or a relative record number, the format of this field must be 32-bit binary; and either the RBA or the RRN option must be specified as appropriate.
• A relative byte address can be greater than, or equal to, zero; a relative record number can be greater than, or equal to, 1.
• For KSDS files, setting the RIDFLD positions the cursor to the last record of the file.
• See KEYLENGTH and RIDFLD for more information about using this option.

RRN
• Specifies that the record identification field that is supplied in the RIDFLD option contains a relative record number.
• Use this option only when browsing an RRDS.
• The RRN option should not be present if the record identification field that is supplied in the RIDFLD option contains either a key (use the KEYLENGTH option) or a relative byte address (use the RBA option).

SYSID(name)
• Specifies on which CICS region the STARTBR is to run.
• The SYSID name has one through four characters.
• For a full description of the SYSID option, refer to SYSID.
• If the SYSID option is not specified, it defaults to the value that is in the RemoteSysId attribute of the FD entry for the file that is requested in the FILE option.
• If the SYSID option requests a remote SYSID, the KEYLENGTH must be specified for a KSDS browse because the length of the key can not be determined from the FD entry.

Condições:

DISABLED
• Occurs if a file is disabled.
• A file might be disabled because:
  • It was initially defined as disabled and has not since been enabled.
  • It has been disabled by an EXEC CICS SET FILE command or by the CEMT transaction.
• Ação pré-definida: Terminates the task abnormally.

FILENOTFOUND
• Occurs if the name that is specified in the FILE option cannot be found in the FD.
• Ação pré-definida: Terminates the task abnormally.

ILLOGIC
• Occurs if an error occurs that does not fall within one of the other CICS response categories.
• Further information is available in the EIBRCODE field; see Appendix A, EXEC interface block (EIB) fields for details.
• Ação pré-definida: Terminates the task abnormally.

INVREQ
• Occurs for the following conditions, depending on the options that are specified on the STARTBR command:
  • Browse operations are not currently allowed for the file.
  • The KEYLENGTH option is specified (but the GENERIC option is not specified), and the specified length differs from the length that is defined for the underlying file.
  • The KEYLENGTH and GENERIC options are specified, and the length that is specified in the KEYLENGTH option is either less than zero, or greater than, or equal to, the length of a full key.
  • An attempt is made to start a browse with a REQID that is already in use for another browse.
  • An invalid combination of RIDFLD, RBA, and RRN is specified for the file type.
• Ação pré-definida: Terminates the task abnormally.

IOERR
• Occurs if an I/O error occurs during the file control operation.
• An I/O error is any unusual event that is not covered by a CICS condition.
• Further information is available in the EIBRCODE field; see Appendix A, EXEC interface block (EIB) fields for details.
• See Processing the IOERR condition for information about handling the IOERR condition.
• Ação pré-definida: Terminates the task abnormally.

ISCINVREQ
• Occurs if the remote system indicates a failure that does not correspond to a known condition.
• Ação pré-definida: Terminates the task abnormally.

NOTAUTH
• Occurs for the following conditions:
  • When a resource security check is unsuccessful on FILE(name)
  • When SYSID is specified by a transaction that is defined with the RSLCheck attribute set to either internal or external
• Ação pré-definida: Terminates the task abnormally.

NOTFND
• Occurs if an attempt to position on a record, based on the search argument provided, is unsuccessful.
• NOTFND can also occur if a generic STARTBR with KEYLENGTH(0) specifies the EQUAL option.
• Ação pré-definida: Terminates the task abnormally.

NOTOPEN
• Occurs for the following conditions:
  • The requested file is CLOSED and UNENABLED.
  • The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file, and the file is no longer in use.
  • The requested file is OPEN and in use by other transactions, but a CLOSE request against the file has been received.
  • Current activity is allowed to complete, but no new activity is allowed to start.
• This condition does not occur if the request is made to either a CLOSED, ENABLED file or a CLOSED, DISABLED file.
• In the first case, the file is opened as part of executing the request.
• In the second case, the DISABLED condition occurs.
• Ação pré-definida: Terminates the task abnormally.

SYSIDERR
• Occurs if a problem with the communications configuration prevents the STARTBR from proceeding.
  For example:
  • The connection that is named in the SYSID option is not the name of a Communications Definition (CD) entry.
  • The SYSID option references a CD entry that is incorrectly configured.
  • The SYSID option references a CD entry that is marked as out of service.
• It can also occur if the connection to the remote system is closed.
• This could be because the remote system is not available.
• Ação pré-definida: Terminates the task abnormally.

Informações relacionadas:

• INQUIRE FILE
• READNEXT
• READPREV
• ENDBR
• Appendix A, EXEC interface block (EIB) fields
• TXSeries for Multiplatforms Administration Reference
• TXSeries for Multiplatforms Intercommunication Guide