RETRIEVE

Retrieve data stored for a task.

RETRIEVE

Read syntax diagramSkip visual syntax diagramRETRIEVEINTO( data-area)SET( ptr-ref)LENGTH( data-area)RTRANSID( data-area)RTERMID( data-area)QUEUE( data-area)WAIT

Conditions: ENDDATA, ENVDEFERR, INVREQ, IOERR, LENGERR

Note for dynamic transaction routing: Using RETRIEVE with WAIT could create inter-transaction affinities that adversely affect the use of dynamic transaction routing. See Affinity for more information about transaction affinities.

Description

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

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

If the START command specified ATTACH, the storage is not released. (ASSIGN STARTCODE in such a task returns 'U' rather than 'S' or 'SD').

A task that is associated with a terminal can access all data records associated with all expired START commands having the same transaction identifier and terminal identifier as this task, that is the task issuing the RETRIEVE command; 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 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 using the REQID of the original START command as the identification of the record in temporary storage.

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

If the retrieved data contains FMHs (Function Management Headers), as specified by the FMH option on the associated START command, field EIBFMH in the EIB is set to X'FF'. If no FMH is present, EIBFMH is set to X'00'.

Options

INTO(data-area)
specifies the user data area into which retrieved data is to be written.
LENGTH(data-area)
specifies a halfword binary value to define the length of the data area the retrieved data is written into.

If you specify the INTO option, the argument must be a data area that specifies the maximum length of data that the program is prepared to handle. If the value specified is less than zero, zero is assumed. If the length of the data exceeds the value specified, the data is truncated to that value and the LENGERR condition occurs. On completion of the retrieval operation, the data area is set to the original length of the data.

If you specify the SET option, the argument must be a data area. On completion of the retrieval operation, the data area is set to the length of the data.

For a description of a safe upper limit, see LENGTH options in CICS commands.

QUEUE(data-area)
specifies the 8-character area for the temporary storage queue name that may be accessed by the transaction issuing the RETRIEVE command.
RTERMID(data-area)
specifies a 4-character area that can be used in the TERMID option of a START command that may be executed subsequently.
RTRANSID(data-area)
specifies a 4-character area that can be used in the TRANSID option of a START command that may be executed subsequently.
SET(ptr-ref)
specifies the pointer reference to be set to the address of the retrieved data.

If DATALOCATION(ANY) is associated with the application program, the address of the data may be above or below the 16MB line.

If DATALOCATION(BELOW) is associated with the application program, and the data resides above the 16MB line, the data is copied below the 16MB line, and the address of this copy is returned.

If TASKDATAKEY(USER) is specified for the running task, and storage protection is active, the data returned is in a user-key. If TASKDATAKEY(CICS) is specified and storage protection is active, the data returned is in a CICS-key.

If you use SET you must also include LENGTH.

WAIT
specifies that, if all expired data records have already been retrieved, the task is to be put into a wait state until further expired data records become available. Although this means that the ENDDATA condition is not raised at the time the RETRIEVE command is issued, it is raised later if CICS enters shutdown or if the task is subject to deadlock timeout and it waits for longer than the deadlock timeout interval. (See the DTIMOUT option of RDO DEFINE TRANSACTION.)

An attempt to issue RETRIEVE WAIT during shutdown leads to an AICB abend if there is no data record already available to satisfy the request.

If you use WAIT, you must have at least one other option.

Conditions

29 ENDDATA
occurs in any of the following situations:
  • No more data is stored for the task 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 nonterminal task that was not created as a result of a START command.
  • WAIT was specified and the task was waiting for a data record but none became available before the deadlock timeout interval (see the DTIMOUT option of RDO DEFINE TRANSACTION).
  • WAIT was specified and the task was waiting when CICS entered shutdown. An attempt to issue RETRIEVE WAIT during shutdown leads to an AICB abend if there is no data record already available to satisfy the request.
  • A RETRIEVE command with the WAIT option is issued when no data is available; the task was initiated by a START command that specified an APPC connection or terminal in the TERMID option.

Default action: terminate the task abnormally.

56 ENVDEFERR
occurs when a RETRIEVE command specifies an option not specified by the corresponding START command.

Default action: terminate the task abnormally.

16 INVREQ
occurs if the RETRIEVE command is not valid for processing by CICS.

Default action: terminate the task abnormally.

17 IOERR
occurs if an input/output error occurs during a RETRIEVE operation. The operation can be retried by reissuing the RETRIEVE command.

Default action: terminate the task abnormally.

22 LENGERR
occurs if the length specified is less than the actual length of the stored data.

Default action: terminate the task abnormally.

Examples

The following example shows how to retrieve data 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)
The following example shows how to request retrieval of a data record stored for a task into a data area provided by CICS; the pointer reference (PREF) specified by the SET option is set to the address of the storage area reserved for the data record. 
EXEC CICS RETRIEVE
     SET(PREF)
     LENGTH(LENG)