How the WebSphere MQ-IMS bridge deals with messages

When you use the WebSphere(R) MQ-IMS bridge to send messages to an IMS(TM) application, you need to construct your messages in a special format. You must also put your messages on WebSphere MQ queues that have been defined with a storage class that specifies the XCF group and member name of the target IMS system. These are known as MQ-IMS bridge queues, or simply bridge queues.

A user does not need to sign on to IMS before sending messages to an IMS application. The user ID in the UserIdentifier field of the MQMD structure is used for security checking. The level of checking is determined when WebSphere MQ connects to IMS, and is described in the security section of the WebSphere MQ for z/OS System Setup Guide. This enables a pseudo signon to be implemented.

The WebSphere MQ-IMS bridge accepts the following types of message:

WebSphere MQ validates the message data to ensure that the sum of the LL bytes plus the length of the MQIIH (if it is present) is equal to the message length.

When the WebSphere MQ-IMS bridge gets messages from the bridge queues, it processes them as follows:

The WebSphere MQ-IMS bridge uses one or two Tpipes for each WebSphere MQ queue:

The Tpipes are created by WebSphere MQ when they are first used. A non-synchronized Tpipe exists until IMS is restarted. Synchronized Tpipes exist until IMS is cold started. You cannot delete these Tpipes yourself.

Mapping WebSphere MQ messages to IMS transaction types

Table 13. Mapping WebSphere MQ messages to IMS transaction types
WebSphere MQ message type Commit-then-send (mode 0) - uses synchronized IMS Tpipes Send-then-commit (mode 1) - uses non-synchronized IMS Tpipes
Persistent WebSphere MQ messages
  • Recoverable full function transactions
  • Irrecoverable transactions are rejected by IMS
  • Fastpath transactions
  • Conversational transactions
  • Full function transactions
Nonpersistent WebSphere MQ messages
  • Irrecoverable full function transactions
  • Recoverable transactions are rejected by IMS
  • Fastpath transactions
  • Conversational transactions
  • Full function transactions
Note:
IMS commands cannot use persistent WebSphere MQ messages with commit mode 0. See the IMS/ESA Open Transaction Manager Access User's Guide for more information.

If the message cannot be put to the IMS queue

If the message cannot be put to the IMS queue, the following action is taken by WebSphere MQ:

IMS bridge feedback codes

IMS sense codes are normally output in hexadecimal format in WebSphere MQ console messages such as CSQ2001I (for example, sense code 001A). WebSphere MQ feedback codes as seen in the dead-letter header of messages put to the dead-letter queue are decimal numbers.

The IMS bridge feedback codes are in the range 301 through 399. They are mapped from the IMS-OTMA sense codes as follows:

  1. The IMS-OTMA sense code is converted from a hexadecimal number to a decimal number.
  2. 300 is added to the number resulting from the calculation in 1, giving the WebSphere MQ Feedback code.

Refer to the IMS/ESA Open Transaction Manager Access Guide for information about IMS-OTMA sense codes.

The MQMD fields in messages from the IMS bridge

The MQMD of the originating message is carried by IMS in the User Data section of the OTMA headers. If the message originates in IMS, this is built by the IMS Destination Resolution Exit. The MQMD of a message received from IMS is built as follows:

StrucID
"MD  "
Version
MQMD_VERSION_1
Report
MQRO_NONE
MsgType
MQMT_REPLY
Expiry
MQWI_UNLIMITED
Feedback
MQFB_NONE
Encoding
MQENC.Native (the encoding of the z/OS(TM) system)
CodedCharSetId
MQCCSI_Q_MGR (the CodedCharSetID of the z/OS system)
Format
MQFMT_IMS if the MQMD.Format of the input message is MQFMT_IMS, otherwise IOPCB.MODNAME
Priority
MQMD.Priority of the input message
Persistence
Depends on commit mode: MQMD.Persistence of the input message if CM-1; persistence matches recoverability of the IMS message if CM-0
MsgId
MQMD.MsgId if MQRO_PASS_MSG_ID, otherwise New MsgId (the default)
CorrelId
MQMD.CorrelId from the input message if MQRO_PASS_CORREL_ID, otherwise MQMD.MsgId from the input message (the default)
BackoutCount
0
ReplyToQ
Blanks
ReplyToQMgr
Blanks (set to local qmgr name by the queue manager during the MQPUT)
UserIdentifier
MQMD.UserIdentifier of the input message
AccountingToken
MQMD.AccountingToken of the input message
ApplIdentityData
MQMD.ApplIdentityData of the input message
PutApplType
MQAT_XCF if no error, otherwise MQAT_BRIDGE
PutApplName
<XCFgroupName><XCFmemberName> if no error, otherwise QMGR name
PutDate
Date when message was put
PutTime
Time when message was put
ApplOriginData
Blanks

The MQIIH fields in messages from the IMS bridge

The MQIIH of a message received from IMS is built as follows:

StrucId
"IIH "
Version
1
StrucLength
84
Encoding
MQENC_NATIVE
CodedCharSetId
MQCCSI_Q_MGR
Format
MQIIH.ReplyToFormat of the input message if MQIIH.ReplyToFormat is not blank, otherwise IOPCB.MODNAME
Flags
0
LTermOverride
LTERM name (Tpipe) from OTMA header
MFSMapName
Map name from OTMA header
ReplyToFormat
Blanks
Authenticator
MQIIH.Authenticator of the input message if the reply message is being put to an MQ-IMS bridge queue, otherwise blanks.
TranInstanceId
Conversation ID / Server Token from OTMA header if in conversation, otherwise nulls
TranState
"C" if in conversation, otherwise blank
CommitMode
Commit mode from OTMA header ("0" or "1")
SecurityScope
Blank
Reserved
Blank

Reply messages from IMS

When an IMS transaction ISRTs to its IOPCB, the message is routed back to the originating LTERM or TPIPE. These are seen in WebSphere MQ as reply messages. Reply messages from IMS are put onto the reply-to queue specified in the original message. If the message cannot be put onto the reply-to queue, it is put onto the dead-letter queue using the authority of the bridge. If the message cannot be put onto the dead-letter queue, a negative acknowledgement is sent to IMS to say that the message cannot be received. Responsibility for the message is then returned to IMS. If you are using commit mode 0, messages from that Tpipe are not sent to the bridge, and remain on the IMS queue; that is, no further messages are sent until restart. If you are using commit mode 1, other work can continue.

If the reply has an MQIIH structure, its format type is MQFMT_IMS; if not, its format type is specified by the IMS MOD name used when inserting the message.

Using alternate response PCBs in IMS transactions

When an IMS transaction uses alternate response PCBs (ISRTs to the ALTPCB, or issues a CHNG call to a modifiable PCB), the pre-routing exit (DFSYPRX0) is invoked to determine if the message should be rerouted. If the message is to be rerouted, the destination resolution exit (DFSYDRU0) is invoked to confirm the destination and prepare the header information See the WebSphere MQ for z/OS System Setup Guide for information about these exit programs.

Unless action is taken in the exits, all output from IMS transactions initiated from a WebSphere MQ queue manager, whether to the IOPCB or to an ALTPCB, will be returned to the same queue manager.

Sending unsolicited messages from IMS

To send messages from IMS to a WebSphere MQ queue, you need to invoke an IMS transaction that ISRTs to an ALTPCB. You need to write pre-routing and destination resolution exits to route unsolicited messages from IMS and build the OTMA user data, so that the MQMD of the message can be built correctly. See the WebSphere MQ for z/OS System Setup Guide for information about these exit programs.

Note:
The WebSphere MQ-IMS bridge does not know whether a message that it receives is a reply or an unsolicited message. It handles the message the same way in each case, building the MQMD and MQIIH of the reply based on the OTMA UserData that arrived with the message

Unsolicited messages can create new Tpipes. For example, if an existing IMS transaction switched to a new LTERM (for example PRINT01), but the implementation requires that the output be delivered through OTMA, a new Tpipe (called PRINT01 in this example) is created. By default, this is a non-synchronized Tpipe. If the implementation requires the message to be recoverable, set the destination resolution exit output flag. See the IMS Customization Guide for more information.

Message segmentation

You can define IMS transactions as expecting single- or multi-segment input. The originating WebSphere MQ application must construct the user input following the MQIIH structure as one or more LLZZ-data segments. All segments of an IMS message must be contained in a single WebSphere MQ message sent with a single MQPUT.

The maximum length of an LLZZ-data segment is defined by IMS/OTMA (32764 bytes). The total WebSphere MQ message length is the sum of the LL bytes, plus the length of the MQIIH structure.

All the segments of the reply are contained in a single WebSphere MQ message.

There is a further restriction on the 32 KB limitation on messages with format MQFMT_IMS_VAR_STRING. When the data in an ASCII-mixed CCSID message is converted to an EBCDIC-mixed CCSID message, a shift-in byte or a shift-out byte is added every time that there is a transition between SBCS and DBCS characters. The 32 KB restriction applies to the maximum size of the message. That is, because the LL field in the message cannot exceed 32 KB, the message must not exceed 32 KB including all shift-in and shift-out characters. The application building the message must allow for this.

Data conversion

The data conversion (including calling any necessary exits) is performed by the distributed queuing facility when it puts a message to a destination queue that has XCF information defined for its storage class. Any exits needed must be available to the distributed queuing facility in the data set referenced by the CSQXLIB DD statement. This means that you can send messages to an IMS application using the WebSphere MQ-IMS bridge from any WebSphere MQ platform.

Note:
Because the WebSphere MQ-IMS bridge does not convert messages when it gets a message, messages arriving through the CICS(R) distributed queuing facility are not converted.

If there are conversion errors, the message is put to the queue unconverted; this results eventually in it being treated as an error by the WebSphere MQ-IMS bridge, because the bridge cannot recognize the header format. If a conversion error occurs, an error message is sent to the z/OS console.

See Writing data-conversion exits for detailed information about data conversion in general.

Sending messages to the WebSphere MQ-IMS bridge

To ensure that conversion is performed correctly, you must tell the queue manager what the format of the message is. If the message has an MQIIH structure, the Format in the MQMD must be set to the built-in format MQFMT_IMS, and the Format in the MQIIH must be set to the name of the format that describes your message data. If there is no MQIIH, set the Format in the MQMD to your format name.

If your data (other than the LLZZs) is all character data (MQCHAR), use as your format name (in the MQIIH or MQMD, as appropriate) the built-in format MQFMT_IMS_VAR_STRING. Otherwise, use your own format name, in which case you must also provide a data-conversion exit for your format. The exit must handle the conversion of the LLZZs in your message, in addition to the data itself (but it does not have to handle any MQIIH at the start of the message).

If your application uses MFSMapName, you are recommended to use messages with the MQFMT_IMS instead, and define the map name passed to the IMS transaction in the MFSMapName field of the MQIIH.

Receiving messages from the WebSphere MQ-IMS bridge

If an MQIIH structure is present on the original message that you are sending to IMS, one is also present on the reply message.

To ensure that your reply is converted correctly: