Receive data on an APPC basic conversation (assembler-language
and C programs only).
GDS RECEIVE (APPC basic)
>>-GDS RECEIVE--CONVID(name)--+-INTO(data-area)--+-------------->
'-SET(pointer-ref)-'
>--FLENGTH(data-area)--+------------------------+--+-BUFFER-+--->
'-MAXFLENGTH(data-value)-' '-LLID---'
>--CONVDATA(data-area)--RETCODE(data-area)--+-------------+----><
'-STATE(cvda)-'
Description
GDS RECEIVE receives data and indicators
from a partner transaction.
The return code is given in RETCODE (see Table 1). For a list of return code values, see the Return
codes for APPC basic conversations .
EXEC CICS® conditions
are never raised on GDS commands.
Options
In general, the arguments can be replaced
by absolute or relocatable assembler-language expressions.
- BUFFER
- specifies
that the length of the data passed to the application program in response
to the RECEIVE command is to be restricted only by the length specified in
the MAXFLENGTH option, and is not to be affected by GDS structured field boundaries.
Control is returned to the application program when this length has been received,
or when a synchronization request, change-direction, or end-bracket is received.
- CONVDATA(data-area)
- specifies
the 24-byte application data area into which conversation-related information
is to be moved. A description of the format of the data area is given in the
discussion of CONVDATA fields in the Testing indicators .
- CONVID(name)
- identifies
the conversation to which the command relates. The 4-character name identifies
either the token returned by a previously executed GDS ALLOCATE command, or
the token representing the principal session (returned by a previously executed
GDS ASSIGN command).
- FLENGTH(data-area)
- specifies
a fullword binary data area that is set to the length of the data made available
to the application program.
- INTO(data-area)
- specifies
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.
The length of this area must not be less than the value specified in the MAXFLENGTH
option.
- LLID
- specifies
that the delimiter to be used by CICS to terminate the passing of data to
the application program is the end of a GDS structured field, if this occurs
before the MAXFLENGTH limit is reached.
- MAXFLENGTH(data-value)
- specifies,
as a fullword binary value, either the length of the target data area specified
in the INTO option, or the maximum length of data to be addressed by the pointer
reference specified in the SET option. The length must not exceed 32 767 bytes.
CICS does not receive more data than the MAXFLENGTH value allows.
- RETCODE(data-area)
- specifies
the 6-byte application data area into which return code information (shown
in Table 1) is to be moved.
- SET(pointer-ref)
- specifies
the pointer reference to be set to the address of data received from the application
program connected to the other end of the current conversation. The pointer
reference, unless changed by other commands or statements, is valid until
the next RECEIVE (GDS or APPC) command, or the end of the 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.
- STATE(cvda)
- gets
the state of the current conversation. The cvda values returned by CICS are:
- ALLOCATED
- CONFFREE
- CONFRECEIVE
- CONFSEND
- FREE
- PENDFREE
- PENDRECEIVE
- RECEIVE
- ROLLBACK
- SEND
- SYNCFREE
- SYNCRECEIVE
- SYNCSEND
Table 1. GDS RECEIVE return
codesRETCODE (hexadecimal) |
Description |
03 00 |
CONVID is for a session that is not APPC. |
03 00 |
CONVID is for a session that is in use by CPI Communications. |
03 04 |
CONVID is for a conversation that is not basic. |
03 08 |
A state check occurred. |
04 |
CONVID is for a session that is not allocated to the task,
or that is a relay link. |
05 00 00 00 7F FF |
MAXFLENGTH is outside the range 0 through
32 767. |