Writing a front-end transaction program
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: Defining a conversation
Your program can define (allocate) an APPC conversation with its partner TP using the AbtAPPCConnectionSpec. Your program identifies its partner and requests that a connection be made. The caller can use a symbolic destination name to identify the partner; the caller does not need to know where the partner is physically located.
| connection |
"Instantiate the connection"
connection := AbtAPPCConnectionSpec new.
"Initialize the connection, setting the locally known name of the partner
logical unit, the mode name for the conversation, the partner TP name,
the sync level, the security, and the fully-qualified LU name"
connection partnerLUAlias: 'NRI1NC00';
mode: 'LU62APPX';
partnerTPName: 'NEWNAME';
syncLevel: ApConfirm;
security: ApNone;
fqPartnerLUName: 'USIBMNR.NRI1NC00'.
Step 2: Allocating the conversation
By using the AbtAPPCConversation class, your transaction allocates the conversation using the connection defined in step 1.
| conversation |
"Instantiate the conversation"
conversation := AbtAPPCConversation new.
"Allocate the conversation using the connection instance obtained in
step 1"
(conversation connectUsing: connection)isCommunicationsError
ifTrue: [ ^Transcript show: 'Error occurred allocating conversation' ].
APPC makes the connection, if possible, and notifies the partner TP of the conversation request. If the partner TP accepts the conversation, the conversation goes into send state and the partner goes into receive state. Once the conversation is accepted, all calls can be made using methods available on the AbtAPPCConversation class.
Step 3: Sending data to the partner transaction
With the conversation in send state, the front-end transaction can use one of the sendData methods on the AbtAPPCConversation class. The data from the send call is initially stored in a local buffer, which is flushed when any of the following occurs:
•The buffer is full.
•The TP explicitly requests transmission of the buffer contents.
•A line switch occurs (the sender goes into receive state).
It may occur either when the buffer is full or when the transaction requests transmission of the buffer contents. APPC/MVS sends the data and notifies the receiving partner when the data arrives.
| sendToTP |
"Send data, in the form of a byte array, to the partner transaction program"
sendToTP := conversation sendData: data.
"Send data from the buffer"
sendToTP := conversation sendBuffer: (conversation buffer).
The format of the data depends on the type of conversation. In a basic conversation, the caller formats the data into separate records, specifying the length and data of each record. In a mapped conversation, the caller provides the data and lets APPC format it. The front-end and back-end transactions need to agree in advance on which type of conversation they will use.
Step 4: Receiving data from the partner transaction
When the front-end transaction is prepared to receive data from the back-end transaction, you can use the receive methods of the AbtAPPCConversation class. You can use the receiveAndWait methods to wait for inbound data to arrive or use the receiveImmediate methods to receive any data that is available without waiting.
| receiveData |
"Receive data when provided by the back-end transaction"
receiveData := conversation receiveAndWaitDataComplete.
"Check outcome of receiveData"
A transaction program in send state can use the prepareToReceive:locks: or receiveAndWait method to put itself in receive state and put its partner transaction in send state.
Step 5: Ending the conversation
When a TP is finished communicating with its partner, it should end the conversation using either the deallocate: or disconnect method of the AbtAPPCConversation class.
"End conversation with the partner transaction"
conversation disconnect.
The partner receives the deallocation indicator and any remaining data from the buffer. The partner goes into reset state and typically finishes its own processing.