RETRIEVE
Retrieve data stored for a task.
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
EXEC CICS RETRIEVE
INTO(DATAFLD)
LENGTH(LENG)
EXEC CICS RETRIEVE
SET(PREF)
LENGTH(LENG)