RETRIEVE - IBM Mainframe

« Previous Topics
Start
Wait Event
Post
Next Topics »
Cancel
Suspend
Enq

This command will retrieve stored data for a task from an expired START command. This is the only method available for accessing such data. A non-terminal task can access only the single data record associated with the original START command and does so by issuing a RETRIEVE command. The storage containing the data for a task is released when the RETRIEVE command is executed, or at task termination when the RETRIEVE command was not executed prior to the end of the task. A terminal task can access all the data records associated with all expired START commands having the same transaction identifier and terminal identifier. The access is accomplished by issuing consecutive RETRIEVE commands. Expired data records are presented to the task on request in expiration-time sequence, beginning with any data stored by the command that started the task. Included also is any data from any commands that have expired since the task started. Data records are retrieved from temporary storage using the REQID of the original START command as the identification of the record in temporary storage. After all expired records have been retrieved, the ENDDATA condition is set, and any storage that the records occupied is released, and any storage with non retrieved records will be released when the CICS system is SHUT DOWN and NOT at task termination. If the retrieved data contains FMHs, as specified by the FMH option on the associated START command, field EIBFMH in the E1B is set to X'FF'. If no FMH is present, EIBFMH is set to X'OO'. The syntax of the command is given below:

syntax of the command

syntax of the command

The various options of the command are described below:

  • INTO (data_area) - Identifies the user data area setup for retrieval of the data.
  • LENGTH (datavalue) - Halfword binary (PIC 9(4)COMP) indicating the number of bytes of storage required. LENGTH implies storage below the 16MB line with a maximum upper limit of 65,520 bytes. To acquire storage above the 16MB line you must use the FLENGTH option. LENGTH and FLENGTH are mutually exclusive. When using the INTO option and the MAXLENGTH option is omitted, the data area must be large enough to hold the largest record that the program will accept. If a value less than zero is used then zero is assumed. When using the SET option, then the argument must be a data area that contains the length of the data after the data has been received.
  • QUEUE (dataarea) - Character field (8 bytes) containing the name of the queue that the transaction can access with this command and option.
  • RTERMID (data_area) - Character field (4 bytes) that can be used in the TERMID option of a START command that may be executed subsequently.
  • RTRANSID (dataarea) - Character field (4 bytes) that can be used in the TRANSID option of a START command that may be executed subsequently.
  • SET (ptrref) - Set the pointer reference value to the address of where the data is stored. The pointer reference address can be above or below the 16MB line when DATALOCATION (ANY) is associated in RDO with the application program. When the pointer reference address resides above the 16MB line, and the DATALOCATION (BELOW) is associated in RDO with the application program, then the data is copy's below the 16MB line, and the address of this copied new location is returned. When storage protection is active, and TASKDATAKEY (USER) is specified, the returned data is in user-key DSA. When storage protection is active, and TASKDATAKEY (CICS) is specified, the returned data is in CICS-key DSA.
  • WAIT - Option when used, notifies CICS that the task upon retrieving all expired records, that the task is to put into a wait state until further expired data records become available. The ENDDATA condition is not raised when the option is used and all the records are retrieved. However CICS will raise the ENDDATA>condition for one of the following reasons:
    1. CICS enters the shutdown mode
    2. The task is subjected to a deadlock time-out condition and it waits for longer than the deadlock time-out interval.
      An attempt to issue RETRIEVE WAIT during shutdown leads to an AICB abend when there exist no data records available to satisfy the request.
    Handle Conditions:
  • ENDDATA - Condition may be set for any one of the following reasons: No more stored data for the task issuing the RETRIEVE command. When retrieving records sequentially, this becomes the End-Of-File indicator for normal processing.
  • The RETRIEVE command is issued from a task that was started from a START command that did not contain any of the data options: FROM, RTRANSID, RTERMID, or QUEUE.
  • The RETRIEVE command was issued from a non-terminal task that was not created as a result of a START command.
  • WAIT option was used and while the task was waiting for more data records the deadlock time-out interval expired.
  • WAIT was specified and the task was waiting when CICS entered shutdown, with no records to retrieve and the application program attempted to issue RETRIEVE WAIT.
  • A RETRIEVE WAIT command was issued when no data is available; the task was initiated by a START command, which specified an APPC session in the TERMID option. The default action is the abnormal termination of the task.
  • ENVDEFERR - Condition is set when the RETRIEVE command uses an option not specified on a corresponding START command. The default action is the abnormal termination of the task.
  • INVREQ - Invalid RETRIEVE command was issued to CICS. The default action is the abnormal termination of the task.
  • IOERR - Error is set when an I/O error occurs during the RETRIEVE operation. IOERR normally indicates a hardware error. The command may be retried by the application program by reissuing the command. The default action is the abnormal termination of the task. The default action is the abnormal termination of the task.
  • LENCERR - Condition occurs when the length specified is less than the actual length The default action is the abnormal termination of the task.
  • NOTFND - Condition can occur for any of the following reasons:
    1. A RETRIEVE command is issued, but a prior task has already retrieved the data stored under the request identifier directly through temporary storage requests and then released the data.
    2. CICS cannot find the data for the RETRIEVE command because the request identifier associated with the START command is not unique.
« Previous Topics
Start
Wait Event
Post
Next Topics »
Cancel
Suspend
Enq

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM Mainframe Topics