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:
MQIIH LLZZ<trancode><data>[LLZZ<data>][LLZZ<data>]
LLZZ<trancode><data> \ [LLZZ<data>][LLZZ<data>]
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 reply message is also built without an MQIIH structure, taking the Format for the MQMD from the MFSMapName of the IMS output.
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.
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 |
|
|
Nonpersistent WebSphere MQ messages |
|
|
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, the following action is taken by WebSphere MQ:
To resend the messages, do one of the following:
If an exception report message is required, the bridge puts it to the reply-to queue with the authority of the originator. If the message cannot be put to the queue, the report message is put to the dead-letter queue with the authority of the bridge. If it cannot be put to the DLQ, it is discarded.
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:
Refer to the IMS/ESA Open Transaction Manager Access Guide for information about IMS-OTMA sense codes.
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:
The MQIIH of a message received from IMS is built as follows:
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.
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.
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.
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.
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.
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.
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.
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.
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:
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
hbdwm |