Receives data from an advanced program-to-program communications (APPC) mapped conversation. (An APPC conversation allows a program to send data to, and receive data from, a program that is running in a remote system. Programming that uses APPC conversations is called Distributed Transaction Programming (DTP). For guidance information on DTP, see Distributed transaction processing (DTP).)
Syntax
RECEIVE (APPC) >>-RECEIVE--+--------------+--+-----------------+---------------> '-CONVID(name)-' +-INTO(data-area)-+ '-SET(ptr-ref)----' >--+--------------------+--+------------------------+-----------> +-LENGTH(data-area)--+ +-MAXLENGTH(data-value)--+ '-FLENGTH(data-area)-' '-MAXFLENGTH(data-value)-' >--+------------+--+-------------+----------------------------->< '-NOTRUNCATE-' '-STATE(cvda)-'
Conditions: INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR
Description
RECEIVE receives data from either an APPC mapped conversation or a terminal. The form of RECEIVE command that is described here is used for receiving data from the conversation partner in an APPC mapped conversation.
For details about the RECEIVE command for use with terminals, see RECEIVE (terminal).
Options
- CONVID(name)
- Identifies
the conversation to which the command relates. The four-byte name
identifies either the token that is returned by a previously executed
ALLOCATE command in the EIBRSRCE field of the EXEC Interface Block
(EIB), or the token that represents the principal facility (that was
returned by a previously executed ASSIGN command).
If this option is omitted, the principal facility is assumed.
- FLENGTH(data-area)
- A 32-bit alternative to LENGTH(data-area).
- INTO(data-area)
- Specifies the application target data area into which data is to be received from the application program that is connected to the other end of the current conversation. The length of the INTO data area must be greater than, or equal to, the maximum that is specified in the LENGTH and MAXLENGTH options. For more information about using this option, see INTO and SET.
- LENGTH(data-area)
- Specifies
a 16-bit binary value that CICS® uses to return the maximum
amount of data that is received. If the NOTRUNCATE option is specified,
the LENGTH option contains the amount of data that is to be passed
back to the application. If the NOTRUNCATE option is not specified,
the LENGTH option contains the amount of data that was received by CICS before
any truncation occurred.
If MAXLENGTH is not specified, the LENGTH option is also used to specify that maximum amount of data that CICS can return to the application on the RECEIVE call. If LENGTH is used to pass the maximum value, it must be set up before each call to RECEIVE because its value might have been changed by the previous RECEIVE command. If the value of LENGTH passed is less that zero, CICS uses the maximum length of zero For more information about using this option, see LENGTH.
- MAXFLENGTH(data-value)
- A 32-bit alternative to MAXLENGTH(data-value).
- MAXLENGTH(data-value)
- Specifies,
as a 16-bit binary value, the maximum amount of data that CICS can
return to the application on the RECEIVE command. This value must
be 0 through 32767.
If the NOTRUNCATE option is specified and the data that is received is longer than the maximum that is specified in MAXLENGTH, CICS returns the data up to the maximum length and sets EIBCOMPL=EIBFALSE to indicate that more data is to follow. The remaining data can be received by using one or more of the RECEIVE commands.
If the NOTRUNCATE option is not specified and the data that is received is longer than the maximum that is specified in MAXLENGTH, CICS returns the data up to the maximum length and returns the LENGERR condition. The remaining data is discarded by CICS and cannot be received by the application.
If MAXLENGTH is not coded on the RECEIVE command, CICS uses the value that is passed in the LENGTH argument as the maximum length.
- NOTRUNCATE
- Specifies that, when the data available exceeds the length that is requested, the remaining data is not to be discarded but is to be retained for retrieval by subsequent RECEIVE commands.
- SET(ptr-ref)
- Specifies a pointer reference that is to be set to the address of the data that is received from the partner transaction. This pointer reference is valid until the next APPC or terminal control command, or the end of task. For more information about using this option, see INTO and SET.
- STATE(cvda)
- Gets the state of the current conversation. See STATE.
Conditions
- INVREQ
- Occurs
for the following conditions, depending on the options that are specified
on the RECEIVE command:
- If the STATE option is specified, but the CONVID option is omitted and the principal facility for the task is not an APPC conversation (that is, it is a terminal).
- When an attempt is made to use a distributed transaction processing (DTP) command on a valid non-DTP CONVID.
- A remotely linked-to program attempted to execute a RECEIVE command that refers to the principal facility.
Default action: Terminates the task abnormally.
- LENGERR
- Occurs
for the following conditions:
- Received data was truncated because the length exceeded the maximum that is allowed by the program and the NOTRUNCATE option was not specified. Refer to the option descriptions for information about maximum lengths.
- An out-of-range value is supplied in the LENGTH, FLENGTH, or MAXLENGTH option, or in one of the alternative 32-bit length options.
Default action: Terminates the task abnormally.
- NOTALLOC
- Occurs
if the specified CONVID value does not relate to a conversation owned
by the application.
Default action: Terminates the task abnormally.
- SIGNAL
- Occurs
if an inbound SIGNAL data flow control command is received
from the partner transaction. EIBSIG is always set when an inbound
signal is received.
Default action: Ignore the condition.
- TERMERR
- Occurs
if a session-related error occurs. Any subsequent action on that conversation
other than a FREE command causes an ATCV abend.
Default action: Terminate the task abnormally (with abend code ATNI).