Receiving data from the partner transaction

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.

Figure 20. Receiving data on an APPC basic conversation
*         ...
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
*         ...

Receiving data by the record

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.

Figure 21. An example of the effect of the LLID option.

The data to be received consists of two logical records:

  1. A GDS RECEIVE LLID command specifying MAXFLENGTH(maxfl1) is issued. This returns the first portion of the first record. CDBCOMPL is set to X'00', indicating that a complete record has not been received.
  2. A GDS RECEIVE LLID comand specifying MAXFLENGTH(maxfl2) is issued; because maxfl2 exceeds the length of the remaining data contained in the first logical record, the remaining data from the record is returned. CDBCOMPL is set to X'FF', indicating that a complete record has been received.
  3. A GDS RECEIVE LLID command specifying MAXFLENGTH(maxfl3) is issued, where has a value of 2. The LL field from the second logical record is returned. CDBCOMPL is set to X'00', indicating that a complete record has not been received.
  4. A GDS RECEIVE LLID command specifying MAXFLENGTH(maxfl4) is issued, wheremaxfl4 is the length of the remaining data in the second logical record. CDBCOMPL is set to X'FF', indicating that a complete record has been received.
 This figure shows the portions of two logical records which are returned when a series of GDS RECEIVE commands specify the LLID option.

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.

Receiving data by the buffer

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.

Figure 22. An example of the effect of the BUFFER option.

The data to be received consists of two logical records:

  1. A GDS RECEIVE BUFFER command specifying MAXFLENGTH(maxfl1) is issued. This returns the first portion of the first record.
  2. A GDS RECEIVE BUFFER comand specifying MAXFLENGTH(maxfl2) is issued; because maxfl2 exceeds the length of the remaining data contained in the first logical record, the remaining data from the first record, and the first part of the second record (including the LL field), are returned.
  3. A GDS RECEIVE LLID command specifying MAXFLENGTH(maxfl3) is issued, where has a value of 2. Two further bytes from the second logical record are returned.
  4. A GDS RECEIVE LLID command specifying MAXFLENGTH(maxfl4) is issued, wheremaxfl4exceeds the length of the remaining data in the second logical record. The application waits until the partner transaction sends either enough data to satisfy the RECEIVE request, or the INVITE or LAST option.
 This figure shows the portions of two logical records which are returned when a series of GDS RECEIVE commands specify the BUFFER option.
[[ Contents Previous Page | Next Page Index ]]