Using Link3270 messages

To run transactions using the Link3270 Bridge, a client program does the following:

  1. Creates an inbound message
  2. Links to DFHL3270 with a COMMAREA containing the message
  3. Interprets the result of the outbound message
The inbound message
The inbound message is passed on the LINK, ECI or EXCI call as a COMMAREA. It contains the following data structures:
Bridge message header (BRIH)
A data structure containing parameters to be passed to the Link3270 bridge mechanism, such as the name of the user transaction; the facilitylike template to be used when the bridge facility is created, and the termid to be assigned to the bridge facility.
Bridge message vectors (BRIV)s
Zero or more data structures containing data to be passed to the user transaction containing the data requested by the EXEC CICS command for 3270 terminal input.

For example, if the application issues an EXEC CICS RECEIVE MAP, the inbound message will have the following form:

Table 2. Message structure for the EXEC CICS RECEIVE MAP command
BRIH BRIV-RM ADS

Where ADS is the application data structure expected by the RECEIVE MAP command.

Sample BRIH and BRIV copybooks are supplied, primed with the default values, to simplify programming. You can include these in your program and then change only the specific fields relevant to the request.

The outbound message
The outbound message is passed in the COMMAREA on return from the LINK, ECI or EXCI call. It contains the following data:
Bridge message header (BRIH)
A data structure containing parameters returned by the Link3270 mechanism, such as return and response codes; the actual termid assigned to the bridge facility, and the length of the returned message.
Bridge message vectors (BRIV)s
Zero or more data structures containing the data supplied by the EXEC CICS command for a 3270 terminal output request, or requests for more data, to be passed to the client program.

For example, if the application issues several non-terminal EXEC CICS commands, an EXEC CICS SEND MAP and then an EXEC CICS RETURN, the outbound message will have the following form:Where ADS is the application data structure expected by the SEND MAP command.

Table 3. Message structure for the EXEC CICS SEND MAP command
BRIH BRIV-SM ADS

A more complicated example would be one where the application issues several non-terminal EXEC CICS commands, an EXEC CICS SYNCPOINT, an EXEC CICS SEND CONTROL, an EXEC CICS SEND MAP, and then an EXEC CICS RETURN. In this case the outbound message will have the following form:

Table 4. More complicated message structure
BRIH BRIV-SP BRIV-SC BRIV-SM ADS

Inbound BRIV vectors

One BRIV vector is required containing the data requested by every EXEC CICS command for 3270 terminal input issued by the user transaction. The following commands are supported:

Note:
If the application issues CONVERSE, and there is an inbound converse vector to satisfy this request, then the output from the converse is used to build an output SEND vector.

When the user transaction issues the command, the bridge mechanism searches the inbound message for the first BRIV that matches the command type. For RECEIVE MAP commands it attempts to match the MAPSET and MAP if these have been supplied by the client. RECEIVE MAP vectors are processed in order, and those that do not match the current command are discarded until a match is found. Blank names in the vector match any command.

Where there are several input vectors of different types, the order is not important.

For 'conversational' transactions (see Conversational transactions) when the client is asked for further input, the previous inbound message vectors (except RETRIEVE vectors) are discarded when a new inbound message is received. Note that RETRIEVE vectors can only flow in the first message of the first transaction in a session. See Using Link3270 session mode for an explanation of the session programming mode.

Outbound BRIV vectors

One BRIV vector is created containing the data supplied by every EXEC CICS command for 3270 terminal output issued by the user transaction. This passes to the client all the information and data relating to the command. The following commands are supported:

Notes:
  1. SEND PAGE and PURGE MESSAGE are only available for the Link3270 bridge with extended support. SeeLink3270 bridge basic and extended support for an explanation of the differences between Link3270 bridge basic and extended support.

For 'conversational' transactions (see Conversational transactions), the last BRIV vector can represent an EXEC CICS command that requests more data. This vector is only created if the previous input message did not contain a BRIV to satisfy all the CICS® commands. The following commands are supported:

Link3270 bridge basic and extended support

There are two levels of support for the Link3270 bridge in CICS Transaction Server for z/OS, Version 2 Release 3:

Copybooks and default vectors

To simplify the task of constructing and analyzing Link3270 messages, CICS provides copybooks and header files containing BRIH and BRIV structures. Sample BRIH and input BRIV structures already primed with default values are also supplied, so all you need to do is copy them into your COMMAREA and modify relevant fields. The following default structures are supplied in all supported languages:

You will find the copybooks and headers in the files listed in the tables below. Table 5 shows the basic copybooks. Table 6 shows the extended copybooks.
Table 5. Link3270 message copybooks for basic support
structure COBOL C PLI Assembler
BRIH DFHBRIHO DFHBRIHH DFHBRIHL DFHBRIHD
Inbound BRIVs DFHBRIIO DFHBRIHH DFHBRIHL DFHBRIHD
Outbound BRIVs DFHBRIOO DFHBRIHH DFHBRIHL DFHBRIHD
Defaults and constants DFHBRICO DFHBRICH DFHBRICL DFHBRICD
Table 6. Link3270 message copybooks for extended support
structure COBOL C PLI Assembler
BRIH DFHBR2HO DFHBR2HH DFHBR2HL DFHBR2HD
Inbound BRIVs DFHBR2IO DFHBR2HH DFHBR2HL DFHBR2HD
Outbound BRIVs DFHBR2OO DFHBR2HH DFHBR2HL DFHBR2HD
Defaults and constants DFHBR2CO DFHBR2CH DFHBR2CL DFHBR2CD

Sample client programs are supplied to illustrate the use of the copybooks and defaults. You will find a description of these in Running the sample client programs.

Related concepts
The Link3270 bridge mechanism
Link3270 programming considerations
Related tasks
Establish Link3270 suitability
Using the Link3270 bridge
Writing the Link3270 client
Using Link3270 single transaction mode
Using Link3270 session mode
Calling the Link3270 bridge
Using data conversion with Link3270
Related reference
Link3270 message formats
Link3270 diagnostics
[[ Contents Previous Page | Next Page Index ]]