Receive data from a 3790 full-function or inquiry logical unit.

RECEIVE (3790 full-function or inquiry)
>>-RECEIVE--+---------------------+--+-LENGTH(data-area)--+----->
'-+-INTO(data-area)-+-' '-FLENGTH(data-area)-'
'-SET(ptr-ref)----'
>--+------------------------+--+------------+------------------><
+-MAXLENGTH(data-value)--+ '-NOTRUNCATE-'
'-MAXFLENGTH(data-value)-'
Conditions: EOC, EODS, INBFMH, INVREQ, LENGERR, SIGNAL, TERMERR
Description
RECEIVE receives data from the terminal. This
form of RECEIVE also applies to the following devices:
- 3650/3680 full-function logical unit
- 3770 full-function logical unit
If data is to be received, you must specify either the INTO or
the SET option. If a RECEIVE is issued purely to detect an attention identifier
(AID) you can omit both the INTO and SET options.
Options
- FLENGTH(data-area)
An alternative to LENGTH. For architectural reasons, this option
is limited to a maximum of 32K for all terminal-related RECEIVE commands.
- INTO(data-area)
- specifies
the receiving field for the data read from the logical unit or terminal, or
the application target data area into which data is to be received from the
application program connected to the other end of the current conversation.
- LENGTH(data-area)
- specifies
the length, as a halfword binary value, of the data received.
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 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.
- 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 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.
- SET(ptr-ref)
- specifies
the pointer reference that is to be set to the address of the data read from
the logical unit or terminal, or the partner transaction. 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.
Conditions
Some
of the following conditions may occur in combination with others. CICS checks
for these conditions in the following order:
- EODS
- INBFMH
- EOC
If more than one occurs, only the first is passed to the application
program. EIBRCODE, however, is set to indicate all the conditions that occurred.
- EOC
- occurs
when a request/response unit (RU) is received with end-of-chain-indicator
set. Field EIBEOC also indicates this condition.
Default action: ignore
the condition.
- EODS (interpreter logical unit only)
- occurs
when an end-of-data-set indicator is received.
Default action: terminate
the task abnormally.
- 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.
- INVREQ
- RESP2 values:
- 200
- A distributed program link server application specified the function-shipping
session (its principal facility) on the CONVID option.
also occurs (RESP2 not set) in any of the following situations:
- The command is used on an APPC conversation that is not using the EXEC
CICS interface or that is not a mapped conversation.
Default action: terminate the task abnormally.
- 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.
- SIGNAL
- occurs
when an inbound SIGNAL data-flow control command is received from a partner
transaction. EIBSIG is always set when an inbound signal is received.
Default
action: ignore the condition.
- TERMERR
- occurs
for a session-related or terminal-related error. Any action on that conversation
other than a FREE causes an ATCV abend.
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.