Transferring data on the conversation

This section discusses how to pass data between the front-end 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 includes an example program fragment, which illustrates the commands described and the suggested response code checking.

Sending data to the partner transaction

The SEND command is used to send data to the connected partner. This command is valid in allocated state (state 1) or send state (state 2). Because a successful simple SEND completes in send state (state 2), it is possible to issue a number of successive sends.

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

Figure 11. Transferring data on an MRO conversation
      *    ...
       DATA DIVISION.
       WORKING-STORAGE SECTION.
      *    ...
       01  FILLER.
           02  WS-CONVID       PIC X(4).
           02  WS-RESP         PIC S9(8) COMP.
           02  WS-STATE        PIC S9(8) COMP.
      *    ...
       01  FILLER.
           02  WS-SEND-AREA    PIC X(70).
           02  WS-SEND-LEN     PIC S9(5) COMP VALUE +70.
      *    ...
       01  FILLER.
           02  WS-RCVD-AREA    PIC X(100).
           02  WS-MAX-LEN      PIC S9(5) COMP VALUE +100.
           02  WS-RCVD-LEN     PIC S9(5) COMP VALUE +0.
      *    ...
       PROCEDURE DIVISION.
      *    ...
           EXEC CICS SEND CONVID(WS-CONVID) RESP(WS-RESP)
                          STATE(WS-STATE)
                          FROM(WS-SEND-AREA) LENGTH (WS-SEND-LEN)
           END-EXEC.
      *    ... Check outcome of SEND.
      *    ...
      *
           EXEC CICS SEND INVITE CONVID(WS-CONVID)
                          RESP(WS-RESP) STATE(WS-STATE)
           END-EXEC.
      *    ...
      *    Receive data from the partner transaction.
      *
           EXEC CICS RECEIVE CONVID(WS-CONVID)
                             RESP(WS-RESP) 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 table in State transitions in MRO conversations shows that there is only one way of switching from send state (state 2) to receive state (state 5). That is to use a SEND INVITE command with or without the WAIT option. The state table shows that after both SEND INVITE and SEND INVITE WAIT, the conversation switches the current state to receive state (state 5).

An example of a SEND INVITE command can be seen in Figure 11.

Figure 12. Checking the outcome of a SEND INVITE command
      *    ...
       DATA DIVISION.
       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 SEND INVITE
           IF WS-RESP = DFHRESP(NORMAL)
           THEN
      *       ...  Request successful, check state
              IF WS-STATE = DFHVALUE(RECEIVE)
              THEN
      *          ...  SEND OK, continue processing
              ELSE
      *          ...  Logic error, should never happen
              END-IF
           ELSE
      *       ...  Examine EIBRCODE 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 table also shows the order in which the tests should be made. Instead of testing some of the EIB fields, you can test the resulting conversation state; this is shown in Figure 13. Note that you should always test the value returned by the RESP option.

Figure 13. Checking the outcome of a RECEIVE command
      *    ...
       DATA DIVISION.
       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(NORMAL)
           THEN
      *       ...  Request successful, check state
              EVALUATE WS-STATE
                WHEN DFHVALUE(ROLLBACK)
      *              ...  Partner issued SYNCPOINT ROLLBACK
                WHEN DFHVALUE(SYNCFREE)
      *              ...  Partner issued SYNCPOINT and LAST
                WHEN DFHVALUE(SYNCRECEIVE)
      *              ...  Partner issued SYNCPOINT
                WHEN DFHVALUE(FREE)
      *              ...  Partner issued LAST
                WHEN DFHVALUE(SEND)
      *              ...  Partner issued INVITE
                WHEN DFHVALUE(RECEIVE)
      *              ...  Processing for receipt of data
      *                   (including EIBCOMPL for incomplete data)
                WHEN OTHER
      *              ...  Logic error, should never happen
              END-EVALUATE.
           ELSE
      *       ...  Examine EIBRCODE for source of error
           END-IF.
      *    ...
Note:
In the same way as it is possible to send the INVITE and LAST indicators with data, it is also possible to receive them with data. Syncpoint requests may also be received with data. However, indications of conversation failure are never received with data.

The CONVERSE command

The CONVERSE command combines the functions SEND INVITE 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 ]]