Writing IMS transaction programs through IBM MQ

The coding required to handle IMS transactions through IBM MQ depends on the message format required by the IMS transaction and the range of responses it can return. However, there are several points to consider when our 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 must be re-created in the new application.

In some IMS transactions, the end-user application can modify certain 3270 screen behavior, for example, highlighting a field that 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 that needs 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 might need to code information in your program to process:

  • Which key is pressed (for example, Enter and PF1)
  • Where the cursor is when the message is passed to our application
  • Whether the attribute fields have been set by the IMS application

    • High, normal, or zero intensity
    • Color
    • Whether IMS is expecting the field back the next time that Enter is pressed
  • Whether the IMS application has used null characters ( X'3F') in any fields.

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 has an MODname of the form DFSMOx, where x is a number in the range 1 through 5. This is put in the MQMD.Format.

If your IMS message contains binary, packed, or floating point data (apart from the LLZZ-data segment), code your own data-conversion routines. Refer to IMS/ESA® Application Programming: Transaction Manager for information about IMS screen formatting.

Consider the following topics when writing code to handle IMS transactions through IBM MQ.


Writing IBM MQ applications to invoke IMS conversational transactions

Use this information as a guide for considerations when writing IBM MQ application to invoke IMS conversational transactions.

When you write an application that invokes an IMS conversation, consider the following:

  • Include an MQIIH structure with our application message.
  • Set the CommitMode in MQIIH to MQICM_SEND_THEN_COMMIT.
  • To invoke a new conversation, set TranState in MQIIH to MQITS_NOT_IN_CONVERSATION.
  • To invoke second and subsequent steps of a conversation, set TranState to MQITS_IN_CONVERSATION, and set TranInstanceId to the value of that field returned in the previous step of the conversation.
  • There is no easy way in IMS to find the value of a TranInstanceId, should you lose the original message sent from IMS.
  • The application must check the TranState of messages from IMS to check whether the IMS transaction has terminated the conversation.
  • We can use /EXIT to end a conversation. You must also quote the TranInstanceId, set TranState to MQITS_IN_CONVERSATION, and use the IBM MQ queue on which the conversation is being carried out.
  • We cannot use /HOLD or /REL to hold or release a conversation.
  • Conversations invoked through the IBM MQ - IMS bridge are terminated if IMS is restarted.


Writing programs containing IMS commands

An application program can build an IBM MQ message of the form LLZZcommand, 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 IMS V11 Communications and Connections for details. The command output is received in the IBM 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 returns an architected form of the output. The exact format is defined in IMS V11 Communications and Connections. To invoke this form from an IBM MQ message, build the message data as before, for example /DIS TRAN PART, and set the TranState field in the MQIIH to MQITS_ARCHITECTED. IMS processes the command, and returns the reply in the architected form. An architected response contains all the information that could be found in the text form of the output, and one additional piece of information: whether the transaction is defined as recoverable or non-recoverable.


Triggering

The IBM 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.