Transferring data on the conversation

This section discusses how to pass data between the front- and back-end transactions. The first subsection explains how to send data, the second describes how to switch from sending to receiving data, and the third explains how to receive data. This section also contains a program fragment illustrating the commands described below and the suggested response code checking.

Sending data to the partner transaction

The SEND command is valid only in send state (state 2). Because a successful simple SEND leaves the conversation in send state (state 2), it is possible to issue a number of successive sends. The data from the simple SEND command is initially stored in a local CICS® buffer which is "flushed" either when this buffer is full or when the transaction requests transmission. The transaction can request transmission either by using a WAIT CONVID command or by using the WAIT option on the SEND command. The reason data transmission is deferred is to reduce the number of calls to the network. However, the application should use WAIT if the partner transaction requires the data to continue processing.

An example of a simple SEND command can be seen in Figure 6.

Figure 6. Transferring data on a conversation at sync level 2
      *    ...
       DATA DIVISION.
       WORKING-STORAGE SECTION.
      *    ...
       01  FILLER.
           02  WS-CONVID       PIC X(4).
           02  WS-STATE        PIC S9(7) COMP.
      *    ...
       01  FILLER.
           02  WS-SEND-AREA    PIC X(70).
           02  WS-SEND-LEN     PIC S9(4) COMP VALUE +70.
      *    ...
       01  FILLER.
           02  WS-RCVD-AREA    PIC X(100).
           02  WS-MAX-LEN      PIC S9(4) COMP VALUE +100.
           02  WS-RCVD-LEN     PIC S9(4) COMP VALUE +0.
      *    ...
       PROCEDURE DIVISION.
      *    ...
           EXEC CICS SEND CONVID(WS-CONVID) STATE(WS-STATE)
                          FROM(WS-SEND-AREA) LENGTH(WS-SEND-LEN)
           END-EXEC.
      *    ... Check outcome of SEND.
      *    ...
      *
           EXEC CICS SEND CONVID(WS-CONVID) STATE(WS-STATE)
                          INVITE WAIT
           END-EXEC.
      *    ...
      *    Receive data from the partner transaction.
      *
           EXEC CICS RECEIVE CONVID(WS-CONVID) STATE(WS-STATE)
                             INTO(WS-RCVD-AREA) MAXLENGTH(WS-MAX-LEN)
                             NOTRUNCATE LENGTH(WS-RCVD-LEN)
           END-EXEC.
      *
      *    ... Check outcome of RECEIVE.
      *    ...

Switching from sending to receiving data

The column for send state (state 2) in the state tables (see topic The state tables for APPC mapped conversations) shows that there are several ways of switching from send state (state 2) to receive state (state 5).

One possibility is to use a RECEIVE command. The state tables show that CICS supplies the INVITE and WAIT when a SEND is followed immediately by a RECEIVE.

Another possibility is to use a SEND INVITE command. The state tables show that after SEND INVITE the conversation switches to pendreceive state (state 3). The column for state 3 shows that a WAIT CONVID command switches the conversation to receive state (state 5).

Still another possibility is to specify the INVITE and WAIT options on the SEND command. The state tables show that after SEND INVITE WAIT, the conversation switches to receive state (state 5).

An example of a SEND INVITE WAIT command can be seen in Figure 6. Figure 7 illustrates the response-testing sequence after a SEND INVITE WAIT with the STATE option. For more information on response testing, see Checking the outcome of a DTP command.

Figure 7. Checking the outcome of a SEND INVITE WAIT command
      *    ...
       DATA DIVISION.
       WORKING-STORAGE SECTION.
      *    ...
       01  FILLER.
           02  WS-RESP         PIC S9(7) COMP.
           02  WS-STATE        PIC S9(7) COMP.
      *    ...
       PROCEDURE DIVISION.
      *    ...
      * Check return code from SEND INVITE WAIT
           IF WS-RESP = DFHRESP(NORMAL)
           THEN
      *       ...  Request successful
              IF EIBERR = LOW-VALUES
              THEN
      *          ...  No errors, check state
                 IF WS-STATE = DFHVALUE(RECEIVE)
                 THEN
      *             ...  SEND OK, continue processing
                 ELSE
      *             ...  Logic error, should never happen
                 END-IF
              ELSE
      *          ...  Error indicated
                 EVALUATE WS-STATE
                   WHEN DFHVALUE(ROLLBACK)
      *                 ...  ROLLBACK received
                   WHEN DFHVALUE(RECEIVE)
      *                 ...  ISSUE ERROR received, reason in EIBERRCD
                   WHEN OTHER
      *                 ...  Logic error, should never happen
                 END-EVALUATE
              END-IF
           ELSE
      *       ...  Examine RESP code for source of error.
           END-IF.

Receiving data from the partner transaction

The RECEIVE command is used to receive data from the connected partner. The rows in the state tables for the RECEIVE command show the EIB fields that should be tested after issuing a RECEIVE command. As well as showing which field should be tested, the state tables also show the order in which the tests should be made.

As an alternative to testing the EIB fields it is possible to test the resulting conversation state; this is shown in Figure 8. The conversation state can be meaningfully tested only after issuing a command with the STATE option or by using the EXTRACT ATTRIBUTES STATE command. Note that the RESP value returned and EIBERR should always be tested. If EIBNODAT is set on (X'FF'), no data has been received. For more information about response testing, see Checking the outcome of a DTP command. For information about testing the conversation state, see Testing the conversation state.

An example of a RECEIVE command with the STATE option can be seen in Figure 6. Figure 8 illustrates the response-testing and state-testing sequence.

Note:
In the same way as it is possible to send the INVITE, LAST, and CONFIRM commands with data, it is also possible to receive them with data. It is also possible to receive a syncpoint request with data. However, ISSUE ERROR, ISSUE ABEND, and conversation failure are never received with data.
Figure 8. Checking the outcome of a RECEIVE command
      *    ...
       WORKING-STORAGE SECTION.
      *    ...
       01  FILLER.
           02  WS-RESP         PIC S9(8) COMP.
           02  WS-STATE        PIC S9(8) COMP.
      *    ...
       PROCEDURE DIVISION.
      *    ...
      * Check return code from RECEIVE
           IF WS-RESP = DFHRESP(EOC)
           OR WS-RESP = DFHRESP(NORMAL)
           THEN
      *       ...  Request successful
              IF EIBERR = LOW-VALUES
              THEN
      *          ...  No errors, check state
                 EVALUATE WS-STATE
                   WHEN DFHVALUE(SYNCFREE)
      *                 ...  Partner issued SYNCPOINT and LAST
                   WHEN DFHVALUE(SYNCRECEIVE)
      *                 ...  Partner issued SYNCPOINT
                   WHEN DFHVALUE(SYNCSEND)
      *                 ...  Partner issued SYNCPOINT and INVITE
                   WHEN DFHVALUE(CONFFREE)
      *                 ...  Partner issued CONFIRM and LAST
                   WHEN DFHVALUE(CONFRECEIVE)
      *                 ...  Partner issued CONFIRM
                   WHEN DFHVALUE(CONFSEND)
      *                 ...  Partner issued CONFIRM and INVITE
                   WHEN DFHVALUE(FREE)
      *                 ...  Partner issued LAST or FREE
                   WHEN DFHVALUE(SEND)
      *                 ...  Partner issued INVITE
                   WHEN DFHVALUE(RECEIVE)
      *                 ...  No state change.  Check EIBCOMPL.
                   WHEN OTHER
      *             ...  Logic error, should never happen
                 END-EVALUATE.
              ELSE
      *          ...  Error indicated
                 EVALUATE WS-STATE
                   WHEN DFHVALUE(ROLLBACK)
      *                 ...  ROLLBACK received
                   WHEN DFHVALUE(RECEIVE)
      *                 ...  ISSUE ERROR received, reason in EIBERRCD
                   WHEN OTHER
      *                 ...  Logic error, should never happen
                 END-EVALUATE
              END-IF
           ELSE
      *       ...  Examine RESP code for source of error
           END-IF.

The CONVERSE command

The CONVERSE command combines the functions SEND INVITE WAIT and RECEIVE. This command is useful when one transaction needs a response from the partner transaction to continue processing.

[[ Contents Previous Page | Next Page Index ]]