533-MigratingYourMQIApplicationsToJMS.pdf

IBM TechCon 2024,
a TechXchange Virtual Event
Session 533
Migrating your MQI
applications to JMS
Matt Leming
Architect, MQ for z/OS
IBM

APIs and protocols
2
MQI
C, Java, Node
Go, Python, C++
COBOL, PL/I, HLASM
JMS
Java
REST
AMQP 1.0
Various languages
MQTT
.NET
IBM TechCon 2024, a TechXchange Virtual Event | © 2024 IBM
Corporation
JMS “like"
Go, XMS

Why migrate from MQI to JMS?
3
The MQI is, and will continue to be, the main API for MQ
It underpins all the other APIs
Every API capability we write comes to the MQI first. Recent
examples:
-JWT support
-Uniform cluster rebalancing
However, some of the languages that the MQI supports
are perhaps less fashionable, so being aware of how to
move from those to something more common such as
Java is useful
Even for programming languages which remain mainstream
(for example C), there is still the need to be able to support
changing requirements and moving to different frameworks
HLASM
COBOL
Corporation

MQ classes for Java
4
MQ has two Java based APIs:
-MQ classes for JMS
-MQ classes for Java
The MQ classes for Java is a fairly close mapping of the
MQI to Java
If language modernization was the goal, then moving
to the MQ classes for Java might seem reasonable
However, this is not recommended. The MQ classes for Java
are functionally stabilised at the level of capability shipped in
MQ 8 (May 2014)
They don’t support many recent (including MQ 7) capabilities
such as automatic client reconnect
If you are going to modernize your MQI applications to use Java
then use the MQ classes for JMS
Corporation

High level comparison
5
MQI JMS
IBM MQ proprietary, premier API for MQ Standards based API for messaging,
implementations provided by IBM and
other companies
Applications are MQ aware Applications don’t need to be MQ
aware, but might be. MQ specific
configuration can be abstracted away
Wide variety of languages supported: C,
COBOL, Java, HLASM, Node, Go,
Python, C++, PL/I
Java only API, but has inspired “JMS
like” APIs in other languages, e.g Go
Supports all MQ capabilities (apart from
rare language specific features)
Supports most MQ capabilities, but not
as feature rich as the MQI. Some JMS
only capabilities exist
Can be used in a wide variety of
environments, on z/OS is tightly
integrated with CICS, IMS, Db2
Can be used in a wide variety of
environments, tight integration with JEE
(WAS, WLP) environments and
CICS/IMS on z/OS
Widely used by MQ customers Widely used by MQ customers
Corporation

JMS intro
6
Originally designed in 1998 as a partnership between
IBM and several other companies, the JMS spec has
been through a number of revisions over time
• JMS 1: initial spec, domain (p2p, pub-sub) specific
interfaces
• JMS 1.1: addition of domain independent interfaces
• JMS 2: introduction of JMSContext, runtime
exceptions, delivery delay, and many other things
• JMS 3: move to Jakarta EE, package name
changed, but API remains the same as JMS 2
Going forwards we would recommend use of the JMS
3 interfaces, and that is what this presentation
focusses on
NB: JMS 3 and 2 are backwards compatible and
therefore allow the old JMS 1 interfaces (not shown)
to be used
JMSConsumer
Message
(5 types)
JMSProducer
JMSContext
Connection
Factory
Destination
(queue or
topic)
Administered
objects
Corporation

JMS administered objects
7
JMS is a vendor neutral API, but in order to connect to a
messaging provider (connection factory) and access its
destinations (queues and topics) there is always going to
need to be some configuration which is likely to be
messaging provider specific
For example with MQ you might need: queue manager
name, transport mode, host name and port number, TLS
configuration, queue name, CCSID etc
All of these can be specified programmatically, but that
makes code less portable
JNDI and JMS administered objects solves this problem
In contrast, the MQI doesn’t have to abstract this
information away, but in some cases it does via
environment variables: e.g. MQCCDTURL for accessing a
CCDT
JNDI Server
(WAS, file-system, LDAP)
jms/cf
qmgr: QM1
host: localhost
port: 1414
QM1
Q1
App Administrator
jms/q
queueName: Q1
ccsid: 500
1: bind administered
objects into JNDI
2: lookup resources
from JNDI
3: connect to queue
manager
4: access queue
Corporation

Connecting to MQ
8
Creating a connection using the MQI is performed using
the MQCONN/MQCONNX verbs
MQCONNX provides the ability to specify various options,
including use of client connections with TLS
In general most of these options closely map to JMS and
configuration options on the MQConnectionFactory, or via
JNDI
Not all options are available though. A notable example
being MQCNO_SERIALIZE_CONN_TAG_* on z/OS
In the MQI a connection to MQ is represented via an
HCONN, in it is represented via a JMSContext
Note that CICS provides an implicit connection to MQ, but
with JMS you still need to explicitly connect to create the
JMSContext
MQI
cno.Options |= MQCNO_RECONNECT_Q_MGR;
MQCONNX(qmgrName,
&cno,
&hconn,
&compcode,
&creason);
JMS
MQConnectionFactory cf = new MQConnectionFactory();
cf.setQueueManager(qmgrName);
cf.setClientReconnectOptions(WMQConstants.WMQ_CLIENT_RECONNECT_Q_MGR);
JMSContext context = cf.createContext();
Corporation

Opening / closing an object: MQI
9
With the MQI, once you have connected to the queue
manager you open (MQOPEN) one or more objects so
that you can interact with it
Objects can be: queues, distribution lists, namelists,
processes, queue managers, topics
Objects can be opened for input (MQGET), output
(MQPUT) browse, inquire, set. And multiple of these
can be used at the same time
The open object, regardless of type, is represented by
an HOBJ
Once finished with the object is closed (MQCLOSE)
COMPUTE VAR-OPEN-OPTIONS = MQOO-INPUT-AS-Q-DEF +
MQOO-OUTPUT +
MQOO-INQUIRE.
CALL 'MQOPEN' USING VAR-HCONN
MQOD
VAR-OPEN-OPTIONS
VAR-HOBJ
VAR-COMPCODE
VAR-REASON.
....
CALL 'MQCLOSE' USING VAR-HCONN
VAR-HOBJ
VAR-CLOSE-OPTIONS
VAR-COMPCODE
VAR-REASON.
Corporation

Opening / closing an object: JMS
10
With JMS, once you have connected to the queue
manager you can interact with queues or topics
JMS has no knowledge of distribution lists, namelists,
processes or queue managers. So, they can’t be used
JMS allows messages to be put, got or browsed. It
doesn’t have anything like an MQINQ or MQSET to get
or change attributes
Any MQI code that makes use of these capabilities
would need to do something else, for example the
administrative REST API which is easy to use in Java
There are different objects (JMSConsumer,
JMSProducer** and QueueBrowser) which are similar
to the HOBJ, but are operation specific (get, put,
browse). The creation of these objects is equivalent
to an MQOPEN
Closing them is the equivalent to the MQCLOSE
JMSConsumer topicConsumer = context.createConsumer(topic);
JMSConsumer queueConsumer = context.createConsumer(queue);
QueueBrowser queueBrowser = context.createBrowser(queue);
JMSProducer producer = context.createProducer();
topicConsumer.close();
queueConsumer.close();
queueBrowser.close();
Corporation
NB: JMS always uses MQOO_INPUT_AS_Q_DEF, there is
no equivalent of MQOO_INPUT_SHARED /
MQOO_INPUT_EXCLUSIVE

Opening / closing an object: JMS
11
JMSProducer does however play by different rules
It isn’t associated with a destination when it is
created, that happens later when sending messages
As a result it doesn’t need a close method
This is quite different to the JMS 1 equivalent, the
MessageProducer which is associated with a
destination for its lifetime
JMSConsumer topicConsumer = context.createConsumer(topic);
JMSConsumer queueConsumer = context.createConsumer(queue);
QueueBrowser queueBrowser = context.createBrowser(queue);
topicConsumer.close();
queueConsumer.close();
queueBrowser.close();
Corporation

Messages
12
In the MQI, a message is represented by an MQMD
followed by a buffer containing the message payload,
it may also contain message properties
JMS messages contain a header, properties and a
body. They are represented by the Message interface,
which has sub-interfaces depending on body type:
TextMessage, BytesMessage, ObjectMessage,
StreamMessage and MapMessage
TextMessage: payload is a string -> MQFMT_STRING
in the MQI
BytesMessage: payload is a byte array -> any other
MQI format
These three don’t have an MQI equivalent:
ObjectMessage: payload is a serialised Java object
StreamMessage: payload is serialised stream of Java
primitives
MapMessage: payload is a map of Java key/value
pairs
JMS Message
Header
Properties
Payload
MQMD
Properties
Payload
MQI Message
Corporation

Message properties
13
JMS message properties are simpler, and have been around
longer, than the equivalent function now available in the MQI
JMS messages can contain arbitrary sets of properties in the
form of name-value pairs
They are sent in the message in the form of an RFH2 header
JMS provides the ability to set MQMD properties, such as
report options, via message properties:
message.setIntProperty(JMS_IBM_REPORT_EXCEPTION,
MQRO_EXCEPTION_WITH_DATA);
message.setIntProperty(JMS_IBM_MSGTYPE,
MQMT_REQUEST);
Corporation
MQI
//Create a message handle to set properties on.
MQCRTMH ...
//Set a message property
MQSETMP ...
//Get a message property
MQINQMP ...
JMS
Message message = context.createTextMessage();
message.setStringProperty("StringKey", "A string");
message.setIntProperty("IntKey", 1999);
message.setBooleanProperty("BooleanKey", false);
…
//Show all the message properties in the message
Enumeration propertyNames = message.getPropertyNames();
while(propertyNames.hasMoreElements()) {
System.out.println(message.getStringProperty((String)
propertyNames.nextElement()));
}

Sending messages
14
Sending a message to a queue or publishing a
message to a topic is performed using the send
method of the JMSProducer class
This effectively maps onto an MQPUT1, which might
be less performant if sending lots of messages to the
same queue
With the JMS 2/3 interfaces there is no equivalent of
MQPUT, you need to use the JMS 1 style interfaces,
and the MessageProducer for that
MQI
CALL 'MQPUT' USING VAR-HCONN
VAR-HDEST
VAR-MQMD
VAR-MQPMO
VAR-MSGLENGTH
VAR-MSGBUFFER
VAR-COMPCODE
VAR-REASON.
CALL 'MQPUT1' USING VAR-HCONN
VAR-MQOD
VAR-MQMD
VAR-MQPMO
VAR-MSGLENGTH
VAR-MSGBUFFER
VAR-COMPCODE
VAR-REASON.
JMS
Message message = context.createTextMessage("A message");
producer.send(queue, message);
Corporation

Receiving messages
15
Messages can be synchronously consumed from a
queue or topic via a JMSConsumer
This maps pretty closely to what is available with the
MQI, including the ability to receive with or without a
wait
Support for getting specific messages is provided by
a selector. E.g. message ID, correlation ID, or a
message property
As with the MQI, use of complex message selectors
can be inefficient. If you can, use get by message ID
or correlation ID, with the ID prefix, which will use
the MQI MQMO_MATCH_*_ID approach
JMS will automatically manage message buffers for
you under the cover, so no need to worry about
message truncation etc
Corporation
https://www.ibm.com/docs/en/ibm-mq/9.3?topic=messages-message-selectors-in-jms
Message m1 = consumer.receiveNoWait();
//Will return an available message, waiting until one
//is available
Message m2 = consumer.receive();
//Will return an available message, waiting for a number
//of ms until one is available
Message m3 = consumer.receive(60_000);
//Selectors are associated with a consumer:
consumer.close();
//ID: prefix is required to use MQI correlation/message ID match
//options.
String selector =
"JMSMessageID='ID:414D51207061756C745639314C545320C57C1A5F25ECE602’”;
consumer = context.createConsumer(queue, selector);
//Wait for message with specified message ID to turn up.

Browsing messages
16
The JMS spec is fairly limited when it comes to
browsing messages, much of the MQI capability is
unavailable (browse with mark, browse cursors, etc),
as there is no way to map it to the JMS spec
However, that doesn’t seem to have been much of an
issue so far!
You can only browse messages from a queue, topics
aren’t supported
As there is no concept of a browse cursor, you have to
use a selector to destructively get a message that you
have browsed
Corporation
//Browse all available messages on the queue, in order.
Message m1 = null;
while(messages.hasMoreElements()) {
m1 = (Message) messages.nextElement();
}
//Destructively get the last one by message ID.
if(m1 != null) {
String selector = "JMSMessageID='" + m1.getJMSMessageID() + "'";
JMSConsumer consumer = context.createConsumer(queue, selector);
Message m2 = consumer.receiveNoWait();
consumer.close();
}

Pub/sub
17
JMS supports most of the capabilities of MQI pub/sub,
including durable and non-durable subscribers,
retained publications and administrative subscriptions
The main thing to be aware of is that MQ provides
support for both managed, and unmanaged,
subscriptions:
• Managed subscription: the queue manager will
automatically create and manage a queue to store
the messages associated with the subscriber
• Unmanaged subscription: the application has to
manage its own queue
The MQI provides support for both types of
subscription. JMS only supports managed
subscriptions
Corporation
//Needed for durable consumer
context.setClientID("clientID");
JMSConsumer durableSubscriber = context.createDurableConsumer(topic,
"subscriptionName");
JMSConsumer nonDurableSubscriber = context.createConsumer(topic);
producer.send(topic, "A publication");
System.out.println(nonDurableSubscriber.receive());
System.out.println(durableSubscriber.receive());

Transactions
18
JMS takes quite a different approach to transactions
compared to the MQI
With the MQI you can decide on a per-API call basis
whether a message is put or got inside a transaction, you
can also decide to only get messages inside a transaction
if they are persistent
With JMS you decide transactional behaviour when you
connect. If you want to send / receive some messages in
/ outside of transactions then you need two different
JMSContexts, or to disconnect and reconnect
JMS also has the idea of receiving and then
acknowledging messages, there isn’t a direct mapping
for this in the MQI, but it does use transactions under the
covers
Corporation
MQI
PutMsgOpts.Options = MQPMO_SYNCPOINT;
MQPUT...
PutMsgOpts.Options = MQPMO_NO_SYNCPOINT;
MQPUT...
GetMsgOpts.Options = MQGMO_SYNCPOINT_IF_PERSISTENT;
MQCMIT...
JMS
//Create a context with a transaction
JMSContext context1 = cf.createContext(JMSContext.SESSION_TRANSACTED);
//Send or receive messages inside transaction
//Commit
context1.commit();
…
//Create a context without a transaction
JMSContext context2 = cf.createContext();
//Send or receive messages outside transaction
…
//Received messages must be acknowledged before MQ will remove them
//from the queue.
JMSContext context3 = cf.createContext(JMSContext.CLIENT_ACKNOWLEDGE);
JMSConsumer consumer = context3.createConsumer(queue);
m1.acknowledge();

Mixing and matching JMS and MQI
19
It is common for MQI and JMS applications to exchange
messages
Messages sent from MQI applications will be received by
JMS applications as either a TextMessage, or a
BytesMessage
MQI applications will receive a TextMessage as a message
with an MQMD.FORMAT of MQFMT_STRING. JMS
applications can associate a BytesMessage with a specific
format:
message.setStringProperty(JMS_IBM_FORMAT,
“MYFORMAT”);
Corporation
MQI JMS
https://www.ibm.com/docs/en/ibm-mq/9.3?topic=mjmomm-exchanging-
messages-between-jms-application-traditional-mq-application

Mixing and matching JMS and MQI
20
When sending a JMS message, the message will have an
RFH2 header after the MQMD, and before the message data.
In most cases consuming MQI applications won’t expect this
header, so it can be switched off on the queue / topic object:
queue.setTargetClient(WMQConstants.
WMQ_CLIENT_NONJMS_MQ);
JMS applications don’t have to do anything special when
receiving a message from an MQI application. MQ’s JMS
code will deal with the presence or absence of an RFH2
header automatically
When a JMS application replies to a message, by default it
will only add an RFH2 header to that message if it contained
an RFH2 header, again to maintain compatibility with MQI
applications
Corporation
MQI JMS
https://www.ibm.com/docs/en/ibm-mq/9.3?topic=mjmomm-exchanging-
messages-between-jms-application-traditional-mq-application

Data conversion
21
Always a tricky topic! But, in general, everything works the
same with the MQI and JMS, using the concepts of format,
CCSID and encoding. And you probably only need to care
about data conversion when exchanging messages
between JMS and MQI applications
An important thing to be remember is that every string in a
JVM is in UTF-16, so when receiving a TextMessage, its
contents will have automatically been converted into UTF-
16 from whichever CCSID it was originally put
Like-wise, if you want to exchange text with an MQI
application, the text in a TextMessage will be in UTF-16,
and might need to be converted, either by that application
when the message is received, or by MQ JMS when the
message is sent (the default)
If you want the queue manager to perform data-
conversion, particularly when receiving a BytesMessage
and using a data conversion exit you can do this using a
property on the destination
Corporation
https://www.ibm.com/docs/en/ibm-mq/9.3?topic=messages-jms-
message-conversion
//Messages sent to this queue will use EBCDIC for character data
queue.setCCSID(500);
Message message = context.createTextMessage("Hello in EBCDIC!");
//The queue manager will do data conversion when
//receiving messages from this destination.
queue.setReceiveConversion(WMQConstants.WMQ_RECEIVE_CONVERSION_QMGR);
BytesMessage message = (BytesMessage) consumer.receive();

Dealing with errors
22
With MQ, every MQI operation returns a completion and
reason code. These should be checked and dealt with
appropriately
JMS provides similar function via exceptions, there are
two types:
• JMSException, a checked exception, part of the
original API
• JMSRuntimeException, an unchecked exception,
introduced in JMS 2
Even though JMSRuntimeException is an unchecked
exception you should always catch it!
Every JMS*Exception thrown by the JMS API will have a
nested MQ specific exception, you can use this to get
specific information about what has gone wrong
Corporation
MQI
IF (VAR-CC NOT = MQCC-OK) THEN
DISPLAY 'DETECTED AN ERROR: MQPUT1' VAR-RC
END-IF.
JMS
try {
//Perform JMS operation
}
catch(JMSException | JMSRuntimeException e) {
Throwable t = e;
while (t != null) {
//Write out the message that is applicable to all exceptions
System.err.println("Exception Msg: " + t.getMessage());
//Write out the exception stack trace
t.printStackTrace(System.err);
//Add on specific information depending on the type of exception
if (t instanceof MQException) {
MQException mqe = (MQException) t;
System.err.println("MQ Completion code: " + mqe.getCompCode());
System.err.println("MQ Reason code: " + mqe.getReason());
}
//Get the next cause
t = t.getCause();
}
}
https://www.ibm.com/docs/en/ibm-mq/9.3?topic=jms-handling-unchecked-
exceptions

Defaults
23
There are a few differences in defaults between JMS and
the MQI:
• The JMS default priority is 4, with the MQI the default is
taken from the queue, and that by default is 0. Only
important for queues with MSGDLVSQ(PRIORITY)
• The JMS default persistence is persistent, with the MQI
the default is taken from the queue, and that by default
is non-persistent
Changing to the MQI defaults is possible by changing the
configuration of the JMS queue object
It’s also worth bearing in mind that not all MQ platforms
have the same defaults. However, the MQ JMS has the
same defaults regardless of platform. The main example
of this is that on z/OS messages are put and got in synch-
point, on other platforms they aren’t
Corporation
queue.setIntProperty(WMQConstants.PRIORITY,
WMQConstants.PRIORITY_AS_DEST);
queue.setIntProperty(WMQConstants.DELIVERY_MODE,
WMQConstants.DELIVERY_AS_DEST);
MQI
MOVE MQPRI-PRIORITY-AS-Q-DEF TO MQMD-PRIORITY.
MOVE MQPER-PERSISTENCE-AS-Q-DEF TO MQMD-PERSISTENCE.
JMS

What does JMS give you that MQI doesn’t?
24
Because JMS is a standardized API there are a number of
frameworks which the MQ JMS API can be used in, which
make application development simpler, or provide powerful
additional capabilities beyond those available in standard
Java
• Jakarta EE
• Spring and Spring Boot
Additionally, the JMS 2 API introduced delivery delay, the
ability to send a message which only becomes available to be
consumed at specified time. This capability doesn’t exist in
any other MQ API
Lastly, JMS is the only MQ API that has built-in support for
the BOQNAME and BOTHRESH queue attributes, this
provides an automatic solution for dealing with poisoned
messages
Corporation
APPQ
-BOQNAME(ERRQ)
-BOTHRESH(10)
App
ERRQ
MQGET
If backout > 10

Performance comparison
25
The JMS API is more CPU intensive than the MQI. This
increased CPU results in less throughput. Some example
numbers on distributed are shown on the right
It’s also worth bearing in mind that JMS will sometime
issue multiple MQ calls under the covers. For example,
creating a JMSContext will result in two connections to
the queue manager, which incurs some extra expense,
and JMS also will issue some MQINQ calls internally at
connect time
Connection pooling can mitigate this
Corporation
Green is JMS
Red is MQI
Thin line is client CPU
Thick line is message throughput

Recommended reading
26
Writing your first MQ JMS application: https://developer.ibm.com/tutorials/mq-develop-mq-jms/
Main JMS topic: https://www.ibm.com/docs/en/ibm-mq/9.3?topic=applications-developing-jmsjakarta-messaging-java
Mapping between JMS and MQI: https://www.ibm.com/docs/en/ibm-mq/9.3?topic=messages-mapping-jms-onto-mq
Message conversion: https://www.ibm.com/docs/en/ibm-mq/9.3?topic=messages-jms-message-conversion
JMS Javadoc: https://jakarta.ee/specifications/messaging/3.0/apidocs/
JMS specification https://jakarta.ee/specifications/messaging/3.0/
Corporation

Questions
27
Corporation

Thank you.
28
Corporation

533-MigratingYourMQIApplicationsToJMS.pdf

533-MigratingYourMQIApplicationsToJMS.pdf

More Related Content

Similar to 533-MigratingYourMQIApplicationsToJMS.pdf (20)

More from Matt Leming (13)

Recently uploaded (20)

533-MigratingYourMQIApplicationsToJMS.pdf