Using Link3270 session mode

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:

Note:
The USERID must be the same for the whole session and must be specified in every Link3270 request.
Start of change

How to create a message

Before sending each message:

  1. Move the default bridge message header (BRIH) into a message area.
  2. For all messages other than the allocate, set BRIH_FACILITY to the value returned on the allocate.
  3. Modify other parameters of the message as required, as described in the following sections.
End of change

Allocating a bridge facility

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

:

Note:
The BRIH-FACILITYLIKE value supplied by your client program is not validated until the first application transaction is run. It is only when the first application transaction is processed that the AOR region is determined and the facilitylike value can be validated within the selected AOR.

Running transactions

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.   
Note:
When adding a BRIV always remember to increment the BRIH-DATALENGTH

Conversational transactions

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

Note:
If BRIH-CONVERSATIONALTASK is set to BRIHCT-NO, the bridge will abend the user transaction if it issues an input command for which no vector has been supplied.

Pseudoconversational transactions

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:

  1. EXEC CICS RETURN TRANSID
  2. EXEC CICS RETURN TRANSID IMMEDIATE
  3. EXEC CICS START TRANSID TERMID
  4. EXEC CICS SET TERMINAL/NETNAME NEXTTRANSID
  5. Terminal data
Note:
Transactions initiated by START TERMID are not necessarily pseudoconversational. Here we are considering only those transactions initiated by a START to the principal facility (the bridge facility) where the STARTING and STARTED applications are associated in a pseudoconversation. In this case, START TERMID must specify the bridge facility.

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.

Note:
The same bridge facility must be used by all transactions in the pseudoconversation.

Deleting a bridge facility

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.

Delivering large messages

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.

Recovery from connection failure

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.

Notes:
  1. A resend request must be sent before the interval specified in BRIH-FACILITYKEEPTIME on the allocate request has expired. Otherwise, both the bridge facility and the outstanding message are deleted.
  2. You can use the field BRIH-SEQNO to check whether the previous request has worked.

Validity of Link3270 requests

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:

Table 7. Validity of Link3270 requests
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
Notes:
  1. BRIH-RETURNCODE set to BRIHRC-INVALID-FACILITYTOKEN.
  2. This is defined as single transaction mode.
  3. BRIH-RETURNCODE set to BRIHRC-FACILITYTOKEN-IN-USE.
  4. The resulting stated depends on whether the transaction issues further requests for which there is no BRIV. Possible new states are Conversational or Transaction-ended
  5. BRIH-RETURNCODE set to BRIHRC-TRANSACTION-NOT-RUNNING.
  6. BRIH-RETURNCODE set to BRIHRC_NO-DATA.
  7. The resulting state depends on whether there is more data to send ( indicated by BRIH-REMAININGDATALENGTH).
  8. This state is not relevant, as Allocate always creates a new facility.

Expiry of facilitytoken

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.

Related concepts
The Link3270 bridge mechanism
Link3270 programming considerations
Related tasks
Establish Link3270 suitability
Using the Link3270 bridge
Writing the Link3270 client
Using Link3270 messages
Using Link3270 single transaction mode
Calling the Link3270 bridge
Using data conversion with Link3270
Related reference
Link3270 message formats
Link3270 diagnostics
[[ Contents Previous Page | Next Page Index ]]