RECEIVE - IBM Mainframe

The RECEIVE command will receive data from either a standard CICS terminal (BTAM or TCAM) or from a task that is not attached to a terminal. This command is used for all other CICS supported terminals for which there are no other appropriate RECEIVE descriptions. For receiving data, you must specify either the INTO or SET option. If the intent is solely to detect an attention identifier (AID), the INTO and SET options can be omitted. The syntax of the command is given below:

RECEIVE

An example of the RECEIVE command is given below:

example of the RECEIVE command

The various options of the RECEIVE command are given below:

  • FLENGTH (data_area) - Fullword binary field (PIC S9(8) COMP) containing the length value of the data made available to the application program. This option is a fullword alternative to the LENGTH option. For safety reasons the value should not exceed 24kb although it can be as high as 32kb.
  • INTO (data_area) - Identifies the data area for receiving data from the terminal.
  • LENGTH (data_area) - Haifword binary field (PIC S9(4) COMP) containing the length of the data being transmitted. When using the INTO option, if the MAXLENGTH is omitted then the argument must be a data area that specifies the maximum length that the program accepts. A value of zero is assumed if the specified value is less than zero. When the retrieved record exceeds the LENGTH option value specified, and the NOTRUNCATE option is omitted, the data is truncated to the LENGTH value, the LENGERR condition is set, and after the data has been retrieved, the data area is set to the original length of the data. When using the SET option, the LENGTH option is not required, but if it is used, then the argument must be a data area.
  • MAXFLENGTH (data_value) - Fullword binary field (PIC S9(8) COMP) containing the length value of the data made available to the application program. This option is a fullword alternative to the MAXLENGTH option. For safety reasons the value should not exceed 24kb although it can be as high as 32kb.
  • MAXLENGTH (data_value) - Haifword binary field (PIC S9(4) COMP) length value. This specifies to CICS the maximum amount of data that can be recovered in response to a RECEIVE command. The LENGTH option value is assumed as the default for this option when it is omitted. When MAXLENGTH and SET are used together, it provides a means to the program in limiting the amount of data it can receive at one time. When the data length exceeds the MAXLENGTH value and the NOTRUNCATE option is omitted, then the data is truncated to the MAXLENGTH value and the LENGERR condition is set. The TOLENGTH option value is then set to the original length of data. When the data length exceeds the MAXLENGTH value and the NOTRUNCATE is specified, then CICS will retain the remaining data for use in satisfying subsequent RECEIVE commands. In determining whether all the data has been received, the program can query the EIBCOMPL field in the EIB block. For safety reasons the value should not exceed 24kb in size.
  • NOTRUNCATE - Option which specifies that when the retrieved data exceeds the requested length, the remaining data is not discarded, but rather retained for any subsequent retrieval commands such as a RECEIVE command.
  • SET (ptr_ref ) - Set the pointer reference value to the address of where the data is stored that was read from a terminal after a RECEIVE command. The pointer reference value is valid until one of the following occurs:
    1. Another command or statement changes its value
    2. Task termination occurs

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 copied below the 16MB line, and the address of this copy's 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 (C1CS) is specified, the returned data is in CICS-key DSA.

The main handle conditions are:

  • INVREQ - For a distributed program link server application attempted to receive data on its function-shipping (principal facility) session. The default action is the abnormal task termination.
  • LENGERR - CO discards the data because the data length exceeds the program specified maximum length and the NOTRUNCATE option was not specified. The default action is the abnormal task termination.
  • NOTALLOC - Condition is set when a non-terminal task issues a RECEIVE command from the transaction. The default action is the abnormal task termination.

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

IBM Mainframe Topics