This section discusses writing applications to exploit the WebSphere MQ-IMS bridge. The following topics are discussed:
For information about the WebSphere MQ-IMS bridge, see WebSphere MQ for z/OS Concepts and Planning Guide.
When you use the WebSphere MQ-IMS bridge to send messages to an IMS 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 WebSphere MQ for z/OS System Setup Guide. This enables a pseudo sign-on to be implemented.
The WebSphere MQ-IMS bridge accepts the following types of message:
MQIIH LLZZ<trancode><data>[LLZZ<data>][LLZZ<data>]
Notes:
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.
Table 15. 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 |
|
|
| Nonpersistent WebSphere MQ messages |
|
|
| ||
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 re-routed. If the message is to be re-routed, the Destination Resolution Exit (DFSYDRU0) is invoked to confim the destination and prepare the header information See 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 required that the output be delivered through OTMA; a new Tpipe (called PRINT01 in this example) would be created. By default this will be a non-synchronized Tpipe. If the implementation requires the message to be recoverable the destination resolution exit Output flag must be set. See the IMS Customization Guide for more information.
IMS transactions may be defined 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 any one 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 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 the calling of 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 Chapter 11, 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 makes use of 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 your reply is converted correctly, follow these steps:
The coding required to handle IMS transactions through WebSphere MQ is dependent on the message format required by the IMS transaction and the range of responses it may return. However, there are several points to be borne in mind when your application handles IMS screen formatting information.
When an IMS transaction is started from a 3270 screen, the message passes through IMS Message Format Services. This can remove all terminal dependency from the data stream seen by the transaction. When a transaction is started through OTMA, MFS is not involved. If application logic is implemented in MFS, this will have to be recreated in the new application.
In some IMS transactions, the end-user application can modify certain 3270 screen behavior, for example, highlighting a field which has had invalid data entered. This type of information is communicated by adding a two byte attribute field to the IMS message for each screen field needing to be modified by the program.
Thus, if you are coding an application to mimic a 3270, you need to take account of these fields when building or receiving messages.
You may need to code information in your program to process:
If your IMS message contains only character data (apart from the LLZZ-data segment), and you are using an MQIIH structure, set the MQMD format to MQFMT_IMS and the MQIIH format to MQFMT_IMS_VAR_STRING.
If your IMS message contains only character data (apart from the LLZZ-data segment), and you are not using an MQIIH structure, set the MQMD format to MQFMT_IMS_VAR_STRING and ensure that your IMS application specifies MODname MQFMT_IMS_VAR_STRING when replying. If a problem occurs (for example, user not authorized to use the transaction) and IMS sends an error message, this will have a MODname of the form DFSMOx, where 'x' is a number between 1 and 5. This will be put in the MQMD.Format.
If your IMS message contains binary, packed, or floating point data (apart from the LLZZ-data segment), you will need to code your own data-conversion routines. Refer to the IMS/ESA Application Programming: Transaction Manager for information about IMS screen formatting.
When you write an application which will invoke an IMS conversation, you should bear the following in mind:
The WebSphere MQ-IMS bridge does not support trigger messages.
If you define an initiation queue that uses a storage class with XCF parameters, messages put to that queue are rejected when they get to the bridge.
An application programme can build a WebSphere MQ message of the form LLZZ<command>, instead of a transaction, where <command> is of the form /DIS TRAN PART or /DIS POOL ALL. Most IMS commands can be issued in this way, see the IMS/ESA V6 OTMA Guide and Reference for details. The command output will be received in the WebSphere MQ reply message in the text form as would be sent to a 3270 terminal for display.
OTMA has implemented a special form of the IMS display transaction command, which will return an architected form of the output. The exact format is defined in the IMS/ESA V6 OTMA Guide and Reference. To invoke this form from a WebSphere MQ message, build the message data as before, for example /DIS TRAN PART, and set the TranState field in the MQOOH to MQITS_ARCHITECTED. The command will be processed by IMS, and the reply returned in the architected form. An architected response contains all the information that could be found in the text form of the ouput, and one additional piece of information: whether the transaction is defined as recoverable or non-recoverable.