Link3270 message header (BRIH)

The Link3270 bridge message header prefixes all input and output messages. Some fields are meaningful only on input, and some are meaningful only on output. Some input fields are modified. Table 11 shows the fields that you need to define for input, and Table 12 shows the fields that are relevant in an output message. Inbound BRIH message header describes the values of fields used for input. Outbound BRIH message header describes the values of fields used for output.

Table 11. The BRIH message header on input
Offset
Hex
Type
Len
Name
Default
(0)
STRUCTURE
180
BRIH
(0)
CHARACTER
4
BRIH-STRUCID
BRIH-STRUC-ID
(4)
FULLWORD
4
BRIH-VERSION
BRIH-CURRENT-VERSION
(8)
FULLWORD
4
BRIH-STRUCLENGTH
BRIH-CURRENT-LENGTH
(C)
n/a
36
reserved
(30)
FULLWORD
4
BRIH-GETWAITINTERVAL
BRIHGWI-MAXWAIT
(34)
n/a
4
reserved
(38)
FULLWORD
4
BRIH-DATALENGTH
BRIH-CURRENT-LENGTH
(3C)
FULLWORD
4
BRIH-FACILITYKEEPTIME
BRIHKT-DEFAULT
(40)
FULLWORD
4
BRIH-ADSDESCRIPTOR
BRIHADSD-YES
(44)
FULLWORD
4
BRIH-CONVERSATIONALTASK
BRIHCT-NO
(48)
n/a
4
reserved
(4C)
CHARACTER
8
BRIH-FACILITY
BRIHFACT-NEW
(54)
n/a
40
reserved
(7C)
CHARACTER
4
BRIH-TRANSACTIONID
(80)
CHARACTER
4
BRIH-FACILITYLIKE
BRIHFACL-DEFAULT
(84)
CHARACTER
4
BRIH-ATTENTIONID
DFHENTER
(88)
CHARACTER
4
BRIH-STARTCODE
BRIHSC-TERMINPUT
(8C)
CHARACTER
4
BRIH-CANCELCODE
blanks
(90)
n/a
4
reserved
(94)
CHARACTER
8
BRIH-NETNAME
BRIHNN-DEFAULT
(9C)
CHARACTER
4
BRIH-TERMINAL
BRIHTN-DEFAULT
(A0)
n/a
4
reserved
(A4)
FULLWORD
4
BRIH-CURSORPOSITION
BRIHCP-DEFAULT
(A8)
n/a
12
reserved

Inbound BRIH message header

The following fields are used in an input message. You can supply values in these fields, other fields are ignored on input. A BRIH structure primed with input default values (BRIH-DEFAULT) is supplied in the DFHBRICx copybooks. If a default value is not specified, the field is initialized to nulls.

Fields are valid on all calls, except where indicated. See also Using Link3270 single transaction mode and Using Link3270 session mode.

BRIH-STRUCID
The identifier for the header structure. You must set this to BRIH-STRUC-ID. The default is BRIH-STRUC-ID.
BRIH-VERSION
The version number for the header structure. You must set this to BRIH-CURRENT-VERSION, which is the default. Refer to Link3270 bridge basic and extended support for a description of the different levels of support for the Link3270 bridge for CICS Transaction Server for z/OS, Version 2 Release 3.
BRIH-STRUCLENGTH
The length of the header structure. You must set this to BRIH-CURRENT-LENGTH. The default is BRIH-CURRENT-LENGTH.
BRIH-DATALENGTH
The length of the input message, including the BRIH. The default is BRIH-CURRENT-LENGTH.
BRIH-TRANSACTIONID
The transaction identifier of the user transaction, as defined in the routing region. In session mode, this can also specify the following request values:
BRIHT-ALLOCATE-FACILITY
Allocate a new bridge facility
BRIHT-DELETE-FACILITY
Delete an existing bridge facility
BRIHT-CONTINUE-CONVERSATION
Reply to a conversational request message
BRIHT-GET-MORE-MESSAGE
Obtain the remainder (or next section) of the Link3270 message. This applies if the COMMAREA in the original request was too small to accommodate the output message
BRIHT-RESEND-MESSAGE
Resend the previous saved Link3270 message. This is used if the communications connection is broken in executing the previous request. See Recovery from connection failure for further information.
Note:
A message is not saved if an error occurs before the message starts the user transaction. The BRIH-SEQNO can be used to determine whether a message returned by the RESEND-MESSAGE command is from the last Link3270 request issued, or the previous request.
BRIH-FACILITY
The facilitytoken of the bridge facility. For single transaction mode this must be set to BRIHFACT-NEW. For session mode, on allocation, this is set to BRIHFACT-NEW. For subsequent requests, this must be set to the value returned on the allocate.

The default is BRIHFACT-NEW.

BRIH-FACILITYLIKE
(Single transaction mode and allocation of a bridge facility in session mode)

The name of an installed terminal that is to be used as a model for the bridge facility. If no value is supplied in single-transaction mode, and a FACILITYLIKE value has been specified in the PROFILE definition of the user transaction, this value is used. Otherwise, or if no value is specified in session mode, a CICS-supplied definition, CBRF, is used.

The default BRIHFACL-DEFAULT means that no value is specified.

BRIH-NETNAME
(Single transaction mode and allocation of a bridge facility in session mode)

The NETNAME to be assigned to the bridge facility.

The default value, BRIHNN-DEFAULT, causes CICS® to generate a name. The name is subject to change or rejection by the autoinstall URM whether specified by the user or generated by CICS. The name, as modified, is returned in this field in the response from the Link3270 bridge.

If you are specifying your own BRIH-NETNAME, the valid character set is the same as that for the NETNAME attribute of the CICS TERMINAL definition. See the CICS Resource Definition Guide.

BRIH-TERMINAL
(Single transaction mode and allocation of a bridge facility in session mode)

The TERMID to be assigned to the bridge facility.

The default value, BRIHTN-DEFAULT, causes CICS to generate a name. The name is subject to change or rejection by the autoinstall URM whether specified by the user or generated by CICS. The name, as modified, is returned in this field in the response from the Link3270 bridge.

If you are specifying your own BRIH-TERMINAL, the valid character set is the same as that for the TERMINAL attribute of the CICS TERMINAL definition. See the CICS Resource Definition Guide.

If you plan to specify your own BRIH-TERMINAL and to allow BRIH-NETNAME to default to this, you must use the BRIH-NETNAME character set, which is more restricted.

BRIH-FACILITYKEEPTIME
(Allocation of a bridge facility in session mode)

The length of time that the bridge facility is kept after the user transaction has ended (in seconds). The value used is the smaller of this value, and the value specified in the router region's SIT parameter BRMAXKEEPTIME.

The default is BRIHKT-DEFAULT.

BRIH-CONVERSATIONALTASK
(Run transaction in session mode)

An indicator specifying what the Link3270 bridge should do if the user transaction issues an input command for which no input vector has been provided. Possible values are:

BRIHCT-YES
The Link3270 bridge suspends the transaction and adds a request vector to the end of the output message. The client is expected to send a CONTINUE-CONVERSATION message containing the requested vector.
BRIHCT-NO
The Link3270 bridge abends the user transaction.

The default is BRIHCT-NO.

BRIH-GETWAITINTERVAL
(Run transaction in session mode)

The maximum wait interval for message input (in milliseconds). The value used is the smaller of the BRIH-GETWAITINTERVAL and the RTIMEOUT value for the transaction.

This value is used only when BRIH-CONVERSATIONALTASK is BRIHCT-YES

The default is BRIHGWI-MAXWAIT.

BRIH-CANCELCODE
(Session mode - continue conversation only)

The abend code with which the Link3270 bridge is to terminate a user transaction. This value is meaningful only in CONTINUE-CONVERSATION messages. If it is non-blank, Link3270 l abends the suspended user transaction with an abend code of BRIH-CANCELCODE. It should be used only when the client wants to terminate the transaction rather than supply the requested vector.

BRIH-ADSDESCRIPTOR
(Single transaction mode and run transaction in session mode)

An indicator specifying whether ADS descriptors are sent on outbound SEND MAP and RECEIVE MAP messages. Possible values are:

BRIHADSD-YES
ADS descriptors are sent.
BRIHADSD-NO
ADS descriptors are not sent.

The default is BRIHADSD-YES.

BRIH-ATTENTIONID
(Single transaction mode and run transaction in session mode)

The initial value of the AID key (EIBAID) when the user transaction is started. This is a 1-byte value, left justified. EIBAID is reset after each RECEIVE, RECEIVE, or CONVERSE command from the AID value in the input vector

The default is DFHENTER (The enter key).

BRIH-STARTCODE
(Single transaction mode and first run transaction in a session)

An indicator available to the first transaction in a session to show the type of start that the request is emulating. The value generated depends on whether there is a RETRIEVE vector present in the input. Possible values are:

BRIHSC-START
START command
BRIHSC-TERMINPUT
Terminal input

The default is BRIHSC-TERMINPUT.

BRIH-CURSORPOSITION
(Single transaction mode and run transaction in session mode)

The initial cursor position, EIBCPOSN, when the transaction is started. EIBCPOSN is reset from the value in the input vector after every RECEIVE, RECEIVE MAP or CONVERSE command.

The default is BRIHCP-DEFAULT, the top left of the screen.

Outbound BRIH message header

Table 12. The output BRIH message header
Offset
Hex
Type
Len
Name
(0)
STRUCTURE
180
BRIH
(0)
CHARACTER
4
BRIH-STRUCID
(4)
FULLWORD
4
BRIH-VERSION
(8)
FULLWORD
4
BRIH-STRUCLENGTH
(C)
n/a
20
reserved
(20)
BINARY
4
BRIH-RETURNCODE
(24)
BINARY
4
BRIH-COMPCODE
(28)
BINARY
4
BRIH-REASON
(2C)
n/a
8
reserved
(34)
BINARY
4
BRIH-REMAININGDATALENGTH
(38)
FULLWORD
4
BRIH-DATALENGTH
(3C)
n/a
12
reserved
(48)
FULLWORD
4
BRIH-TASKENDSTATUS
(4C)
CHARACTER
8
BRIH-FACILITY
(54)
CHARACTER
4
BRIH-FUNCTION
(58)
CHARACTER
4
BRIH-ABENDCODE
(5C)
CHARACTER
4
BRIH-SYSID1
(60)
n/a
28
reserved
(7C)
CHARACTER
4
BRIH-TRANSACTIONID
(80)
n/a
16
reserved
(90)
CHARACTER
4
BRIH-NEXTTRANSACTIONID
(94)
CHARACTER
8
BRIH-NETNAME
(9C)
CHARACTER
4
BRIH-TERMINAL
(A0)
FULLWORD
8
BRIH-NEXTTRANIDSOURCE
(A8)
FULLWORD
4
BRIH-ERROROFFSET
(AC)
FULLWORD
4
BRIH-SEQNO
(B0)
n/a
4
reserved
Notes:
  1. BRIH-SYSID is available only for the Link3270 bridge with extended support.

The following fields are returned in an output message. Other fields are not relevant.

BRIH-RETURNCODE
Return code from the Link3270 interface. See BRIH-RETURNCODE values for a list of possible return codes, and their associated BRIH-COMPCODE and BRIH-REASON values.
BRIH-COMPCODE
Additional error information. See BRIH-RETURNCODE values for a list of possible return codes, and their associated BRIH-COMPCODE and BRIH-REASON values.
BRIH-REASON
Additional error information. See BRIH-RETURNCODE values for a list of possible return codes, and their associated BRIH-COMPCODE and BRIH-REASON values.
BRIH-REMAININGDATALENGTH
(Session mode)

The length of the remaining message if the COMMAREA is too small to return the complete outbound message. The remaining message is prefixed by another BRIH (included in the length). If there is no more data , this field is set to zero. See Delivering large messages for information about processing large messages.

BRIH-DATALENGTH
The length of the output message, including the BRIH.
BRIH-TASKENDSTATUS
The status of the user transaction. Possible values are:
BRIHTES-CONVERSATION
The user transaction has issued an input command for which no vector has been supplied, and BRIH-CONVERSATIONALTASK was specified in the inbound BRIH header.
BRIHTES-ENDTASK
The user transaction has ended (or abended).
BRIH-FACILITY
This value identifies the session. It is set on return from an allocate request and must be supplied on every subsequent request in the session. On return from a delete-facility request or a run request in single-transaction mode, it is reset to BRIHFACT-NEW.
BRIH-FUNCTION
Additional error information returned for some return codes. See BRIH-RETURNCODE values for details.
BRIH-ABENDCODE
The abend code returned if the transaction abends. If the transaction completed successfully, this is set to BRIHAC-NONE.

Transaction abends are indicated by the return code BRIHAC-APPLICATION-ABEND. See BRIH-RETURNCODE values for details.

BRIH-SYSID
The region in which the transaction ran. This is the system ID of the AOR as it is known by the routing region. If the transaction ran in the routing region, this field is set to blanks. This field is available only for the Link3270 bridge with extended support. See Link3270 bridge basic and extended support for a description of the different levels of support for the Link3270 bridge.
BRIH-TRANSACTIONID
BRIH-TRANSACTIONID is both an input and an output field. Normally the output value is the same as the input value. The exceptions to this are:
  1. When the request is for message recovery and the input BRIH-TRANSACTIONID is set to BRIHT-RESEND-MESSAGE. See Recovery from connection failure for further information.
  2. When the router region resource definition of the transaction is an alias of the definition in the AOR, the transaction id in the AOR is returned.
BRIH-NEXTTRANSACTIONID
The name of the next transaction returned by the user transaction (usually by EXEC CICS RETURN TRANSID). If there is no next transaction, this field is set to blanks.
BRIH-NETNAME
(Allocation only)

The NETNAME assigned to the bridge facility.

BRIH-TERMINAL
(Allocation only)

The TERMID assigned to the bridge facility.

BRIH-NEXTTRANIDSOURCE
The source of the next transaction id. Possible values are:
BRIHNTS-NORMAL
Created by the TRANSID option of an EXEC CICS RETURN command, or by SET TERMINAL NEXTTRANSID.
BRIHNTS-IMMEDIATE
Created by the TRANSID option of an EXEC CICS RETURN IMMEDIATE command.
BRIHNTS-STARTED
Created by the TRANSID option of an EXEC CICS START command.
BRIH-ERROROFFSET
The offset from the start of the message to the location of the invalid data for message validation errors.
BRIH-SEQNO
(Session mode only)

A sequence number returned on every message. The sequence number is set to 0 on an allocate facility request and incremented on subsequent requests. The exceptions to this are:

  1. A successful BRIHT-RESEND-MESSAGE request returns the previous message and its sequence number.
  2. If BRIHRC-INVALID-FACILITY-TOKEN is returned, the sequence number is undefined.

Related concepts
The Link3270 bridge mechanism
Related tasks
Using the Link3270 bridge
Writing the Link3270 client
Related reference
Link3270 message formats
Inbound Link3270 vectors
Outbound Link3270 vectors
The application data structure (ADS)
Link3270 diagnostics
[[ Contents Previous Page | Next Page Index ]]