Overview of 3270 bridge
To discuss the bridge, some definitions are in order.
Server: The transaction to be driven through the bridge
Client: The transaction or program that uses the bridge to drive the server
Facility: What the bridge calls the "fake terminal" that the server transaction interacts with
The bridge comes in two flavors. The older version uses the BREXIT parameter of the START command. BREXIT names a routine to act as a "bridge exit" that interacts with the server transaction. This interaction takes the form of simulated messages over a pretend terminal. If everything works correctly, the server transaction is none the wiser. In the meantime, the client transaction waits to hear back from the bridge exit through a mechanism like a temporary storage (TS) or transient data (TD) queue.
CICS/TS 2.2 introduced the Link3270 mechanism. Instead of using an intermediary bridge exit, the client program links to program DFHL3270, passing a communications area (COMAMREA) expressing its wishes. DFHL3270, in turn, interprets the COMMAREA and manages the server transaction. Usually there is one DFHL3270 link for each message to the client program besides the other types of necessary housekeeping calls.
Note that, although the bridge can talk with symbolic maps, it also supports native 3270 streams. However, this is not recommended unless you're trying to drive a non-BMS transaction.
Preparing to use the 3270 bridge
The bridge doesn't involve a lot of setup, but there are a few interesting system initialization table (SIT) parameters:
|AIBRIDGE||Specifies if you want the bridge to invoke your terminal auto-install exit when creating a new facility.|
|BRMAXKEEPTIME||Number of seconds to keep an idle bridge facility before deletion|
|WEBDELAY||Two values; the first is the number of minutes a web bridge transaction can wait in a terminal read before CICS purges it. The second tells CICS how long to keep a web bridge transaction's state data.|
The bridge also requires the definition of VSAM file DFHBRNSF to track facility use. There are sample IDCAMS statements for defining DFHBRNSF in the CICS External Interfaces Guide. How you define DFHBRNSF depends on your terminal naming space and function shipping, transaction routine and distributed program link (DPL) requirements. Also note that there is no utility for adding records to it. Instead, you should initialize it with one bogus record and let the bridge do the rest.
Last, there are several sample resource definition online (RDO) definitions for the many configurations of DFHBRNSF. Pick the sample based on your own needs.
Talking to the Sever
What makes the bridge easier to use than ordinary screen scraping (such as FEPI) is that data can be exchanged through the symbolic maps spit out by the basic mapping support (BMS) definition macros. Most programmers can easily include the symbolic maps and understand how to populate them, especially in higher-level languages like COBOL and C.
DFHBMSUP can provide the symbolic map utility if you don't have one. Just point it to the load library containing the map's load module and provide the mapset's name as a parameter. Out pops a copy book suitable for inclusion in a program of the same language for which the mapset was originally created. One downside is DFHBMSUP-generated symbolic maps contain imaginative field names such as "FLD00001," meaning you might have to use a little guesswork to flange up the data with the actual screen field. For more information, please see the CICS Operations and Utility Guide.
The bridge refers to the symbolic map as an Application Data Structure (ADS). In addition, with the proper call, the bridge can provide an Application Data Structure Descriptor (ADSD). The ADSD provides a list of map field names (the real ones), lengths, attributes and positions. This is particularly useful if you want to create a generic utility program to interface between a client and server. In short, the logic would look like this:
- Client calls the utility specifying the server transaction and a list of input and output fields.
- The utility starts the transaction and asks the bridge for an ADSD.
- The utility matches the client's requested fields with those in the ADSD. Then the utility can drive the server transaction with the given inputs to provide the requested outputs.
I didn't pay too much attention when IBM presented information about the 3270 bridge because it was usually in the context of accessing "legacy" applications from the Internet. That was of little interest to my shop. However, at the suggestion of IBM Level 2, my dim bulb went off and I realized it could used to drive a transaction for which I don't have the source or file record layouts. My next column will go into more details including my lessons learned from the experience.
ABOUT THE AUTHOR: For 24 years, Robert Crawford has worked off and on as a CICS systems programmer. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.
This was first published in February 2008