MQCIH (CICS bridge header) on IBM i

The MQCIH structure describes the information that can be present at the start of a message sent to the CICS® bridge through IBM MQ for z/OS®.

Overview

Format name: FMCICS.

Version: The current version of MQCIH is CIVER2. Fields that exist only in the more-recent version of the structure are identified as such in the descriptions that follow.

The COPY file provided contains the most recent version of MQCIH, with the initial value of the CIVER field set to CIVER2.

Character set and encoding: Special conditions apply to the character set and encoding used for the MQCIH structure and application message data:

Applications that connect to the queue manager that owns the CICS bridge queue must provide an MQCIH structure that is in the character set and encoding of the queue manager. This is because data conversion of the MQCIH structure is not performed in this case.
Applications that connect to other queue managers can provide an MQCIH structure that is in any of the supported character sets and encodings; conversion of the MQCIH is performed by the receiving message channel agent connected to the queue manager that owns the CICS bridge queue. Note: There is one exception to this. If the queue manager that owns the CICS bridge queue is using CICS for distributed queuing, the MQCIH must be in the character set and encoding of the queue manager that owns the CICS bridge queue.
The application message data following the MQCIH structure must be in the same character set and encoding as the MQCIH structure. The CICSI and CIENC fields in the MQCIH structure cannot be used to specify the character set and encoding of the application message data.
A data-conversion exit must be provided by the user to convert the application message data if the data is not one of the built-in formats supported by the queue manager.

Usage: If the values required by the application are the same as the initial values shown in Table 2, and the bridge is running with AUTH=LOCAL or AUTH=IDENTIFY, the MQCIH structure can be omitted from the message. In all other cases, the structure must be present.

The bridge accepts either a version-1 or a version-2 MQCIH structure, but for 3270 transactions a version-2 structure must be used.

The application must ensure that fields documented as request fields have appropriate values in the message sent to the bridge; these fields are input to the bridge.

Fields documented as response fields are set by the CICS bridge in the reply message that the bridge sends to the application. Error information is returned in the CIRET, CIFNC, CICC, CIREA, and CIAC fields, but not all of them are set in all cases. Table 1 shows which fields are set for different values of CIRET.

Table 1. Contents of error information fields in MQCIH structure
CIRET	CIFNC	CICC	CIREA	CIAC
CRC000	-	-	-	-
CRC003	-	-	FBC*	-
CRC002 CRC008	IBM MQ call name	IBM MQ CMPCOD	IBM MQ REASON	-
CRC001 CRC006 CRC007 CRC009	CICS EIBFN	CICS EIBRESP	CICS EIBRESP2	-
CRC004 CRC005	-	-	-	CICS ABCODE

Fields
Initial values
RPG declaration

Fields

The MQCIH structure contains the following fields; the fields are described in alphabetical order:

CIAC (4-byte character string)

Abend code.

The value returned in this field is significant only if the CIRET field has the value CRC005 or CRC004. If it does, CIAC contains the CICS ABCODE value.

This is a response field. The length of this field is given by LNABNC. The initial value of this field is 4 blank characters.

This is an indicator specifying whether ADS descriptors should be sent on SEND and RECEIVE BMS requests. The following values are defined:

ADNONE: Do not send or receive ADS descriptor.
ADSEND: Send ADS descriptor.
ADRECV: Receive ADS descriptor.
ADMSGF: Use message format for the ADS descriptor.
This causes the ADS descriptor to be sent or received using the long form of the ADS descriptor. The long form has fields that are aligned on 4-byte boundaries.

The CIADS field should be set as follows:

If ADS descriptors are not being used, set the field to ADNONE.
If ADS descriptors are being used, and with the same CCSID in each environment, set the field to the sum of ADSEND and ADRECV.
If ADS descriptors are being used, but with different CCSIDs in each environment, set the field to the sum of ADSEND, ADRECV, and ADMSGF.

This is a request field used only for 3270 transactions. The initial value of this field is ADNONE.

CIADS (10-digit signed integer)

Send/receive ADS descriptor.

This is an indicator specifying whether ADS descriptors should be sent on SEND and RECEIVE BMS requests. The following values are defined:

ADNONE: Do not send or receive ADS descriptor.
ADSEND: Send ADS descriptor.
ADRECV: Receive ADS descriptor.
ADMSGF: Use message format for the ADS descriptor.
This causes the ADS descriptor to be sent or received using the long form of the ADS descriptor. The long form has fields that are aligned on 4-byte boundaries.

The CIADS field should be set as follows:

If ADS descriptors are not being used, set the field to ADNONE.
If ADS descriptors are being used, and with the same CCSID in each environment, set the field to the sum of ADSEND and ADRECV.
If ADS descriptors are being used, but with different CCSIDs in each environment, set the field to the sum of ADSEND, ADRECV, and ADMSGF.

This is a request field used only for 3270 transactions. The initial value of this field is ADNONE.

CIAI (4-byte character string)

AID key.

This is the initial value of the AID key when the transaction is started. It is a 1-byte value, left-aligned.

This is a request field used only for 3270 transactions. The length of this field is given by LNATID. The initial value of this field is 4 blanks.

CIAUT (8-byte character string)

Password or passticket.

This is a password or passticket. If user-identifier authentication is active for the CICS bridge, CIAUT is used with the user identifier in the MQMD identity context to authenticate the sender of the message.

This is a request field. The length of this field is given by LNAUTH. The initial value of this field is 8 blanks.

CICC (10-digit signed integer)

IBM MQ completion code or CICS EIBRESP.

The value returned in this field is dependent on CIRET ; see Table 1.

This is a response field. The initial value of this field is CCOK.

CICNC (4-byte character string)

Abend transaction code.

This is the abend code to be used to terminate the transaction (normally a conversational transaction that is requesting more data). Otherwise this field is set to blanks.

This is a request field used only for 3270 transactions. The length of this field is given by LNCNCL. The initial value of this field is 4 blanks.

CICP (10-digit signed integer)

Cursor position.

This is the initial cursor position when the transaction is started. Later, for conversational transactions, the cursor position is in the RECEIVE vector.

This is a request field used only for 3270 transactions. The initial value of this field is 0. This field is not present if CIVER is less than CIVER2.

CICSI (10-digit signed integer)

Reserved.

This is a reserved field; its value is not significant. The initial value of this field is 0.

CICT (10-digit signed integer)

Whether task can be conversational.

This is an indicator specifying whether the task should be allowed to issue requests for more information, or should abend. The value must be one of the following:

CTYES: Task is conversational.
CTNO: Task is not conversational.

This is a request field used only for 3270 transactions. The initial value of this field is CTNO.

CIENC (10-digit signed integer)

Reserved.

This is a reserved field; its value is not significant. The initial value of this field is 0.

CIEO (10-digit signed integer)

Offset of error in message.

This is the position of invalid data detected by the bridge exit. This field provides the offset from the start of the message to the location of the invalid data.

This is a response field used only for 3270 transactions. The initial value of this field is 0. This field is not present if CIVER is less than CIVER2.

CIFAC (8-byte bit string)

Bridge facility token.

This is an 8-byte bridge facility token. The purpose of a bridge facility token is to allow multiple transactions in a pseudoconversation to use the same bridge facility (virtual 3270 terminal). In the first, or only, message in a pseudoconversation, a value of FCNONE should be set; this tells CICS to allocate a new bridge facility for this message. A bridge facility token is returned in response messages when a nonzero CIFKT is specified on the input message. Subsequent input messages can then use the same bridge facility token.

The following special value is defined:

FCNONE: No BVT token specified.

This is both a request and a response field used only for 3270 transactions. The length of this field is given by LNFAC. The initial value of this field is FCNONE.

CIFKT (10-digit signed integer)

Bridge facility release time.

This is the length of time in seconds that the bridge facility will be kept after the user transaction has ended. For nonconversational transactions, the value should be zero.

This is a request field used only for 3270 transactions. The initial value of this field is 0.

CIFL (4-byte character string)

Terminal emulated attributes.

This is the name of an installed terminal that is to be used as a model for the bridge facility. A value of blanks means that CIFL is taken from the bridge transaction profile definition, or a default value is used.

This is a request field used only for 3270 transactions. The length of this field is given by LNFACL. The initial value of this field is 4 blanks.

CIFLG (10-digit signed integer)

Flags.

The value must be:

CIFNON: No flags.

This is a request field. The initial value of this field is CIFNON.

CIFMT (8-byte character string)

IBM MQ format name of data that follows MQCIH.

This specifies the IBM MQ format name of the data that follows the MQCIH structure.

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data. The rules for coding this field are the same as those for the MDFMT field in MQMD.

This format name is also used for the reply message, if the CIRFM field has the value FMNONE.

For DPL requests, CIFMT must be the format name of the COMMAREA.
For 3270 requests, CIFMT must be CSQCBDCI, and CIRFM must be CSQCBDCO.

The data-conversion exits for these formats must be installed on the queue manager where they are to run.

If the request message results in the generation of an error reply message, the error reply message has a format name of FMSTR.

This is a request field. The length of this field is given by LNFMT. The initial value of this field is FMNONE.

CIFNC (4-byte character string)

IBM MQ call name or CICS EIBFN function.

The value returned in this field is dependent on CIRET ; see Table 1. The following values are possible when CIFNC contains an IBM MQ call name:

CFCONN: MQCONN call.
CFGET: MQGET call.
CFINQ: MQINQ call.
CFOPEN: MQOPEN call.
CFPUT: MQPUT call.
CFPUT1: MQPUT1 call.
CFNONE: No call.

This is a response field. The length of this field is given by LNFUNC. The initial value of this field is CFNONE.

CIGWI (10-digit signed integer)

Wait interval for MQGET call issued by bridge task.

This field is applicable only when CIUOW has the value CUFRST. It allows the sending application to specify the approximate time in milliseconds that the MQGET calls issued by the bridge should wait for second and subsequent request messages for the unit of work started by this message. This overrides the default wait interval used by the bridge. The following special values may be used:

WIDFLT: Default wait interval.
This causes the CICS bridge to wait for the period specified when the bridge was started.
WIULIM: Unlimited wait interval.

This is a request field. The initial value of this field is WIDFLT.

CIII (10-digit signed integer)

Reserved.

This is a reserved field. The value must be 0. This field is not present if CIVER is less than CIVER2.

CILEN (10-digit signed integer)

Length of MQCIH structure.

The value must be one of the following:

CILEN1: Length of version-1 CICS information header structure.
CILEN2: Length of version-2 CICS information header structure.

The following constant specifies the length of the current version:

CILENC: Length of current version of CICS information header structure.

This is a request field. The initial value of this field is CILEN2.

CILT (10-digit signed integer)

Link type.

This indicates the type of object that the bridge should try to link. The value must be one of the following:

LTPROG: DPL program.
LTTRAN: 3270 transaction.

This is a request field. The initial value of this field is LTPROG.

CINTI (4-byte character string)

Next transaction to attach.

This is the name of the next transaction returned by the user transaction (typically by EXEC CICS RETURN TRANSID). If there is no next transaction, this field is set to blanks.

This is a response field used only for 3270 transactions. The length of this field is given by LNTRID. The initial value of this field is 4 blanks.

CIODL (10-digit signed integer)

Output COMMAREA data length.

This is the length of the user data to be returned to the client in a reply message. This length includes the 8-byte program name. The length of the COMMAREA passed to the linked program is the maximum of this field and the length of the user data in the request message, minus 8.

Note: The length of the user data in a message is the length of the message excluding the MQCIH structure.

If the length of the user data in the request message is smaller than CIODL, the DATALENGTH option of the LINK command is used; this allows the LINK to be function-shipped efficiently to another CICS region.

The following special value can be used:

OLINPT: Output length is same as input length.
This value might be needed even if no reply is requested, in order to ensure that the COMMAREA passed to the linked program is of sufficient size.

This is a request field used only for DPL programs. The initial value of this field OLINPT.

CIREA (10-digit signed integer)

IBM MQ reason or feedback code, or CICS EIBRESP2.

The value returned in this field is dependent on CIRET ; see Table 1.

This is a response field. The initial value of this field is RCNONE.

CIRET (10-digit signed integer)

Return code from bridge.

This is the return code from the CICS bridge describing the outcome of the processing performed by the bridge. The CIFNC, CICC, CIREA, and CIAC fields may contain additional information (see Table 1 ). The value is one of the following:

CRC000: (0, X'000') No error.
CRC001: (1, X'001') EXEC CICS statement detected an error.
CRC002: (2, X'002') IBM MQ call detected an error.
CRC003: (3, X'003') CICS bridge detected an error.
CRC004: (4, X'004') CICS bridge ended abnormally.
CRC005: (5, X'005') Application ended abnormally.
CRC006: (6, X'006') Security error occurred.
CRC007: (7, X'007') Program not available.
CRC008: (8, X'008') Second or later message within current unit of work not received within specified time.
CRC009: (9, X'009') Transaction not available.

This is a response field. The initial value of this field is CRC000.

CIRFM (8-byte character string)

IBM MQ format name of reply message.

This is the IBM MQ format name of the reply message that will be sent in response to the current message. The rules for coding this are the same as those for the MDFMT field in MQMD.

This is a request field used only for DPL programs. The length of this field is given by LNFMT. The initial value of this field is FMNONE.

CIRSI (4-byte character string)

Reserved.

This is a reserved field. The value must be 4 blanks. The length of this field is given by LNRSID.

CIRS1 (8-byte character string)

Reserved.

This is a reserved field. The value must be 8 blanks.

CIRS2 (8-byte character string)

Reserved.

This is a reserved field. The value must be 8 blanks.

CIRS3 (8-byte character string)

Reserved.

This is a reserved field. The value must be 8 blanks.

CIRS4 (10-digit signed integer)

Reserved.

This is a reserved field. The value must be 0. This field is not present if CIVER is less than CIVER2.

CIRTI (4-byte character string)

Reserved.

This is a reserved field. The value must be 4 blanks. The length of this field is given by LNTRID.

CISC (4-byte character string)

Transaction start code.

This is an indicator specifying whether the bridge emulates a terminal transaction or a START transaction. The value must be one of the following:

SCSTRT: Start.
SCDATA: Start data.
SCTERM: Terminate input.
SCNONE: None.

In the response from the bridge, this field is set to the start code appropriate to the next transaction ID contained in the CINTI field. The following start codes are possible in the response:

SCSTRT
SCDATA
SCTERM

For CICS Transaction Server Version 1.2, this field is a request field only; its value in the response is undefined.

For CICS Transaction Server Version 1.3 and subsequent releases, this is both a request and a response field.

This field is used only for 3270 transactions. The length of this field is given by LNSTCO. The initial value of this field is SCNONE.

CISID (4-byte character string)

Structure identifier.

The value must be:

CISIDV: Identifier for CICS information header structure.

This is a request field. The initial value of this field is CISIDV.

CITES (10-digit signed integer)

Status at end of task.

This field shows the status of the user transaction at end of task. One of the following values is returned:

TENOSY: Not synchronized.
The user transaction has not yet completed and has not syncpointed. The MDMT field in MQMD is MTRQST in this case.
TECMIT: Commit unit of work.
The user transaction has not yet completed, but has syncpointed the first unit of work. The MDMT field in MQMD is MTDGRM in this case.
TEBACK: Back out unit of work.
The user transaction has not yet completed. The current unit of work will be backed out. The MDMT field in MQMD is MTDGRM in this case.
TEENDT: End task.
The user transaction has ended (or abended). The MDMT field in MQMD is MTRPLY in this case.

This is a response field used only for 3270 transactions. The initial value of this field is TENOSY.

CITI (4-byte character string)

Transaction to attach.

If CILT has the value LTTRAN, CITI is the transaction identifier of the user transaction to be run; a nonblank value must be specified in this case.

If CILT has the value LTPROG, CITI is the transaction code under which all programs within the unit of work are to be run. If the value specified is blank, the CICS DPL bridge default transaction code (CKBP) is used. If the value is nonblank, it must have been defined to CICS as a local TRANSACTION with an initial program of CSQCBP00. This field is applicable only when CIUOW has the value CUFRST or CUONLY.

This is a request field. The length of this field is given by LNTRID. The initial value of this field is 4 blanks.

CIUOW (10-digit signed integer)

Unit-of-work control.

This controls the unit-of-work processing performed by the CICS bridge. We can request the bridge to run a single transaction, or one or more programs within a unit of work. The field indicates whether the CICS bridge should start a unit of work, perform the requested function within the current unit of work, or end the unit of work by committing it or backing it out. Various combinations are supported, to optimize the data transmission flows.

The value must be one of the following:

CUONLY: Start unit of work, perform function, then commit the unit of work (DPL and 3270).
CUCONT: Additional data for the current unit of work (3270 only).
CUFRST: Start unit of work and perform function (DPL only).
CUMIDL: Perform function within current unit of work (DPL only).
CULAST: Perform function, then commit the unit of work (DPL only).
CUCMIT: Commit the unit of work (DPL only).
CUBACK: Back out the unit of work (DPL only).

This is a request field. The initial value of this field is CUONLY.

CIVER (10-digit signed integer)

Structure version number.

The value must be one of the following:

CIVER1: Version-1 CICS information header structure.
CIVER2: Version-2 CICS information header structure.

Fields that exist only in the more-recent version of the structure are identified as such in the descriptions of the fields. The following constant specifies the version number of the current version:

CIVERC: Current version of CICS information header structure.

This is a request field. The initial value of this field is CIVER2.

Initial values

Table 2. Initial values of fields in MQCIH
Field name	Name of constant	Value of constant
CISID	CISIDV	'CIH¬'
CIVER	CIVER2	2
CILEN	CILEN2	180
CIENC	None	0
CICSI	None	0
CIFMT	FMNONE	Blanks
CIFLG	CIFNON	0
CIRET	CRC000	0
CICC	CCOK	0
CIREA	RCNONE	0
CIUOW	CUONLY	273
CIGWI	WIDFLT	-2
CILT	LTPROG	1
CIODL	OLINPT	-1
CIFKT	None	0
CIADS	ADNONE	0
CICT	CTNO	0
CITES	TENOSY	0
CIFAC	FCNONE	Nulls
CIFNC	CFNONE	Blanks
CIAC	None	Blanks
CIAUT	None	Blanks
CIRS1	None	Blanks
CIRFM	FMNONE	Blanks
CIRSI	None	Blanks
CIRTI	None	Blanks
CITI	None	Blanks
CIFL	None	Blanks
CIAI	None	Blanks
CISC	SCNONE	Blanks
CICNC	None	Blanks
CINTI	None	Blanks
CIRS2	None	Blanks
CIRS3	None	Blanks
CICP	None	0
CIEO	None	0
CIII	None	0
CIRS4	None	0

Notes:

The symbol ¬ represents a single blank character.

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D* MQCIH Structure
     D*
     D* Structure identifier
     D  CISID                  1      4    INZ('CIH ')
     D* Structure version number
     D  CIVER                  5      8I 0 INZ(2)
     D* Length of MQCIH structure
     D  CILEN                  9     12I 0 INZ(180)
     D* Reserved
     D  CIENC                 13     16I 0 INZ(0)
     D* Reserved
     D  CICSI                 17     20I 0 INZ(0)
     D* MQ format name of data that followsMQCIH
     D  CIFMT                 21     28    INZ('        ')
     D* Flags
     D  CIFLG                 29     32I 0 INZ(0)
     D* Return code from bridge
     D  CIRET                 33     36I 0 INZ(0)
     D* MQ completion code or CICSEIBRESP
     D  CICC                  37     40I 0 INZ(0)
     D* MQ reason or feedback code, or CICSEIBRESP2
     D  CIREA                 41     44I 0 INZ(0)
     D* Unit-of-work control
     D  CIUOW                 45     48I 0 INZ(273)
     D* Wait interval for MQGET call issuedby bridge task
     D  CIGWI                 49     52I 0 INZ(-2)
     D* Link type
     D  CILT                  53     56I 0 INZ(1)
     D* Output COMMAREA data length
     D  CIODL                 57     60I 0 INZ(-1)
     D* Bridge facility release time
     D  CIFKT                 61     64I 0 INZ(0)
     D* Send/receive ADS descriptor
     D  CIADS                 65     68I 0 INZ(0)
     D* Whether task can beconversational
     D  CICT                  69     72I 0 INZ(0)
     D* Status at end of task
     D  CITES                 73     76I 0 INZ(0)
     D* Bridge facility token
     D  CIFAC                 77     84    INZ(X'00000000000000-
     D                                     00')
     D* MQ call name or CICS EIBFNfunction
     D  CIFNC                 85     88    INZ('    ')
     D* Abend code
     D  CIAC                  89     92    INZ
     D* Password or passticket
     D  CIAUT                 93    100    INZ
     D* Reserved
     D  CIRS1                101    108    INZ
     D* MQ format name of reply message
     D  CIRFM                109    116    INZ('        ')
     D* Remote CICS system ID to use
     D  CIRSI                117    120    INZ
     D* CICS RTRANSID to use
     D  CIRTI                121    124    INZ
     D* Transaction to attach
     D  CITI                 125    128    INZ
     D* Terminal emulated attributes
     D  CIFL                 129    132    INZ
     D* AID key
     D  CIAI                 133    136    INZ
     D* Transaction start code
     D  CISC                 137    140    INZ('    ')
     D* Abend transaction code
     D  CICNC                141    144    INZ
     D* Next transaction to attach
     D  CINTI                145    148    INZ
     D* Reserved
     D  CIRS2                149    156    INZ
     D* Reserved
     D  CIRS3                157    164    INZ
     D* Cursor position
     D  CICP                 165    168I 0 INZ(0)
     D* Offset of error in message
     D  CIEO                 169    172I 0 INZ(0)
     D* Reserved
     D  CIII                 173    176I 0 INZ(0)
     D* Reserved
     D  CIRS4                177    180I 0 INZ(0)
     D*