From 3270 legacy to 3270 bridge

From 3270 legacy to 3270 bridge - an example

This Section illustrates the differences in the data flows that take place when a CICS 3270 transaction interacts with a 3270 terminal, and a CICS bridge application.

In this example, the transaction has an identifier of BAAA. It uses BMS maps, which allow the transaction to be adapted easily to run under the CICS bridge.

In the legacy environment, the transaction is started by entering its name at the CICS 3270 terminal and pressing ENTER. Logic in the transaction causes it to issue EXEC CICS SEND MAP the first time it is invoked in a pseudoconversation, and then to terminate by issuing EXEC CICS RETURN TRANSID(BAAA).

The user enters values into fields in the map that is displayed at the terminal, and then presses an AID key. Logic in the transaction the second time it is invoked causes it to issue EXEC CICS RECEIVE MAP to receive the map. It updates certain fields in the map by changing values in its own application data structure, and then issues EXEC CICS SEND MAP to re-display the map at the user's terminal.

The user can then update fields in the re-displayed map, and start the RECEIVE MAP - SEND MAP cycle again. The logic can be illustrated like this (where EC represent EXEC CICS):

Terminal user                                       3270 Transaction
BAAA <ENTER>           ------------------->         <Initial start>
                                                    <business logic>
                     <-------------------          EC SEND MAP FROM(ads)
                                                    EC RETURN TRANSID(BAAA)
 
Update fields 
<ENTER>                ------------------->         EC RECEIVE MAP INTO(ads)
                                                    <business logic>
                      <-------------------          EC SEND MAP
                                                    EC RETURN TRANSID(BAAA)
Update fields
<ENTER>                ------------------->         EC RECEIVE MAP
                                                   
·
·
·

When the transaction runs in the bridge environment, the physical terminal is replaced by an application. The logic of the 3270 transaction is unchanged, and the application data that it receives is the same, but the data that flows, and the means by which it is transmitted, are different. Instead of a 3270 data stream, a WebSphere MQ message is used that contains an MQCIH structure (a CICS Information Header), a bridge vector structure, and optionally a representation of the application data structure.

Inclusion of these objects in the message depends on the direction in which the message flows (inbound to the bridge or outbound from the bridge), the sequence of the message in the exchange, and whether an application data structure descriptor has been requested by setting the appropriate value in a field in the MQCIH.

The section Exact emulation - no optimization shows the flows that take place when the above scheme is emulated exactly. There is scope for optimization by including more than one vector in inbound messages, as shown in the section Improved emulation, with optimization.

It is assumed that MQCIH.ADSDescriptor is set to

MQCADSD_SEND + MQCADSD_RECV + MQCADSD_MSGFORMAT

so application data structure descriptors in long form are appended to both outbound and inbound application data structures during the exchange of messages.

For clarity, the details of messaging are omitted here. For a description of the queuing model used by the CICS bridge, see WebSphere MQ for z/OS Concepts and Planning Guide.

Exact emulation - no optimization

WebSphere MQ Bridge Application                           3270 Transaction
 
MQPUT to     --MQCIH--------------------------------> <Initial start>     
Bridge                     (Note 1)                   <business logic>   
RequestQ                           
 
MQGET from  <--MQCIH+brmq_send_map+ADS+ADSDL--------  EC SEND MAP FROM(ads)
Bridge                     (Note 2)                   EC RETURN 
ReplyQ                                                   TRANSID(BAAA)
 
MQPUT to     --MQCIH--------------------------------> <Start>     
Bridge                     (Note 3)                     
RequestQ                           
 
MQGET from  <--MQCIH+brmq_receive_map_request+ADSDL-  EC RECEIVE MAP INTO(ads)
Bridge                     (Note 4)                         |
ReplyQ                                                      |
                                                          waits
Updates fields                                              |
                                                            |
MQPUT to     ----MQCIH+brmq_receive_map+ADS--------->       V
Bridge                     (Note 5)
RequestQ
                                                      <business logic>
 
MQGET from  <--MQCIH+brmq_send_map+ADS+ADSDL--------  EC SEND MAP FROM(ads)
Bridge                     (Note 6)                   EC RETURN 
ReplyQ                                                   TRANSID(BAAA) 
                                                      
·
·
·

Notes:

The initial flow from the application contains just an MQCIH. The MQCIH includes control information specifying which transaction is to be started.
The return flow from the 3270 transaction contains an MQCIH, which has important information including a facility token to be used for all subsequent flows, and diagnostic information if an error has occurred. It also contains a SEND MAP vector structure containing control information relating to the map itself, and data that represents the map. If the initiating application has requested it, an application data structure descriptor is also be included.
The bridge application sends a message back containing only an MQCIH. This contains control information to start the transaction once more.
The 3270 transaction issues EC RECEIVE MAP, as it did in the legacy environment. However, in the bridge environment the map data is not immediately available. The call is converted to a message containing an outbound RECEIVE MAP request vector. The application data structure descriptor is also included in the message. In this example, the transaction waits while the message is turned around by the bridge application. The model here is a little different to that in the legacy environment. Note, however, that the bridge architecture allows messages to contain more than one vector, so a number of requests could be satisfied by a single inbound message.
Having updated any fields it needs to in the application data structure, the bridge application sends an inbound RECEIVE MAP reply vector to satisfy the outbound request.
The 3270 transaction issues EC SEND MAP, which converts to a SEND MAP vector, and the cycle repeats.

If you examine the flows that are captured when such a transaction is run using the Passthrough tool (CICS SupportPac CA1E "CICS 3270 Bridge Passthrough"), you will be able to identify the structures with the help of the available online documentation.

Improved emulation, with optimization

WebSphere MQ Bridge Application                           3270 Transaction
 
MQPUT to     --MQCIH--------------------------------> <Initial start>     
Bridge                                                <business logic>   
RequestQ                           
 
MQGET from  <--MQCIH+brmq_send_map+ADS+ADSDL---------  EC SEND MAP FROM(ads)
Bridge                                                EC RETURN 
ReplyQ                                                   TRANSID(BAAA)
                                                             
MQPUT to     ----MQCIH+brmq_receive_map+ADS---------> <Start>
Bridge                                                  
RequestQ                                             EC RECEIVE MAP INTO(ads)
                                                      <business logic>
 
MQGET from  <--MQCIH+brmq_send_map+ADS+ADSDL---------  EC SEND MAP FROM(ads)
Bridge                                                EC RETURN 
ReplyQ                                                   TRANSID(BAAA) 
                                                      
·
·
·

If you compare this sequence with the un-optimized flows shown at the section Exact emulation - no optimization, you can see that the CICS transaction does not have to send a RECEIVE MAP request vector, because the inbound RECEIVE MAP vector has already anticipated the requirement and the inbound map is already available to the transaction.