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.
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.
* ...
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.
* ...
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.
* ...
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.
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.
* ...
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 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 ]]