STARTBR - IBM Mainframe

This command is used to start a browse from a specified record in a file or in a CICS maintained data table, on a local or a remote system. This command only positions the pointer, no records are retrieved until a READNEXT command or for VSAM and CICS maintained tables only, a READPREV command is executed. The browse operation may be:

  • A direct browse of a key sequenced data set (KSDS) by record key
  • A direct browse of an entry sequenced data set (ESDS) by relative byte address (RBA)
  • A direct browse of a relative record data set (RRDS) by relative record number (RRN)
  • A browse of a key sequenced data set (KSDS) using an alternate index path.
  • A browse of an entry sequenced data set (ESDS) using an alternate index path. For this type of browse, an ESDA is browsed by key in the same way as a KSDS. Some of the options that are invalid for a direct ESDS

The characteristics the browse operation takes on are defined by several options, which are specified on the STARTBR command.

  • GENERIC or GTEQ are used in determining the starting point for the browse and also can redefine the starting point whenever the R1DFLD value is changed prior to issuing a READNEXT command.
  • RBA option applies to every READNEXT or READPREV command in the browse operation and causes CICS to return the relative byte address for each record retrieved.

These options can only be modified by issuing the RESETBR command. These options cannot be changed during the browse, except by issuing a RESETBR command. The syntax of the STARTBR command is given below:

syntax of the STARTBR command

syntax of the STARTBR command

syntax of the STARTBR commandAn example of the STARTBR command is given below:

The various options available for the STARTBR command are given below:

  • DEBKEY (blocked BDAM only) - Key deblocking is to occur. No deblocking occurs when neither DEBREC nor DEBKey is specified.
  • DEBREC (blocked BDAM only) - Relative record (relative to zero) is to occur. No deblocking occurs when neither DEBREC nor DEBKey is specified.
  • EQUAL (VSAM only) - Search will only be satisfied when a record containing the same key (complete or generic) as the one specified in the RIDFLD option. This option is the default field for a direct ESDS browse.
  • FILE (filename) - Contains the name of the file to be accessed. The FCT entry for the filename will determine where the location (local or remote) of the data set resides. However, when the SYSID option is used, the location of the filename is assumed to exist on a remote system regardless of what the entry has defined in the FCT if one exists on the local system.
  • GENERIC (VSAM only) - The search key contains a generic key with the length value being specified in the KEYLENGTH option. The search condition is satisfied when a record is found that contains the same starting characters from the generic key used. This option is only valid on a KSDS VSAM file, or a path over either a KSDS or an ESDS.
  • GTEQ (VSAM only) - When searching for a record with the same key (complete or generic) specified in the RIDFLD option, if the search is unsuccessful, then the next record having a greater key is retrieved. This option should only be used on a KSDS VSAM file, or a path over either a KSDS or an ESDS.
  • KEYLENGTH (data_value) - Halfword binary length (PIC S9(4) comp) returning the length of the key specified in the RIDFLD option. This option is invalid when RBA or RRN options specified. It is required when the GENERIC option is used, and also may be used whenever a key is specified. If KEYLENGTH (0) is used with the intent of reading the first record in the file, then the GTEQ option is also required. If EQUAL is specified either explicitly or by default with KEYLENGTH (0), the results of the READ will be' unpredictable. An INVREQ condition occurs with either of the following conditions (a) the length specified is different from the length defined for the data set and the operation is not generic or (b) GENERIC is specified and the KEYLENGTH is not less than that specified in the VSAM definition.
  • KEYLENGTH (data value) - Haifword binary length (PIC S9(4) COMP) returning the length of the key specified in the RIDFLD option. An INVREQ condition occurs when the key length specified is different from the key length of the file.
  • KEYLENGTH (data_value) - Haifword binary length (PIC S9(4) COMP) returning the length of the key specified in the RIDFLD option. This option is invalid when RBA or RRN options are specified. If GENERIC is used then this option is required. An INVREQ condition occurs when the key length specified is different from the key length of the file and the operation is not generic. The INVREQ condition also occurs when the STARTBR command uses the GENERIC option and the KEYLENGTH is greater than what was defined in the VSAM file definition. When using the KEYLENGTH (0) option with the intent of starting at the first record in the file, then the GTEQ option is also required. Results will be unpredictable if the option EQUAL is used in combination with KEYLENGTH(O).
  • RBA (VSAM only) - Option when used will identify the record identification field of the RIDFLD option as a relative byte address. This option is only used for reading records directly from an ESDS file, or when reading from a KSDS file and using relative byte addresses instead of keys to identify the records.
  • REQID (datavalue) - Haifword binary field (PIC S9(4) COMP) containing the value of the unique request identifier for a browse, used in controlling multiple browse operations on a data set. The default for this option when used is zero.
  • RIDFLD (dataarea) - Specifies the record identification field. The contents can be one of the following:
    1. A key
    2. A relative byte address, with a format that is a fullword binary integer (PIC S9(8) comp) value that can be greater than or equal to zero
    3. A relative record number (for VSAM data sets), with a format that is a fullword binary integer (PIC S9(8) COMP) value that can be greater than or equal to one.
    4. A block reference
    5. A physical key
    6. A deblocking argument (for BDAM data sets)
  • Results can be unpredictable for any of the following:
    1. If the variable specified by RIDFLD is shorter than the KEYLENGTH specified in the command
    2. If KEYLENGTH is not specified, then the key length of the file being read must not be shorter than the RIDFLD variable specified in the command.
  • RRN (VSAM only) - Option indicates that the RIDFLD contains a relative record number in the record identification field. This option is required for a relative record data set.
  • SYSID (systemname) - Character field (4 bytes) specifying the name for the APPC connection where the request will be directed to. If this option is used and omit both RBA and RRN, then LENGTH and KEYLENGTH must be specified because these values cannot be found in the FCT entry.

The handle conditions are:

  • DISABLED - DISABLED is set when a file is disabled. The default action is the abnormal termination of the task. This can occur if:
    1. It was initially defined as disabled and has not since been enabled
    2. It has been disabled by an EXEC C1CS SET FILE or a CEMT SET FILE command
  • FILENOTFOUND - When a file name specified in the FILE option of the command cannot be located in the FCT. The default action is the abnormal termination of the task.
  • ILLOCIC (VSAM only) - Set when a VSAM error occurs that is not defined by one of the other C1CS response categories. The default action is the abnormal termination of the task.
  • INVREQ - Occurs for any of the following reasons:
    1. Browse is not permitted per the FCT entry definition
    2. KEYLENGTH and GENERIC options are used and the length used with the KEYLENGTH option is greater than or equal to the length of a full key
    3. KEYLENGTH option is used without the GENERIC option and the specified length is not equal to the length defined for the data set to which this file refers
    4. SRARTBR command issued with a REQID that is already in use by another browse operation KEYLENGTH and GENERIC options are used and the length used with the KEYLENGTH option is less than or equal to zero
    5. The file used by the command is a user maintained data table
  • The default action is the abnormal termination of the task. IOERR - This is set when an I/O error occurs during the READ. An I/O error can be any unusual event not covered by an existing C1CS condition. For VSAM files, IOERR normally indicates a hardware error. The default action is the abnormal termination of the task.
  • ISCINVREQ - Set when the remote system indicates a failure that is not covered by an existing C1CS condition.

The default action is the abnormal termination of the task.

  • NOTAUTH - Resource security check failure has occurred on filename. The default action is the abnormal termination of the task.
  • NOTFND - Set when an unsuccessful attempt is made to retrieve a record based on the search argument provided. This can also occur if a generic STARTBR with KEYLENGTH (0) specifies the EQUAL option. The default action is the abnormal termination of the task.
  • NOTOPEN - NOTOPEN is set for any one of the following conditions that may occur:
    1. The requested file is a CLOSED and UNENABLED state. This condition occurs after a CLOSE request has been received against an OPEN ENABLED file and the file is no longer in use. The CLOSED UNENABLED state can also be set by specifying the initial state of the FILSTAT parameter (TYPE=FILE) of the FCT, or by defining the RDO options for the file definition as STATUS=UNENABLED and OPENTlME=FIRSTREF.
    2. The requested file is in use by other transactions with an OPEN status but a CLOSE request against the file has been received. This error does not occur when the request is made to a file that has a status of either CLOSED ENABLED or CLOSED DISABLED. The CLOSED ENABLED condition when encountered from this command will cause the file to open as a part of executing the request. When the CLOSED DISABLED condition is encountered the DISABLED condition is set as a result of executing this command.

The default action is the abnormal termination of the task.

  • SYSIDERR - The SYSID specified cannot be found in the intersystem table, (defined in CICS by defining a CONNECTION), or if the link to the remote system is unavailable or closed. The default action is the abnormal termination of the task.

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM Mainframe Topics