Session mode allows a client to run a number of transactions using the same bridge facility. It is more efficient than running each of these transaction in single transaction mode. Session mode supports the following operations:
Before sending each message:
To allocate a bridge facility, your client program must set the value of the BRIH_TRANSACTIONID field of the bridge message header (BRIH) to BRIHT-ALLOCATE-FACILITY. See Link3270 message header (BRIH) for a description of the BRIH. The following parameters may also be optionally defined:
Other fields in the message are ignored.
For example, to allocate a bridge facility using the supplied default BRIH and constants:
Working-Storage Section
...
copy dfhbrico.
...
Linkage Section
01 msg-area
copy DFHBRIHO.
...
Procedure Division.
...
move brih-default to msg-area.
set briht-allocate-facility to true.
EXEC CICS LINK PROGRAM('DFHL3270) COMMAREA(msg-area)
LENGTH(length of brih) DATALENGTH(len)
END-EXEC
...
:
To run transactions in session mode, your client program must supply the name of the user transaction in the BRIH_TRANSACTIONID field of the bridge message header (BRIH), and set BRIH-FACILITY to the value returned by the allocate request. The following parameters may also be optionally defined:
Other fields in the BRIH are ignored.
For example, to run transaction NACT using the supplied default BRIH and constants:
Working-Storage Section
.
.
copy dfhbrico.
.
Linkage Section.
01 msg-area.
copy DFHBRIHO.
03 msg-vectors pic x(2000).
.
Procedure Division
.
move brih-default to msg-area
move 'NACT' to brih-transactionid
move facility to brih-facility
move brih-datalength to len
EXEC CICS LINK PROGRAM('DFHL3270') COMMAREA(msg-area)
LENGTH(length of msg-area) DATALENGTH(len)
END-EXEC
.
.
Your client program must also create BRIV vectors for any input commands. For example:
move briv-receive-map-default to briv-in.
move 'DFH0MNA ' to briv-rm-mapset.
move 'ACCTMNU ' to briv-rm-map.
move '422' to briv-rm-cposn.
move length of acctmnui to briv-rm-data-len.
set address of acctmnui to address of briv-rm-data.
move low-values to acctmnui.
add briv-rm-data-len to briv-input-vector-length.
add briv-input-vector-length to brih-datalength.
A traditionally conversation transaction, making multiple interactions with a terminal, can be run under the Link3270 bridge as a simple 'non-conversational' transaction by providing all the terminal input in multiple BRIV vectors in the Link3270 request message.
Here, the term 'conversational' refers to transactions where there are multiple flows between the client and the user transaction. To enable this conversational interaction, you must set BRIH-CONVERSATIONALTASK to BRIHCT-YES.
If the user transaction encounters a CONVERSE, RECEIVE or RECEIVE MAP and the Link3270 mechanism has not received a BRIV to satisfy the request, and the BRIH allows conversations (BRIH-CONVERSATIONALTASK is set to BRIHCT-YES), a message is returned to the client requesting further data. The value of BRIH-TASKENDSTATUS is set to the value BRIHTES-CONVERSATION, and a request BRIV is the last vector in the message.
The client then responds by sending a further input message containing the required 3270 input data. The client initializes the message to the default BRIH and sets the value of the BRIH-TRANSACTIONID field to BRIHT-CONTINUE-CONVERSATION and BRIH-FACILITY to the value returned on the allocate request. The following parameters may also be optionally defined:
Other fields in the BRIH are ignored.
The client program may also need to create BRIV vectors if appropriate, and it must reply within the time specified in BRIH-GETWAITINTERVAL
A pseudoconversation normally involves a series of transactions, each initiated by the previous transaction, which may also pass some data. The name of the next transaction to be run can be defined by the user transaction in different ways:
Commands 1-4 all cause the bridge mechanism to set the next transaction identifier in the BRIH-NEXTTRANSACTIONID field to be returned to the client in the next response message.
The client responds by sending a run request for the next transaction, with BRIH-TRANSACTIONID set to the value from BRIH-NEXTTRANSACTIONID and BRIH-FACILITY set to the value returned on the allocate request. The following parameters may also be optionally defined:
Other fields in the BRIH are ignored.
When all session activity is complete, the client can delete the bridge facility. To do this, your client program must set the value of the BRIH_TRANSACTIONID field of the BRIH to BRIHT-DELETE-FACILITY, and set BRIH-FACILITY to the value returned by the allocate request. Other fields in the message are ignored.
For example, to delete a bridge facility using the supplied default BRIH and constants:
Working-Storage Section
.
.
copy dfhbrico
.
Linkage Section.
01 msg-area.
copy DFHBRIHO.
.
Procedure Division
.
move brih-default to msg-area
set briht-delete-facility to true
move facility to brih-facility
move brih-datalength to len
EXEC CICS LINK PROGRAM('DFHL3270') COMMAREA(msg-area)
LENGTH(length of brih) DATALENGTH(len)
END-EXEC
.
.
If the bridge facility is not explicitly deleted, it is scheduled for deletion automatically by CICS® if it is unused for the time specified in the BRIH-FACILITYKEEPTIME field, or in the BRMAXKEEPTIME system initialization parameter. The smaller interval is used.
If the output message from the user transaction is larger than the size of the COMMAREA passed on the request, the bridge mechanism returns a BRIH and as many complete BRIV vectors as will fit into the returned COMMAREA. If it is not possible to fit the whole of the outbound message into the COMMAREA, the field BRIH-REMAININGDATALENGTH is set to a non zero value. The client can then issue one or more requests to obtain the rest of the data. To do this, your client program must set the value of the BRIH-TRANSACTIONID field to BRIHT-GET-MORE-MESSAGE, and set BRIH-FACILITY to the value returned by the allocate request. Other fields in the message are ignored.
When further sections of the message are returned, they are always be prefixed by a BRIH. This is so that CICS can return error information. Clients should follow CICS recommendations regarding COMMAREA lengths described in the CICS Application Programming Reference.
If the communications connection fails before a response message is received, the client can reconnect to the same router and request that the message be sent again. To do this, your client program must set the value of the BRIH-TRANSACTIONID field to BRIHT-RESEND-MESSAGE, and set BRIH-FACILITY to the value returned by the allocate request. Other fields in the message are ignored.
If successful, the outbound Link3270 bridge Message will contain as much of the message as can be fitted into the COMMAREA. If either the router or the AOR CICS region has failed, the message returned indicates that the facilitytoken is unknown.
If unsuccessful, the output is the BRIHT-RESEND-MESSAGE message with an appropriate BRIH-RETURNCODE.
At any time, the bridge facility is considered to be in a specific state. Some requests are only valid is the facility is in an appropriate state. If the request is not valid, BRIH-RETURNCODE is set to the value indicated in Table 7.
Possible states are:
The following table will help you to decide when a request is valid, and what the resulting state will be. If a request is invalid, the state does not change:
Request | Not Allocated | Allocated | Conversational | Transaction ended |
---|---|---|---|---|
Allocate Facility | valid ->Allocated | note8 | note8 | note8 |
Run Transaction | valid2 | valid4 | invalid3 | valid4 |
Continue Conversation | invalid1 | invalid5 | valid4 | invalid5 |
Get More Message | invalid1 | invalid6 | valid/invalid7 | valid/invalid7 |
Resend Message | invalid1 | invalid6 | valid ->Conversational | valid ->Transaction ended |
Delete Facility | invalid1 | valid ->Not Allocated | invalid3 | valid ->Not Allocated |
If the facilitytoken expires due to inactivity, any subsequent requests are invalid. BRIH-RETURNCODE is set to BRIHRC-INVALID-FACILITYTOKEN and the resulting state is Not Allocated. Conversational requests may result in loss of data.