POLO RALPH

LAUREN

WEBSPHERE MQ
BEST PRACTICES
Design & Programming Standards

FEBRUARY 4, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

TABLE OF CONTENTS
1.0

INTRODUCTION.....................................................................................................................1
1.1

2.0

3.0

4.0

SCOPE...................................................................................................................................1

MESSAGING TECHNOLOGY...............................................................................................2
2.1

INTRODUCTION.....................................................................................................................2

2.2

REASONS FOR USING WMQ.................................................................................................2

2.3

MESSAGING PATTERNS.........................................................................................................3

2.4

WMQ REQUEST/REPLY PROCESSING...................................................................................5

2.5

SYNCHRONOUS VERSUS ASYNCHRONOUS PROCESSING.......................................................5

2.6

UNDELIVERED MESSAGES....................................................................................................6

2.7

CLOSE OF BUSINESS PROCESSING........................................................................................7

2.8

TRANSACTIONAL INTEGRITY................................................................................................7

MESSAGING TECHNIQUES AVAILABLE THROUGH THE MQI..................................8

3.1

INTRODUCTION.....................................................................................................................8

3.2

CLIENT/SERVER DESIGN.......................................................................................................8

3.3

INQUIRY MESSAGES.............................................................................................................8

3.4

UPDATE MESSAGES..............................................................................................................8

3.5

REPORT MESSAGES..............................................................................................................9

APPLICATION DEVELOPMENT BEST PRACTICES.....................................................10

4.1

INTRODUCTION...................................................................................................................10

4.2

BEST PRACTICES................................................................................................................10
4.2.1 Application Design.................................................................................................10
4.2.2 Dead Letter queue handling....................................................................................11
4.2.3 Interface to Messaging Services.............................................................................12
4.2.4 MQI Calls - General...............................................................................................13
4.2.5 Queue Manager Connection Handling...................................................................14
4.2.6 Queue Open Handling............................................................................................15

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

4.2.7 Putting Messages....................................................................................................17

4.2.8 Getting Messages...................................................................................................18
4.2.9 Message Content....................................................................................................19
5.0

6.0

APPENDIX A JAVA MESSAGING SERVICE (JMS).......................................................20

5.1

INTRODUCTION...................................................................................................................20

5.2

APPLICATION OF JMS.........................................................................................................21

APPENDIX B SAMPLE APPLICATION PROGRAMMING INTERFACE..................22

ii

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

1.0

INTRODUCTION

1.1

SCOPE

This document is one of a set of documents that describe the WebSphere MQ (WMQ) Best Practices
for use at Polo Ralph Lauren National. These procedures cover the Development, Test, Quality
Assurance and Production environments. This particular document describes the Standards and
Guidelines to be followed in developing software that utilizes WMQ.
This document is designed to both identify the processes that are to be followed within Polo and to
describe the specific implementation details entailed in the execution of those processes. As needs
arise to modify the processes described within this document, the appropriate modifications should be
made and documented. This document should thus be updated to reflect both changes in process and
changes in implementation detail.
The information contained within this document covers a wide range of topics, covering design and
programming techniques and practices. Industry wide best practices are identified within these
various topics. Best practices and guidelines are just thatguidelines. POLO WMQ standards are
identified as such. Within topics, both standards and guidelines are identified. This document also
describes the rationale behind the standards and guidelines so that they can be best understood.
As always, the business requirements for the application must drive the messaging design and
implementation decisions. It is always possible to have exceptions to the rules defined within this
document. When exceptions are needed, however, they are best determined through consensus with
both the application designers and programmers and the WMQ administrators. This ensures that the
most comprehensive possible messaging knowledge, as well as the broadest possible viewpoints, are
brought into the decision making process.

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

2.0

MESSAGING TECHNOLOGY

2.1

INTRODUCTION

There are numerous options to be considered in the design, programming, and administration of
software utilizing WMQ services. These areas are also all interrelated. Many options can be handled
at both the programming and the administration levels. Some WMQ features require that the
software be designed appropriately to be able to exploit the features. For all of these reasons, the
construction of a WMQ application requires collaboration between programmers, designers, and the
WMQ administrators.
In order to make the best possible application design decisions, the development team requires a
broad understanding of messaging architecture in general and WMQ capabilities in particular. The
purpose of this section is to describe the conceptual background in which the specific application
implementation decisions will be made. The actual implementation Standards and Guidelines are
described in Section 4.

2.2

REASONS FOR USING WMQ

There are several different reasons why applications may utilize WMQ messaging services.
Understanding why the application is using WMQ has a significant impact on determining how
WMQ services should be used. There are three basic reasons why WMQ should be used. Note that
these reasons are not mutually exclusive. The basic reasons for using WMQ are as follows:
Communication between application code on different computing platforms, different
programming language environments, or both. When used in this manner, WMQ
messaging simulates a Remote Procedure Call (RPC).
Asynchronous communication capabilities are required. The decoupling of the
message writer from the message reader can simplify applications, provide increased enduser application availability, and decrease end-user response time.
Provide a data integrity mechanism within an Open Systems computing environment.
Open Systems environments (WAS, J2EE, JVM, UNIX, and Windows) have not generally
had transactional integrity. While Teleprocessing Monitors products such as CICS and
Tuxedo can provide this capability on some platforms, these products are not in general use
on these platforms. WAS has these capabilities, but they may be limited in scope due to
either limitations in capability or in configuration.
The reasons for using WMQ create design, programming, and administrative requirements. This is
particularly true when WMQ is being used for data integrity reasons. Application designers must

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

understand the potentially severe data integrity limitations that exist within the Open Systems
environment.

2.3

MESSAGING PATTERNS

Application message flows fall into a number of basic patterns. While the details of messaging
applications can vary widely, the ways in which these applications use basic messaging services are
essentially quite standardized. By identifying the messaging pattern being used, many of the WMQ
implementation details can be derived. This removes the need to specify these details for each
message flow and also standardizes the behavior of the messaging system.
These patterns describe how messages flow between application components. There are several
different ways to evaluate the basic message flow patterns. Perhaps the most basic distinction is to
look at the possible linkages between messages. From this perspective, there are several different
messaging patterns.
Table 1: Message Flow Patterns
Pattern
Datagram

Description
A message is sent. No reply to the message is expected.
This pattern is sometimes called Fire and Forget.
One-way message flow.
Inherently asynchronous.

Request/Reply

A message is sent and a reply to the message is expected.

The reply may range from returned data to a simple acknowledgement.

Conversational

A series of messages are sent and replies are received.

This is actually a linked set of Request/Reply messages. The set may also include
Datagrams. What distinguishes a conversation is that the entire set of messages pertains to
a business transaction. Data integrity must thus be maintained across multiple messages.

A further refinement of these basic flows involves analyzing how the data in the message flows is to
be used. This involves determining whether external data sources will be modified as a result of the
message. The patterns that result from this kind of analysis are as follows.

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

Table 2: Messaging Patterns 2

Pattern
Broadcast
(Datagram pattern)
Post
(Datagram pattern)

Description
The message writer has no interest in any permanent storage of the message content.
An example of this would be publishing stock market prices.
The message writer expects that the message reader will update some permanent storage
as a result of receiving the message. An example of this is a message causing a database
update in an asynchronous manner. In publish/subscribe architectures, this is the pattern
the publisher uses.

Inquiry
(Request/Reply
pattern)

The purpose of sending the message is to receive a reply. In this case, the message
originator (client) sends key information to the server application. The server uses the
key information to obtain data that is then returned to the client. No data is updated
during this process.

Update
(Request/Reply
pattern)

The purpose of sending the message is to receive a reply. This final refinement of these
patterns involves determining, for multiple message flows, how the message originator
behaves. Does the sender wait for a response (synchronous behavior) or does the
sending application process the response at a later time. The resulting messaging
patterns can be seen in the following table.

Table 3: Messaging Patterns 3

Pattern

Synchronous

Asynchronous

N/A

Non-persistent messages.

N/A

Persistent messages.

Inquiry

Non-persistent messages.

Persistent messages.

(Request/Reply)

Expiring Request messages.

Non-expiring Request
messages.

Broadcast
(Datagram)
Post
(Datagram)

Expiring Reply messages.

Message Id / Correlation Id or Model queues.

Non-expiring Reply messages

Message Id / Correlation Id or
Model queues.

Update

Persistent messages.

Persistent messages.

(Request/Reply)

Non-expiring Request messages.

Non-expiring Request

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

Pattern

Synchronous
Non-expiring Reply messages.

Asynchronous
messages.

Message Id / Correlation Id or Model queues.

Non-expiring Reply
messages.
Message Id / Correlation Id or
Model queues.

Conversational
(Request/Reply Set)

2.4

Typically, inquiry patterns followed by a final

update pattern.

N/A

WMQ REQUEST/REPLY PROCESSING

In order to perform Request/Reply processing, two messages need to be sent. The client application
sends a message to the server application. This is done with the MQ Interface (MQI) MQPUT
command. The server application then processes the message and sends a reply message. Finally, the
client application receives the reply message. This is done with the MQI MQGET command.
Any WMQ Request/Reply pattern requires a decision as to how the client application is to identify
the reply message. There are two basic approaches to resolving this issue. Either the reply message
must be uniquely identified so that it can be found and retrieved from within an existing queue or the
reply message must be routed to a unique queue that will only contain the reply message.
Either WMQ or the application can generate a unique message identifier. This message identifier is
stored in the message header (MQMD). This message identifier can be used by the server application
and stored in the Correlation Identifier field in the MQMD. If the client application stores the original
message identifier, then the reply message can be retrieved from the queue using the Correlation
Identifier. Note that the queue must be defined to support this type of access.
If Correlation Identifiers are not used, the message may be routed to a unique queue defined by the
client. This is where dynamic queues can be used. In general, it is recommended that Correlation
Identifiers be used to solve this problem. In either case, this mechanism must be reviewed with the
WMQ administrators, as neither solution will work without WMQ administrator support.

2.5

SYNCHRONOUS VERSUS ASYNCHRONOUS PROCESSING

In all bi-directional communications, there is some delay between the sending of a message and the
receipt of a response. If the message originator does not attempt to perform any work while waiting
for the response, then this is termed synchronous processing. If, on the other hand, the message

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

originator performs other processing while waiting for the arrival of a response, then the resulting
messaging pattern is termed asynchronous.
The difference between synchronous and asynchronous processing thus revolves around the behavior
of the message originator. When the messaging is being performed to support a User Interface (UI graphical or otherwise), then the messaging approach will generally be visible to the user. In order to
exploit the asynchronous capabilities of WMQ, the UI must be designed to support an asynchronous
request/reply messaging strategy. This means that the user will be aware that the work process was
initiated, but not necessarily finished.
It is important to note that an asynchronous messaging strategy usually involves placing some type of
business responsibility on the user. This typically involves ensuring that the business transaction
completed successfully. While the responsibility for managing the business transaction is similar for
both synchronous and asynchronous processes, the responsibility is usually explicitly designed into
the UI for asynchronous solutions. In the case of synchronous solutions, this responsibility is usually
implicit.
Any application that intends to exploit the asynchronous capabilities of WMQ must explicitly define
the error recovery strategy for a failure between the asynchronous reply

2.6

UNDELIVERED MESSAGES

WMQ assures delivery of messages. WMQ does not guarantee delivery of a message to the queue to
which the message was sent. The reason for this is that messages may be undeliverable. A message
may be sent to a queue that no longer exists, or to an unknown destination. In either of these cases,
the message will end up in a Dead Letter queue. All applications have the responsibility for
monitoring, identifying, and retrieving their own messages from these queues.
While the depths of the Dead Letter queues will be monitored by Operations, the contents of these
queues cannot be automatically handled by Operations personnel. If proper coding standards are
followed, Operations personnel will be able to determine the Application that generated the message
from information in the message header (MQMD). From this point on, it is the Applications
responsibility to handle the message.
The documentation of Dead Letter queue message handling, and the creation of any necessary
software tools to accomplish that handling, must be part of the process of migrating the application
into the Production environment. This requirement cannot be an afterthought, but must be seen as an
integral part of the Application design. If lost message are not handled correctly, the data integrity
of the application can/will be compromised. For the majority of applications, the data integrity of the
application will be compromised without this handling.

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

2.7

CLOSE OF BUSINESS PROCESSING

Due to the inherent asynchronous nature of WMQ messages, the writing of a WMQ message does not
translate into an immediate reading of that message by the destination application. This means that
the successful completion of a process generating messages does not ensure that those messages were
if fact read. Delays in message transmission may prevent any, or all, of the messages written from
being available to the message recipient.
If business requirements require some type of Close of Business (COB) processing, then the
application must specifically design a mechanism to accommodate this. For example, a COB trailer
record could be generated that contains the daily message count. Since WMQ does not guarantee
message delivery sequence, some kind of count mechanism is necessary to ensure that all previous
messages were in fact received.

2.8

TRANSACTIONAL INTEGRITY

Transactional integrity involves maintaining a consistent set of business data as each transaction is
processed. In order to support transactional integrity, either all necessary data sources are updated, or
none of them are. Within the context of messaging, there are usually at least two data sources related
to a business transaction: the message and one or more database tables.
In order to ensure that the data in each message is processed once, and only once, the Commit /
Rollback processing between the messaging system and the database system must be coordinated.
This involves something called Two Phase Commit processing. On the mainframe, this capability is
provided by either CICS or DB2.
Within the Open Systems environment, this capability is usually not present. While there are products
to do this (CICS, Tuxedo, etc.), they are not in general use. The implications of this are significant. If
data integrity is to be maintained, then data sources other than messages must not be updated unless a
resource coordinator is available.

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

3.0

MESSAGING TECHNIQUES AVAILABLE THROUGH THE MQI

3.1

INTRODUCTION

The previous Section discussed various essential application design considerations. The following
Section describes specific design and coding practices. This section bridges the gap between those
areas and describes some WMQ messaging techniques that can be exploited.

3.2

CLIENT/SERVER DESIGN

All WMQ applications that respond to incoming messages are essentially asynchronous server
processes. In general, these processes are very loosely coupled with their client processes. The server
processes usually contain no state information vis--vis the client process. This decoupling can
substantially simplify the application design and implementation. In order to facilitate this type of
design, the following is standard practice:

3.3

MQMD CorrelId

= Request message MsgId field value.

MQMD ReplyToQ

= From request message. Write reply message to this queue.

MQMD ReplyToQmgr

= From request message. Route reply to this Queue Manager.

INQUIRY MESSAGES

Consider treating Inquiry messages as non-persistent. If the inquiry message is generated from a user,
then there is usually no detrimental impact if the message is lost. In this circumstance, there is no data
integrity issue; only a UI design consideration. Consider the following settings:

3.4

MQMD Persistence

= MQPER_NOT_PERSISTENT.

MQMD Expiry

= Set expiration time (in tenths of seconds).

MQMD ReplyToQ

= Set by the message originator.

MQMD ReplyToQmgr

= Set by the message originator.

MQPMO Options

= MQPMO_NO_SYNCPOINT.

UPDATE MESSAGES

Consider treating Update messages as persistent. There is usually a transactional integrity requirement
with updates, so these messages are normally processed using Syncpoint processing. Consider the
following settings:

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

3.5

MQMD Persistence

= MQPER_PERSISTENT.

MQMD Expiry

= MQEI_UNLIMITED.

MQMD ReplyToQ

= Set by the message originator.

MQMD ReplyToQmgr = Set by the message originator.

MQPMO Options

= MQPMO_SYNCPOINT.

REPORT MESSAGES

It is possible with WMQ messages to send a meaningful acknowledgement message which contains
no message data. In this case, all of the necessary message information is contained within the
Message Descriptor. These types of messages have the following characteristics:
MQMD Format

= MQFMT_REPORT.

MQMD Feedback

= MQFB_xxx (where xxx is the desired acknowledgement).

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

4.0

APPLICATION DEVELOPMENT BEST PRACTICES

4.1

INTRODUCTION

The principles and guidelines that this paper presents focus on use of a messaging paradigm to enable
asynchronous data processing. Use of queues focuses on the conversation between a requestor and
responder. This conversation can, for different purposes, have a variable number of interactions as a
way of effecting the communication between the two entities. The transfer of data using the
messaging concept gives a greater flexibility and the application developers need not worry about all
of the underlying architectural and infrastructural programming aspects. This insulation of the
application programmer is designed to accomplish the following goals:
Make the application independent of the underlying (messaging) engine. This generic
approach allows for substitution of any third party software by wrapping the core in
functions that all developers know and can use.
Isolate any functionality to a single source, which is, in effect isolating any potential bugs
to one place. The actual third party code is found in common libraries. These modules are
debugged once, and re-used everywhere.
Make the source code a shareable resource.
Make application maintenance independent of any external software (middleware, DBMS,
etc.).
This building block approach reduces or eliminates the developers' need to know the
intimate details of the engine, thereby increasing developer productivity.
A well-defined, well-designed, common API can be platform agnostic.
Functionality can be propagated across disparate platforms.

4.2

BEST PRACTICES

4.2.1 Application Design

1. All Queuing-based applications should have their application design reviewed by the
relevant Queue administrators prior to the beginning of programming.
Overview: Messaging and Queuing enables many possible solutions and approaches to a
fixed set of problems. Not all of the nuances of asynchronous messaging are apparent to
all application designers.

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

Justification: This review process provides two different benefits. The first benefit is
that the widest possible WMQ knowledge can be brought to bear during this critical
project phase. This is important because the second benefit is that this practice will
ensure that the application meets all necessary production requirements and is designed
for deployment.
2. Do not include other resource modifications (file I/O, database I/O, etc.) within a
Queue-based unit of work unless an external Resource Coordinator exists.
Overview: When WMQ is used for data integrity purposes, the integrity of the
application data must not be compromised. For example, database updates must be
synchronized with message I/O. No database updates should be performed twice, or not
performed at all, because message commit/rollback processing was not coordinated with
database commit/rollback processing.
Justification: Not all platforms on which WMQ runs are capable of the necessary two
phase commit processing required to support multiple updates across heterogeneous
resource managers. On these Open System platforms, the WMQ MQCMIT and
MQBACK calls apply only to the WMQ messages.
3. In general, avoid single threading message processing logic within applications.
Overview: Whenever possible, design applications to be able to have multiple readers
and/or multiple writers.
Justification: This allows the maximum flexibility for managing the performance and
capacity of the application. It also creates a flexible application architecture that is
conducive to future modifications. Additional, or new, application instances can write
messages to the queue. Additional application instances can read messages from the
queue. Channels will ideally be opened one time, and the readers and writers for those
channels will be made available and used repetitively. This is a huge resource savings
since instantiating any communication conduits are traditionally the most expensive
commodity in the system.

4.2.2 Dead Letter queue handling

4. Design the application to handle Dead Letter queue messages.
Overview: Messages may be sent to a Dead Letter queue on each Queue Manager that
the message passes through.
Justification: Any such messages will not be received by the application for which they
were destined. The design of the application must handle this basic fact.
5. Design an automated mechanism to process Dead Letter queue messages.

10

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

Overview: Messages may end up on a Dead Letter queue. This queue will quite likely be
shared by multiple applications.
Justification: The integrity of the application may depend upon processing all of the
applications messages. Messages routed to the Dead Letter queue will not be processed
by the intended application. A mechanism should be designed and built to extract and
process an applications messages from the Dead Letter queue. The reprocessing of these
messages must be a part of the design of the application. Note that this reprocessing may
be accomplished through tools (for example, copy messages to an application queue) or
through specific application programming.
6. Never write messages directly to the Queue Manager's Dead Letter queue.
Overview: There is a Dead Letter queue on each Queue Manager. This queue is for
messages that WMQ is unable to process. All undeliverable WMQ messages from all
applications are sent to this queue by the Messaging and Queuing Service.
Justification: It should not be used by applications as an error queue. This type of usage
only complicates the necessary processing required for these queues.
7. Create an application Error queue.
Overview: Applications will detect messages that they are unable to process. These
messages must be handled in some manner. They should not be sent to the local Dead
Letter queue.
Justification: It is the applications responsibility to handle its own messages. These
messages will require manual processing. The application should isolate and identify
these messages in a manner that facilitates their correct processing.

4.2.3 Interface to Messaging Services

8. The Application should encapsulate the interface to the underlying messaging
system.
Overview: Individual programs or classes need to process messages. A design decision
must be made as to how these units of code will access messaging services.
Justification: Irrespective of the API chosen to interface to the underlying messaging
software, this API should not be widely exposed. This design approach allows the
application to be in the best possible position to migrate to other technologies. If the API
is encapsulated behind application programs/classes providing the services, then it will
also be far easier to maintain and upgrade the application software. This approach has the
added advantage of hiding some of the complexities of the message vendors API.

11

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

9. The MQI should be used as the programmatic interface to WMQ services.

Overview: Applications have a choice of using the MQI, AMI, or JMS programmatic
interfaces.
Justification: Any interface used should be abstracted, so that the application is not
tightly coupled to the chosen interface. This design approach allows even more flexibility
than using a specific interface, such as JMS, provides and it avoids the costs of
implementing and administering the logical JMS system. It should be noted that all JMS
related costs are in addition to the underlying WMQ administration costs. As a final note,
the MQI interface is the only interface supported on all programming platforms and
languages.

4.2.4 MQI Calls - General

10. Check the MQCC (MQ Completion Code) on every WMQ call.
Overview: Native MQ API calls never ABEND. Not all language compilers force the
programmer to handle exceptions, which, if trapped and processed, could avert the need
for manual intervention.
Justification: Since MQI calls do not cause fatal errors or ABENDs (Abnormal Ends) in
all Operating System environments, this field must be checked to ensure that the call was
successful. If the value of this field is not MQCC_OK, then the appropriate error
processing should be performed. Additional response information can be found in the
MQRC (MQ Reason Code) field.
11. Set the MQxxx_FAIL_IF_QUIESCING field parameter on appropriate WMQ calls.
Overview: Specification of this attribute in WMQ function calls is necessary in order to
notify applications currently connected of an impending shutdown of services. In the
event that applications continue writing to queues after the Messaging and Queuing
Subsystem has been told to stop, data may persist. This can delay shutdown until the
incoming data have been processed, and thereby compromise the time frames in which
backups and regular maintenance might otherwise occur. Maintenance and backups are
normally conducted with empty queues.
Justification: This allows the WMQ applications shut down gracefully and prevents a
Force shutdown. This parameter should be used on MQOPEN, MQGET, MQPUT, and
MQPUT1 calls.

4.2.5 Queue Manager Connection Handling

12. In general, always use MQCONN and MQDISC calls.

12

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

Overview: Before any WMQ services can be obtained, a connection to a Queue Manager
must be made to a Queue Manager.
Justification: Even though these calls are not required in all environments, coding them
will allow the application code to be migrated to another platform without WMQ
modifications. Note that this recommendation can be ignored if the application code
contains significant environment specific commands (for example, EXEC CICS calls).
13. Do not hard code the Queue Manager connection parameters to which the
MQCONN connection is to be made.
Overview: Parameters are to be stored either in database tables or files to which only the
API has access. In this manner, it is possible to isolate the data that drive any action to
external data files and ensure that the executable code is fully functional and independent
of data that they process.
Justification: This information should be externalized (for example, in a file) and read
during runtime. This allows the Queue Manager to be changed without requiring any
application code changes since the required data elements are dynamically read
parameters.
14. Do not restrict MQCONN attempts to a single Queue Manager.
Overview: The various Queue Managers to which connection requests may be directed
need to be found in a resource file. In this manner, it is possible to isolate the data that
drive any attempts to connect to a queue(s), and retain the API's independence of the data
processed.
Justification: If the connection to the specified Queue Manager fails, then another
Queue Manager should be tried. This approach will result in significantly higher
application availability. As previously mentioned, this list of Queue Managers should be
externalized.
15. For Online Transaction Processing (OLTP), consider Queue Manager Connection
pooling.
Overview: Queue Manager connection pooling is a way of distributing the incoming
transaction load. This is a model that behaves exactly as adding more cashiers when the
lines in the supermarket become too deep. It serves to lessen the number of pending
transactions per queue, and makes handling the work load easier and more efficient.
Justification: For transactional types of applications, rather than each transaction having
its own paired connection/disconnection logic, consider designing the application to
maintain a pool of connections. In this way, the overhead of making a connection can be

13

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

shared across multiple transactions. This can lead to very substantial performance and
capacity increases.
16. Minimize the number of MQCONN calls executed within a program.
Overview: An application may not request WMQ services until a connection to the
Queue Manager has been made. This connection is established through the MQI
MQCONN call.
Justification: This is the single most costly WMQ call in terms of overhead. In normal
batch processing circumstances, the connection should be made once; at the beginning of
a programs processing loop. For OLTP transactions, connection pooling may be used.
17. Pair the MQCONN call with a matching MQDISC call.
Overview: It is an important principle to match function calls for memory allocation/deallocation, file open/close, session connect/disconnect as a way of ensuring (to the degree
that it is actually possible) that no memory leaks occur.
Justification: Structured design/programming techniques should be used to ensure that
every open connection is closed. This will conserve the Queue Manager pool of
connections.

4.2.6 Queue Open Handling

18. Do not hard code the Queue name to which the MQOPEN call is to be made.
Overview: The request to open a queue should be driven by an external data file or data
base table, secured and maintained by the Messaging and Queuing Administrator. In this
way, the application and its request are removed, or uncoupled, from having intimate
knowledge of the specific queue. If the name changes, only an entry in a file or a row in a
data base will change, and the application will feel no adverse effects.
Justification: This information should be externalized in a file and parameters extracted
from within. This allows the Queue to be changed without requiring any application code
changes.
19. Names of permanent dynamic queues must be predictable across multiple
invocations of the application.
Overview: Permanent dynamic queues are created and named when they are opened.
Justification: It is the responsibility of the application not to proliferate orphan queues.
If an application creates a permanent dynamic queue, the application must be able to
survive a restart and still successfully process the queue. The use of persistent identifiers,
such as User IDs, is one such way to create survivable queue names.

14

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

20. Do not open temporary dynamic queues for writing persistent messages.
Overview: Temporary dynamic queues are created and named when they are opened.
These queues may not hold persistent messages.
Justification: Any attempt to place a message identified as persistent in a temporary
dynamic queue will result in the message being sent to the Dead Letter queue. This is a
design or programming error and will never result in correct processing.
21. Minimize the number of MQOPEN calls executed within a program.
Overview: Since this is an expensive I/O operation, the number of open calls will be
reduced or eliminated. Ideally, the main loop or function of an application will perform
any needed opens and closes, exceptions being any dynamic opening and closing of
queues due to the need to maintain a flexible design and a malleable execution
environment.
Justification: This is a costly I/O function call in terms of overhead. In normal batch
processing circumstances, the queue should be opened once; at the beginning of a
programs processing loop.
22. For Online Transaction Processing (OLTP), consider Queue pooling.
Overview: Every access to a WMQ object requires a handle for the object. This handle
is obtained from the MQOPEN command.
Justification: For transactional types of applications, rather than having each transaction
have its own paired open/close logic, consider designing the application to maintain a
pool of queue handles. In this way, the overhead of opening a queue can be shared across
multiple transactions. Note that this pool can also be used to handle concurrent access to
the Queue.
23. Specify the correct access (Browse, Read, Update) options on the MQOPEN call.
Overview: The type of queue access desired must be specified when a queue is opened.
Justification: Depending upon how queues are defined, WMQ can lock queues to
prevent concurrent access. It is important to identify to WMQ the correct access required
so that unnecessary contention is avoided.
24. Pair the MQOPEN call with a matching MQCLOSE call.
Overview: It is an important principle to match function calls for memory allocation/deallocation, file open/close, session connect/disconnect as a way of ensuring (to the degree
that it is actually possible) that no memory leaks occur.

15

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

Justification: Structured design/programming techniques should be used to ensure that

every open connection is closed. This will conserve Queue Manager resources and
eliminate unnecessary lock contention.

4.2.7 Putting Messages

25. In general, never have a message receiving application reply to queues defined
within the receiving application.
Overview: It is proper queuing theory design to rely on the Queue Manager (traffic cop)
to distribute the work load properly. In this manner, the application is responsible only for
de-queuing its queue and not performing the task of distributing the queue's work load
over the individual underlying queues.
Justification: This effectively tightly couples the sending (Client) and receiving (Server)
applications. Instead, the server application should route its reply to the Queue Manager
and Queue described by the ReplyToQmgr and ReplyToQ of the MQMD (MQ Message
Descriptor). This decouples the client application from the server application and allows
considerable changes to be made on the client application(s) side without any impact to
the server application. See the associated practice under Putting Messages.
26. For the Request/Reply messaging pattern, specify the ReplyTo Queue Manager
and Queue parameters in the MQMD (MQ Message Descriptor).
Overview: The MQMD contains fields to define both the Queue Manager and the Queue
to which a response to the message should be sent.
Justification: This decouples the requesting application (Client) from the responding
application (Server). See the associated practice under Queue Handling.
27. In general, specify a Format of String on all appropriate messages.
Overview: In order for WMQ to perform character set conversion (for example, ASCI
to/from EBCDIC), the message format must be MQFMT_STRING.
Justification: If this field is set to a value of String and the Get Message Options
(GMO) field is set to a value of Convert, then the MQGET call will fail. If character
conversion is to be explicitly turned off, the value of MQFMT_NONE value should be
used and conversion should not be requested on the MQGET call. Note that with the
exception of the MQFMT_REPORT value, all other values for this field relate to specific
WMQ message formats and are not for general application use.
28. Assign Polo defined Message Types to each message.

16

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

Overview: The values in the MsgType field in the MQMD are not enforced by WMQ.
WMQ also provides for user-defined values within this field.
Justification: This field was designed to allow application message handling to be
defined dynamically, based upon differing field values. This has generally been found to
be needlessly complex within an application environment. By defining standardized
information, operational management information can be encoded within the message
header. This is particularly useful in managing Dead Letter queues. Possible values can
describe how to render (display) the message contents (for example, Text, XML, JPEG,
etc.), how to handle errors (severity levels, processing, etc).
29. In general, use queue defined message priorities.
Overview: The MQI allows message delivery priorities to be defined or managed at the
message, queue, or channel level.
Justification: While applications may be able to prioritize their own messages,
applications cannot make priority decisions about the messaging infrastructure as a
whole. In combination with appropriate messaging design, delivery prioritization is best
handled at the WMQ administrative level. Furthermore, messages will not be retrieved in
priority sequence unless the WMQ administrator has defined to queue to behave in that
manner. Thus, priority based behavior cannot be enforced at the programmatic level.

4.2.8 Getting Messages

30. In general, always include the MQGM_CONVERT parameter in the Get Message
Options (GMO) field.
Overview: The Message-Queuing middleware provides built-in facilities to perform data
conversion between heterogeneous environments. These facilities may be invoked either
by coding the convert parameter on the sending side channel to Yes, or by using the
convert option on the MQOPEN call (MQGMO_CONVERT). Conversions take place
optimally on the transmit side of the communication.
Justification: The receiving application should perform this conversion, not the channel.
This ensures that the target character set conversion is always applied. It also ensures that
multiple conversions are not performed when a message is routed across multiple
channels. Note that the MQFMT_ NONE parameter (for the Format field) may be used
for messages that should not be converted.
31. Always evaluate the BackoutCount field of the MQMD (MQ Message Descriptor).
Overview: When a message is retrieved under Syncpoint and subsequently backed out,
the BackoutCount field in the MQMD is incremented.

17

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

Justification: This field specifies the number of times a message has been the subject of
a MQOPEN request and subsequently rolled back. In a situation where getting a message
causes a fatal application error or ABEND, an infinite loop exists. The message will be
rolled back and then subsequently retrieved causing another fatal error. This is not
something that Message-Queuing middleware can prevent. It is the program's
responsibility to prevent this loop from occurring.

4.2.9 Message Content

32. Consider using XML syntax for encoding message content.
Overview: This allows message content to be coded for relational data bases by use of
start and stop tags, and embedding unstructured relational data to form the message
payload. With use of compression and encryption, relational data can be transacted with
facility and security.
Justification: This allows messages to be modified without necessarily requiring
application coding changes. Note that maximum message length changes may require
both WMQ coding and WMQ administrative changes. This practice also facilities
production error handling, as simple tools displaying message content may be used to
diagnose application errors.

18

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

5.0

APPENDIX A JAVA MESSAGING SERVICE (JMS)

5.1

INTRODUCTION

The JMS is a generic API for the Java programming language as a programmatic interface to any
messaging service. Therefore, any messaging service or middleware that has the ability to accept
function calls from a Java program, will support JMS. This is due to Java's deliberate isolation, as are
C and C++'s decoupling, from any messaging or queuing protocols. Java relies on the JMS as an
external series of functions to implement what is not a native part of the core language.
JMS provides an interface to its own internal messaging and queuing structures and features that are
public domain specifications and designed for Internet-based applications. This interface supports the
publish-subscribe model of messaging, and allows for asynchronous, loosely coupled applications
that may still need to communicate with one another.
The potential gain from JMS would come when either another vendor's technology was chosen to
replace WMQ, or, if a new technology came into being that provided additional functionality while
utilizing an identical interface to JMS. Again, both of these are rather unlikely scenarios. To
summarize, the JMS advantages are as follows:
WMQ could easily be replaced by a competitor product that supports JMS
WMQ could easily be replaced by a new technology that supports JMS
The first disadvantage of JMS is the introduction an artificial administration layer on top of the WMQ
layer. JMS is essentially a wrapper around the underlying MQI Services, and introduces some
computational overhead, resulting in a small loss of performance. JMS supports a subset of WMQ
capabilities, and consequently some product functionality is sacrificed. Finally, since JMS is a Java
only solution, non-Java software would continue to use a language and protocol mediator. This results
in both a reduction of the potential benefits and an increase in the skill set required to support
messaging. To summarize, the JMS disadvantages are as follows:
JMS involves additional administration on top of the Messaging and Queuing
administration
JMS involves a small loss in performance
Some Messaging and Queuing product functionality is sacrificed
Messaging skill set size increased
IBM supplies two interfaces to Messaging and Queuing services, the MQ Interface (MQI) and the
Application Messaging Interface (AMI). The MQI is the original interface and provides full
messaging capability and control. The AMI is a high-level interface designed to move some of the

19

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

control for the specification of messaging services out of the programming environment and into the
Messaging and Queuing administrative area.
To some extent, the decision as to which interface to use redirects attention from a far more important
interface design decision. The issue of the choice of interface is essentially a question of abstraction.
The basic design question revolves around the amount of detailed a knowledge that the underlying
service structure an application should have. Sound design inevitably leads to the abstraction of
messaging within an application, regardless of the messaging interface.

5.2

APPLICATION

OF

JMS

JMS is a useful API for achieving and implementing language and platform-agnostic messaging
interfaces. It too allows isolation of messaging and queuing functionality into an API library that,
once debugged, is a shareable, reliable, and reusable programmatic resource. Through use of such an
API, any breakdowns are then attributable to the application using the services and not the API itself,
as the API's functions are tried and true. One of the core differences between JMS and other services
lies with the byte-code, which can create a slight performance bottleneck if all Web-based services are
built in Java.
The current Best Practice is to create an enterprise wide abstract interface. This generalized
interface can be extremely simple for the overwhelming majority of applications. For those few
applications that require more sophistication, there are several options. It is possible to extend the
generalized interface or, alternatively, create a custom interface for the application. The usual
practice, however, is to use the underlying messaging API directly in the code for those few
applications, and accept the localized risk of more tightly coupling the application to the underlying
technology.

20

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

6.0

APPENDIX B SAMPLE APPLICATION PROGRAMMING

INTERFACE

There are numerous reasons for creating an abstract message and queuing interface for use within an
application. These reasons include:
Simplifying application development.
Isolating a proprietary API to minimize application dependency upon the API.
Ensuring consistent usage of WMQ messaging parameters within the application.
Augmenting the functionality of the existing MQI (for example, Connection Pooling).
There are many possible messaging API designs. The important criteria to use in creating an abstract
messaging interface is to separate the use of messaging by the application from the mechanics of the
vendor implementation of the messaging subsystem. The abstract interface should be as simple as
possible to meet all of the necessary business requirements.
The sample interface shown below is an extremely simple interface that will fulfill most messaging
needs for most applications. As can be easily seen, most of the messaging implementation details are
buried within the defined functions. The application calling these functions has little actual message
implementation knowledge.
Table 4: Sample Message and Queuing API
Function Name
OpenQueue

Parameters
QmgrName
QueueName
ReturnCode

WriteMessage

QmgrName
QueueName

Description
Open a queue for processing. This call will also result
in a Queue Manager connection being made, if it has
not already been done. If Queue Manager or Queue
pooling is to be performed, it can be implemented here.
Put a message on a queue. The message is not
committed.

MessageData
ReturnCode
ReadMessage

QmgrName
QueueName

Read a message from a queue. The message is not

committed.

MessageData
ReturnCode

21

January 30, 2009

POLO RALPH LAUREN

WEBSPHERE MQ BEST PRACTICES DESIGN & PROGRAMMING STANDARDS

Function Name
CloseQueue

Parameters
QmgrName,
QueueName
ReturnCode

MessageCommit

QmgrName,

Description
Close a queue for processing and release all WMQ
locks on the queue. This call will also result in a Queue
Manager connection being closed, if necessary. If
Queue Manager or Queue pooling is being performed,
the pool resources are freed here.
Commit all messages within a Unit of Work.

ReturnCode
MessageRollback

QmgrName,

Rollback all messages within a Unit of Work.

ReturnCode

22

January 30, 2009