MQIIH (IMS information header) on IBM i

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

Overview

Format name: FMIMS.

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

Applications that connect to the queue manager that owns the IMS bridge queue must provide an MQIIH structure that is in the character set and encoding of the queue manager. This is because data conversion of the MQIIH structure is not performed in this case.
Applications that connect to other queue managers can provide an MQIIH structure that is in any of the supported character sets and encodings; conversion of the MQIIH is performed by the receiving message channel agent connected to the queue manager that owns the IMS bridge queue. Note: There is one exception to this. If the queue manager that owns the IMS bridge queue is using CICS® for distributed queuing, the MQIIH must be in the character set and encoding of the queue manager that owns the IMS bridge queue.
The application message data following the MQIIH structure must be in the same character set and encoding as the MQIIH structure. The IICSI and IIENC fields in the MQIIH 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.

Authenticating passtickets for IMS bridge applications
Fields
Initial values
RPG declaration

Authenticating passtickets for IMS bridge applications

It is now possible for IBM MQ administrators to specify the application name to be used for authenticating passtickets, for IMS bridge applications. To do this, the application name is specified as a new attribute PTKTAPPL for the STGCLASS object definition, as a 1 to 8 character alphanumeric string.

A blank value means that authentication occurs as with previous releases of IBM MQ, that is, no application name flows on the authentication request, and the MVSxxxx value to is used instead.

A value of 1 - 8 alphanumeric characters must follow the rules for passticket application names as described in the RACF® publications.

IBM MQ Administrators and RACF administrators must both agree on the valid application names to be used. The RACF administrator must create a profile in the PTKTDATA class giving READ access to the user IDs of all applications that are to be granted access. The IBM MQ administrator must create or alter the required STGCLASS definitions that specify the application name to be used for passticket authentication.

For related information, see the Script (MQSC) Command Reference.

Fields

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

IIAUT (8-byte character string)

RACF password or passticket.

This is optional; if specified, it is used with the user ID in the MQMD security context to build a UTOKEN that is sent to IMS to provide a security context. If it is not specified, the user ID is used without verification. This depends on the setting of the RACF switches, which may require an authenticator to be present.

This is ignored if the first byte is blank or null. The following special value may be used:

IAUNON: No authentication.

The length of this field is given by LNAUTH. The initial value of this field is IAUNON.

IICMT (1-byte character string)

Commit mode.

See the OTMA Reference for more information about IMS commit modes. The value must be one of the following:

ICMCTS: Commit then send.
This mode implies double queuing of output, but shorter region occupancy times. Fast-path and conversational transactions cannot run with this mode.
ICMSTC: Send then commit.

The initial value of this field is ICMCTS.

IICSI (10-digit signed integer)

Reserved.

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

IIENC (10-digit signed integer)

Reserved.

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

IIFLG (10-digit signed integer)

Flags.

The value must be:

IINONE: No flags.

The initial value of this field is IINONE.

IIFMT (8-byte character string)

IBM MQ format name of data that follows MQIIH.

This specifies the IBM MQ format name of the data that follows the MQIIH 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.

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

IILEN (10-digit signed integer)

Length of MQIIH structure.

The value must be:

IILEN1: Length of IMS information header structure.

The initial value of this field is IILEN1.

IILTO (8-byte character string)

Logical terminal override.

This is placed in the IO PCB field. It is optional; if it is not specified the TPIPE name is used. It is ignored if the first byte is blank, or null.

The length of this field is given by LNLTOV. The initial value of this field is 8 blank characters.

IIMMN (8-byte character string)

Message format services map name.

This is placed in the IO PCB field. It is optional. On input it represents the MID, on output it represents the MOD. It is ignored if the first byte is blank or null.

The length of this field is given by LNMFMN. The initial value of this field is 8 blank characters.

IIRFM (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.

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

IIRSV (1-byte character string)

Reserved.

This is a reserved field; it must be blank.

IISEC (1-byte character string)

Security scope.

This indicates the required IMS security processing. The following values are defined:

ISSCHK: Check security scope.
An ACEE is built in the control region, but not in the dependent region.
ISSFUL: Full security scope.
A cached ACEE is built in the control region and a non-cached ACEE is built in the dependent region. If we use ISSFUL, you must ensure that the user ID for which the ACEE is built has access to the resources used in the dependent region.

If ISSCHK and ISSFUL are not specified for this field, ISSCHK is assumed.

The initial value of this field is ISSCHK.

IISID (4-byte character string)

Structure identifier.

The value must be:

IISIDV: Identifier for IMS information header structure.

The initial value of this field is IISIDV.

IITID (16-byte bit string)

Transaction instance identifier.

This field is used by output messages from IMS so is ignored on first input. If IITST is set to ITSIC, this must be provided in the next input, and all subsequent inputs, to enable IMS to correlate the messages to the correct conversation. The following special value may be used:

ITINON: No transaction instance ID.

The length of this field is given by LNTIID. The initial value of this field is ITINON.

IITST (1-byte character string)

Transaction state.

This indicates the IMS conversation state. This is ignored on first input because no conversation exists. On subsequent inputs it indicates whether a conversation is active or not. On output it is set by IMS. The value must be one of the following:

ITSIC: In conversation.
ITSNIC: Not in conversation.
ITSARC: Return transaction state data in architected form.
This value is used only with the IMS /DISPLAY TRAN command. It causes the transaction state data to be returned in the IMS architected form instead of character form. See Writing IMS transaction programs through IBM MQ for further details.

The initial value of this field is ITSNIC.

IIVER (10-digit signed integer)

Structure version number.

The value must be:

IIVER1: Version number for IMS information header structure.

The following constant specifies the version number of the current version:

IIVERC: Current version of IMS information header structure.

The initial value of this field is IIVER1.

Initial values

Table 1. Initial values of fields in MQIIH
Field name	Name of constant	Value of constant
IISID	IISIDV	'IIH¬'
IIVER	IIVER1	1
IILEN	IILEN1	84
IIENC	None	0
IICSI	None	0
IIFMT	FMNONE	Blanks
IIFLG	IINONE	0
IILTO	None	Blanks
IIMMN	None	Blanks
IIRFM	FMNONE	Blanks
IIAUT	IAUNON	Blanks
IITID	ITINON	Nulls
IITST	ITSNIC	'࿢'
IICMT	ICMCTS	'0'
IISEC	ISSCHK	'C'
IIRSV	None	'࿢'

Notes:

The symbol ¬ represents a single blank character.

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D*
     D* MQIIH Structure
     D*
     D* Structure identifier
     D  IISID                  1      4    INZ('IIH ')
     D* Structure version number
     D  IIVER                  5      8I 0 INZ(1)
     D* Length of MQIIH structure
     D  IILEN                  9     12I 0 INZ(84)
     D* Reserved
     D  IIENC                 13     16I 0 INZ(0)
     D* Reserved
     D  IICSI                 17     20I 0 INZ(0)
     D* MQ format name of data that followsMQIIH
     D  IIFMT                 21     28    INZ('        ')
     D* Flags
     D  IIFLG                 29     32I 0 INZ(0)
     D* Logical terminal override
     D  IILTO                 33     40    INZ
     D* Message format services map name
     D  IIMMN                 41     48    INZ
     D* MQ format name of reply message
     D  IIRFM                 49     56    INZ('        ')
     D* RACF password or passticket
     D  IIAUT                 57     64    INZ('        ')
     D* Transaction instance identifier
     D  IITID                 65     80    INZ(X'00000000000000-
     D                                     000000000000000000')
     D* Transaction state
     D  IITST                 81     81    INZ(' ')
     D* Commit mode
     D  IICMT                 82     82    INZ('0')
     D* Security scope
     D  IISEC                 83     83    INZ('C')
     D* Reserved
     D  IIRSV                 84     84    INZ