Retrieve data stored for a task.
RETRIEVE >>-RETRIEVE--+-INTO(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.
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'.
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.
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.
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.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
EXEC CICS RETRIEVE
INTO(DATAFLD)
LENGTH(LENG)
EXEC CICS RETRIEVE
SET(PREF)
LENGTH(LENG)