Writing a front-end transaction program for CICS
The front-end transaction program (TP) is responsible for acquiring a session, specifying the conversation characteristics, and requesting the startup of the back-end TP.
Step 1: Allocating a session to the conversation
By issuing an ALLOCATE command, your transaction program acquires a session to start a new conversation. The ALLOCATE command allocates a CICS session from the session pool defined for the connection. If all sessions are in use, the program waits, unless you specify noqueue or nosuspend, in which case the SYSBUSY condition is raised.
The RESP value returned should be checked to ensure that a session has been allocated. If the session is successfully allocated (the RESP value is zero), the conversation is in allocated state (state 1) and the session identifier, convid, in EIBRSRCE must be saved.
| allocateConversation |
"Allocate a conversation using the workstation system id"
allocateConversation := CICS appcallocate
sysid: (self workstationSysid);
exec.
"Check the RESP value. If 0, set convid to EIBRSRCE"
allocateConversation resp = 0
ifTrue: [self convid: (CICS address exec eib eibrsrce).]
"If RESP value other than 0, no session allocated.
Examine RESP code."
The convid must be used in subsequent commands for this conversation.
Step 2: Connecting the partner transaction
By issuing the CONNECT PROCESS command, your transaction initiates the partner transaction. The CONNECT PROCESS command allows the conversation characteristics to be specified and attaches the required back-end transaction. It should be noted that the results of the CONNECT PROCESS command are placed in the send buffer and are not sent immediately to the partner system. Transmission occurs when the send buffer is flushed, either by sending more data than fits in the send buffer or by issuing a WAIT CONVID command.
| connectPartner confirmResult |
"Connect the partner transaction using the convid
acquired in Step 1"
connectPartner := CICS appcconnectprocess
convid: (self convid);
procname: 'TAPS';
proclength: 4;
synclevel: 0;
exec.
"Confirm the connection"
confirmResult := CICS appcsend
convid: (self convid);
confirm;
exec.
A successful CONNECT PROCESS causes the conversation to switch to send state (state 2). While connecting the back-end transaction, the front-end transaction can send initial data called program initialization parameters (PIPs). For more information about PIPs, see the CICS documentation.
Step 3: Sending data to the partner transaction
The SEND command is valid only in send state (state 2). Because a successful simple SEND command leaves the conversation in send state, it is possible for your program to issue consecutive SEND commands. The data from the simple SEND command is initially stored in a local CICS buffer, which is flushed either when the buffer is full or when the transaction requests transmission of the buffer contents. The transaction can request transmission either by using a WAIT CONVID command or by using the WAIT option on the SEND command.
| sendFirst sendLast |
"Send data to partner transaction using the convid acquired in Step 1"
sendFirst := CICS appcsend
convid: (self convid);
from: data;
length: dataLength;
exec.
"Check outcome of send"
"Send data to partner transaction using invite and wait to change
state to pendreceive state (state 3)"
sendLast := CICS appcsend
convid: (self convid);
from: moreData;
length: moreDataLength;
invite;
wait;
exec.
You can switch from sending to receiving data in one of the following ways:
•Use the RECEIVE command after sending data. CICS supplies an INVITE and WAIT when a SEND is immediately followed by a RECEIVE command.
•Use the SEND INVITE command. The conversation switches to pendreceive state (state 3). A WAIT CONVID command switches the command to receive state (state 5).
•Use the SEND command with both INVITE and WAIT. This changes the conversation to the receive state (state 5).
Step 4: Receiving data from the partner transaction
The RECEIVE command is used to receive data from the connected partner transaction. After issuing a RECEIVE command, test the EIB fields or the conversation state for successful completion of the command.
| receiveData |
"Receive data from the partner transaction using convid acquired in Step 1"
receiveData := CICS appcreceive
convid: (self convid);
maxlength: 1024;
exec.
"Check outcome of receive"
For more information about testing the EIB fields in the correct order, see the CICS documentation.
Step 5: Ending the conversation
You can end an APPC conversation in one of three ways:
•Normal end of a conversation
•Emergency end of a conversation
•Unexpected end of a conversation
For more information about ending a conversation in one of these ways, see the CICS documentation.
| freeConversation |
"Free the conversation (use only with sync level 0)"
freeConversation := CICS appcfree
convid: (self convid);
exec.
To end the conversation, one transaction issues a request to end the conversation, and the other transaction receives the request. Once this has happened, the conversation is unusable and both transactions must issue a FREE command to release the session.