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:
  • Allocating a bridge facility
  • Running transactions
  • Deleting a bridge facility
  • Delivering large messages
  • Recovery in the event of communications failure
Note: The USERID must be the same for the whole session and must be specified in every Link3270 request.

Procedure

  • Create a message

    Before sending each message, you must perform these steps:

    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.
  • Allocate 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 Inbound Link3270 message header (BRIH) and Outbound Link3270 message header (BRIH) for a description of the BRIH. The following parameters may also be optionally defined, but other fields in the message are ignored.
    • BRIH-FACILITYKEEPTIME
    • BRIH-FACILITYLIKE
    • BRIH-TERMINAL
    • BRIH-NETNAME
    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.
    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
...
  • Run transactions in session mode

    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. For details, see Conversational 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. For details, see Pseudoconversational transactions.

    1. 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, but other fields in the BRIH are ignored.
      • BRIH-DATALENGTH
      • BRIH-CONVERSATIONALTASK
      • BRIH-GETWAITINTERVAL
      • BRIH-ADSDESCRIPTOR
      • BRIH-ATTENTIONID
      • BRIH-STARTCODE
      • BRIH-CURSORPOSITION
      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..
    2. Your client program must also create BRIV vectors for any input commands.
      Note: When adding a BRIV, always remember to increment the BRIH-DATALENGTH.
      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.
  • Delete 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.

    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.

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

    This is so that CICS can return error information. Clients should follow CICS recommendations regarding COMMAREA lengths described in Translation considerations: LENGTH options in EXEC CICS commands.

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

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