Menu principal                 [Fechar]


CICS Manual do Usuário - READ


Volta a página anterior

Volta ao Menu Principal


Desenvolvido por DORNELLES Carlos Alberto - Analista de Sistemas - Brasília DF. - cad_cobol@hotmail.com

READ

Reads a record from a file.

Nota:
If you want to ensure that only committed data is read, use READ UPDATE.

Sintaxe:

Notes:

  1. DATASET is also accepted, but FILE is preferred.
  2. When SYSID is specified, the LENGTH option can be omitted if SET is also specified, but not if INTO is also specified.
  3. KEYLENGTH is required with SYSID for a KSDS READ.
  4. DSIDERR is equivalent to FILENOTFOUND.

Descrição:

READ reads a record from a file that is on a local or a remote system.

For both UPDATE and non-update commands, you must identify the record that is to be retrieved by the record identification field that is specified in the RIDFLD option. Immediately on completion of a READ UPDATE command, the RIDFLD data area is available for reuse by the application program.

The following example shows how to read a record from a file named MASTER into a specified data area:

     EXEC CICS READ
          INTO(RECORD)
          FILE('MASTER')
          RIDFLD(ACCTNO)
     END-EXEC

The following example shows how to read a record for update, by using a generic key and specifying a greater-or-equal key search.

     EXEC CICS READ
          INTO(RECORD)
          LENGTH(RECLEN)
          FILE('MASTFILE')
          RIDFLD(ACCTNO)
          KEYLENGTH(4)
          GENERIC
          GTEQ
          UPDATE
     END-EXEC

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.
    FILE(name)
  • Specifies the name of the CICS file that is to be accessed.
  • The name must be alphanumeric, up to eight characters long, and the file must be currently READABLE (see INQUIRE FILE).
  • If a remote SYSID is specified in the SYSID option, 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 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 is retrieved.
  • This option should be used only with a KSDS or with a KSDS or ESDS through an alternative index path.
    INTO(data-area)
  • Specifies the data area into which the record that is retrieved from the file is to be written.
  • The contents of the data area are unpredictable if a condition other that LENGERR occurs.
  • See INTO and SET for more information about using this option.
    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 in the File Definitions (FD) if the file is remote.
  • If either GENERIC or SYSID is present, KEYLENGTH is required; the length cannot be taken from the FD.
  • See KEYLENGTH and RIDFLD for more information about using this option.

  • KEYLENGTH should not be present if the record identification field that is supplied in the RIDFLD option contains either a relative byte address (use the RBA option) or a relative record number (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 previous).
  • If KEYLENGTH(0) is used for reading the first record in the file, the GTEQ option must also be specified; otherwise, the NOTFND condition might occur.
    LENGTH(data-area)
  • Specifies, as a 16-bit binary value, the length of the data area into which the retrieved record is to be placed.
  • On completion of the READ command, the LENGTH argument (which must be a data area) contains the actual length of the record.
  • The LENGTH option must be specified if the SYSID and INTO options are both present.
  • It must also be specified with the INTO option on READ commands that involve variable-length records.
  • It need not be specified for fixed-length records, but its inclusion is recommended because:
    • It causes a check to be made that the record that is being read is not too long for the available data area.
    • If fixed-length records are being read into an area that is longer than the record that is being accessed, and the LENGTH option is not specified, the LENGERR condition occurs (for COBOL and PL/I applications).
  • If the target data area is longer than the record that is being read, the contents of the target data area, from the end of the retrieved record to the end of the target data area, are unpredictable.
  • If you specify the INTO option, the LENGTH argument must specify the largest record that the program accepts.
  • If the retrieved record is longer than the value that is specified in the LENGTH option, the record is truncated to the specified value, and the LENGERR condition occurs.
  • In this case, the LENGTH argument is set to the length of the record before truncation.
  • If you specify the SET option, the LENGTH option need not be specified but, if it is, the argument must be a data area.
  • See LENGTH for more information about using this option.
    RBA
  • Specifies that the record identification field that supplied in the RIDFLD option contains a relative byte address.
  • Use this option only when reading records directly from an ESDS.
  • 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).
    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.
  • Enure that the RIDFLD data area is not shorter than the KEYLENGTH that is specified in this command or, if KEYLENGTH is not specified, the key length of the file that you are reading; otherwise, the results are unpredictable.
  • 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 reading records from 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).
    SET(ptr-ref)
  • Indicates that CICS is to supply a buffer into which the record is read, and specifies a pointer reference that is to be set to the address of the retrieved record.
  • See INTO and SET for more information about using this option.
  • For a READ UPDATE SET command, the pointer reference is valid until completion of a corresponding REWRITE, DELETE, or UNLOCK command; or until a SYNCPOINT. Otherwise, the pointer reference is valid until the next READ command for the same file.
  • If you want to retain the data within the field that is addressed by the pointer, it should be moved to your own area.
    SYSID(name)
  • Specifies on which CICS region the READ 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:
    • KEYLENGTH must be specified for a KSDS read because the length of the key cannot be determined from the FD entry.
    • LENGTH is required if SET is not specified.
    UPDATE
  • Specifies that the record is to be obtained for updating or deletion.
  • The file must be currently UPDATABLE (see INQUIRE FILE). If this option is omitted, a read-only operation is assumed.

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.
    DUPKEY
  • Occurs if a record is retrieved by way of an alternative index that supports non-unique keys, and another alternative index record that has the same key follows.
  • 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 READ command:
    • Read operations are not currently allowed for the file.
    • Update operations are not currently allowed for the file (applicable to READ UPDATE commands only).
    • 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.
    • Following a READ UPDATE command for a file, another READ UPDATE command is issued for a file referencing the same underlying file, before exclusive control is released by a REWRITE, DELETE, or UNLOCK command.
    • 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 READ. 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.
    LENGERR Occurs for the following conditions:
    • The length of a record read with the INTO option specified exceeds the value that is specified in the LENGTH option; the record is truncated, and the data area that is supplied in the LENGTH option is set to the actual length of the record.
    • The length of a record for a file with fixed-length records is less than the value that is specified in the LENGTH option; the record is copied to the start of the INTO data-area, and the contents of the rest of the data-area is undefined.
    • The data area that is supplied in the LENGTH option is set to the actual length of the record.
  • Ação pré-definida: Terminates the task abnormally.
    NOTAUTH
  • Occurs for the following conditions:
    • A resource security check is unsuccessful on FILE(name).
    • SYSID was 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 retrieve a record, based on the search argument provided, is unsuccessful.
  • Any data that is returned with this exception is unspecified for abnormal conditions.
  • 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 READ 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.
P>Informações relacionadas:
© Copyright IBM Corp.