Last month I spoke generally about CICS' 3270 bridge. In this column I go into more detail on how to use the link interface through the program DFHL3270.
Interacting with DFHL3270
As the name suggests, the 3270 bridge link interface involves an EXEC CICS LINK command to program DFHL3270. In the link command you include a COMMAREA specifying your wishes, which DFHL3270 will return with the results. The COMMAREA consists of a series of vectors. It sounds scary, but it's basically a concatenation of variable length structures. IBM provides layouts of the structures in COBOL, Assembler and C. IBM also helpfully provides another copy book of constants and default values, making it easy to initialize the structures at one go.
One note of caution to Assembler and C programmers: Many bridge structure fields are four bytes long, where one might expect them to be less. An example is the 3270 attention identifier (AID) field. In the bridge vectors it is four bytes long, even though most people are used to dealing with a one-byte AID. In this case and others like it you must take care to pad the value with blanks before inserting it into the vector stream.
It helps to think of each link to DFHL3270 as an interaction with a terminal. In bridge parlance, an input message is bound for the target transaction. DFHL3270 returns the target transaction's output message in the same COMAREA.
You can interact with the target one message at a time or stack them up into one COMMAREA. Then DFHL3270 examines the input message vectors looking for one matching what the target transaction expects. The decision could involve BMS mapping, a 3270 stream or a record to be read with the RETRIEVE command. If DFHL3270 does not find a matching input message it will send back an output message that may include an application data structure descriptor (ADSD), as described in last month's column.
DFHL3270 Communications Area (COMMAREA)
The first structure in the COMMAREA for both input and output messages is the bridge header (BRIH). The BRIH tells DFHL3270, among other things:
- The type of call
- The target transaction's terminal interaction style (e.g. conversational, pseudo-conversational)
- The length of the vectors to follow including BRIHs
- The type of the included input.
Following the BRIH is the bridge input vector (BRIV) header and one of many types of BRIVs. The 16-byte header contains information common to all the BRIV types and indicates in the vector descriptor field the kind of BRIV to follow. The values of the descriptor field actually match the execution interface block (EIB) function code of the command BRIV represents. For example, the descriptor x'1804' denotes a send map input vector. The BRIV also provides a field for specifying the 3270 AID that matches those in IBM's DFHAID copybook. However, as mentioned above, the BRIV field is four bytes long, so be careful to pad the DFHAID value with blanks.
After the BRIV comes the input stream to be received by the target transaction. This is where the bridge has the advantage, for if the receiving transaction uses basic mapping support (BMS), data may be exchanged in the logical map format. You can even tweak the field attribute bytes (e.g. length) to simulate spaces or the erase end of field button. After you build all of this, assuming the proper message lengths are in the right places, your program links to DFHL3270.
Return from DFHL3270
When DFHL3270 returns, you must check BRIH_RETURNCODE to know the high-level results. I say high-level results because BRIH_RETURNCODE will tell you if there were any problems with the bridge or external errors (e.g. ABEND) in the target transaction. It will not tell you anything about a purely application-level problem.
Following the BRIH will be another vector corresponding to the last terminal control command the target transaction issued. Again, you may distinguish the command by the EIBFN function code.
Following the header is the output stream. This is where things might get complicated. First you have to decide if the target transaction issued the command you expected. Second, if DFHL3270 didn't find an input vector matching the target transaction's expectations, it may return an ADSD. Third, everything might have gone well as far as the bridge is concerned, but there was something the target transaction didn't like (e.g. customer record not found). In this case, to ensure everything is going according to plan, you must traipse through the output looking for places where you know error messages may appear.
Using DFHL3270 is not as hard as it looks. For me, the most difficult part of it was getting the vector lengths correct and leaving out contradictory parameters. Next month's column will go into the structure of a program carrying on a 3270 bridge conversation.
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.
