RECEIVE (MRO)
Receive data on an MRO conversation.
Description
RECEIVE receives data from the conversation partner in an MRO conversation.
Options
- FLENGTH(data-area)
- A fullword alternative to LENGTH.
- INTO(data-area)
- specifies the receiving field
for the data read from the terminal or logical unit, or the application
target area receiving the data from the application program connected
to the other end of the current conversation.
If you specify the INTO option, but omit the MAXLENGTH option, the argument for the LENGTH option must be a data area that specifies the maximum length that the program accepts. If the value specified is less than zero, zero is assumed.
If the length of the data exceeds the value specified, but the NOTRUNCATE option is not specified, the data is truncated to that value and the LENGERR condition occurs. When the data has been received, the data area for the LENGTH option is set to the original length of the data.
- LENGTH(data-area)
- specifies the length, as a
halfword binary value, of the data transmitted.
If you specify the INTO option, but omit the MAXLENGTH option, the argument must be a data area that specifies the maximum length that the program accepts. If the value specified is less than zero, zero is assumed.
If the length of the data exceeds the value specified, but the NOTRUNCATE option is not specified, the data is truncated to that value and the LENGERR condition occurs. When the data has been received, 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. When the data has been received, 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.
- MAXFLENGTH(data-value)
- A fullword alternative to MAXLENGTH.
- MAXLENGTH(data-value)
- specifies the maximum amount
(halfword binary value) of data that CICS® is
to recover. If INTO is specified, MAXLENGTH overrides the use of LENGTH
as an input to CICS. If SET
is specified, MAXLENGTH provides a way for the program to limit the
amount of data it receives at one time.
If the value specified is less than zero, zero is assumed.
If the length of data exceeds the value specified and the NOTRUNCATE option is not present, the data is truncated to that value and the LENGERR condition occurs. The data area specified in the LENGTH option is set to the original length of data.
If the length of data exceeds the value specified and the NOTRUNCATE option is present, CICS retains the remaining data and uses it to satisfy subsequent RECEIVE commands. The data area specified in the LENGTH option is set to the length of data returned.
If this option is omitted, the value indicated in the LENGTH option is assumed.
- NOTRUNCATE
- specifies that, when the data available exceeds the length requested, the remaining data is not to be discarded but is to be retained for retrieval by subsequent RECEIVE commands.
- SESSION(name)
- specifies the symbolic identifier (1–4 characters) of a session TCTTE. This option specifies the alternate facility to be used. If this option is omitted, the principal facility for the task is used.
- SET(ptr-ref)
- specifies a pointer reference
that is to be set to the address of data received from the conversation
partner in an MRO conversation. The pointer reference is valid
until the next receive command or the end of task.
If DATALOCATION(ANY) is associated with the application program, the address of the data can 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 specify the SET option, the argument for the LENGTH option must be a data area. When the data has been received, the data area is set to the length of the data.
- STATE(cvda)
- gets
the state of the current conversation. The cvda values returned by CICS are:
- ALLOCATED
- FREE
- PENDFREE
- RECEIVE
- ROLLBACK
- SEND
- SYNCFREE
- SYNCRECEIVE
- SYNCSEND
Conditions
- INBFMH
- EOC
- 06 EOC
- occurs when a request/response
unit (RU) is received with the end-of-chain indicator set. Field EIBEOC
also contains this indicator.
Default action: ignore the condition.
- 07 INBFMH
- occurs if a request/response
unit (RU) contains a function management header (FMH). Field EIBFMH
contains this indicator and it should be used in preference to INBFMH.
The IGNORE CONDITION command can be used to ignore the condition.
Default action: terminate the task abnormally.
- 16 INVREQ
- RESP2 values:
- 200
- A distributed program link server application specified the function-shipping session (its principal facility) on the CONVID option.
Default action: terminate the task abnormally.
- 22 LENGERR
- occurs if data is discarded
by CICS because its length
exceeds the maximum the program accepts and the NOTRUNCATE option
is not specified.
Default action: terminate the task abnormally.
- 61 NOTALLOC
- occurs if the facility specified
in the command is not owned by the application.
Default action: terminate the task abnormally.
- 81 TERMERR
- occurs for a terminal-related
error, such as a session failure. This condition applies to z/OS® Communications Server-connected
terminals only.
A CANCEL TASK request by a user node error program (NEP) may cause this condition if the task has an outstanding terminal control request active when the node abnormal condition program handles the session error.
Default action: terminate the task abnormally with abend code ATNI.