The GDS RECEIVE command is used to receive data from the connected partner transaction. The rows in the state tables for the GDS RECEIVE command show the CONVDATA fields that should be tested after issuing a GDS RECEIVE command. As well as showing which fields should be tested, the state tables also show the order in which the tests should be made. As an alternative to testing some of the CONVDATA fields it is possible to test the resulting conversation state. This is shown in Figure 24. Note that both RETCODE and CDBERR should always be tested.
The amount of data received is determined by:
The first factor is obvious: the application cannot receive more than is sent. The value of MAXFLENGTH is an upper limit; CICS® never returns more bytes than this value specifies. The LLID and BUFFER options enable the application to specify how CICS is to treat the data. This is described in Receiving data by the record and Receiving data by the buffer.
In the same way as it is possible to send GDS records with the INVITE, LAST, or CONFIRM option, it is also possible to receive them together. Syncpoint requests can also be received with GDS records. However, GDS ISSUE ERROR, GDS ISSUE ABEND, and indications of conversation failure are received by themselves --never with GDS records.
An example of a GDS RECEIVE command can be seen in Figure 20. Figure 24 illustrates the response testing sequence.
* ...
RECVLOOP DS 0H
LA R5,L'RECVHDR Length of GDS header
ST R5,RECVMAX as maximum receive length
* Receive GDS header from partner transaction
EXEC CICS GDS RECEIVE INTO(RECVHDR) MAXFLENGTH(RECVMAX) *
LLID FLENGTH(RECVLEN) *
CONVID(WCONVID) RETCODE(WRETC) *
STATE(WSTATE) CONVDATA(WCDB)
*
* ... Check outcome of the GDS RECEIVE
* ...
LA R5,L'RECVAREA Length of application buffer
ST R5,RECVMAX as maximum receive length
* Receive application data from partner transaction
EXEC CICS GDS RECEIVE INTO(RECVAREA) MAXFLENGTH(RECVMAX) *
LLID FLENGTH(RECVLEN) *
CONVID(WCONVID) RETCODE(WRETC) *
STATE(WSTATE) CONVDATA(WCDB)
* ...
* ... Check outcome of the GDS RECEIVE
* ... (including CDBCOMPL).
B RECVLOOP Loop while in receive state
* ...
*
WSTATE DS F
WRETC DS XL6
WCDB DS 0CL24
COPY DFHCDBLK
WCONVID DS CL4
RECVAREA DS CL100
RECVMAX DS F
RECVLEN DS F
RECVHDR DS H
* ...
If you specify the LLID option on a GDS RECEIVE command, the data is considered as a series of GDS records. On each GDS RECEIVE request, data is received from not more than one record. If the record is longer than the value specified in the MAXFLENGTH option, two or more RECEIVE commands are required to recover the whole record. CDBCOMPL is set on when the end of a GDS record has been received. Consider the example shown in Figure 21.
The data to be received consists of two logical records:
The first RECEIVE command receives the front portion of the first record. The length received is restricted by the MAXFLENGTH value (MAXFL1). The second RECEIVE command receives the rest of the first logical record. Even though the MAXFLENGTH value (MAXFL2) allows more data to be received, this cannot be done without breaking the LL boundary rule. The third RECEIVE command is for two bytes of data (the LL field). The fourth RECEIVE command receives the rest of the second record.
The application can tell if a complete record has been received, because CDBCOMPL is set (X'FF'). So, in the example given above, CDBCOMPL is set on after the second and fourth RECEIVE commands. CDBCOMPL is set off (X'00') after the first and third RECEIVE commands.
Unlike the LLID option, the BUFFER option does not respect GDS record boundaries. If the MAXFLENGTH value allows, bytes will be received for more than one record. A GDS RECEIVE command with the BUFFER option recovers the length of data specified in the MAXFLENGTH option, ignoring GDS record boundaries. CICS does not return control to the application program until this length of data has been received or the partner transaction sends the INVITE or LAST option.
Figure 22 shows the effect of the BUFFER option on the same four RECEIVE commands discussed in Receiving data by the record.
The data to be received consists of two logical records: