I have been writing about the 3270 bridge and going into details about how it works (Mainframe applications never die: Using the 3270 bridge, and CICS 3270 bridge tutorial, Part 2: Using DFHL3270). This month, I want to put it all together and take a brief walk through a client program's logic to show how the pieces fit together.
Program Overview
To make this as useful and thorough as possible, I will go through the calls to the link 3270 bridge (DFHL3270). This particular example interacts with a pseudo-conversational BMS transaction. Each explanatory step ends with an implied EXEC CICS LINK to bridge program DFHL3270. The LINK command should use both the DATALENGTH and LENGTH parameters. DATALENGTH denotes the size of the input data while LENGTH specifies to the total COMMAERA size. A program may have to call DFHL3270 multiple times if the output message from the target transaction is too large for a single COMMAREA.
Also remember a client program must maintain two levels of fault tolerance: one for the DFHL3270 environment, and one for the target application. Because DFHL3270's errors aren't likely to change, they are a bit easier to manage. The bridge also uses several fields to show, for example, if the target transaction ABEND'ed. The second level of error processing involves watching the driven application and making sure it responds as desired.
Last, I'll use the Assembler names for the structures, labels and fields. The names may be different for COBOL or C programs.
Allocate
Using the bridge always begins with a fairly simple ALLOCATE command. As mentioned before, a facility is a fake terminal provided by the 3270 Bridge for the target transaction to talk to. Note that there is no explicit allocate flag. Instead, you specify a special transaction ID (constant BRIHT_ALLOCATE_FACILITY which resolves to "CBRA") into BRIH field BRIH_TRANSACTIONID.
You may specify a facility name or let the bridge pick one for you. In either case, VSAM file DFHBRNSF must be available to CICS. If you specify a facility, the bridge will look for it in this file. If you let the bridge pick a name it will add it to DFHBRNSF. The decision for sharing DFHBRNSF comes down to avoiding name conflicts should you use a target transaction participating in transaction routing.
If you let the bridge pick a facility, be sure to save its name when the allocate call returns. You'll need it for each link afterwards.
Starting the Conversation
My example program starts the target transaction from a clear screen. The structures for this interaction are fairly simple. First it must put this information into the BRIH:
- The target transaction ID (BRIH_TRANSACTIONID)
- An attention identifier (AID) key of "enter" (BRIH_ATTENTIONID)
- The facility name gotten through the allocate command (BRIH_FACILITY)
- Indicate an application data structure is not included (Clear BRIH_ADSDESCRIPTOR to low values)
- Pseudo conversational task flag (Move flag BRIHCT_YES into field BRIH_CONVERSATIONALTASK)
The input DATALENGTH is just the BRIH length.
The Conversation
At this point the bridge starts the target transaction, intercepts terminal I/O and returns the results to the client program in an outbound (from the target's point of view) bridge message vector (BRIV). The BRIV header contains a type field matching the CICS command code. In this example it will be a SEND MAP (x'1804').
Work from here on out requires intimate knowledge of the target transaction's behavior. This example opens an options panel by moving the PF9 AID value into the BRIH. Note that an Application Data Structure (ADS) may or may not be necessary depending on if the target transaction wants more information.
After opening the options panel the client populates some fields. This operation will require an ADS with the layout of the target transaction's logical map. The client program must also fill in BRIV fields listing the map it formatted the data for. Lastly, the client will insert the ENTER AID for the target to process.
These may be some of the BRIV fields in use:
- BRIV_RM_MAPSET -- Mapset name
- BRIV_RM_MAP -- Map name
- BRIH_ADSDESCRIPTOR set to a non-zero value to indicate ADM presence
- BRIV_RM_DATA_LEN -- Input data length
Following the BRIV is the input message's symbolic map as an ADS. Again, the messages to and from DFHL3270 are a stream of concatenated structures. Therefore, a client must take care to ensure all the length fields for the individual structures are correct and present or else they might be missed.
The End
The conversation ends with a bridge deallocate facility command. Like the allocate command, there is no specific command type. Instead the client program passes special transaction code BRIH_DELETE_FACILITY (CBRD).
As stated (three months) ago, the CICS 3270 bridge was originally presented as a way to reuse 3270 transactions for the web but has shown itself useful for more mundane automation. While DFHL3270 isn't difficult to use it requires precise and sometimes tedious programming. Therefore, if your shop is going to make extensive use of the bridge I would recommend either developing a generic client utility or purchasing one available on the market. I would also recommend you make good use of the examples provided by IBM.
