Considerations when using the IMS adapter

One connection handle for each queue manager

Only one connection handle at a time to a specific queue manager is allowed in IMS dependent regions. Any subsequent attempts to connect to the same queue manager reuse the existing handle.

While this behavior should not cause any problems in an application that only uses the IBM MQ classes for JMS, this behavior can cause problems in applications that interact with IBM MQ, when using both the IBM MQ classes for JMS and the MQI in native code written in languages, such as COBOL or C.

Implications of interacting with IBM MQ when using both JMS and native code

Problems can occur when interleaving Java code and native code that both use IBM MQ functionality and when the connection to IBM MQ is not closed before leaving either the native or Java code.

For example, in the following pseudo code, a connection handle to a queue manager is originally established in Java code using the IBM MQ classes for JMS. The connection handle is reused in COBOL code and invalidated by a call to MQDISC.

COBOL code running in message processing region
    Use the Java Native Interface (JNI) to call Java code  
       Create MQ connection and session - this creates an MQ connection handle    
       Send message to MQ queue
       Store connection and session in static variable  
       Return to COBOL code

    MQCONN - picks up MQ connection handle established in Java code
    MQDISC - invalidates connection handle

    Use the Java Native Interface (JNI) to call Java code
       Get session from static variable
       Create a message consumer - fails as connection handle invalidated

There are other similar usage patterns which can result in MQRC_HCONN_ERROR.

While it is possible to share IBM MQ connection handles between native and Java code (for example, the previous example would work if there had not been an MQDISC call) in general, the best practice is to close any connection handles before transitioning from Java to native code, or the other way round.

Connection authentication and authorization

The JMS specification allows a user name and password to be specified for authentication and authorization when creating a connection or JMS context object.

This is not supported in an IMS environment. Attempting to create a connection while specifying a user name and password results in a JMS Exception being thrown. Attempting to create a JMS context, while specifying a user name and password, results in a JMSRuntimeException being thrown.

Instead, existing mechanisms for authentication and authorization when connecting to IBM MQ from an IMS environment must be used.

For more information, see Setting up security on z/OS®. In particular, refer to User IDs for security checking, which describes the user IDs that can be used.