CICS Manual do Usuário - RETRIEVE

RETRIEVE

Retrieves data stored for a task.

Sintaxe:

Descrição:

RETRIEVE retrieves data that is stored by expired START commands.
It is the only method that is available for accessing such data.

A task that is not associated with a terminal can access only the single data record that is associated with the original START command; it does so by issuing a RETRIEVE command.
The storage that is occupied by the data that is associated with the task is released on execution of the RETRIEVE command, or at termination of the task if no RETRIEVE command is executed before termination.

A task that is associated with a terminal can access all data records that are associated with all expired START commands that have the same transaction identifier and terminal identifier as does the START command that started the task; it does so by issuing consecutive RETRIEVE commands.
Expired data records are presented to the task on request in expiration time sequence, starting with any data that is stored by the command that started the task, and including data from any commands that have expired since the task started.
Each data record is retrieved from temporary storage by using the REQID of the original START command as the identification of the record in temporary storage.

If the task that is issuing the retrieve is long running, and the data that it retrieves was created with a PROTECTed START, the retrieving task should syncpoint after retrieving that data (or at regular intervals while issuing multiple RETRIEVEs).

When all expired data records have been retrieved, the ENDDATA condition occurs.
The storage that is occupied by the single data record that is associated with a START command is released after the data has been retrieved by a RETRIEVE command.

The following example shows how to retrieve data that is stored by a START command for the task, and store it in the user-supplied data area called DATAFLD.

     EXEC CICS RETRIEVE
          INTO(DATAFLD)
          LENGTH(LENG)
     END-EXEC

The following example shows how to request retrieval of a data record that is stored for a task into a data area that CICS provides; the pointer reference (PREF) that is specified by the SET option is set to the address of the storage area that is reserved for the data record.

     EXEC CICS RETRIEVE
          SET(PREF)
          LENGTH(LENG)
     END-EXEC

Opções:

INTO(data-area)

Specifies the user data area into which retrieved data is to be written.
See INTO and SET for more information about using this option.

LENGTH(data-area)

Specifies, as a 16-bit binary value, the length of the data that is retrieved.
If you specify the INTO option, the LENGTH argument must be a data area that specifies the maximum length of data that the program is prepared to handle.
If the value that is specified is less than zero, zero is assumed.
If the length of the data exceeds the value that is specified, the data is truncated to that value and the LENGERR condition occurs.
On completion of the retrieval operation, the LENGTH argument is set to the original length of data (before any truncation).
If you specify the SET option, the LENGTH argument must be a data area.
On completion of the retrieval operation, the data area is set to the length of the data.
See LENGTH for more information about using this option.

QUEUE(data-area)

Specifies an eight-byte field that is to receive the name of a temporary storage queue that can be accessed by the transaction issuing the RETRIEVE command.

RTERMID(data-area)

Specifies a four-character field that is to receive data that can be used in the TERMID option of a subsequent START command.

RTRANSID(data-area)

Specifies a four-character field that is to receive data that can be used in the TRANSID option of a subsequent START command.

SET(ptr-ref)

Specifies a pointer reference that is to be set to the address of the retrieved data.
See INTO and SET for more information about using this option.

Condições:

ENDDATA

Occurs for the following conditions:
- No more data is stored for the task that is issuing a RETRIEVE command.
- It can be considered a normal end-of-file response when retrieving data records sequentially.
- The RETRIEVE command is issued by a task that is started by a START command that did not specify any of the data options FROM, RTRANSID, RTERMID, or QUEUE.
- The RETRIEVE command is issued by a task that is not started by a START command.
Ação pré-definida: Terminates the task abnormally.

ENVDEFERR

Occurs if a RETRIEVE command specifies an option that is not specified by the corresponding START command.
Ação pré-definida: Terminates the task abnormally.

IOERR

Occurs if an input/output error occurs during a RETRIEVE operation.
The operation can be retried by reissuing the RETRIEVE command.
(See Processing the IOERR condition for information about handling the IOERR condition.)
Ação pré-definida: Terminates the task abnormally.

LENGERR

Occurs if INTO has been specified and the length that is specified is less than the actual length of the stored data.
Ação pré-definida: Terminates the task abnormally.

NOTFND

Occurs for the following conditions:
- The data could not be retrieved because an earlier task retrieved the data that is stored under the request identifier directly through temporary storage requests and deleted the data when the task released it.
- The request identifier that is associated with the START command is not unique, so when a RETRIEVE command is issued, CICS cannot find the data.
Ação pré-definida: Terminates the task abnormally.

Informações relacionadas: