Programming Using Base Classes for Java
Programming Using Base Classes for Java
cover
WebSphere MQ
Programming
Using Base Classes for Java
(Course Code MQ09)
Student Notebook
ERC 2.0
Trademarks
IBM® is a registered trademark of International Business Machines Corporation.
The following are trademarks of International Business Machines Corporation in the United
States, or other countries, or both:
AIX AS/400 CICS
DB2 IBM IMS
MQSeries OS/2 OS/390
OS/400 RACF SupportPac
WebSphere z/OS
Linux is a registered trademark of Linus Torvalds in the United States and other countries.
Microsoft, Windows, Windows NT Microsoft, Windows, Windows NT, and the Windows
logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
Java, Java Development Kit, JDBC, JDK and all Java-based trademarks are trademarks of
Sun Microsystems, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product, and service names may be trademarks or service marks of
others.
The information contained in this document has not been submitted to any formal IBM test and is distributed on an “as is” basis without
any warranty either express or implied. The use of this information or the implementation of any of these techniques is a customer
responsibility and depends While each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee
that the sa Customers attempting to adapt these techniques to their own environments do so at their own risk. The original reposi
© Copyright International Business Machines Corporation 2000, 2002. All rights reserved.
This document may not be reproduced in whole or in part without the prior written permission of IBM.
Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure i
V1.0
Student Notebook
Contents
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Course Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v
Agenda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
TMK Trademarks
The reader should recognize that the following terms, which appear in the content of this
training document, are official trademarks of IBM or other companies:
IBM® is a registered trademark of International Business Machines Corporation.
The following are trademarks of International Business Machines Corporation in the United
States, or other countries, or both:
AIX AS/400 CICS
DB2 IBM IMS
MQSeries OS/2 OS/390
OS/400 RACF SupportPac
WebSphere z/OS
Linux is a registered trademark of Linus Torvalds in the United States and other countries.
Microsoft, Windows, Windows NT Microsoft, Windows, Windows NT, and the Windows
logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
Java, Java Development Kit, JDBC, JDK and all Java-based trademarks are trademarks of
Sun Microsystems, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product, and service names may be trademarks or service marks of
others.
Course Description
WebSphere MQ Programming Using Base Classes for Java
Purpose
This classroom class teaches Java application programmers to
develop basic MQSeries applications written in Java. The course
contains extensive machine exercises.
Audience
The class is for Java programmers who want to learn to write basic
MQSeries applications.
Prerequisites
Students must know basic Java application programming and also
basic MQSeries information.
Objectives
After completing this course, you should be able to:
• Design and develop application programs for MQSeries Java
environment
• Develop Java applets and Java applications
• Connect and disconnect the application to a queue manager
• Work with messages
• Handle and manage exception conditions
• Manipulate message delivery
• Use triggering functions
• Write messages on a distribution list
Curriculum relationship
• MQ01 MQSeries Technical Introduction (classroom)
• MQ82 MQSeries Technical Introduction (CBT)
Agenda
Day 1
Welcome
Course Introduction and Administration
Unit 1 - Introduction
Unit 2 - Queue Manager Connection
Exercise 1 - Customize the Queue Manager
Unit 3 - Working with Queues
Exercise 2 - Basic Put and Get (Part 1)
Unit 4 - Error Handling
Unit 5 - Messaging and Queuing (Part 1)
Day 2
Day 1 - Review
Unit 5 - Messaging and Queuing (Part 2)
Exercise 2 - Basic Put and Get (Part 2)
Unit 6 - Message Types
Unit 7 -Retrieval of Messages
Exercise 3 - Request and Reply
Unit 8 - More on Messages
Exercise 4 - Triggered Server Application
Day 3
Day 2 - Review
Unit 9 - Security
Unit 10 - Units of Work
Exercise 5 - Get and Reply under Syncpoint
Unit 11 - Exits
Unit 12 - Multithreading
Exercise 6 - Put it Together
“End of Course” Evaluations
References
SC34-5456 MQSeries Using Java
http://www.ibm.com/software/ts/mqseries/messaging/
WebSphere MQ
http://www.java.sun.com
The Source for Java Technology
2EMHFWLYHV
/HDUQWKHEDVLF-DYDFRQFHSWV
$5HYLHZRI046HULHV
Notes:
:KDWLV-DYD"
$Q2EMHFW2ULHQWHGSURJUDPPLQJODQJXDJHGHYHORSHGE\
6XQ0LFURV\VWHPV
-DYDUHTXLUHVDYLUWXDOPDFKLQH UXQWLPHHQYLURQPHQW
Notes:
Java is an object oriented programming language, developed by Sun Microsystems. As
such, it incorporates many of the object-oriented characteristics of more traditional object
oriented languages like C++ or Smalltalk.
Like other OO languages, Java comes with a set of class libraries containing the code
which is used by your program to communicate with users, and with other machines.
Java applications are bundled up into deliverable chunks of code called "packages".
What makes Java different from the other members of the object oriented family is its ability
to "run anywhere". In theory, once written, a Java program can run on any machine which
has a Java Virtual Machine (JVM). The Java Virtual Machine provides the run-time
environment in which a Java program executes. Most Web browsers come with a JVM
built in, so that special Java programs called applets can be run inside the browser. It is
this aspect of Java which makes it so attractive for the writers of distributed applications.
Uempty
-90-DYD9LUWXDO0DFKLQH
-DYDLVFRPSLOHGWRE\WHFRGHVZKLFKDUHLQWHUSUHWHGE\
WKH-DYD9LUWXDO0DFKLQH -90
7KH-90UXQVVWDQGDORQHRUDVSDUWRIDQRWKHUVRIWZDUH
HQYLURQPHQWRQPDQ\RSHUDWLQJV\VWHPV
(QYLURQPHQW
MDYDF MDYD
-DYD -DYD -90
6RXUFH %\WHFRGH
MDYD FODVV
Notes:
JVM is the processor on which Java's byte-codes run. It is the instruction set that the
interpreter understands.
The Java compiler, javac, takes as input the java source code and produces as output,
java byte-codes. When the program is executed, these byte-codes are interpreted by the
JVM, which executes them by issuing instructions understood by the machine on which the
JVM is running. The Java compiler creates one .class file for each class definition.
Because the JVM is not unique to any particular hardware/operating system, .class files
are portable to any implementation of the JVM. Most Web browsers come with a JVM built
into them, to allow them to run special Java programs called applets. An applet is a Java
program which has been written to be downloadable to a Web Browser, and which usually
only supports a subset of the Java classes.
The JVM includes a byte-code verifier to validate byte-codes as they are imported into the
JVM It also includes a Class Loader, which can be used to perform security checking on
classes loaded over the network.
-'.-DYD'HYHORSPHQW.LW
3DFNDJHRIWRROVIRUZULWLQJ-DYDSURJUDPV
7KUHHSULQFLSDOWRROVDUH
MDYDFFRPSLOHV-DYDVRXUFHLQWRE\WHFRGH
MDYDH[HFXWHVVWDQGDORQHDSSOLFDWLRQV
DSSOHWYLHZHU7RROIRUWHVWLQJDSSOHWV
Notes:
JDK is a package of tools for writing Java programs.
Other parts of the JDK are:
javap - disassembles .class (bytecode) file
jar - creates archive file
javadoc - produces HTML documentation from source
jardesigner - prepares jar files to be authenticated
javah - creates header and stub for inter language linking
native2ascii - converts native to Unicode encoded file
jdb - a rudimentary debugger
rmic - creates stub and skeleton for RMI
keytool - creates pairs of keys used to "sign" and authenticate programs
rmiregistry - starts remote object registry naming server
policytool - defines authentication criteria and allowed functions of "trusted" programs
serialVer - creates unique id for serialization
Uempty The javap command can be used to extract and list a brief description of a .class file’s API,
but without any comments. It can also list the java bytecode with the -c flag.
The javadoc command was used to generate the apidocs using the “/**...*/” (documentation
comments).
-DYD3DFNDJHV
MDYDDSSOHW $SSOHWGHYHORSPHQW
MDYDDZW $EVWUDFW:LQGRZ7RRONLW
MDYDDZWHYHQW ,QSXWHYHQWSURFHVVLQJ
MDYDLR ,QSXWRXWSXWVWUHDPV
MDYDODQJ &RUHODQJXDJHVXSSRUW
MDYDQHW 1HWZRUNLQJVXSSRUW
MDYDXWLO 0LVFHOODQHRXVXWLOLW\VXSSRUW
MDYD[VZLQJ 5HOHDVH*8,VXSSRUW
Notes:
java.applet provides the base class for all Applets. It also provides interfaces to the Web
Browser and the services it exports.
java.awt is the GUI class library. It provides support for the development of User-Interfaces.
java.awt.event provides support events and processing input. New for version 1.1.
java.io provides support for stream based I/O. It also supports files and file descriptors. Two
major divisions exist for byte and character streams. Character streams are new for
Version 1.1.
java.lang is the set of fundamental classes which make up Java's environment. These
include String, Thread, System, Runtime,...
java.net provides support for operating in a networked environment, e.g. Sockets, URLs,
etc.
java.util includes useful miscellaneous classes including some basic container classes.
javax.swing contains new light-weight GUI objects Jxxxxxx.
Uempty There are many more packages included with Version 1.2 of the Java Development Kit.
See the API documentation for more information on these and the other packages.
:KDWLVD-DYD&ODVV"
3RLQW
3RLQW
[B
\B
GLVWDQFH)URP
SXEOLFFODVV3RLQW^
SULYDWHIORDW[B
D3RLQW
SULYDWHIORDW\B
SXEOLF3RLQW IORDW[YDOIORDW\YDO ^
[B [YDO\B \YDO`
SXEOLFIORDWGLVWDQFH)URP 3RLQWUHISW ^
`
`
Notes:
The Java language is a class-based object-oriented language, implementing inheritance.
Your Java program will probably create a class, which does three things:
1. Encapsulates your new code so that the implementation is hidden from the users of your
code.
2. Inherits the characteristics of another, higher class, of which yours is a subset
3. Provides one or more methods which cause your code to perform some action related to
an instantiation of your class.
When you define a class, you define how an object of that class will look and behave once
instantiated.
In our example here, we have a class Point, which has one public function, the
distanceFrom function. Once we have written our Java class file, any other Java program
can instantiate two Point objects, passing values for the x and y coordinates, and then
invoke the distanceFrom method of one of the points, passing the other as an input
parameter, to find out the distance between the two points.
&ODVV6\QWD[
>PRGLILHU@FODVV&ODVV1DPH!>H[WHQGV&ODVV1DPH!@
>LPSOHPHQWVLQWI1DPHV!@^`
3RLQW
3RLQW
[B
&ODVV
\B
GLVWDQFH)URP
D3RLQW
Notes:
Modifiers - A class can be specified as any of:
• abstract - No objects can be instantiated. Only an abstract class may declare abstract
methods
• final - No subclasses
• public - Accessibility from outside of its package
Extends - (Optional) Name of the class which is the immediate superclass
Implements - (optional) name of the interface(s) implemented by this class. If the class is
not abstract, then every method of each interface must be defined by some superclass or
by itself.
Uempty
0HWKRG6\QWD[
>PRGLILHU@&ODVV1DPH!PHWK1DPH! >DUJV!@
>WKURZV([FHSW1DPH/LVW!@^`
3RLQW
3RLQW
[B
0HWKRG
\B
GLVWDQFH)URP
D3RLQW
Notes:
Modifiers - In addition to access specifiers:
• static - class method. Does not require an object of class. Only has access to static fields
and methods
• abstract - no implementation provided, subclass must implement or redeclare abstract
• final - cannot be overridden. (A private method is effectively final)
• native - declares a signature for code to be implemented outside of Java
• synchronized - states that a thread must acquire a monitor lock prior to execution
Throws list - Declares any exceptions that result from its execution
Again, many combinations of the modifiers are legal.
Like static (class) variables, a static method may be called by using the class name as the
"scope" resolution. For example:
public class X
{
public static void f1() { /* ... */ }
}
Y y = new Y();
y.f1(); // invoke static method f1
Note, these are different. Static methods can be dispatched using "Class." or "object.," but
the behavior is the static type of the object reference. Thus, above, y.f1() looks at the
runtime type of y to determine which f1 method to invoke. In the case of X.f1(), the method
is statically dispatched.
Uempty
&RQVWUXFWRUV
3RLQW
3RLQW
[B
&RQVWUXFWRU
\B
GLVWDQFH)URP
D3RLQW
Notes:
Every class in Java has at least one constructor method, which has the same name as the
class. When the constructor method of a class is invoked, all necessary initialization for a
new instance of that class is performed. If no constructor is defined for a class, Java uses
a default constructor that takes no arguments, and performs no special initialization for that
class.
Java allows you to define more than one constructor for a class, so that you can use the
one which is most suited to the circumstances in which you are working.
You can use the usual modifiers, but in general you would expect constructors to be public
methods.
046HULHV&RPPHUFLDO0HVVDJLQJ
$VLQJOHPXOWLSODWIRUP$3,
$VVXUHGPHVVDJHGHOLYHU\
)DVWHUDSSOLFDWLRQGHYHORSPHQW
7LPHLQGHSHQGHQWSURFHVVLQJ
$SSOLFDWLRQSDUDOOHOLVP
4XHXH
%
$
4XHXH
Notes:
In a commercial messaging environment, programs send data to other programs by putting
the data in the form of messages onto queues.
Programs do not have to be concerned with the availability of the receiving program or the
network that might lie in between.
Once a program receives a successful return code from the call that puts the message on
the queue, it is free to continue to do other work. The delivery of the message becomes the
responsibility of the queue manager.
The getting application can be started when a message arrives on its queue. This is called
event-driven or message-driven processing.
Uempty
7KH7KUHH6W\OHVRI&RPPXQLFDWLRQ
&RQYHUVDWLRQDO
3URJUDP 3URJUDP
$ %
0HVVDJLQJ
3URJUDP
%
3URJUDP
&
Notes:
Conversational or transaction oriented communication is characterized by two or more
programs executing in a cooperative manner to perform a transaction. They communicate
with each other through an architected interface. While one program is waiting for a reply
from another program with which it is communicating, it may continue with other
processing. APPC, CPI-C and the sockets interface of TCP/IP are examples of this type of
communication.
The call and return style is similar, except that the interface is structured to resemble a
call-and-return mechanism. When one program calls another program, the former is
blocked and cannot perform any other processing. Remote procedure call (RPC) is an
example of this style of communication.
The messaging style implies that communicating programs can execute independently. An
executing program receives input in the form of messages and outputs its results also as
messages. A message that is the output from one program becomes the input to another
program, but there is no requirement that the latter must be executing when the former
outputs the message. Contrast this with the conversational ant call-return styles where all
cooperating partners must be executing at the same time. The messaging style is used by
MQSeries.
Uempty
4XHXHV
352*5$0 352*5$0
:5,7( 5($'
352*5$0 352*5$0
04387 04*(7
Notes:
Queues are as easy to access as files. However, there are some major differences to be
aware of:
• GETting a message from a queue can delete it from the queue
• When a message is PUT on a queue in syncpoint, it becomes visible to another process
as soon as it is committed.
Typically, records are written to a file and when the file is closed, the records are made
available to be read. The immediate nature of message delivery means that messages can
still be PUT by the initiating application while the retrieving application is GETting message.
This can allow for shorter overall processing.
4XHXH0DQDJHUV
352*5$0
'%
'$7$
352*5$0 48(8(
0$1$*(5 0(66$*(6
48(8(0$1$*(5
352*5$0
Notes:
Queues are controlled by a queue manager.
Queue managers provide:
• interface to messages on queues (the MQI)
• security and authorization control
• administration control
Uempty
3XEOLVK6XEVFULEH
%52.(5
Notes:
With MQSeries Publish/Subscribe, you eliminate the need for an application to know
specifically where to send data. All it does is send information it wants to share to a
standard destination managed by MQSeries Publish/Subscribe, and let MQSeries
Publish/Subscribe deal with the distribution. The target application does not have to know
anything about the source of the information it receives.
Publishers supply information about a subject, without having any knowledge about the
applications that are interested in the information.
Subscribers decide what information they are interested in, and wait to receive that
information. Subscribers can receive information from many different publishers, and the
information can also be sent to other subscribers. The information is sent in an MQSeries
message, and the subject of the information is identified by a topic. The publisher specifies
the topic when it publishes the information, and the subscriber specifies the topics on which
it wishes to receive publications. The subscriber is only sent information about those topics
it subscribes to.
Interactions between publishers and subscribers are all controlled by a broker. The broker
receives messages from publishers, and subscription requests from subscribers (to a
range of topics). The broker's job is to route the published data to the target subscribers.
The broker uses standard MQSeries facilities to do this, so applications can use all the
features that are available to existing MQSeries applications. This means that you can use
persistent messages to get once-only, assured delivery, and that messages can be part of
a transactional units-of-work to ensure that messages are delivered to the subscriber only if
they are committed by the publisher.
Uempty
04,0HVVDJLQJDQG4XHXLQJ,QWHUIDFH
6LPSOH&$// 0LQRUFDOOV
LQWHUIDFH 04,14
046(7
04&211;
0DMRUFDOOV
04%(*,1
04&211
04&0,7
0423(1
04%$&.
04387
04387
04*(7
04&/26(
04',6&
Notes:
A brief look at the calls:
• MQCONN Connect to a queue manager
• MQOPEN Open an MQSeries object
• MQPUT Place a message on a queue
• MQPUT1 Put a single message on a queue (not available with MQSeries for Java
classes)
- No MQOPEN required
- No MQCLOSE required
- Use for single messages only
• MQGET Retrieve a message from a queue
• MQCLOSE Close an MQSeries object
• MQDISC Disconnect from a queue manager
Uempty
%XLOGLQJDQ046HULHV-DYD$SSOLFDWLRQ
3URJUDP
6RXUFH
046HULHVIRUMDYD
FODVVHV
MDYDF
%<7(&2'(
Notes:
The procedure to follow for successful compilation is slightly different for each Java
development environment, you should refer to the products documentation.
046HULHVIRU-DYD&ODVVHV
046HULHVIRU-DYD&ODVVHVDUHLQFOXGHGLQWKHIROORZLQJ
MDUILOHV
FRPLEPPTMDU 7KLVFRGHLQFOXGHVVXSSRUWIRUDOOWKH
FRQQHFWLRQRSWLRQV
FRPLEPPTLLRSMDU 7KLVFRGHVXSSRUWVRQO\WKH
9LVLEURNHUFRQQHFWLRQ
FRPLEPPTELQGMDU 7KLVFRGHVXSSRUWVRQO\WKHELQGLQJV
FRQQHFWLRQ
Notes:
The MQSeries classes for Java allow a program written in the Java programming language
to connect to MQSeries as an MQSeries client, or directly to an MQSeries server. It
enables Java applets, applications, and servlets to issue calls and queries to MQSeries
giving access to mainframe and legacy applications, typically over the Internet, without
necessarily having any other MQSeries code on the client machine. With the MQSeries
classes for Java the user of an Internet terminal can become a true participant in
transactions, rather than just a giver and receiver of information.
Uempty
(QYLURQPHQW
7RUXQ046HULHV%DVH&ODVVHVIRU-DYDWKHIROORZLQJ
VRIWZDUHLVUHTXLUHG
046HULHVIRUWKHVHUYHUSODWIRUP
-DYD'HYHORSPHQW.LWIRUWKHVHUYHUSODWIRUP
-DYD'HYHORSPHQW.LWRU-DYD5XQWLPH(QYLURQPHQW
RU-DYDHQDEOHG:HEEURZVHUIRUFOLHQWSODWIRUPV
7RUXQ3XE6XEDSSOLFDWLRQVDOVRWKHIROORZLQJLV
QHHGHG
046HULHV3XEOLVK6XEVFULEH
RU:HE6SKHUH04,QWHJUDWRU
Notes:
To run MQSeries base Java, you require the following software:
• MQSeries for the server platform you wish to use.
• Java Development Kit (JDK) for the server platform.
• Java Development Kit, or Java Runtime Environment (JRE), or Java-enabled Web
browser for client platforms.
• For z/OS & OS/390, OS/390 Version 2 Release 9 or higher, or z/OS, with UNIX System
Services (USS).
• For OS/400, the AS/400 Developer Kit for Java, 5769-JV1, and the Qshell Interpreter,
OS/400 (5769-SS1) Option 30.
Please check the README file for the latest information about operating system levels this
product has been tested against.
6XSSRUW3DFV
0$046HULHVFODVVHVIRU-DYDDQG046HULHV
FODVVHVIRU-DYD0HVVDJH6HUYLFH
0$&046HULHV3XEOLVK6XEVFULEH
06%046HULHV-DYDFODVVHVIRU3&)
Notes:
SupportPac MA88 provides support for developing MQSeries Java applications through
the MQSeries classes for Java and the MQSeries classes for Java Messaging Service
(JMS).
SupportPac MA0C is a product extension that helps to distribute information to where it is
wanted. Providers and consumers of information don’t need to know anything about each
other. Information is sent to MQSeries Publish/Subscribe, which looks after the distribution.
MQSeries Publish/Subscribe is available for Microsoft Windows NT, Windows 2000, AIX,
HP-UX, Linux and Sun Solaris.
SupportPac MS0B contains a set of Java classes representing PCF header structures as
well as an agent that can be used to simplify the task of communicating with a target queue
manager and thus enable the use of MQSeries Programmable Command Formats for
queue manager administration.
The MQSeries Programmable Command Formats (PCF) provide the capability to perform
administration tasks on a queue manager by sending and receiving MQSeries messages of
Uempty a special format. PCF request messages are sent to the queue manager's command
queue, where they are processed by the command server and replies returned to the
designated reply-to queue.
6XPPDU\
<RXVKRXOGQRZXQGHUVWDQGWKHEDVLF-DYDFRQFHSWV
-90-'.
&ODVVHV
0HWKRGV
DQGWKHEDVLF046HULHVFRQFHSWV
0HVVDJLQJ
4XHXHPDQDJHUV
4XHXHV
Notes:
References
SC34-5456 MQSeries Using Java
GC33-1632 MQSeries Clients
http://www.ibm.com/software/ts/mqseries/messaging/
WebSphere MQ
© Copyright IBM Corp. 2000, 2002 Unit 2. Queue Manager Connection 2-1
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
2EMHFWLYHV
%LQGLQJVPRGHYV&OLHQWFRQQHFWLRQPRGH
$SSOHWYV$SSOLFDWLRQ6HUYOHW
6HWWLQJXSWKH04HQYLURQPHQW
&RQQHFWLQJWRDTXHXHPDQDJHU
7KH044XHXH0DQDJHUFODVV
'LVFRQQHFWLQJIURPDTXHXHPDQDJHU
Notes:
© Copyright IBM Corp. 2000, 2002 Unit 2. Queue Manager Connection 2-3
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
:KDWLVD4XHXH0DQDJHU"
4XHXH
3URJUDP 0DQDJHU 0HVVDJHV
4XHXH0DQDJHU
3URJUDP
4XHXH
4XHXH
Notes:
Queues are controlled by a queue manager.
Queue managers provide:
• interface to messages on queues (the MQI)
• security and authorization control
• administration control
A queue manager is managed using the MQQueueManager class.
Uempty
&RQQHFWLRQ7\SH
" 046(5,(6
3URJUDP 48(8(
0$1$*(5
Notes:
The way you program for MQSeries classes for Java has some dependencies on the
connection modes you want to use.
There are two connection modes for connecting to a queue manager:
1. Client connections (as an MQSeries client using TCP/IP)
2. Bindings mode (connecting directly to MQSeries).
© Copyright IBM Corp. 2000, 2002 Unit 2. Queue Manager Connection 2-5
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
&RQQHFWLRQ7\SH&OLHQW&RQQHFWLRQV
046HULHV
$SSOLFDWLRQ
046HULHV
046HULHV
4XHXH
&OLHQW&RGH
0DQDJHU
&/,(170$&+,1( 6(59(50$&+,1(
Notes:
An application that runs in the MQSeries client environment must first be linked with the
relevant client library. When the application issues an MQI (Message Queue Interface) call,
the MQSeries client code directs the request to a queue manager, where it is processed
and from where a reply is sent back to the MQSeries client. The link between the
application and the MQSeries client code is established dynamically at runtime.
The MQI is available to applications running on the client platform; the queues and other
MQSeries objects are held on a queue manager that is installed on a server machine.
If you are using MQ Java as an MQSeries client, it can be installed either on the MQSeries
server machine, which may also contain a Web server, or on a separate machine.
Installation on the same machine as a Web server has the advantage of allowing you to
download and run MQSeries client applications on machines that do not have MQ Java
installed locally.
Uempty
&RQQHFWLRQ7\SH%LQGLQJV0RGH
3URJUDP
-1,
48(8(0$1$*(5
Notes:
This mode is also known as the "native connection" mode.
When used in bindings mode, MQ Java uses the JNI (Java Native Interface) to call directly
into the existing queue manager API rather than communicating through a network. This
provides better performance for MQSeries applications than using network connections.
Unlike client mode, applications written using the bindings mode cannot be downloaded as
applets.
To use the bindings connection, MQ Java must be installed on the MQSeries server.
In bindings mode, most of the parameters provided by the MQEnvironment class are
ignored. This class shall be further exposed in the following pages.
© Copyright IBM Corp. 2000, 2002 Unit 2. Queue Manager Connection 2-7
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
:KDW VWKH$GYDQWDJH"
-DYD&OLHQW
(QGXVHUVGRQ WQHHGWRUXQ046HULHVFRGH
'RZQORDGDEOHDSSOHWV
(DV\PDLQWHQDQFHDQGKLJKUHXVDELOLW\
$OORZVHYHU\RQHWRSDUWLFLSDWHIXOO\LQWUDQVDFWLRQV
-DYD%LQGLQJV
+LJKSURGXFWLYLW\DQGSHUIRUPDQFHGHYHORSPHQWRSWLRQ
$SSOLFDWLRQVFRPPXQLFDWHGLUHFWO\ZLWKWKHTXHXH
PDQDJHU
Notes:
The most important advantage to using the MQSeries for Java Client is that the end-user
does not need to run any MQSeries code. It opens the MQSeries network to all
participants. The MQSeries for Java Client allows Internet applications easy access to
MQSeries networks, via downloadable applets.
The most important advantage to using the MQSeries for Java Bindings is that they enable
MQSeries server-side applications to be written using the Java programming language.
Uempty
-DYD%DVLFV$SSOLFDWLRQYV$SSOHW
$SSOLFDWLRQ
046HULHV6HUYHU
046HULHV
:HE6HUYHU
6HUYHU -DYD$SSOHW
,QWHUQHW
RU,QWUDQHW
-DYD$SSOLFDWLRQ
$SSOLFDWLRQ
$SSOHW
Figure 2-7. Java Basics: Application vs. Applet MQ092.0
Notes:
You can create two different types of programs with Java: applications and applets.
Applets are restricted programs: they are intended to be delivered over the Internet.
Applets are small, and do not have access to all Java functions. This restriction provides
the security required to avoid intentional data corruption and viruses.
Applications do not have to be run in a browser or an applet viewer, which is why they are
often used as servlets, running on the MQ Server.
The principal difference between the two is that an application requires a main() method to
run, whereas an applet does not.
© Copyright IBM Corp. 2000, 2002 Unit 2. Queue Manager Connection 2-9
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
'HILQLQJ:KLFK&RQQHFWLRQWR8VH
&ODVV04(QYLURQPHQW
SXEOLFVWDWLFMDYDXWLO+DVKWDEOHSURSHUWLHV
NH\
04&75$163257B3523(57<
YDOXHV
04&75$163257B046(5,(6B%,1',1*6
04&75$163257B046(5,(6B&/,(17
04&75$163257B046(5,(6
Notes:
The connection is determined by the key/value pairs contained in the properties variable of
the MQEnvironment class.
For client connections, use:
MQEnvironment.properties.put(MQC.TRANSPORT_PROPERTY,
MQC.TRANSPORT_MQSERIES_CLIENT)
For bindings connections, use:
MQEnvironment.properties.put(MQC.TRANSPORT_PROPERTY,
MQC.TRANSPORT_MQSERIES_BINDINGS)
The default value for MQC.TRANSPORT_PROPERTY is
MQC.TRANSPORT_MQSERIES. In this case, the connection type is selected according to
the value of the "hostname" variable of the MQEnvironment class (if the hostname is not
set, then bindings mode will be used).
Uempty
2WKHU8VHIXO04(QYLURQPHQW9DULDEOHV
04(QYLURQPHQWKRVWQDPH
04(QYLURQPHQWSRUW
04(QYLURQPHQWFKDQQHO
04(QYLURQPHQWXVHU,'
04(QYLURQPHQWSDVVZRUG
Notes:
For client connections, it is often necessary to set these variables before trying to connect
to a queue manager.
hostname public static String hostname
The TCP/IP hostname of the machine on which the MQSeries
server resides. If the hostname is not set, and no overriding
properties are set, bindings mode is used to connect to the local
queue manager.
port public static int port
The port to connect to. This is the port on which the MQSeries
server is listening for incoming connection requests. The default
value is 1414.
channel public static String channel
© Copyright IBM Corp. 2000, 2002 Unit 2. Queue Manager Connection 2-11
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
Uempty
&RQQHFWLQJWRD4XHXH0DQDJHU
4XHXH
3URJUDP
0DQDJHU
Notes:
To connect to a queue manager, all you need to do is create a new instance of the
MQQueueManager class:
MQQueueManager queueManager = new MQQueueManager("qMgrName");
If the queue manager name is left blank (null or ""), a connection is made to the default
queue manager.
© Copyright IBM Corp. 2000, 2002 Unit 2. Queue Manager Connection 2-13
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
&RPSOHWLRQDQG5HDVRQ&RGHV
&RPSOHWLRQ&RGHV
04&&B121(
04&&B:$51,1*
04&&B)$,/('
5HDVRQ&RGHV
045&B121(
045&B$/5($'<B&211(&7('
045&B$127+(5B4B0*5B&211(&7('
045&B4B0*5B67233,1*
045&B127B$87+25,=('
045&B4B0*5B127B$9$,/$%/(
Notes:
All connection attempts will result in one of the three listed completion codes:
0 a successful call completed
1 warning - the call completed but reason code indicates certain conditions
2 failed - the call did not complete successfully
The programmer needs to handle exceptions to check of completion codes and reason
codes.
The list of reason codes is an example of some of the most common that might occur when
a connection is attempted.
Uempty
7HVWLQJWKH&RQQHFWLRQ
&ODVV044XHXH0DQDJHU
0HWKRGSXEOLFERROHDQLV&RQQHFWHG
Notes:
You can use the isConnected method of the MQQueueManager class to test the
connection to a queue manager:
public boolean isConnected()
Returns the value True if the connection to the queue manager is still open.
© Copyright IBM Corp. 2000, 2002 Unit 2. Queue Manager Connection 2-15
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
'LVFRQQHFWLQJIURPD4XHXH0DQDJHU
3URJUDP
; 4XHXH
0DQDJHU
TXHXH0DQDJHUGLVFRQQHFW
Notes:
To disconnect from a queue manager, call the disconnect() method on the queue manager:
queueManager.disconnect();
(queueManager being the name of the MQQueueManager object)
Calling the disconnect method causes all open queues and processes that you have
accessed through that queue manager to be closed. It is good programming practice,
however to close these resources yourself when you have finished using them (you will
learn how to do this in Unit 3).
When you have disconnected from a queue manager, the only way to reconnect is to
create a new MQQueueManager object.
Uempty
([DPSOH
SULYDWH044XHXH0DQDJHUT0JUGHILQHDTXHXH0DQDJHUREMHFW
6HWXS046HULHVHQYLURQPHQW
04(QYLURQPHQWKRVWQDPH P\BKRVWQDPH
04(QYLURQPHQWFKDQQHO P\BVHUYHUBFKDQQHO
04(QYLURQPHQWSRUW
T0JUGLVFRQQHFW 'LVFRQQHFWIURPWKHTXHXHPDQDJHU
Notes:
The above example shows how to connect to a queue manager using the client connection
mode.
© Copyright IBM Corp. 2000, 2002 Unit 2. Queue Manager Connection 2-17
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
© Copyright IBM Corp. 2000, 2002 Unit 2. Queue Manager Connection 2-19
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
8QLW&KHFNSRLQW
:KDWLVWKHQDPHRIWKH046HULHVFODVVWKDWLVXVHGWR
PDQDJHDTXHXHPDQDJHU"
:KLFKFRQQHFWLRQW\SHXVHVWKH-DYD1DWLYH,QWHUIDFHWR
FRQQHFWWRDTXHXHPDQDJHU"
D &OLHQW0RGH
E %LQGLQJV0RGH
,IWKHKRVWQDPHHQYLURQPHQWYDULDEOHLVQRWVHWZKDW
FRQQHFWLRQPRGHZLOOEHXVHGE\GHIDXOW"
D &OLHQW0RGH
E %LQGLQJV0RGH
:KDWLVWKHFRUUHFWV\QWD[WRFRQQHFWWRDTXHXH
PDQDJHU"
D TXHXH0DQDJHU QHZ044XHXH0DQDJHU T0JU1DPH
E TXHXH0DQDJHUFRQQHFW
Notes:
Uempty
6XPPDU\
<RXVKRXOGQRZNQRZKRZWRXVHWKHIROORZLQJ
046HULHVFODVVHVWRFRQQHFWWRDQGGLVFRQQHFWIURPD
VSHFLILFTXHXHPDQDJHU
04(QYLURQPHQW
044XHXH0DQDJHU
<RXVKRXOGDOVREHDFTXDLQWHGZLWKWKHGLIIHUHQW
FRQQHFWLRQPRGHVDQGXQGHUVWDQGWKHGLIIHUHQFHV
EHWZHHQDQ04DSSOHWDQGDQ04DSSOLFDWLRQ
Notes:
© Copyright IBM Corp. 2000, 2002 Unit 2. Queue Manager Connection 2-21
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
References
SC34-5456 MQSeries Using Java
GC33-1632 MQSeries Clients
SC33-1673 MQSeries Application Programming Reference
http://www.ibm.com/software/ts/mqseries/messaging/
WebSphere MQ
© Copyright IBM Corp. 2000, 2002 Unit 3. Working with Queues 3-1
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
2EMHFWLYHV
2SHQLQJDQGFORVLQJTXHXHV
6HWWLQJRSHQDQGFORVHRSWLRQV
4XHXH7\SHV
Notes:
© Copyright IBM Corp. 2000, 2002 Unit 3. Working with Queues 3-3
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
$FFHVVLQJ4XHXHV
044XHXH0DQDJHU
4XHXH
044XHXH
352*5$0 48(8(0$1$*(5
&ODVV044XHXH0DQDJHU
SXEOLFV\QFKURQL]HG044XHXHDFFHVV4XHXH
6WULQJTXHXH1DPH
LQWRSHQ2SWLRQV
6WULQJTXHXH0DQDJHU1DPH
6WULQJG\QDPLF4XHXH1DPH
6WULQJDOWHUQDWH8VHU,G
Notes:
Queues are accessed using the accessQueue method of the MQQueueManager class.
The accessQueue method returns a new object of class MQQueue. For example, to open a
queue on a queue manager "queueManager", use the following code:
MQQueue queue = queueManager.accessQueue(
"qName",
MQC.MQOO_OUTPUT,
"qMgrName",
"dynamicQName",
"altUserID");
Uempty With MQSeries classes for Java, you can also create a queue object using the MQQueue
constructor. The parameters are exactly the same as for the accessQueue method, with
the addition of a queue manager parameter. For example:
MQQueue queue = new MQQueue(
queueManager,
"qName",
MQC.MQOO_OUTPUT,
"qMgrName",
"dynamicQName",
"altUserID");
© Copyright IBM Corp. 2000, 2002 Unit 3. Working with Queues 3-5
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
2SHQ2SWLRQV
2SHQ2SWLRQVVSHFLI\RSHUDWLRQVUHTXLUHG
04&0422B,1387B6+$5('
04&0422B,1387B(;&/86,9(
04&0422B,1387B$6B4B'()
04&0422B287387
04&0422B%52:6(
2EMHFWFDQEHRSHQHGIRUDFRPELQDWLRQRIRSWLRQV
2SWLRQVPXVWEHYDOLGIRUREMHFWW\SH
8VHUPXVWEHDXWKRUL]HGIRUDOORSWLRQVUHTXHVWHG
6SHFLILHGRSWLRQVPXVWQRWEHFRQWUDGLFWRU\
Notes:
Open options specify what a program wants to do with the object it is opening. Those listed
are some of the most common but there are others. If more than one option is required the
values can be added together or combined using the bitwise OR operator.
For instance, a common pair of options is MQC.MQOO_INPUT_SHARED and
MQC.MQOO_BROWSE. Generally, a browse will be done to determine if there are any
messages that meet some processing criteria. If so, the application will want to take the
message off the queue for processing. However, combining
MQC.MQOO_INPUT_EXCLUSIVE and MQC.MQOO_INPUT_SHARED is not valid.
Note that the program can defer to the queue definition for the open options to be used.
Uempty
5HDVRQ&RGHVZKHQ2SHQLQJD4XHXH
045&B121(
045&B127B$87+25,=('
045&B2%-(&7B,1B86(
045&B237,21B127B9$/,'B)25B7<3(
045&B237,216B(5525
045&B81(;3(&7('B(5525
Notes:
There are many reason codes that can be returned if an open call is unsuccessful. The
Application Programming Reference contains a description of each along with
recommended actions.
© Copyright IBM Corp. 2000, 2002 Unit 3. Working with Queues 3-7
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
&ORVLQJD4XHXH
FORVH2SWLRQV 04&04&2B121(
TXHXHFORVH
Notes:
When you have finished using the queue, close it using the close() method of MQQueue
class, as in the above example.
public synchronized void close()
Closing a queue will return a completion code and a reason code. These are documented
in the Application Programming Reference.
You can also set close options before closing a queue using the closeOptions variable of
the MQQueue object:
public int closeOptions
Set this attribute to control the way the resource is closed. The default value is
MQC.MQCO_NONE, and this is the only permissible value for all resources other than
permanent dynamic queues.
Uempty For these queues, the following additional values are permissible:
MQC.MQCO_DELETE
Delete the queue if there are no messages.
MQC.MQCO_DELETE_PURGE
Delete the queue, purging any messages on it.
© Copyright IBM Corp. 2000, 2002 Unit 3. Working with Queues 3-9
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
$OLDV4XHXHV
3URJUDP
4XHXH0DQDJHU
044XHXH $OLDV4XHXH
4XHXH
Notes:
An alias queue is simply a definition. It allows a local or remote definition to be referred to
by another name. An alias queue can actually have some different properties from the
underlying queue it is pointing to. For instance, a queue can allow Getting and Putting
messages, while its alias only allows Getting.
It is important to note that the program thinks that the alias queue it is working with is a
"real" queue, not simply a pointer to another queue.
The advantage of using aliases is that you can change queue names and properties
without having to update programs, as long as the aliases still point to the correct base
queue.
Uempty
0RGHO4XHXHV
0RGHO4XHXH
3URJUDP
DFFHVV4XHXH 4XHXH
Notes:
When an administrator defines a model queue, that definition is nothing more than a
template. When used as the queueName in the accessQueue method, the result is that a
queue is dynamically created that has all the attributes of the model. The model itself is
never actually used for anything else.
Thus, a program is simply creating a queue that looks like the model. We will talk about
names and types of dynamic queues in the next few pages.
© Copyright IBM Corp. 2000, 2002 Unit 3. Working with Queues 3-11
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
'\QDPLF4XHXHV
0RGHO4XHXH
7(0325$5<
3(50$1(17 '<1$0,&48(8(
'<1$0,&48(8(
Notes:
When a model queue is defined by the administrator, one of the attributes will ultimately
determine whether the dynamic queue your program creates will be long-lived or not.
The queue type can be either temporary or permanent:
A temporary dynamic queue will ONLY last until the execution of the program that created it
ends (normally or abnormally) or until that creating execution closes it. There is no way to
keep the temporary dynamic queue beyond that point.
A permanent dynamic queue is created in exactly the same way but does NOT
automatically disappear. It must be explicitly deleted (using a close option of delete or by
the administrator with a delete command) or it simply becomes another local queue. Once
created, there is nothing that MQSeries does to keep track of the dynamically created
permanent dynamic queues that would allow them to be identified as different from any
other local queues.
Uempty
'\QDPLF4XHXH1DPHV
T0JUDFFHVV4XHXH T1DPH
RSHQ2SWLRQV
T0JU1DPH
G\QDPLF41DPH
DOWXVHU,G
0<48(8(
0<48(8(
Notes:
Remember the accessQueue method. One of the fields that we saw was the dynamic
queue name. It has several potential values:
XXX* - where XXX is some prefix that the programmer wants at the beginning of a unique
name that will be generated by the queue manager
* alone will mean that there is no prefix that might be used. The name will be unique but
might not be one that will be of much value.
"XXXXX" where the entire name is provided (no trailing *). This means that the queue
manager will play no part in generating a unique name. The name, as provided, will be
used as the queue name.
© Copyright IBM Corp. 2000, 2002 Unit 3. Working with Queues 3-13
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
© Copyright IBM Corp. 2000, 2002 Unit 3. Working with Queues 3-15
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
8QLW&KHFNSRLQW
:KDWLVWKHFRUUHFWV\QWD[WRRSHQDTXHXH"
D TXHXHRSHQ
E 044XHXHTXHXH TXHXH0DQDJHUDFFHVV4XHXH
<RXFDQFRPELQHVHYHUDORSHQRSWLRQV7UXH)DOVH"
6HYHUDODOLDVTXHXHVFDQUHSUHVHQWRQHVLQJOHORFDO
TXHXH7UXH)DOVH"
<RXFDQSXWPHVVDJHVRQWRDPRGHOTXHXH
7UXH)DOVH"
:KLFKRIWKHIROORZLQJQDPHVIRUDG\QDPLFTXHXHZLOO
JHQHUDWHDTXHXHZLWKDXQLTXHQDPH"
D $%&
E $%&
F $%&
G
Notes:
Uempty
6XPPDU\
<RXVKRXOGQRZNQRZKRZWRRSHQDQGFORVHDTXHXH
<RXVKRXOGDOVRXQGHUVWDQGZKLFKRSWLRQV\RXQHHGWR
VHWEHIRUHRSHQLQJDQGFORVLQJDTXHXH
)LQDOO\\RXVKRXOGNQRZZKLFKW\SHVRITXHXHWRXVH
DFFRUGLQJWR\RXUUHTXLUHPHQWV ORFDOTXHXHVDOLDV
TXHXHVRUG\QDPLFTXHXHVWKURXJKDPRGHOTXHXH
Notes:
© Copyright IBM Corp. 2000, 2002 Unit 3. Working with Queues 3-17
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
References
SC34-5456 MQSeries Using Java
SC33-1673 MQSeries Application Programming Reference
2EMHFWLYHV
(UURU+DQGOLQJLQ-DYD
04([FHSWLRQ&ODVV
&RPSOHWLRQ&RGHVDQG5HDVRQ&RGHV
Notes:
04([FHSWLRQ&ODVV
SXEOLFFODVV04([FHSWLRQ
H[WHQGV([FHSWLRQ
9DULDEOHV
ORJ
FRPSOHWLRQ&RGH
UHDVRQ&RGH
H[FHSWLRQ6RXUFH
Notes:
Methods in the Java interface do not return a completion code and a reason code. Instead,
they throw an exception whenever the completion code and reason code resulting from an
MQSeries call are not both zero. This simplifies the program logic so that you do not have
to check the return codes after each call to MQSeries.
Whenever an MQSeries error occurs, an MQException is thrown. This class contains
definitions of completion code and reason code constants. Constants beginning with
MQCC_ are MQSeries completion codes and constants beginning with MQRC_ are
MQSeries reason codes. The MQSeries Application Programming Reference contains a
full description of these errors and their probable causes.
Uempty
04([FHSWLRQORJ
SXEOLFVWDWLFMDYDLRRXWSXW6WUHDP:ULWHUORJ
GHIDXOWYDOXH
6\VWHPHUU
QRORJJLQJ
QXOO
Notes:
This variable of the MQException class indicates the stream to which exceptions are
logged. (The default is System.err) If you set this to null, no logging occurs.
04([FHSWLRQFRPSOHWLRQ&RGHDQG04([FHSWLRQUHDVRQ&RGH
SXEOLFLQWFRPSOHWLRQ&RGH
04([FHSWLRQ04&&B121(
04([FHSWLRQ04&&B:$51,1*
04([FHSWLRQ04&&B)$,/('
SXEOLFLQWUHDVRQ&RGH
04([FHSWLRQ045&B121(
04([FHSWLRQ045&B[[[[[[[[[
6HH$SSOLFDWLRQ3URJUDPPLQJ5HIHUHQFH
Notes:
completionCode returns the MQSeries completion code giving rise to the error. The
possible values are:
0 (MQCC_NONE) - a successful call completed
1 (MQCC_WARNING) - the call completed but reason code indicates certain conditions
2 (MQCC_FAILED) - the call did not complete successfully.
reasonCode returns the MQSeries reason code describing the error. The possible values
are:
0 (MQRC_NONE) - a successful call completed
2000 to 2xxx - reason code returned for a completion code of 1 or 2.
For a full explanation of the reason codes refer to the MQSeries Application Programming
Reference.
Uempty
04([FHSWLRQH[FHSWLRQ6RXUFH
SXEOLF2EMHFWH[FHSWLRQ6RXUFH
Notes:
exceptionSource returns the object instance that threw the exception. You can use this as
part of your diagnostics when determining the cause of an error.
7U\&DWFK%ORFNV
WU\^
04&DOOVDUHLQVHUWHGKHUH
`
FDWFK 04([FHSWLRQH[ ^
6\VWHPRXWSULQWOQ $QHUURUKDVRFFXUHG&RPSOHWLRQFRGH
H[FRPSOHWLRQ&RGH5HDVRQFRGHH[UHDVRQ&RGH
`
Notes:
You can decide at which point in your program you want to deal with the possibility of failure
by surrounding your code with 'try' and 'catch' blocks, as in the example above.
The 'catch' block is only executed if one of the instructions within the try block gives rise to
a non-zero completion code or reason code.
8QLW&KHFNSRLQW
:KDWLVWKHQDPHRIWKHYDULDEOHWKDWLGHQWLILHVWKH
UHDVRQIRUWKH04([FHSWLRQ"
:KDWLVWKHQDPHRIWKHYDULDEOHWKDWLGHQWLILHVWKH
REMHFWWKDWKDVWKURZQWKH04([FHSWLRQ"
Notes:
Uempty
6XPPDU\
%\QRZ\RXVKRXOGXQGHUVWDQGKRZWR
7UDS046HULHVH[FHSWLRQV
5HWULHYHFRPSOHWLRQFRGHVDQGUHDVRQFRGHV
+DQGOHWKHHUURU
Notes:
References
SC34-5456 MQSeries Using Java
SC33-1673 MQSeries Application Programming Reference
http://www.ibm.com/software/ts/mqseries/messaging/
WebSphere MQ
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-1
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
2EMHFWLYHV
&RQVWUXFWDPHVVDJHREMHFW
3XWPHVVDJHVRQWRTXHXHV
*HWPHVVDJHVIURPTXHXHV
5HWULHYHDQGVHWPHVVDJHDWWULEXWHV
Notes:
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-3
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
0HVVDJH +HDGHU$SSOLFDWLRQ'DWD
0HVVDJH
+HDGHU $SSOLFDWLRQ'DWD
6HWE\DSSOLFDWLRQDQGTXHXHPDQDJHU $Q\VHTXHQFHRIE\WHV
0VJ,G 3ULYDWHWRWKHVHQGLQJDQGUHFHLYLQJ
3ULRULW\ SURJUDPV
5HSO\7R4XHXH1DPH 1RWPHDQLQJIXOWRWKHTXHXHPDQDJHU
Notes:
A message has two parts: the application data and a header called the message descriptor.
The message descriptor contains information about the message which is used by both
MQSeries and the receiving application. Some of the fields it contains are:
• The type of message
• An identifier for the message
• The priority of the message (Priority)
• The identifier of the coded character set of the character data within the application data
• The name of the queue to which a reply should be sent...
There is no limitation on the contents of the application data, but there is a maximum
allowable length for the message whose value is platform dependent.
Uempty
&RQVWUXFWLQJD0HVVDJH
3URJUDP 4XHXH0DQDJHU
4XHXH
0HVVDJHREMHFW
4XHXH
040HVVDJHP\0HVVDJH QHZ040HVVDJH
Notes:
The first step in constructing a message is to create a new message object. This is done by
instantiating the MQMessage class giving the new object a name. In this example, we have
named the new object myMessage.
As an alternative to creating a new object an existing message object can be reused, but
first it must be reset. This is done with the clearMessage method: the clearMessage
method will reset the MQMessage variables to their default settings, clear the message
buffer and reset the buffer cursor to the start of the buffer.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-5
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
7KH040HVVDJH2EMHFW
040HVVDJH
040HVVDJHYDULDEOHV 040HVVDJHEXIIHU
Notes:
The MQMessage object represents the message descriptor as variables and the user
message data as the buffer.
There is a group of readXXX methods for reading data from a message, and a group of
writeXXX methods for writing data into a message. The format of numbers and strings used
by these read and write methods can be controlled by the encoding and characterSet
member variables.
The remaining member variables contain control information that accompanies the
application message data when a message travels between sending and receiving
applications. The application can set values into the member variable before putting a
message to a queue and can read values after retrieving a message from a queue.
Uempty
8VHU'DWD)RUPDWV
ZULWH
ZULWH%\WH
ZULWH6WULQJ
FXUVRU
040HVVDJH
040HVVDJHYDULDEOHV 'DWD
FXUVRU
UHDG
UHDG%\WH
UHDG6WULQJ
Notes:
The next step is to move the required user data into the message buffer of the MQMessage
object. The data can be written using the writeXXX methods.
The message buffer maintains a cursor to indicate the current location for the write
methods to place the data.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-7
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
ZULWHDQGZULWH6WULQJ
LQWRQH%\WH 5
P\0HVVDJHZULWH RQH%\WH
E\WH>@VWU'DWD QHZE\WH>@
VWU'DWD 0HOERXUQH$XVWUDOLD
P\0HVVDJHZULWH VWU'DWD
P\0HVVDJHZULWH VWU'DWD
P\0HVVDJHZULWH VWU'DWD
VWULQJVWU'DWD KHOORZRUOG
P\0HVVDJHZULWH6WULQJ VWU'DWD
Notes:
The write method is overloaded to allow for either a single parameter or three parameters.
If a single parameter is specified then the data is either a single integer or a string array:
public void write(int b)
Throws IOException.
Write a byte into the message buffer at the current position
public void write(byte b[])
Throws IOException.
Write an array of bytes into the message buffer at the current position.
When three parameters are specified, the first is the data, the second is the offset for the
data and the third parameter is the length of the data:
public void write(byte b[], int off, int len)
Throws IOException
Write a series of bytes into the message buffer at the current position. len bytes will be
written, taken from offset off in the array b.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-9
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
ZULWH&KDUZULWH&KDUVDQGZULWH87)
LQWFRQILUP
P\0HVVDJHZULWH&KDU FRQILUP
6WULQJFRQILUP \HV
P\0HVVDJHZULWH&KDUV FRQILUP
6WULQJQDPH %LOO
P\0HVVDJHZULWH87) QDPH
Notes:
public void writeChar(int v)
Throws IOException
The writeChar method will write a Unicode character into the message buffer at the current
position.
public void writeChars(String s)
Throws IOException
The writeChars method will write a string as a sequence of Unicode characters into the
message buffer at the current position.
public void writeUTF(String str)
Throws IOException
The writeUTF method will write a UTF (Universal Text Format) string, prefixed by a 2-byte
length field, into the message buffer at the current position.
The value of the buffer cursor is taken as the current starting position for the data transfer,
with the method updating the cursor on completion of the data move.
Uempty
1XPHULF'DWD)RUPDWV
LQWY
P\0HVVDJHZULWH,QW Y
VKRUW\HDUV
P\0HVVDJHZULWH'HFLPDO \HDUV
LQWVHFRQGV7R'D\
P\0HVVDJHZULWH'HFLPDO VHFRQGV7R'D\
ORQJVHFRQGV7R'DWH
P\0HVVDJHZULWH'HFLPDO VHFRQGV7R'DWH
Notes:
public void writeInt(int v)
Throws IOException
The writeInt method will write an integer into the message buffer at the current position.
public void writeDecimal2(short v)
Throws IOException
The writeDecimal2 method will write a 2-byte packed decimal format number in the range
-999 to +999 into the message buffer at the current position.
public void writeDecimal4(int v)
Throws IOException
The writeDecimal4 method will write a 4-byte packed decimal format number in the range
-9 999 999 to +9 999 999 into the message buffer at the current position.
public void writeDecimal8(long v)
Throws IOException
The writeDecimal8 method will write a 8-byte packed decimal format number in the range
-999 999 999 to +999 999 999 into the message buffer at the current position.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-11
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
You can also use the writeDouble and writeFloat methods to write floating point numbers.
Uempty
2WKHU'DWD)RUPDWV
LQWGD\V
P\0HVVDJHZULWH%\WH GD\V
6WULQJGD\V GD\V
P\0HVVDJHZULWH%\WHV GD\V
ERROHDQDJUHH IDOVH
P\0HVVDJHZULWH%RROHDQ DJUHH
$Q\2EMHFWP\2EMHFW QHZ$Q\2EMHFW
P\0HVVDJHZULWH2EMHFW P\2EMHFW
Notes:
public void writeByte(int v)
Throws IOException
The writeByte method will write the specified byte into the message buffer at the current
position.
public void writeBytes(string v)
Throws IOException
The writeBytes method will write the specified string to the message buffer as a sequence
of bytes. Each character in the string is written out in sequence by discarding its high eight
bits.
public void writeBoolean(boolean v)
Throws IOException
The writeBoolean method will write the specified boolean into the message buffer at the
specified position.
public void writeObject(Object obj)
Throws IOException
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-13
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
The writeObject method will write the specified object to the message buffer at the
specified position. The class of the object, the signature of the class, and the values of the
non-transient and non static fields of the class and all its supertypes are all written.
Uempty
&KDQJLQJWKH%XIIHU/RFDWLRQ
LQWEXI3RV
P\0HVVDJHVHHN EXI3RV
0(66$*(
Notes:
The buffer location for the data being stored can be altered by the use of the seek or
setDataOffset methods:
The seek method will move the cursor to the absolute position in the message buffer given
by the integer parameter. The setDataOffset method is a synonym for seek(), and is
provided for cross-language compatibility with the other MQSeries APIs.
Subsequent read and write methods will work from this new position within the message
buffer. The seek and setDataOffset methods throw IOException if the MQMessage object
is not open. The seek and setDataOffset methods also throw EOFException if the specified
position is outside the message data length.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-15
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-17
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
0HVVDJH'HVFULSWRU3URSHUWLHV
040HVVDJH
040HVVDJHYDULDEOHV 040HVVDJHEXIIHU
SULRULW\
SHUVLVWHQFH
PHVVDJH,G
UHSO\7R4XHXH0DQDJHU1DPH
UHSO\7R4XHXH1DPH
FRQWH[WYDULDEOHV
PHVVDJHJURXSYDULDEOHV
PHVVDJHVHJPHQWDWLRQYDULDEOHV
Notes:
The put method will take an instance of the MQMessage object as the first parameter.
The variables of this object are also known as the message descriptor properties. They
may be altered as a result of this method.
The values they have immediately after the completion of this method are the values that
were put onto the MQSeries queue.
Modifications to the MQMessage object after the put has completed do not affect the actual
message on the MQSeries queue.
Performing a put may update the messageId and correlationId.
On successful completion of the put request the named variables of the MQMessage
object have been updated.
Uempty
3ULRULW\
3ULRULWLHV
LRULW\
3U
Notes:
It is possible to have messages delivered in a different order than that in which they were
put on a queue. One of the easiest ways to do this is using delivery by priority.
The valid range of values for this variable is zero to nine, with nine being the highest and
zero being the lowest.
If the priority variable is set to the special value of MQC.MQPRI_PRIORITY_AS_Q_DEF
then the message will inherit the default message priority value from the queue definition.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-19
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
3HUVLVWHQFH
$SSOLFDWLRQSURJUDP
4XHXHPDQDJHU
3HUVLVWHQW0HVVDJH
Notes:
When messages are put on a queue with persistence, at restart time, the queue manager
will recover the messages by replaying its logs. At the same time, ALL messages that were
put as non-persistent will be explicitly deleted at restart.
The possible returned value for this variable is either MQC.MQPER_PERSISTENT or
MQC.MQPER_NOT_PERSISTENT.
If at the time of the put request the persistence variable is set to
MQC.MQPER_PERSISTENCE_AS_Q_DEF the queue manager will update the value to
reflect the persistence attribute of the queue definition, and return the new value on
completion of the put request. When the MQMessage object is instantiated the persistence
variable inherits the default value of MQC.MQPER_PERSISTENCE_AS_Q_DEF.
Uempty
PHVVDJH,G
,' ,'*,'
06*06*06
Notes:
The messageId variable can later be used to retrieve a specific message from a queue.
If the messageId variable is set to MQC.MQMI_NONE when the put is issued, the queue
manager will generate a unique message identifier.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-21
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
3XW0HVVDJH2SWLRQV
043XW0HVVDJH2SWLRQVP\302 QHZ043XW0HVVDJHRSWLRQV
P\302RSWLRQV
P\302FRQWH[W5HIHUHQFH
P\302UHFRUG)LHOGV
P\302UHVROYHG4XHXH1DPH
P\302UHVROYHG4XHXH0DQDJHU1DPH
P\302NQRZQ'HVW&RXQW
P\302XQNQRZQ'HVW&RXQW
P\302LQYDOLG'HVW&RXQW
Notes:
The Put Message Options (MQPMO) control how a message is put on a queue: a PMO
object contains variables that influence the operation of the put request, and is updated by
the put request.
Uempty
302RSWLRQV
LQWP\2XW2SWLRQV 04&04302B121(
P\302RSWLRQV P\2XW2SWLRQV
LQWP\2WKHU2SWLRQV 04&04302B)$,/B,)B48,(6&,1*_
04&04302B1(:B06*B,'
P\302RSWLRQV P\2WKHU2SWLRQV
Notes:
The settings of the options variable controls the selectable functions performed by the
queue manager on receipt of the put request.
If more than one option is required the values can be added together or combined using
the bitwise OR operator.
The purpose of the options will be detailed in subsequent modules of this course.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-23
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
3XWWLQJ0HVVDJHV
043XW0HVVDJH2SWLRQVP\302 QHZ043XW0HVVDJH2SWLRQV
P\4XHXHSXW P\0HVVDJHP\302
3URJUDP 4XHXH0DQDJHU
SXW
040HVVDJH 4XHXH
4XHXHRSHQ
IRURXWSXW
4XHXH
Notes:
To put a message on a queue, the queue must have been opened with the output option.
The parameters to the put method are the message object and the put message options
object. The put method will use these objects to construct the underlying MQI put call.
The variables of the MQMessage object will be used to construct the message descriptor
and will be updated on successful completion of the put request.
Uempty
302UHVROYHG4XHXH1DPH
UHVROYHG4XHXH0DQDJHU1DPH
3URJUDP 4XHXH0DQDJHU
DFFHVV4XHXH 4XHXH
040HVVDJH
SXW
TXHXHUHVROYHG
E\302
4XHXH
Notes:
The resolvedQueueName variable is an output field that is set by the queue manager to the
name of the queue on which the message is placed.
This may be different from the name used on the accessQueue request if the named queue
was an alias or model queue.
For example:
MQQueue myOutputQueue = qMgr.accessQueue("ABC");
System.out.println("the queue we opened to put our messages on is: " +
myOutputQueue.name());
myOutputQueue.put(myMessage,myPMO);
if (myPMO.resolvedQueueName != "ABC") {
System.out.println("the queue we have put our message to is named: " +
resolvedQueueName); }
The resolvedQueueManagerName variable is an output field set by the queue manager to
the name of the queue manager that owns the queue specified by the remote queue name.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-25
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
This may be different from the name of the queue manager from which the queue was
accessed if the queue is a remote queue.
For example:
int oOpts = MQC.MQOO_OUTPUT;
String yRR = "ATLANTA";
MQQueue myOutputQueue = qMgr.accessQueue("ABC", oOpts, yRR, null, null);
myOutputQueue.put(myMessage,myPMO);
if (myPMO.resolvedQueueManagerName != yRR) {
System.out.println("the queue manager that owns the queue our message is
being put on is named: "
+ resolvedQueueManagerName); }
Uempty
3XW0HVVDJH%XIIHU&RQVLGHUDWLRQV
3URJUDP
040HVVDJH
ZULWH
ZLWKRXWFOHDULQJEXIIHU
P\0HVVDJHFOHDU0HVVDJH
Notes:
The put method does not clear the message buffer, therefore if the following sequence was
performed, the second message may not be as expected.
myMessage.writeString("Atlanta");
myOutputQueue.put(myMessage,myPMO);
myMessage.writeString("Melbourne");
myOutputQueue.put(myMessage,myPMO);
The first message contains "Atlanta" and the second "AtlantaMelbourne".
If the MQMessage buffer is to be reused with different message variables, then the
clearMessage method should be used after each put request.
If the successive messages are to be put with the same message variables then use the
seek method to reposition the buffer cursor to the beginning of the buffer.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-27
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-29
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
*HWWLQJ0HVVDJHV
3URJUDP 4XHXH0DQDJHU
P\0HVVDJH
4XHXH
Notes:
The get will retrieve a message from the opened queue and place it into the named
message object. All the properties of the message, known as fields of the Message
Descriptor, are available as properties of the message object. The size of the user
message buffer is indicated either on the get request, by a method of the MQMessage
class or automatically by the get method.
Options specified on the get dictate which message is returned and what if any exception
handling is to be handled by the request.
The get request is a method of the MQQueue class, if issued before the accessQueue
request is issued it will throw an MQException.
Uempty
3URFHVVLQJWKH0HVVDJH
3URJUDP 4XHXH0DQDJHU
P\0HVVDJH
4XHXH
$WWULEXWHV
SHUVLVWHQFH
SULRULW\
PHVVDJHW\SH
PHVVDJHOHQJWK
Notes:
The message is placed in the specified MQMessage buffer on successful completion of the
get request. The MQMessage class provides methods for the reading and writing of the
user portion of the message data, and the setting or viewing of the message attributes.
The provided methods allow for the user data portion to be manipulated by field type, by
number of characters or even as a variable length binary image.
The length and format of the user data is stored as attributes of the message and are
available by MQMessage method calls.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-31
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
&UHDWLQJWKH0HVVDJH%XIIHU
3URJUDP
P\0HVVDJH
LQWEXIIV]
040HVVDJHP\0HVVDJH QHZ040HVVDJH
P\0HVVDJHUHVL]H%XIIHU EXIIV]
Notes:
The first thing to do before getting a message is to create a message buffer:
int buffsz = 2000;
An integer is named and set to 2000 as an example. The required value would be the size
of a user message to be received. An integer value is required by the resize method.
MQMessage myMessage = new MQMessage();
The Java program must provide an object to store the user data and message descriptor
fields. This object is created by the constructor of the MQMessage class. The constructor
has no parameters, it is instantiated with default values.
The fields of the descriptor are named to provide the program with the ability to set them as
required before the get is issued.
MQMessage represents both the message descriptor and the data for an MQSeries
message.
myMessage.resizeBuffer(buffsz);
Uempty The program can set the size of the user data area, at any time, with the resizeBuffer
method or use a parameter on the get request. If the existing buffer contains data, the
resizeBuffer request may result in the loss of data. MQMessage represents both the
message descriptor and the data for an MQSeries message.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-33
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
*HW0HVVDJH2SWLRQV
9DULDEOHV
RSWLRQV
ZDLW,QWHUYDO
UHVROYHG4XHXH1DPH
PDWFK2SWLRQV
JURXS6WDWXV
VHJPHQW6WDWXV
VHJPHQWDWLRQ
Notes:
Like the PMO object for Put Message Options, there is a GMO object that allows for
definition of options to be used when the get is issued.
The Get Message Options object supplies information that controls the functions performed
by the get request. It will subsequently be named on a get request.
Uempty
*02RSWLRQV
04&04*02B121(
04&04*02B12B:$,7
04&04*02B:$,7
04&04*02B%52:6(B),567
04&04*02B%52:6(B1(;7
04&04*02B06*B81'(5B&85625
04&04*02B)$,/B,)B48,(6&,1*
Notes:
The options variable controls the actions performed by the get request. There are many
values that can be specified for this variable. If more than one value is required they can be
added together or combined using the bitwise OR operator.
MQC.MQGMO_NONE
The options variable is set to this value when the program does not require special actions
to be performed on the get request. No other option would be specified with this option, as
it would nullify this specification.
MQC.MQGMO_NO_WAIT
Upon receiving the get request, the queue manager will search the associated queue for a
message that matches the selection criteria, as specified by the associated variables of this
GetMessageOptions object. If no qualifying message is found, this option will result in the
program regaining control with an MQException being thrown. The reasonCode field of the
MQException class will be set to no message available.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-35
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
MQC.MQGMO_WAIT
The specification of this option results in the queue manager blocking response to the
program if there is no qualifying message currently on the queue.
MQC.MQGMO_BROWSE_FIRST
This option indicates to the queue manager that the get request is not to be a destructive
read request but instead, the qualifying message is to be retrieved without deletion. To use
this option the queue must have been opened with the get and browse options.
MQC.MQGMO_BROWSE_NEXT
This request moves the browse cursor, established by the browse first request, on to the
next qualifying message on the queue, and retrieves that message. The retrieved message
is not marked for deletion and is not locked, unless the associated lock option was also
specified. Therefore the message potentially remains available to other programs for
retrieval.
MQC.MQGMO_MSG_UNDER_CURSOR
This option results in the message, that had previously been returned on a browse first or
browse next request, being re-obtained with the standard get request and is subsequently
marked for deletion. The use of this option requires that a browse request had previously
been issued, else an MQException will be thrown.
MQC.MQGMO_FAIL_IF_QUIESCING
This option indicates to the queue manager that this request can be terminated, thereby
throwing an MQException, if it is received during a time when the queue manager is in the
process of shutting down. The program would be expected to honor this response by
closing any open queues and disconnecting from the queue manager.
Uempty
,VVXHWKH*HW5HTXHVW
3URJUDP 4XHXH0DQDJHU
P\0HVVDJH
4XHXH
P\4XHXHJHW P\0HVVDJHP\*HW2SWLRQVEXIIV]
Notes:
The get method retrieves a message from the associated queue, it takes a MQMessage
object as the first parameter. A number of fields in the MQMessage object are treated as
input, in the processing performed by the underlying MQSeries queue manager in
response to the get request.
If the get throws an MQException and the associated completion code is set to failed, the
fields and message buffer of the MQMessage object are unchanged, as no message has
been returned. If the get request does not throw an MQException or does, but the
completion code is set to warning. The message fields (also known as member variables or
Message Descriptor) and the message buffer of the associated MQMessage object are
completely replaced with the message descriptor and message data from the incoming
message.
The second parameter of the get method is the name of the associated
getMessageOptions object. The fields of this object control the actions of the MQGET
request, in particular the options field controls the type of get request and another field
controls the method of message identification.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-37
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
Other fields within the getMessageOptions object are updated upon successful completion
of the get request and are in addition to the characteristics of the selected message as
stored in the fields of the MQMessage object.
The third and last parameter of the get request is the size of the largest message that can
be returned by this request.
If a value is not supplied the default action will be to adjust the size of the buffer of the
specified MQMessage object to accommodate the selected message. The use of this
parameter can therefore be to restrict the size of the message buffer, and thereby stop a
very large message from being returned.
This parameter overrides the default size and the value set by the resizeBuffer request.
Uempty
5HWULHYLQJ0HVVDJH/HQJWK
LQWWPO
P\0HVVDJHJHW7RWDO0HVVDJH/HQJWK WPO
6\VWHPRXWSULQWOQ 7KHPHVVDJHOHQJWKLVWPO
LQWPO
P\0HVVDJHJHW0HVVDJH/HQJWK PO
6\VWHPRXWSULQWOQ 7KHOHQJWKRIWKHXVHUGDWDLQWKH
PHVVDJHLVPO
Notes:
The getTotalMessageLength method returns an integer. The value is the total number of
bytes of the message, as stored on the queue from which it has been retrieved (or
attempted to be retrieved). If the get method fails, with a message-truncated error code, the
value returned by this method is the total size of the message on the queue.
The getMessageLength returns an integer. The value is set to the length of the user data
portion of the message returned in the associated MQMessage object.
This method throws an IOException if there is no message in the buffer or the buffer size
has been set to zero.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-39
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
5HWULHYLQJ8VHU'DWD
P\0HVVDJHUHDG6WULQJ LQW
P\0HVVDJHUHDG)ORDW
P\0HVVDJHUHDG)XOO\ E\WHRIIVHWQXPEHU
P\0HVVDJHUHDG,QW
P\0HVVDJHUHDG2EMHFW
P\0HVVDJHUHDG87)
P\0HVVDJHUHDG'HFLPDO
P\0HVVDJHUHDG'HFLPDO
P\0HVVDJHUHDG'HFLPDO
Notes:
readString()
The readString method of the MQMessage class will retrieve the specified number of
characters from the message buffer. The data will be retrieved from the current buffer
position as indicated by the cursor. This method throws IOException if there is no message
and EOFException if the requested length plus the current cursor position exceeds the total
message length.
readFloat()
The readFloat method will return a floating point number from the current position in the
message buffer. The cursor will then be incremented past the item in the message buffer.
If the referenced item is not a floating point number an IOException will be raised.
readFully()
This method will treat the message data as bytes, the data will be copied without translation
from the input location to the specified output location.
Uempty The readFully method is overloaded, the first form has only one parameter: the output byte
array. The second form has three parameters, the first is the output byte array, the second
is the byte displacement from the current message buffer position and the third parameter
is the number of bytes to be copied.
In the case of the first form of the method, the number of bytes copied is equal to the size of
the receiving byte array, and the data is taken from the current message buffer position.
The first form throws Exception, EOFException.
The second form throws IOException, EOFException.
readInt()
The readInt method will return an integer from the current message buffer position. The
method readInt4 is a synonym for readInt and is provided for cross-language MQSeries
API compatibility.
The methods throw exceptions of IOException and EOFException.
readObject()
The readObject method will read an object from the current position in the message buffer.
The class of the object, the signature of the class, and the value of the non-transient and
non-static fields of the class are all read and copied to the output specification.
This method throws an OptionalDataException, a ClassNotFoundException or an
IOException.
readUTF()
Reads in a string that has been encoded using a modified UTF-8 format from the current
position in the message buffer, and returns it as a Unicode string. This method blocks until
all the bytes are read, the end of the stream is detected, or an exception is thrown.
The first two bytes of the UTF format is a short binary, the value is the number of bytes
actually written out, not the length of the string. Following the length, each character of the
string is in the UTF-8 encoding for the character.
readDecimalx()
The readDecimal2 method reads a 2-byte packed decimal number in the range (-999.
+999). The readDecimal4 method reads a 4-byte packed decimal number in the range
(-9999999. +9999999).
The readDecimal8 method reads an 8-byte packed decimal number in the range
(-999999999999999 to +999999999999999).
The methods all throw IOException and EOFException.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-41
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
&DWHULQJIRUWKH([FHSWLRQV
04([FHSWLRQ
QRPHVVDJHDYDLODEOH
PHVVDJHLVWRELJ
QRWRSHQIRUJHW
RSWLRQVHUURU
PHVVDJHKDVEHHQWUXQFDWHG
,2([FHSWLRQ
(2)([FHSWLRQ
Notes:
Above are some of the most common exceptions returned by a get. Here is a description of
these exceptions.
MQRC_NO_MESSAGE_AVAILABLE
The get request failed to find a message on the current queue. This can be caused if the
queue is empty or a specific message is being requested but is yet to be placed on the
queue. The situation can also be caused if the message is on the queue but has been
locked by another process. The standard processing would be to try the get request again
after waiting the required period of time.
MQRC_TRUNCATED_MSG_FAILED
When receiving a message the get method will acquire a message buffer large enough for
the selected message. This feature is overridden by the third parameter of the get. If
specified it will restrict the maximum size of the buffer to the value that is specified.
Therefore if a message larger than this value is selected for return to the program the
request will fail with this reason code.
Uempty MQRC_NOT_OPEN_FOR_INPUT
The get request is a method of the MQQueue object. The accessQueue method opens the
associated MQSeries queue object. For the get request to succeed, the open options
specified on the accessQueue method must include an input option. Else an exception will
be raised and the reason code will be set to indicate that the queue was not opened for
input.
MQRC_OPTIONS_ERROR
The options specified on the get request must be consistent, else the get request will fail
with this MQException. If more than one the input options is specified, this exception can
be thrown. If the browse option is specified but an associated input option is not coded,
then this exception can be thrown.
MQRC_TRUNCATED_MSG_ACCEPTED
An optional parameter of the get request is an integer setting the maximum size of a
message that can be received by this request. This parameter will override the resizeBuffer
request or the default nature of the MQMessage buffer size mechanism. If the user
message exceeds this value the request will fail and no message data will be received. But
if the get message option of MQC.MQGMO_ACCEPT_TRUNCATED_MSG is specified,
then the request will raise a warning instead of a failure and the portion of the message that
does not exceed the specified maximum size will be received and the remainder discarded.
IOException or EOFException
The IOException and EOFException conditions thrown by a number of MQMessage
methods relate to the violation of message data integrity. This can be caused by the
truncation of message data, due to size limitations. The incorrect specification of data
types. Or message buffer cursor adjustment errors.
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-43
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-45
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
8QLW&KHFNSRLQW
:KDWLVWKHQDPHRIWKH046HULHVFODVVWKDWLQFRUSRUDWHVWKH
YDULDEOHVDQGGDWDRIDPHVVDJH"
:KDWLVWKHQDPHRIWKH046HULHVFODVVWKDWLQFRUSRUDWHVWKH
YDULDEOHVDQGRSWLRQVUHTXLUHGE\WKHSXWPHWKRG"
String quartet = "notes";
MQMessage myMessage = new MQMessage();
MQPutMessageOptions myPMO = new MQPutMessageOptions();
__________.__________(quartet);
,QWKLVH[DPSOHZKDWLVWKHQDPHRIWKHREMHFWWKDWFRQWDLQVWKH
XVHUPHVVDJHEXIIHU"
,QWKHDERYHH[DPSOHZKDWPHWKRGZLOOEHXVHGWRZULWHWKHVWULQJ
LQWRWKHPHVVDJHEXIIHU"
Notes:
Uempty
8QLW&KHFNSRLQW
String quartet = "notes";
int theAnswer = 42;
MQMessage myMessage = new MQMessage();
MQPutMessageOptions myPMO = new MQPutMessageOptions();
myMessage.writeString(quartet);
myMessage.__________(theAnswer);
:KDWPHWKRGZLOOEHXVHGWRPRYHWKHFXUVRUWRSRVLWLRQIRXUW\WZR
ZLWKLQWKHEXIIHU"
:KDWRSHQRSWLRQVKRXOGEHVSHFLILHGWRDOORZPHVVDJHVWREH
SXWRQWKHTXHXH"
Notes:
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-47
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
8QLW&KHFNSRLQW
String quartet = "notes";
int oOpts = MQC.MQOO_OUTPUT;
MQQueue myOutputQueue = qMgr.accessQueue("amore", oOpts);
MQMessage myMessage = new MQMessage();
MQPutMessageOptions myPMO = new MQPutMessageOptions();
myMessage.writeString(quartet);
__________.put(myMessage, myPMO);
7KHSXWLVDPHWKRGRIZKLFKREMHFW"
:KDWRSHQRSWLRQZLOOEHUHTXLUHGWRRSHQWKHTXHXHWRJHW
PHVVDJHVZKLOHVKDULQJWKHTXHXHZLWKRWKHUSURJUDPV"
:KDWLVWKHQDPHRIWKHPHWKRGWRVSHFLI\WKHVL]HRIWKH
PHVVDJHEXIIHUDV"
:KDWLVWKHQDPHRIWKHFODVVWKDWHQFDSVXODWHVWKHRSWLRQV
UHTXLUHGE\WKHJHWUHTXHVW"
Notes:
Uempty
8QLW&KHFNSRLQW
MQQueueManager eThompson;
eThompson = new MQQueueManager("Atlanta");
int oOpts = MQC.MQOO_INPUT_SHARED;
MQQueue myInputQueue = eThompson.accessQueue("Wildwood", oOpts);
MQMessage myMessage = new MQMessage();
myMessage.resizeBuffer(2000);
MQGetMessageOptions myGetOpts = new MQGetMessageOptions();
myGetOpts.options = MQC.MQGMO_ACCEPT_TRUNCATED_MSG |
MQC.MQGMO_BROWSE_FIST;
__________.get(...
,QWKLVH[DPSOHZKDWLVWKHQDPHRIWKHREMHFWWKDWKDVDPHWKRG
WRJHWPHVVDJHVIURPWKHTXHXH"
Notes:
© Copyright IBM Corp. 2000, 2002 Unit 5. Messaging and Queuing 5-49
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
6XPPDU\
<RXVKRXOGQRZNQRZKRZWR
&RQVWUXFWDQGPDQDJHDQ040HVVDJHREMHFW
3XWPHVVDJHVRQWRTXHXHVLQGLIIHUHQWIRUPDWVZLWK
YDULRXVRSWLRQV
*HWPHVVDJHVIURPTXHXHVLQGLIIHUHQWIRUPDWV
ZLWKYDULRXVRSWLRQV
5HWULHYHDQGVHWPHVVDJHDWWULEXWHV
Notes:
References
SC34-5456 MQSeries Using Java
SC33-1673 MQSeries Application Programming Reference
http://www.ibm.com/software/ts/mqseries/messaging/
WebSphere MQ
2EMHFWLYHV
8QGHUVWDQGGLIIHUHQWPHVVDJHVW\OHV
:RUNZLWKUHTXHVWDQGUHSOLHV
8VHWKH046HULHVUHSRUWIXQFWLRQ
Notes:
0HVVDJH7\SHV
3URJUDP 3URJUDP
4XHXH0DQDJHU
4XHXH
6HQG )RUJHWPHVVDJLQJ
3URJUDP 3URJUDP
4XHXH0DQDJHU
4XHXH
4XHXH
5HTXHVW 5HSO\PHVVDJLQJ
Notes:
The message types used by a messaging system are indicators that are used to show the
purpose or intent of the message. They basically fall into two categories, either the send
and forget style of messaging or the request and reply style.
With the send and forget style, the client program will create a message indicating it is a
datagram message type and put it on the servers input queue. The server program will get
and process the message. When finding that the message is a datagram, the server
program will not generate a reply message, instead it will complete the processing of this
message.
With the request and reply style, the client program will create a message indicating it is a
request message type and put it on the servers input queue. The server program will get
and process the message. When finding that the message is a request, the server program
will generate a reply message and put it on the clients input queue.
Uempty
+RZWRXVH0HVVDJH7\SHV
3URJUDP 4XHXH0DQDJHU
040HVVDJH 4XHXH
4XHXH
PHVVDJH7\SH
'$7$*5$0
5(48(67
5(3/<
5(3257
XVHUGHILQHG
Notes:
One of the MQMessage variables is named the messageType, it is an integer that is set by
the message creator to indicate to the receiver the purpose of the message.
The value of the messageType variable is either ignored or acted upon based on the logic
of the receiver program. This variable is not a message selection option, therefore a
message can not be selected for retrieval based upon the value of this variable. Currently
MQSeries has four system defined values - DATAGRAM, REQUEST, REPLY, REPORT -
and a range assigned for user defined values.
myMessage.messageType =MQC.MQMT_DATAGRAM;
If the program creating the message does not assign a value to the messageType variable,
it will by default be set to message type of datagram. This setting, indicates to the receiving
program, that the sending program has not indicated any special messaging properties or
actions that need to be performed by the receiver program. A datagram is synonymous
with a broadcast or newsletter form of messaging, where the originator is not expecting an
interaction or reply from the receiver of this message.
myMessage.messageType =MQC.MQMT_REQUEST;
The setting of the messageType variable to message type of request, indicates to the
receiver of this message that a reply message is expected to be created and sent to the
reply queue as indicated by the replyToQueueName variable of this message. When the
message is created and put to the queue with this message type, the queue manager will
enforce that there must be a valid value in the replyToQueueName variable. This form of
messaging is synonymous with a conversational style of communications.
myMessage.messageType =MQC.MQMT_REPLY;
The setting of the message type variable to the message type of reply, indicates that the
message is an answer or reply to another message. Presumably the original message was
a message type of request, therefore indicating that it required a reply message. The reply
message is put to the queue identified by the 'replyToQueueName' variable of the request
type message.
myReply.messageType =MQC.MQMT_REPORT;
The setting of the message type variable to a message type of report, indicates that this
message is a status message rather than a reply message. This type of message is
generated by the queue manager when the original message has specified reports are
required. The queue manager will send the report type messages to the queue named by
the replyToQueueName field of the original message. Report type messages can also be
created by programs, to indicate a processing condition has been raised. Presumably the
original message was a message type of request, therefore indicating that it required a
response message.
Uempty
5HTXHVW
5(48(67
3URJUDP 4XHXH0DQDJHU
040HVVDJH
PHVVDJH7\SH 4XHXH
0407B5(48(67
4XHXH
5(3/<
Notes:
When some type of reply is desired, an application should set the messageType variable to
MQMT_REQUEST. Also, the replyToQueueName variable should contain the name of a
queue that will be monitored for responses.
When an application retrieves a message from a queue, it can determine the message
type, and if a request, can use the replyToQueueName and replyToQueueManagerName
variables to know where to send any replies.
The program that initially sent the request can then look for replies on the replyToQueue
that it specified.
UHSO\7R4XHXH0DQDJHU1DPHUHSO\7R4XHXH1DPH
4XHXH0DQDJHU
387
3URJUDP 4XHXH 3URJUDP
5(3/<
4XHXH0DQDJHU
4XHXH
Notes:
The replyToQueueName variable is the name of the message queue to which the
application that issued the get request for the message should send MQC.MQMT_REPLY
and MQC.MQMT_REPORT messages.
The replyToQueueManagerName variable is the name of the queue manager that hosts
the queue that has been specified as the value of the replyToQueueName variable.
If this variable is set to "" on input to the put request, the queue manager will validate the
value of the replyToQueueName variable against the current queue manager and extract
from the resolving definition the name of the hosting queue manager. This subsequent
value will be stored as the replyToQueueManagerName and returned to the program on
successful completion of the put request.
Uempty
5HSO\
3URJUDP
4XHXH
JHW
LI5(48(67
SURFHVVGDWD
4XHXH
5(3/< SXW WRUHSO\7R4XHXH
HQGLI
Notes:
When a program issues an MQGET, it might be designed to interrogate the messageType
to validate that the message is a request. If not, some error process might be invoked if this
getting program always expects request type messages.
Once the message type is deemed to be valid, business processing is completed and
some type of response message can be formulated and sent to the replyToQueue.
Note that for the reply, the messageId and correlationId are usually handled as follows:
3. correlationId takes the value of the request message's messageId
4. messageId is null.
5HWULHYLQJWKH5HSO\4XHXHDQG5HSO\4XHXH
0DQDJHU1DPHV
P\,QSXW4XHXHJHW P\0HVVDJHJPR
UHSO\4XHXH1DPH P\0HVVDJHUHSO\7R4XHXH1DPH
UHSO\4XHXH0DQDJHU1DPH P\0HVVDJHUHSO\7R4XHXH0DQDJHU1DPH
P\5HSO\4XHXH T0JUDFFHVV4XHXH
UHSO\4XHXH1DPH
RSHQ2SWLRQV
UHSO\4XHXH0DQDJHU1DPH
QXOO QRG\QDPLFTXHXHQDPH
QXOO QRDOWHUQDWHXVHU,G
Figure 6-7. Retrieving the Reply Queue and Reply Queue Manager Names MQ092.0
Notes:
The replyToQueueName variable of the MQMessage object is defined as a string. The
value is the name of the message queue for the replies to this message.
The replyToQueueManagerName variable of the MQMessage object is defined as a string.
The value is the name of the queue manager for the replies to this message.
5HSRUW0HVVDJHV
3URJUDP
4XHXH0DQDJHU
4XHXH
GHDGOHWWHUT
5(3257
UHSO\7R4
Notes:
All queue managers have the ability to have messages that are undeliverable placed on an
undeliverable message queue called a dead letter queue.
When a message is placed on the dead letter queue because it can not be delivered, the
queue manager takes no action to notify the sender unless one of the report options
specified when the message was put was MQRO_EXCEPTION_.... (where .... can be
nothing, WITH_DATA or WITH_FULL_DATA). In the case where one of these report
options is specified, the queue manager will build a report message (messageType will be
MQMT_REPORT). The Feedback field in the message descriptor of the report message
(represented by the feedback variable of the MQMessage object) will contain the reason
code associated with the failed attempt to deliver the message. The report message will be
placed on the replyToQueue as specified in the undeliverable message.
Uempty
([FHSWLRQ5HSRUWV
352*5$0
(;&(37,21
UHSO\7R4XHXH
(;&(37,21
5(3257
4XHXH0DQDJHU
Notes:
When an application puts a message on a queue, if the queue is local, the completion and
reason code will immediately tell the program whether the message is successfully
delivered. However, the nature of asynchronous processing means that a message that is
successfully placed on a transmission queue for subsequent delivery across a network
results in a successful completion and reason code being returned to the putting
application.
If the application wishes to have notification that a message is undeliverable, the message
descriptor report field will need to include on of the following report options:
• MQC.MQRO_EXCEPTION
• MQC.MQRO_EXCEPTION_WITH_DATA
• MQC.MQRO_EXCEPTION_WITH_FULL_DATA
Each of the above will cause a report message to be generated. The first will result in a
message descriptor with a zero length message. The second will include the first 100 bytes
of the original message. The last will include the entire original message. In all cases, the
messageType will be MQMT_REPORT and the feedback field will contain the reason code
that tells you why the message could not be delivered.
Uempty
([SLU\5HSRUWV
352*5$0
(;3,5<
UHSO\7R4XHXH
(;3,5$7,21
4XHXH0DQDJHU 5(3257
Notes:
When the report field is set to request expiration reports, there are three types of the
expiration reports that can be specified:
• MQC.MQRO_EXPIRATION
• MQC.MQRO_EXPIRATION_WITH_DATA
• MQC.MQRO_EXPIRATION_WITH_FULL_DATA
This type of report is generated by the queue manager if the message is discarded prior to
delivery to a program because its expiry time has passed. If this option is not set, no report
message is generated if a message is discarded for this reason.
The report option without the specification of data will generate a message that does not
have a message buffer. The report option with the full data option will generate a message
that contains the complete original failing message. While the report option with just the
data option will only generate a message buffer with the first 100 bytes of the failing
message.
An expiration report will only be built when the message is read from the queue, even if the
message has already been expired for a long time.
Uempty
&2$DQG&2'5HSRUWV
352*5$0 352*5$0
&2'
5(3257
UHSO\7R4XHXH
&2$
5(3257
4XHXH0DQDJHU
Notes:
A COA report is generated by the queue manager that owns the destination queue, when
the message is placed on the destination queue. Message data from the original message
is not included with the report message, unless the with data options are specified. If the
message is put as part of a unit of work, and the destination queue is a local queue, the
COA report message generated by the queue manager becomes available for retrieval
only if and when the unit of work is committed.
A COA report is not generated if the Format field in the message descriptor is
MQFMT_XMIT_Q_HEADER or MQFMT_DEAD_LETTER_HEADER. This prevents a COA
report being generated if the message is put on a transmission queue, or is undeliverable
and put on a dead-letter queue.
A COD report is generated by the queue manager when an application retrieves the
message from the destination queue in a way that causes the message to be deleted from
the queue.
If the message is retrieved as part of a unit of work, the report message is generated within
the same unit of work, so that the report is not available until the unit of work is committed.
If the unit of work is backed out, the report is not sent. A COD report is not generated if the
Format field in the message descriptor is MQFMT_DEAD_LETTER_HEADER. This
prevents a COD report being generated if the message is undeliverable and put on a
dead-letter queue.
Uempty
)HHGEDFN
SXEOLFLQWIHHGEDFN
04&04)%B(;3,5$7,21
04&04)%B&2$
04&04)%B&2'
04&04)%B48,7
04&04)%B3$1
04&04)%B1$1
04&04)%B'$7$B/(1*7+B=(52
04&04)%B'$7$B/(1*7+B1(*$7,9(
04&04)%B'$7$B/(1*7+B722B%,*
04&04)%B%8))(5B29(5)/2:
04&04)%B/(1*7+B2))B%<B21(
04&04)%B,,+B(5525
Notes:
The feedback field of the message object is used with a message of type
MQC.MQMT_REPORT to indicate the nature of the report, and is only meaningful with that
type of message.
The following feedback codes are defined by the system for general use:
MQC.MQFB_EXPIRATION
MQC.MQFB_COA
MQC.MQFB_COD
MQC.MQFB_QUIT
MQC.MQFB_PAN
MQC.MQFB_NAN
The default value of this field is MQC.MQFB_NONE, indicating that no feedback is
provided.
Application-defined feedback values in the range MQC.MQFB_APPL_FIRST to
MQC.MQFB_APPL_LAST can also be used.
&23<B06*B,'B72B&255(/B,'
3URJUDP
4XHXH0DQDJHU
4XHXH
GHDGOHWWHUT
5(3257
UHSO\7R4
PHVVDJH,GRIPHVVDJHLVFRSLHG
WRFRUUHODWLRQ,GRIUHSRUW
Notes:
MQC.MQRO_COPY_MSG_ID_TO_CORREL_ID
This is the default report action, and indicates that if a report or reply is generated as a
result of this message, the MessageId of this message is to be copied to the CorrelationId
of the report or reply message.
MQC.MQRO_PASS_CORREL_ID
If a report or reply is generated as a result of this message, the CorrelationId of this
message is to be copied to the CorrelationId of the report or reply message.
Servers replying to requests or generating report messages are recommended to check
whether the MQC.MQRO_PASS_MSG_ID or MQC.MQRO_PASS_CORREL_ID options
were set in the original message. If they were, the servers should take the action described
for those options.
If neither is set, the servers should take the corresponding default action.
8QLW&KHFNSRLQW
:KDWLVWKHQDPHRIWKHYDULDEOHRIWKH040HVVDJHREMHFWWKDW
KROGVWKHW\SHRIPHVVDJHLQGLFDWRU"
public void start(){
MQMessage myMessage = new MQMessage();
myMessage.writeString("Goodbye and thanks for all the Fish");
myMessage.messageType = MQC.MQMT_DATAGRAM;
}
&RXOGDUHSRUWPHVVDJHEHJHQHUDWHGE\WKLVPHVVDJH"
:KDWLVWKHYDOXHWKDWWKHPHVVDJH7\SHYDULDEOHVKRXOGEHVHWWR
WRLQGLFDWHWKDWWKHPHVVDJHQHHGVDUHSO\"
:KDWLVWKHQDPHRIWKHYDULDEOHRIWKH040HVVDJHREMHFWWKDW
PXVWEHWVHWZKHQDPHVVDJHW\SHRIUHTXHVWLVVSHFLILHG"
Notes:
Uempty
6XPPDU\
<RXVKRXOGQRZNQRZKRZWR
:RUNZLWKGLIIHUHQWW\SHVRIPHVVDJHV
6HQGUHTXHVWPHVVDJHV
)RUPXODWHDQGVHQGUHSOLHV
5HTXHVWUHSO\PHVVDJHV
Notes:
References
SC34-5456 MQSeries Using Java
SC33-1673 MQSeries Application Programming Reference
http://www.ibm.com/software/ts/mqseries/messaging/
WebSphere MQ
2EMHFWLYHV
*HWPHVVDJHVVHOHFWLYHO\XVLQJPHVVDJH,GDQG
FRUUHODWLRQ,G
&RGHV\QFKURQRXVSURJUDPVXVLQJWKHZDLW
IXQFWLRQ
*URXSPHVVDJHVDQGUHWULHYHDJURXSRI
PHVVDJHV
8VHPHVVDJHVHJPHQWDWLRQWHFKQLTXHV
Notes:
PHVVDJH,GDQGFRUUHODWLRQ,G
352*5$0
UHSO\7R4XHXH $
SXW WRTXHXH%
352*5$0
JHW " $
Notes:
Consider the above picture:
A continuously running server application is used to process requests for information.
• Several copies of this application may be running at one time
• Each request placed on the queue is for a unique customer
• The replyToQueue is always the same
That same program will process replies in response to each request
• The application must ensure that the reply it processes is for the request it has just sent,
ignoring any that are not
• The replyToQueue may have messages that are related to requests from other copies of
the application that are running at the same time
If an application simply issues GETs, we know the messages are destructively taken from
the queue. The application can't remove other replies that are not for its request. It is
possible to use the BROWSE function and check each message, but that can be wasteful
since additional GETs would be issued just to examine each message.
Uempty Two fields in the message descriptor allow an application to selectively retrieve messages.
The messageId and correlationId fields can be used in our scenario to ensure that the reply
message retrieved is the one that matches the request sent.
PHVVDJH,GDQGFRUUHODWLRQ,G
3URJUDP 4XHXH0DQDJHU
SXW
040HVVDJH
PHVVDJH,G
FRUUHODWLRQ,G
Notes:
After the successful completion of the put request the messageID variable will always have
a value other than null but the correlationId variable may have a value of null.
The two variables are the primary identifiers of a message and will be referenced during
the message selection processing performed by the get process.
The values expressed in these variables do not have to be unique, but if each message is
to be treated as a separate entity, then each message should have a unique value for one
or both of the message identifiers. This can be achieved by specifying
MQPMO_NEW_MSG_ID or MQPMO_NEW_CORREL_ID in the Put Message Options.
Uempty
PHVVDJH,GDQGFRUUHODWLRQ,G
SXEOLFE\WHPHVVDJH,G>@
SXEOLFE\WHFRUUHODWLRQ,G>@
Notes:
The messageId variable is a collection of 24 bytes, the value is not subject to data
conversion as the message moves over a network of disparate nodes.
For an MQQueue.put() method, this specifies the message identifier to use. If
MQC.MQMI_NONE is specified, the queue manager generates a unique message
identifier when the message is put. The value of this member variable is updated after the
put to indicate the message identifier that was used. The default value is
MQC.MQMI_NONE.
For an MQQueue.get() method, this field specifies the message identifier of the message
to be retrieved. Normally the queue manager returns the first message with a message
identifier and correlation identifier match those specified. The special value
MQC.MQMI_NONE allows any message identifier to match.
The correlationId variable is a collection of 24 bytes, the value is not subject to data
conversion as the message moves over a network of disparate nodes.
For an MQQueue.put method, this specifies the correlation identifier to use. The default
value is MQC.MQCI_NONE.
For an MQQueue.get() method, this field specifies the correlation identifier of the message
to be retrieved. Normally the queue manager returns the first message with a message
identifier and correlation identifier that match those specified. The special value
MQC.MQCI_NONE allows any correlation identifier to match.
Uempty
8VLQJPHVVDJH,GDQGFRUUHODWLRQ,G
P\0HVVDJHPHVVDJH,G FXVWQR
P\0HVVDJHFRUUHODWLRQ,G DQVZHU
P\2XWSXW4XHXHSXW P\0HVVDJH
P\5HSO\PHVVDJH,G FXVWQR
P\,QSXW4XHXHJHW P\5HSO\
Notes:
If the program sets the message id variable or the correlation id variable prior to the put
request then the queue manager will not reset the values. The specified values will not be
checked for uniqueness or consistency. The values are considered to be a pattern of bits
and are designated by the queue manager as a byte field. They will not be subjected to
character set conversion, if the message moves onto a node with a different character set
code page setting. The message will then be identifiable by these value as it moves over
the network, but only on nodes with the same character representation.
If the program wants to select a specific message, not just the next available message. It
must set the message id and / or correlation id prior to the get request. But for this to be
successful the server program must be performing compatible processing when putting the
message.
If the program sets the message identifier variable prior to the get request, the queue
manager will search the associated queue for the first available message that matches
that messageId. If a matching message is not found the request will throw an MQException
indicating that there is no message available.
Uempty
8VLQJPHVVDJH,GDQGFRUUHODWLRQ,G
PHVVDJH,G 04&040,B121(
FRUUHODWLRQ,G 04&04&,B121(
PHVVDJH,G 04&040,B121(
FRUUHODWLRQ,G
PHVVDJH,G
FRUUHODWLRQ,G 04&04&,B121(
PHVVDJH,G
FRUUHODWLRQ,G
OL G O LG O LG O LG H O LG OLG
U H UH U UH UUH UU U H
U U U
FR FR FR FR FR FR
LG LG LG LG L G LG
VJ VJ VJ VJ VJ VJ
P P P P P P
Notes:
Let's examine the examples:
1. This is asking for the first available message regardless of the values of messageId and
correlationId
2. This one requests a message that has correlationId of 3, regardless of the value of the
messageId field
3. This MQGET will succeed if it finds a message with messageId of 4, regardless of the
value in correlationId
4. Unless a message with messageId of 4 AND correlationId of 2 is found, this call would
not succeed
On completion of the four MQGETs in the above example, if no other messages have
arrived, two messages would remain on the queue. Which ones?
Be aware that queues with many messages could cause a performance impact if an
application chooses to use MQGET with messageId and correlationId: the queue manager
will actually scan the queue sequentially looking for a match.
:DLW
3URJUDP
P\0HVVDJHUHSO\7R4XHXH1DPH
% $
P\2XWSXW4XHXHSXW
%
P\,QSXW4XHXHJHW
045&B121(
RU
045&B12B06*B$9$,/$%/(
`"
Notes:
Because MQSeries is asynchronous by nature, it is probable that there may be a delay
between the issuance of a request and any reply that is returned. The MQGET will fail with
MQRC_NO_MSG_AVAILABLE if a message retrieval is attempted and none is available.
So, to allow the program to wait for a message to arrive, there is a Get Message Options
option of MQGMO_WAIT.
By specifying the MQGMO_WAIT option as one of the Get Message Options, an
application can issue an MQGET and will essentially "go on hold" until a message arrives
that satisfies the delivery requirements.
Some conditions that the Wait option allows for are:
• messages to be delivered across a network
• another program to be triggered to process the request
• a slower program to complete processing
If an application uses the MQGMO_WAIT, it is highly recommended that the Get Message
Option of MQGMO_FAIL_IF_QUIESCING be used as well. This will allow the call to be
*02ZDLWRSWLRQDQGZDLW,QWHUYDO
3URJUDP 4XHXH0DQDJHU
*(7$1' 4XHXH
:$,7
4XHXH
Notes:
The maximum time (in milliseconds) that an MQQueue.get request is to wait for a suitable
message to arrive. A value of MQC.MQWI_UNLIMITED indicates that an unlimited wait is
required.
Uempty
:DLWZLWKZDLW,QWHUYDO
3URJUDP
P\0HVVDJHUHSO\7R4XHXH1DPH
% $
P\2XWSXW4XHXHSXW
JPRZDLW,QWHUYDO
JPR2SWLRQV
04&04*02B:$,7 %
P\,QSXW4XHXHJHW
Notes:
If a message is available when the MQGET is issued, the wait never takes effect. If not, the
MQGMO_WAIT option along with a value given by waitInterval allow the program to
establish a reasonable time to wait for a message. If none arrives during that time, the
MQGET completes with a failing completion code and a reason code of
MQRC_NO_MSG_AVAILABLE. During the wait interval, if a message arrives, the wait is
immediately satisfied.
Remember, by not specifying a waitInterval, an application could wait forever since the
default is MQWI_UNLIMITED.
:DLW([DPSOH
040HVVDJHUHWULHYHG0HVVDJH QHZ040HVVDJH
04*HW0HVVDJH2SWLRQVJPR QHZ04*HW0HVVDJH2SWLRQV
JPRRSWLRQV 04&04*02B:$,7
JPRZDLW,QWHUYDO 04&04:,B81/,0,7('
PBTXHXH'JHW UHWULHYHG0HVVDJH
JPR
PD[PHVVDJHVL]H
Notes:
,QWURGXFWLRQ
0HVVDJHJURXS
3K\VLFDO0HVVDJH
6PDOOHVWXQLWRILQIRUPDWLRQ
6HJPHQW 6HJPHQW
WKDWFDQEHSODFHGRQDTXHXH
/RJLFDO0HVVDJH 0HVVDJHJURXS
6LQJOHXQLWRIDSSOLFDWLRQ $VHWRIRQHRUPRUHORJLFDO
LQIRUPDWLRQ PHVVDJHVFRPSRVHGRIRQHRU
2QHRUPRUHSK\VLFDOPHVVDJHV PRUHSK\VLFDOPHVVDJHV
FDOOHGVHJPHQWV
6HJPHQWVDUHDQ\ZKHUHLQWKH
TXHXH
Notes:
Messages can occur in groups. This enables ordering of messages as well as
segmentation of large messages within the same group.
Message segments will be discussed in the next topic within this unit. For now, it is enough
to know that a segment is one physical message that, when taken together with other
related segments, make up a logical message. Segments are useful when it is necessary
to handle messages that are too large for the putting or getting application or for the queue
manager.
Logical messages can actually be a physical message as well. If not made up of segments,
then a logical message is the smallest unit of information, by definition, a physical
message.
A message group is made up of one or more logical messages, consisting of one or more
physical messages that have some relationship. We will explore the possible relationships
as we proceed.
Uempty
7KH0HVVDJH*URXS9DULDEOHV
0(66$*(*5283
*URXS;<=
0(66$*( 0(66$*( 0(66$*(
Notes:
The message group variables detail the relationship of this message within a group of
messages. They include the name of the group and the position of this message within the
chronological order of the group.
These variables are controlled by settings within the putMessageOptions object.
0HVVDJH*URXSVDQGWKHJURXS,G9DULDEOH
3URJUDP 4XHXH0DQDJHU
SXW
P\0HVVDJHJURXS,G EDWFK
P\4XHXHSXW P\0HVVDJHP\3PR
Notes:
Each message put on a queue has potentially a unique identifier in the messageId variable.
This is created by the queue manager when the value assigned by the program is
MQC.MQMI_NONE. The correlationId variable can also contain a value, it would be set by
the program to a user defined value.
But what happens when a program needs to put a batch of messages on a queue? It needs
to identify that the messages are to be treated as a batch, yet still allowing for each
message to be individually monitored. The use of a common messageId or correlationId
variable may not provide the required level of identification, association and uniqueness.
To solve this problem, MQSeries introduces another message identifier in the form of the
groupId variable. This variable can be set to a user value or left to the system to define a
unique value.
Several messages with the same groupId form a Message Group.
Uempty
3XWWLQJD0HVVDJHWRD*URXS
3URJUDP 4XHXH0DQDJHU
SXW
04&040)B/$67B06*B,1B*5283
04&040)B06*B,1B*5283
P\0HVVDJHJURXS,G 04&04*,B121(
P\0HVVDJHPHVVDJH)ODJV 04&040)B06*B,1B*5283
P\3PRRSWLRQV 04&04302B/2*,&$/B25'(5
P\2XW4XHSXW P\0HVVDJHP\3PR
Notes:
On a put request MQSeries will ignore the value of the groupId variable when the
MQMessage object does not include the required value in the messageFlags variable.
The default value for the messageFlags variable is MQC.MQMF_NONE this indicates that
the message is not a member of a group.
When the message is a member of a group, the messageFlags variable can take the
following values:
MQMF_MSG_IN_GROUP indicates that the message is a member of the group identified
by the groupId variable.
MQMF_LAST_MSG_IN_GROUP indicates that the message is the last member of the
group or is the only message within the group identified by the groupId variable.
Messages put to this queue by this program will be added to the group while the
messageFlags value remains set to MQMF_MSG_IN_GROUP. When the message group
is to be closed the program specifies the messageFlags value of
Uempty
*HWWLQJD0HVVDJHIURPD*URXS
P\*PRZDLW,QWHUYDO
P\*PRRSWLRQV 04&04*02B$//B06*B$9$,/$%/(_
04&04*02B:$,7
P\,Q4XHJHW \RXU0HVVDJHP\*PR
LI P\*PRJURXS6WDWXV 04&04*6B/$67B06*B,1B*5283 ^`
LI P\*PRJURXS6WDWXV 04&04*6B06*B,1B*5283 ^`
LI P\*PRJURXS6WDWXV 04&04*6B127B,1B*5283 ^`
Notes:
When a program wishes to get a message it issues the get request. If the program is not
sensitive to the message group facility it will retrieve the next available message regardless
of its group status.
If the program is sensitive to the message group facility it will include on the get request the
get message option of MQGMO_ALL_MSG_AVAILABLE. This option indicates to the
queue manager that if the selected message is in a group, do not retrieve the message
unless the message flag of LAST_MSG_IN_GROUP has been received for this group. To
allow for the message group to be received, it is recommended that when using the 'all msg
available' option, that the get message option of wait and an appropriate wait interval be
also coded.
On successful retrieval of a message the MQGetMessageOptions object has been updated
to reflect the status of the message. The groupStatus variable will indicate if the message is
in a group, if it is the last message in the group or it is not in a group. If a group consists of
only one message, when it is retrieved the groupStatus will be LAST_MSG_IN_GROUP.
The program can request the queue manager to return each message in strict logical order.
This order is based on the value of the message sequence number variable. The get
message option of MQGMO_LOGICAL_ORDER must be specified on the options variable
of the relevant MQGetMessageOptions object. The order is maintained by the queue
manager outside the control of the program. If the logical order option is not specified the
messages will be returned in the order as specified by the delivery sequence property of
the queue definition.
Uempty
0DWFK2SWLRQV
3URJUDP 4XHXH0DQDJHU
04*(7
04&040)B/$67B06*B,1B*5283
04&040)B06*B,1B*5283
P\*PRPDWFK2SWLRQV 04&0402B0$7&+B*5283B,'_
04&0402B0$7&+B06*B,'_
04&0402B0$7&+B&255(/B,'
\RXU0HVVDJHPHVVDJH,G $WODQWD
\RXU0HVVDJHFRUUHODWLRQ,G :LOGZRRG
\RXU0HVVDJHJURXS,G EDWFK
P\*PRRSWLRQV 04&04*02B$//B06*B$9$,/$%/(
P\,Q4XHJHW \RXU0HVVDJHP\*PR
Notes:
The MQGetMessageOptions variable matchOptions can also be set to allow the program
to select the message group it wishes to retrieve messages from. This variable also
indicates the message identification selection criteria.
When the matchOptions variable is set to MQMO_MATCH_GROUP_ID
the value of the MQMessage variable groupId will be used as the message selection
identifier.
The matchOptions can also include the specification of both MQMO_MATCH_MSG_ID and
MQMO_MATCH_CORREL_ID in which case a message will not be retrieved unless it
matches all three of these values.
6SDQQLQJ8QLWVRI:RUN
3XWWLQJDSSOLFDWLRQ
6RPHRIWKHJURXSPD\EHFRPPLWWHGEHIRUHD
IDLOXUH
6WDWXVLQIRUPDWLRQPXVWEHVDYHG
6LPSOHVWZD\WRXVHD67$786TXHXH
6WDWXVLQIRUPDWLRQFRQVLVWVRIJURXS,GDQG
0VJ6HT1XP
67$786TXHXHLVHPSW\LIDFRPSOHWHJURXSKDV
EHHQVXFFHVVIXOO\SXW
04302B/2*,&$/B25'(5FDQQRWEHXVHGRQWKH
ILUVWSXWRIWKHUHVWDUWDSSOLFDWLRQ
*HWWLQJDSSOLFDWLRQ
67$786TXHXHDJDLQ
)LUVW*(7RIWKHUHVWDUWDSSOLFDWLRQPXVWPDWFKRQ
JURXS,GDQG0VJ6HJ1XP
Notes:
The MQPMO_LOGICAL_ORDER option affects units of work as follows:
If the first physical message in the unit of work specifies MQPMO_SYNCPOINT, then all
subsequent physical messages in the group or logical message must use the same option.
However, they nee not be put within the same unit of work. This permits spreading a
message group or logical message that has many physical messages into smaller units of
work.
Conversely, if the first physical message has specified MQPMO_NO_SYNCPOINT, then
none of the subsequent physical messages within the group or logical message can do
otherwise.
If these conditions are not met, the MQPUT will fail with MQRC_INCONSISTENT_UOW.
The conditions described for the MQPUT are the same when using the
MQGMO_SYNCPOINT or MQGMO_NO_SYNCPOINT options.
Since it is possible to split a group or logical message over multiple units of work, it is
possible to have some of the physical messages but not all committed when a failure
Uempty occurs. It is the responsibility of the application to keep track of the status information
associated with a group or logical messages that spans units of work. By keeping track of
the groupId and the MsgSeqNumber on a special status queue (using syncpoint options for
the MQPUT and MQGET), an accurate picture of what has been completed can be kept.
If a restart is done, this is the information that can be used, as discussed earlier, without
specifying the Get or Put Message Options option for logical order to essentially restart
proper processing of a group or a logical message.
6HJPHQWDWLRQE\WKH4XHXH0DQDJHU
3URJUDP
48(8(0$1$*(5 48(8(0$1$*(5
P\0HVVDJHPHVVDJH)ODJV 040)B6(*0(17$7,21B$//2:('
P\2XW4SXW P\0HVVDJHP\3PR
Notes:
Each message on a queue is variable in length, up to a maximum of 100 megabytes. The
MQSeries administrator can specify a smaller maximum size for each queue and also the
maximum number of messages that can be stored on a queue. Each queue has a
maximum physical size of 2 gigabytes. A message can not be put on a queue if it exceeds
any of these settings.
Messages that are destined for a queue that is remotely hosted travel to the remote queue
manager via a transmission queue. The message must be able to be stored on the
transmission queue else the put request will fail. The MQSeries component that moves
messages between queue managers is called the message channel agent (MCA).
When moving messages between queue managers. If the message is larger than can be
received by a remote queue, the MCA can break down the message into segments and
store each segment as a separate message on the remote queue. Specifying
MQMF_SEGMENTATION_ALLOWED as the value of the messageFlag variable allows the
queue manager to segment the message.
Uempty If the message is too big for the remote queue and the message indicates that it is not
allowed to be segmented, then the message will be put to the dead letter queue on the
receiving queue manager. The messageFlags variable set to the specification of
MQMF_SEGMENTATION_INHIBITED prevents the message being broken into segments
by the queue manager.
Each segmented message contains the same message header, updated to indicate
segmentation, followed by the next portion of the message data. Each message sent is
known as a physical message. If the message is a segment of a larger message the
complete message is referred to as a logical message.
0HVVDJH6HJPHQWDWLRQ9DULDEOHV
/RJLFDO0HVVDJH
Notes:
The message segmentation variables relate to the segmenting of the user buffer
information. This involves the creating of multiple physical messages that relate to the
same logical message.
Uempty
6HJPHQWDWLRQE\WKH3URJUDP
SURJUDP
TXHXHPDQDJHU
D TXHXH
E
SURJUDP
D
F
E
G F
G
D E F G
P\*PRRSWLRQV 04&04*02B&203/(7(B06*
04&04*02B:$,7
P\*PRZDLW,QWHUYDO
P\2XW4JHW \RXU0HVVDJHP\*PR
Notes:
A program may also segment a message, by putting many messages with the same
header all indicating segmentation, followed by the relevant portion of the message data.
When getting a message, the program can indicate that if the message is segmented it is to
be reassembled into one message. The header from the first message will provide the
header for the reassembled message. A program can issue get requests indicating that if
the message is segmented it is not to be reassembled, but retrieved as a message. Each
message retrieved this way will indicate that it is segmented.
Application segmentation is used for two reasons:
1. Queue manager segmentation is not sufficient because the application buffer is not large
enough to handle the full message
2. Data conversion must be performed by sender channels and the putting program needs
to split the message on specific boundaries to enable successful conversion of the
segments.
The application can include the Put Message Options of MQPMO_LOGICAL_ORDER. The
same caution applies to using unit of work processing. As each segment is built and the
MQPUT is executed, the application needs to make sure the messageFlags field in the
message descriptor includes either MQMF_SEGMENT or MQMF_SEGMENT_LAST. The
queue manager will assign and maintain the groupId, MsgSeqNumber and offset.
If the application does not specify MQPMO_LOGICAL_ORDER, then the program is
responsible for ensuring the assignment of a new groupId, as well as proper
MsgSeqNumbers and offsets.
If MQGMO_LOGICAL_ORDER is specified in the get message options, all remaining
segments for this logical message shall be processed. Not specifying this option can be
used for recovery purposes.
Finally, any intermediate applications that are simply passing the data should not use the
MQGMO_LOGICAL_ORDER option to ensure the offset field is not corrupted.
Uempty
6HOHFWLYH5HDVVHPEO\
PDWFK2SWLRQVILHOGLQWKHJHWPHVVDJHRSWLRQV
)RUVHOHFWLYH04*(7V
0402B0$7&+B06*B,'
0402B0$7&+B&255(/B,'
0402B0$7&+B*5283B,'
0402B0$7&+B2))6(7DQG
0402B0$7&+B06*B6(4B180
2QO\LI04*02B/2*,&$/B25'(5LVQRW
VSHFLILHG
6HJPHQW6WDWXVILHOGLQWKH*02
5HWXUQHGRQWKH04*(7
0466B127B$B6(*0(17
0466B6(*0(17
0466B/$67B6(*0(17
Notes:
It is possible to control which segment is retrieved by a program as well as have total
control over message retrieval by a program. The match options field of the get message
options structure allows for this.
The following is very much like the process to retrieve a complete message group. Now we
want to learn how to retrieve a complete logical message.
If an application wishes to retrieve a particular logical message, it can begin retrieval of
message from the groupId (using match option MQMO_MATCH_GROUP_ID), the logical
message (using MQMO_MATCH_MSG_SEQ_NUM) starting the MQMD.offset set to zero,
and including MQMO_MATCH_OFFSET in the match options of the get message options
structure. The MQMO_MATCH_MSG_SEQ_NUM is not valid if combined with the
MQGMO_LOGICAL_ORDER.
Finally, an application can determine if it has processed the final segment of a logical
message by checking another field in the get message options structure after a message is
retrieved. The MQGMO.segmentStatus field would contain a value represented by the
symbolic MQSS_LAST_SEGMENT. If not, and a group was being processed, the value
would be MQSS_SEGMENT. The groupStatus field could be checked to see if all logical
messages within the group had been processed.
8QLW&KHFNSRLQW
7KHSURJUDPQHHGVWRUHTXHVWWKHUHWULHYDORIDPHVVDJHZLWKWKH
FRUUHODWLRQLGHQWLILHURIDEF:KDW-DYDREMHFWQHHGVWREHVHW"
:KDWYDULDEOHRIWKLVREMHFWQHHGVWREHVHW"
,IWKHSURJUDPLVWRJHWDPHVVDJHEXWRQO\LILWLVFXUUHQWO\
DYDLODEOHZKDW046HULHVFODVVHVIRU-DYDREMHFWZLOOQHHGWREH
PRGLILHG"
,IWKHSURJUDPLVWRJHWDPHVVDJHDQGLVZLOOLQJWRZDLWLIWKH
PHVVDJHLVFXUUHQWO\XQDYDLODEOHZKDWYDOXHZLOOWKHRSWLRQ
YDULDEOHRIWKH*02REMHFWQHHGWREHVHWWR"
,IWKHSURJUDPLVWRJHWDPHVVDJHDQGLVZLOOLQJWRZDLWIRUD
PD[LPXPRIVHFRQGVLIWKHPHVVDJHLVFXUUHQWO\XQDYDLODEOH
ZKDWYDOXHZLOOEHFRGHGRQWKHZDLW,QWHUYDOYDULDEOH"
Notes:
Uempty
8QLW&KHFNSRLQW
:KDWLVWKHQDPHRIWKHYDULDEOHWKDWLGHQWLILHVWKHJURXSVWDWXVRI
DPHVVDJH"
:KDWLVWKHYDOXHWKDWPXVWEHVSHFLILHGLQWKHPHVVDJH)ODJV
YDULDEOHWRLGHQWLI\WKHPHVVDJHLVWREHORQJWRDJURXS"
:KDWLVWKHPHVVDJH)ODJVVHWWLQJWRDOORZIRUWKHVHJPHQWDWLRQRI
WKHPHVVDJH"
:KDWLVWKHRSWLRQVVSHFLILFDWLRQWKDWZLOOUHVXOWLQRQO\RQH
PHVVDJHEHLQJUHWXUQHGUHJDUGOHVVRIVHJPHQWDWLRQ"
Notes:
6XPPDU\
<RXVKRXOGQRZNQRZKRZWR
*HWPHVVDJHVVHOHFWLYHO\XVLQJPHVVDJH,GDQG
FRUUHODWLRQ,G
&RGHV\QFKURQRXVSURJUDPVXVLQJWKHZDLWDQGWKH
ZDLWLQWHUYDOIXQFWLRQV
6HQGEDWFKHVRIPHVVDJHVXVLQJPHVVDJHJURXSV
6HJPHQWDQGUHDVVHPEOHDPHVVDJH
Notes:
References
SC34-5456 MQSeries Using Java
SC33-1673 MQSeries Application Programming Reference
http://www.ibm.com/software/ts/mqseries/messaging
WebSphere MQ
2EMHFWLYHV
7ULJJHUSURJUDPVXVLQJWKH046HULHVWULJJHUIXQFWLRQ
,QTXLUHDWWULEXWHVRI046HULHVREMHFWV
6HWTXHXHDWWULEXWHV
+DQGOHGDWDFRQYHUVLRQ
6HQGPHVVDJHVWRDGLVWULEXWLRQOLVW
Notes:
7ULJJHULQJ7\SHV
3URJUDP "
4XHXH0DQDJHU
4XHXH
4XHXH
Notes:
A client program puts a message on a queue and then waits for the response.
Who generates the response?
A server program.
How is the server program started?
The server program may be started automatically, by a feature of MQSeries known as
triggering.
There are three types of triggering supported by MQSeries:
The first type is where the server program is activated when the number of eligible
messages on the queue reaches a specified value. This form of triggering is known as
'trigger on depth', and is suitable for batch type processing.
The second type of triggering is where the server program is activated when the first
eligible message arrives on the queue. This form of triggering is known as 'trigger on first',
and is suitable for most types of processing and especially where the arrival of messages is
Uempty infrequent. An eligible message is a message that has the priority variable set to a value
equal to or greater than the trigger message priority setting of the queue.
The third type of triggering is where an instance of the server program is to be activated
each time a message is put on the queue. This form of triggering is known as 'trigger on
every', and is suitable for highly available and scalable systems, especially where there is a
requirement for each message to be processed by a separate server.
7ULJJHULQJ&KDUDFWHULVWLFV
7ULJJHU&RQWURO
7ULJJHU'DWD
7ULJJHU'HSWK
7ULJJHU0HVVDJH3ULRULW\
7ULJJHU7\SH
Notes:
A queue can only support one form of triggering at any time. The type of triggering is
controlled by the queue definition as stored on the queue manager. The program can
inquire and change the triggering characteristics by the use of the getxxx and setxxx
methods of the MQQueue class. To support these methods, the queue must have been
opened with the inquire and set options, else their use will result in an MQException being
thrown.
Uempty
3URFHVV
Notes:
The process object is defined to the queue manager by the administration utilities, it details
the program name and associated attributes. The name of this object is referenced by the
process attribute of a local queue. The process object can be referenced by many local
queues, but a local queue can only reference one process object.
You can manage this object using the MQProcess class:
public MQProcess (MQQueueManager qMgr,
String processName,
int openOptions,
String queueManagerName,
String alternateUserId)
,QLWLDWLRQ4XHXH
TXHXHZLWKWULJJHULQJ 21
SXW
3URFHVV WULJJHUFRQWURO
PHVVDJH
LQLWLDWLRQTXHXH
Notes:
When defining a queue, you must associate this queue with two other MQSeries objects in
order to allow triggering:
The first object that the queue definition refers to is the name of another queue to receive
the trigger control messages for this queue. This queue is known as an initiation queue.
The name of this queue is contained in the initiation queue attribute of the current queue.
To extract this value the inquire method must be used. An MQException will be thrown by
this method if the queue is not open or the queue was not opened with the inquire option.
The second object that the queue definition refers to is a process definition. This object
describes the attributes of the required server program.
Uempty
7ULJJHU0RQLWRU
TXHXHZLWKWULJJHULQJ 21
SXW
3URFHVV WULJJHUFRQWURO
PHVVDJH
LQLWLDWLRQTXHXH
75,**(5021,725
Notes:
The initiation queue must be serviced by a special type of program referred to as a trigger
monitor. This program will get messages from the assigned input queue and expect each
message to be a MQSeries trigger control message. This format is documented in the
structure named MQTM. The message is constructed from information obtained by the
queue manager from the input queue and the associated process definition.
The purpose of the trigger monitor program is to activate the required program, as
documented by the MQTM message. The MQSeries server product code includes a
suitable trigger monitor for general use.
,PSOHPHQWDWLRQRI7ULJJHULQJ
TXHXHZLWKWULJJHULQJ 21
SXW
3URFHVV WULJJHUFRQWURO
PHVVDJH
LQLWLDWLRQTXHXH
6HUYHUSURJUDP
JHW
75,**(5021,725
Notes:
When a program puts a message on a queue, the queue manager will automatically
evaluate the queue for a triggering condition. If a trigger condition is raised, the queue
manager will create the trigger control message, from the queue definition and the
associated process definition and write this new message to the associated initiation
queue. Note that no part of the user message that has been placed on the application
queue is included in the special control message written to the initiation queue.
The trigger monitor is waiting on the get request, it now receives the message and
activates the identified program.
The server program now opens and gets messages from the application queue. This
program receives the name of the application queue from the trigger monitor via activation
arguments (in fact, the trigger monitor passes information to the started program via a
structure called MQTMC2, which contains the name of the triggered queue. This structure
is not available for Java, but is described in the Application Programming Reference).
,QTXLUHDQG6HW$WWULEXWHV
LQTXLUH
4XHXH0DQDJHU
DOO
DWWULEXWHV
3URFHVV
VHW
WULJJHU
DWWULEXWHV
Notes:
Inquire and set methods are used to perform some of the administrative functions within a
program.
Inquire allows you to get all of the attributes of any queue, process, queue manager, or
namelist. Set allows you to change attributes, but only some attributes of a queue.
Before you use the inquire or set method your application must be connected to the queue
manager, and the object must be open, with the open or set open option.
Uempty
:K\,QTXLUHDQG6HW"
7RTXHU\WKHPD[LPXPPHVVDJHOHQJWKIRUDTXHXHWR
VHWXSWKHLQSXWEXIIHUVL]HEHIRUWKHJHW
7RTXHU\WKHPD[LPXPGHSWKDQGWKHFXUUHQWGHSWKRID
TXHXH
7RTXHU\WKHQDPHRIWKHGHDGOHWWHUTXHXH
7RFKDQJHDTXHXHZLWK75,*7<3( '(37+IURP
1275,**(5WR75,**(5
Notes:
Within a program, you use this information to discover the maximum message length for a
particular queue, to get the name of the application program pointed to by a process, to find
the name of the dead letter queue, or to find the list of attributes for a namelist.
The set method allows to change the queue attributes associated with triggering.
,QTXLUH$WWULEXWHV
4XHXH0DQDJHU
LQTXLUH
DOO
DWWULEXWHV
3URFHVV
040DQDJHG2EMHFW
P\40JUJHW
SXEOLFYRLGLQTXLUH
LQWVHOHFWRUV>@ P\3URFHVVJHW
LQWLQW$WWUV>@
E\WHFKDU$WWUV>@ P\4XHXHJHW
Notes:
Inquire is a method of the MQManagedObject class. So MQQueue, MQQueueManager,
and MQProcess inherit it.
Many of the more common attributes can be queried using the getXXX() methods defined
in MQManagedObject, MQQueueManager, MQQueue, and MQProcess.
Uempty
6HW$WWULEXWHV
VHW
WULJJHU
DWWULEXWHV
Notes:
Set is a method of the MQManagedObject class. So MQQueue inherits it.
All the queue attributes that can be changed by the program can be set using the setXXX
methods defined in MQQueue.
'DWD)RUPDWV
3&
&RGHSDJH
LEP
$6&,, 26
OLWWOHHQGLDQ
&RGHSDJH
LEP
(%&',&
ELJHQGLDQ
Notes:
When data is moved between different operating system environments it must be checked,
to see if the data was stored using the same or similar code pages.
Each operating system has to identify and store the character set coding being used. The
value will indicate what code page is being used, whether the data is stored in ASCII or
EBCDIC format and what the local language code is set to.
Numeric data is potentially represented differently by each of the operating system
environments. Big endian and little endian are standard identifiers for the representation of
numeric data. Where big endian compliant operating environments store the data in what is
termed as normal format. Little endian compliant operating environments store the data in
the reverse order to big endian data. Also note that the system/390 environment has a
different length for the storage of large floating point numbers compared to the IEEE
standard format.
Java overcomes this by having a standard format for the representation of numeric data
regardless of the operating environment.
Uempty
6HOHFWLQJWKH'DWD)RUPDW
3URJUDP 4XHXH0DQDJHU
040HVVDJH
4XHXH
040HVVDJHP\0HVVDJH QHZ040HVVDJH
P\0HVVDJHFKDUDFWHU6HW 04&04&&6,B4B0*5
P\0HVVDJHHQFRGLQJ 04&04(1&B,17(*(5B1250$/_
04&04(1&B'(&,0$/B1250$/_
04&04(1&B)/2$7B,(((B1250$/
Notes:
On each operating system environment a local identifier is used to indicate the manner in
which data is represented. This indicator is obtained and stored by the queue manager
during queue manager creation. The value is made available to the program via the
getCharacterSet method of the MQQueueManager class:
int ourCodePage = qMgr.getCharacterSet();
System.out.println("the queue manager is using code page numbered:
" + ourCodePage);
When the MQMessage object is instantiated the characterSet variable is set to the default
value of MQC.MQCCSI_Q_MGR. This value indicates that the writexxx methods,
associated with the storing of character based data, are to store that data in the code page
format as indicated by the queue manager characterSet variable.
The MQSeries product identifies internally the manner in which numeric data is stored by
the operating environment. When an MQMessage object is instantiated, the encoding
variable will be set to the default value of MQC.MQENC_NATIVE. This value indicates that
integer, decimal and floating point data when written to the buffer by the supplied writexxx
methods will be stored in big-endian format.
The queue manager automatically converts the message variables of the message that
has been selected, before it is placed in the MQMessage object. This conversion is
performed using the characterSet and encoding of the originating and destination systems.
The exception to this conversion is that all byte type variables are not converted. The byte
type variables are: messageId, correlationId, accountingToken and groupId. As these
variables are not converted, care must be taken when analyzing or reporting their value.
Uempty
'DWD&RQYHUVLRQE\:ULWHRU5HDG0HWKRGV
3URJUDP 3URJUDP
4XHXH0DQDJHU
ZULWH87) UHDG87)
4XHXH
Notes:
The data written to the message buffer by these writexxx methods will automatically be
subject to character and numeric conversion, based on the values of the encoding and
characterSet variables. If these two variables are set to values other than the default then
the data will be converted into the encoding and characterSet as indicated, if that
conversion is supported by this implementation of the MQSeries product.
The data will also be subjected to conversion analysis as it is retrieved by the readxxx
methods.
Using the writeUTF() method automatically encodes the length of the string as well as its
Unicode bytes. This is then the simplest way to send string data if the message data is to
be read by another Java program using the readUTF() method.
5HTXHVWLQJ&RQYHUVLRQ
043XW0HVVDJH2SWLRQVP\302 QHZ043XW0HVVDJH2SWLRQV
P\0HVVDJHIRUPDW $%&
P\0HVVDJHHQFRGLQJ 04&04(1&B,17(*(5B5(9(56('_
04&04(1&B'(&,0$/B5(9(56('_
04&04(1&B)/2$7B,(((B5(9(56('
P\0HVVDJHFKDUDFWHU6HW
P\2XWSXW4XHXHSXW P\0HVVDJHP\3PR
04*HW0HVVDJH2SWLRQVP\*02 QHZ04*HW0HVVDJH2SWLRQV
P\*PRRSWLRQV 04&04*02B&219(57
P\,QSXW4XHXHJHW P\0HVVDJHP\*PR
Notes:
The program can request that MQSeries should check and convert the message data if
required. MQGMO_CONVERT is the get message option to request this feature. If the
code pages of the sender and the MQMessage object are found to be different, the data
contained within the message will be converted to the code page as identified by the
characterSet variable of the MQMessage object. This process occurs before the queue
manager completes the get request.
The conversion of the message data, as performed by the queue manager in response to
the get message option of convert, is controlled by the value of the format variable. The
value is set by the message sender to indicate to the receiver the nature of the message
data. The format variable is an 8 character value, if the value is set to an MQSeries
provided literal, then the queue manager will convert the data using the knowledge it has of
that format.
The possible values of the format variable are:
MQC.MQFMT_NONE
This is the default value for the format variable, as there is no value the queue manager will
Uempty be unable to convert the user message data. A get request with the convert option will
result in an MQException being thrown, if the message encoding or characterSet variables
indicate conversion is required.
MQC.MQFMT_STRING
When the format variable is set to this value it indicates to the queue manager that the user
message data consists entirely of characters. The queue manager will convert the data
character by character, using the sending and receiving character code set conversion
tables.
User declared value.
When the value of the format variable is not recognized by the queue manager, it is
assumed to be the name of a user supplied conversion exit program. The value will be
used in a dynamic link request, if the link fails then the conversion request will fail and an
MQException will be thrown by the interface.
:KDWDUH'LVWULEXWLRQ/LVWV"
3DULV
"
4XHXH
'DOODV
4XHXH
'LVWULEXWLRQ/LVW
4XHXH1DPH 40JU1DPH
0$,/B,1B+856/(< "
0$,/B,1B3$5,6
0$,/B,1B'$//$6 6HDWWOH
0$,/B,1B6($77/(
4XHXH
4XHXH
Notes:
Prior to availability of the Version 5 products, there was no true distribution list support in
MQSeries. Distribution lists allow you to put a message to multiple destinations in a single
MQPUT call. Multiple queues can be opened using a single MQOPEN and then a single
message can be put to each of those queues using the single MQPUT.
The distribution list feature is implemented by the following MQSeries base classes for
Java interface:
MQDistributionList
MQDistributionListItem
MQMessageTracker
Also this feature utilizes the following four variables of the MQPutMessageOptions class:
knownDestCount
unknownDestCount
invalidDestCount
recordFields
Uempty Note: A distribution list can only be used to put a message, it may not be used with the get
method.
The distribution list feature is not available on all implementations of MQSeries. Please
refer to the documentation associated with the installed version before attempting to use
this feature.
&UHDWLQJD'LVWULEXWLRQ/LVW
04'LVWULEXWLRQ/LVW,WHP>@P\'/, QHZ04'LVWULEXWLRQ/LVW,WHP>@
IRU LQWL LL
^
P\'/,>L@ QHZ04'LVWULEXWLRQ/LVW,WHP
`
P\'/,>@TXHXH1DPH -LP
P\'/,>@TXHXH1DPH .HOO\
P\'/,>@TXHXH1DPH .DWK\
P\'/,>@TXHXH1DPH *DLO
P\'/,>@TXHXH1DPH 9DQHVVD
P\'/,>@TXHXH1DPH 5LQJ
Notes:
Each queue that is to be opened is named by the value of the queueName variable of an
MQDistributionListItem object.
The distribution list items are constructed as elements of an array, where the number of
occurrences represents the number of queues that are to be opened.
Uempty
2SHQLQJD'LVWULEXWLRQ/LVW
LQWR2SWV 04&0422B287387
04'LVWULEXWLRQ/LVWP\'/
P\4PJUDFFHVV'LVWULEXWLRQ/LVW P\'/,R2SWV
Notes:
The distribution list is created and an open request is issued to the named queues when
the accessDistributionList request is issued.
The first parameter of this method is an array representing the MQDistributionListItem
objects.
On completion of the accessDistributionList, each element will indicate the outcome of the
request in regards to the named queue. An MQException will still be thrown on the
occurrence of an exception, but as this request references potentially many queues, the
reasonCode and completionCode of the MQException object can not reflect each and
every queue. Therefore the completionCode and reasonCode relating to each queue is
stored in variables of that name in the associated MQDistributionListItem object.
3XWWLQJD0HVVDJHRQWRD'LVWULEXWLRQ/LVW
043XW0HVVDJH2SWLRQVP\302 QHZ043XW0HVVDJH2SWLRQV
P\0HVVDJHZULWH&KDUV 60(WDVNFRPSOHWHG
P\'/SXW P\0HVVDJHP\302
Notes:
The put method of the associated distribution list object, will send the message to each of
the queues that was successfully opened by the accessDistributionList method.
Uempty
(UURU+DQGOLQJ
DFFHVV'LVWULEXWLRQ/LVW
+XUVOH\
P\'LVW/LVWSXW
4XHXH
3DULV
"
4XHXH
'DOODV
4XHXH
'LVWULEXWLRQ/LVW
4XHXH1DPH 40JU1DPH
0$,/B,1B+856/(< "
0$,/B,1B3$5,6
0$,/B,1B'$//$6 6HDWWOH
0$,/B,1B6($77/(
4XHXH
4XHXH
Notes:
Each destination queue is opened separately, meaning some could succeed and others
could fail if they are not valid. If all queues open successfully, the completion code returned
from the MQOPEN will be MQCC_OK. If all the queues failed to open, it will be
MQCC_FAILED. However, if some queues are successfully opened and some fail to open,
the completion code will be MQCC_WARNING. In the last two cases, the reason code will
be MQRC_MULTIPLE_REASONS.
Therefore, it is necessary to use other means to handle errors: on the unsuccessful
completion of the accessDistributionList request, the following methods of the
MQDistributionList class can assist in the problem analysis:
getFirstDistributionListItem
getNextDistributionListItem
getPreviousDistributionListItem
getValidDestinationCount
getInvalidDestinationCount
Uempty
3UREOHP'HWHUPLQDWLRQ
P\'/,WHP P\'/JHW)LUVW'LVWULEXWLRQ/LVW,WHP
LI P\'/,WHPUHDVRQ&RGH 04([FHSWLRQ045&81.12:1B4B1$0( ^`
LQWP\&RXQW P\'/JHW9DOLG'HVWLQDWLRQ&RXQW
LI P\&RXQW!
P\'/SXW P\0HVVDJHP\302
LQWP\&RXQW P\'/JHW,QYDOLG'HVWLQDWLRQ&RXQW
LI P\&RXQW!
6\VWHPRXWSULQWOQ P\FRXQWTXHXHVIDLOHGWRRSHQ
P\'/,WHP P\'/JHW)LUVW'LVWULEXWLRQ/LVW,WHP
LI P\'/,WHPUHDVRQ&RGH 04([FHSWLRQ045&81.12:1B4B1$0( ^`
ORRS
P\'/,WHP P\'/,WHPJHW1H[W'LVWULEXWHG,WHP
LI P\'/,WHPUHDVRQ&RGH 04([FHSWLRQ045&81.12:1B4B1$0( ^`
Notes:
The getFirstDistributionListItem method of the MQDistributionList class will return the first
item associated with the list. Once returned, the variables of this item are available for
analysis.
The getNextDistributionListItem method of the MQDistributionListItem class will return the
next item associated with this list of items. Once returned, the variables of this item are
available for analysis.
The getPreviousDistributionListItem method of the MQDistributionListItem class will return
the previous item associated with this list of items. Once returned, the variables of this item
are available for analysis.
The getValidDestinationCount method of the MQDistributionList class will return an integer,
set to the number of items in the distribution list that were opened successfully.
The getInvalidDestinationCount method of the MQDistributionList class will return an
integer, set to the number of items in the distribution list that failed the open request.
8QLW&KHFNSRLQW
'RHVWKHTXHXHPDQDJHUVWDUWDSURJUDP"
,VWKHWULJJHUHYHQWFRQWUROOHGE\WKHPHVVDJHGDWD"
,VWKHWULJJHUHYHQWFRQWUROOHGE\DPHVVDJHYDULDEOH"
,VWKHPHVVDJHWKDWUHVXOWVLQWKHWULJJHUHYHQWSDVVHGWRWKH
WULJJHUHG SURJUDP"
/LVWDOOWKHTXHXHDWWULEXWHVWKDWFDQEHVHW"
,QGLVWULEXWLRQOLVWSURFHVVLQJZKDWLVWKHQDPHRIWKHFODVVWKDW
KROGVWKHQDPHVRIWKHTXHXHVWREHRSHQHG"
:KDWLVWKHQDPHRIWKHFODVVWKDWUHSUHVHQWVWKHRSHQHGOLVWRI
TXHXHV"
Notes:
Uempty
6XPPDU\
<RXVKRXOGQRZNQRZKRZWR
8VHWKHWULJJHULQJIXQFWLRQRI046HULHV
,QTXLUHDQGVHWDWWULEXWHVRI046HULHVREMHFWV
+DQGOHGDWDFRQYHUVLRQ
6HQGPHVVDJHVWRDGLVWULEXWLRQOLVW
Notes:
References
SC34-5456 MQSeries Using Java
SC33-1673 MQSeries Application Programming Reference
http://www.ibm.com/software/ts/mqseries/messaging/
WebSphere MQ
2EMHFWLYHV
8QGHUVWDQGWKHFRQWH[WYDULDEOHVRIWKHPHVVDJH
REMHFW
6DYHWKHFRQWH[WILHOGVLQDSURJUDPDQGWKHQSDVV
WKRVHILHOGVRQWRDQRWKHUPHVVDJH
8VHDOWHUQDWHXVHUDXWKRULW\WRDOORZRQHXVHUWRVHQG
DPHVVDJHRQEHKDOIRIDQRWKHU
Notes:
8VHU,GHQWLILFDWLRQ
3URJUDP 4XHXH0DQDJHU
6723
4XHXH
Notes:
When a program connects to a queue manager, the current user identity is checked for the
authority to connect to this queue manager.
In the OS/390 environment the type of program is also checked for the authority to connect
to this queue manager.
The queue manager does not include code for the checking of security or authority. Instead
it calls upon an external environment specific authority or security manager. On OS/390
this manager is a SAF enabled security manager, for example the IBM RACF product. On
the distributed platforms the authority manager is supplied, except on OS/2, as a
component of the MQSeries product and is referred to as the Object Authority Manager.
When the program opens the queue, via the accessQueue method, the current user
identification is checked by the object authority manager or external security manager as
appropriate for the environment. The user must have the authority to open the queue for all
the purposes as described by the open options.
Uempty For the Java program the options are values of the options integer as specified on the
accessQueue request. If the user is not authorized for any of the open options, the
accessQueue request will throw an MQException and the reasonCode variable will be set
to MQC.MQRC_NOT_AUTHORIZED.
If the queue object being opened is an alias queue, the authority checking is performed on
the name as specified on the accessQueue request and not the queue object that is the
target of the alias definition. When the put method is issued, the messages are put on the
target of the alias queue and not the alias queue.
7KH&RQWH[W9DULDEOHV
'HIDXOW
352*5$0 &RQWH[W 0(66$*(
3$66B$//B&217(;7
Notes:
The context variables are seven variables that collectively are managed as the context
fields of the message descriptor. The actions performed on these variables is managed by
options specified on the open and put requests.
After the put request has completed successfully by default these variables will reflect the
environment of this program.
Typically, application programs will not explicitly update the context fields. The default
behavior will be that the queue manager plugs in all of the fields. In fact, usually, an
application will not be authorized to update the context fields.
In the case of an application that is simply passing a message along, it is possible (if
authorized) to pass context information from an input message to an output message.
Context variables include userid, and information concerning the putting application.
Uempty
&RQWH[W3URSHUWLHVRID0HVVDJH
3URJUDP 4XHXH0DQDJHU
040HVVDJH
4XHXH
LGHQWLW\FRQWH[W
RULJLQFRQWH[W
Notes:
When a message is placed on the queue the setting of all the message variables has been
completed. A group of the message variables are collectively known and managed as the
context variables. The context variables indicate to the receiver of the message information
pertaining to the originator of the message. For manageability the context variables are
further categorized as either being associated with the identity or origin.
The identity context identifies the user, and consists of three variables:
userId
The identity of the user, as set at the time of the put request, is stored in this variable of the
MQMessage object. The string value has a maximum length of 12 characters.
accountingToken
The accountingToken is a 32 byte variable that the queue manager treats as a string of bits.
The queue manager does not check the content of this variable on the get request. The
value is set by the queue manager, at the time of the put request, as follows. The first byte
of the field is set to the length of the accounting information present in the bytes that follow,
this length is in the range zero through thirty, and is stored in the first byte as a binary
integer. The second and subsequent bytes (as specified by the length field) are set to the
accounting information appropriate to the environment. The last byte of the
accountingToken is identified as the accounting-token type.
applicationIdData
The applicationIdData variable is a 32 character value, the contents are defined by the
program. This variable can be used to provide additional information about the message or
its originator. The queue manager does not set the value to anything other than blank,
unless context manipulation options are used on the put request.
The origin context identifies the program that created the message, and consists of four
variables:
putApplicationType
This variable is an integer that can be set by the queue manager to indicate the type of
program that has put the message. The value can also be set by a program when the
correct put message options are coded.
putApplicationName
This variable is a 28 character string value that names the program that created the
message.
putDateTime
The date and time that the message was put on the queue. The variable is stored as a
GregorianCalendar type. The queue manager records all date and time values relative to
Greenwich Mean Time. The Java classes provide the conversion between the putdate and
puttime attributes of the MQMD object and the putDateTime variable of the MQMessage
object.
applicationOriginData
The applicationOriginData variable is a 4 character string, the value of which is set by the
program. The queue manager makes no use of this variable other than accepting the value
set by the program when the put is issued with the appropriate put option.
Uempty
0DQLSXODWLQJWKH&RQWH[W9DULDEOHV
Notes:
Depending on the Put Message Options, the context variables will contain different values
after a put:
If the program sets the options variable of the MQPutMessageOptions object to include the
option of MQC.MQPMO_DEFAULT_CONTEXT. The queue manager determines the
values of the context variables from the environment and not from the MQMessage object.
The values are returned to the program on completion of the put request. This context
option is the default setting if no context option is specified.
If the program sets the options variable of the MQPutMessageOptions object to include the
option of MQC.MQPMO_NO_CONTEXT. The queue manager sets both the origin and
identity context variables to null. The values are returned to the program on completion of
the put request.
If the program sets the options variable of the MQPutMessageOptions object to include the
option of MQC.MQPMO_SET_IDENTITY_CONTEXT. The queue manager accepts the
values of the identity context variables as coded in the MQMessage object, and determines
from the environment the values for the origin context variables. The values are returned to
the program on completion of the put request.
(For the program to use the put option of MQC.MQPMO_SET_IDENTITY_CONTEXT, the
option of MQC.MQOO_SET_IDENTITY_CONTEXT must have been included in the open
options specified on the accessQueue request.)
If the program sets the options variable of the MQPutMessageOptions object to include the
option of MQC.MQPMO_SET_ALL_CONTEXT. The queue manager accepts the values of
all the identity and origin context variables from the MQMessage object.
(For the program to use the put option of MQC.MQPMO_SET_ALL_CONTEXT, the option
of MQC.MQOO_SET_ALL_CONTEXT must have been included in the open options
specified on the accessQueue request.)
If the program sets the options variable of the MQPutMessageOptions object to include the
option of MQC.MQPMO_PASS_IDENTITY_CONTEXT. This request must also include the
reference to another MQMessage object that had previously received a message. The
queue manager copies from the specified MQMessage object the saved identity context
variables. Then sets the values of the origin context variables from the current
environment. The values are returned to the program on completion of the put request.
(For the program to use the put option of MQC.MQPMO_PASS_IDENTITY_CONTEXT, the
option of MQC.MQOO_PASS_IDENTITY_CONTEXT must have been included in the open
options specified on the accessQueue request.)
If the program sets the options variable of the MQPutMessageOptions object to include the
option of MQC.MQPMO_PASS_ALL_CONTEXT. The queue manager copies all the values
of the context variables from the referenced MQMessage object. No values are taken from
the current environment or from the MQMessage object being put on the queue. The
values are returned to the program on completion of the put request.
(For the program to use the put option of MQC.MQPMO_PASS_ALL_CONTEXT, the
option of MQC.MQOO_PASS_ALL_CONTEXT must have been included in the open
options specified on the accessQueue request.)
Note that you need special authorization to modify the context.
Uempty
3DVV&RQWH[W([DPSOH&RGH
...
oOpts = MQC.MQOO_SAVE_ALL_CONTEXT |
MQC.MQOO_INPUT_AS_Q_DEF;
myInputQueue = myQMgr.accessQueue("Q1", oOpts);
oOpts = MQC.MQOO_PASS_ALL_CONTEXT |
MQC.MQOO_OUTPUT;
myOutputQueue = myQMgr.accessQueue("Q2", oOpts);
Notes:
$OWHUQDWH8VHU,'
3URJUDP 3URJUDP
4XHXH0DQDJHU
4XHXH
4XHXH
P\,QSXW4XHXHJHW \RXU0HVVDJHJP2SWV
LQWR2SWV 04&0422B287387_04&0422B$/7(51$7(B86(5B$87+25,7<
044XHXHP\24 T0JUDFFHVV4XHXH \RXU0HVVDJHUHSO\7R4XHXH1DPH
R2SWV
\RXU0HVVDJHUHSO\7R4XHXH0DQDJHU1DPH
QXOO
\RXU0HVVDJHXVHU,G
Notes:
The server program gets a message from the input queue, services the message then
responds to the client by putting a reply message on the output queue. The server is told
the name of the output queue by the client program in the value of the replyToQueueName
variable of the MQMessage object.
For the subsequent accessQueue request to be successful, the associated userid must be
authorized to perform the specified options on the named queue. The question is: will the
userid assigned to the server program need authority to open any queue for output
processing?
MQSeries provides for a program to specify an alternate userid on the open request. This
feature allows the server to specify the clients userid, as passed in the MQMessage
variable userId, instead of its own userid. It is the client that has named the queue for the
reply message to be put on, it should be therefore authorized to request this. MQSeries
does not check that a userid is authorized to use the queue named as the value of the
replyToQueueName variable. The authority over a queue is checked only during the
accessQueue request.
8QLW&KHFNSRLQW
:KLFKPHWKRGVFDQWKURZDQ04([FHSWLRQZLWKWKHUHDVRQ&RGH
YDULDEOHVHWWR04&045&B127B$87+25,=('"
/LVWDOOFRQWH[WYDULDEOHV
:KLFK3XW0HVVDJH2SWLRQZLOOUHVXOWLQDPHVVDJHZLWKQXOO
YDOXHVLQWKHFRQWH[WYDULDEOHV"
Notes:
Uempty
6XPPDU\
&RQWH[WILHOGVDUHFRQWDLQHGZLWKLQHYHU\PHVVDJHDQG
FDQEHXVHGIRUVHFXULW\
$OWHUQDWHXVHUDXWKRULW\FDQEHXVHGWRDOORZRQHXVHUWR
VHQGPHVVDJHVRQEHKDOIRIDQRWKHUXVHU
Notes:
References
SC34-5456 MQSeries Using Java
SC33-1673 MQSeries Application Programming Reference
http://www.ibm.com/software/ts/mqseries/messaging/
WebSphere MQ
© Copyright IBM Corp. 2000, 2002 Unit 10. Units of Work 10-1
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
2EMHFWLYHV
:RUNXQGHUV\QFSRLQWFRQWURO
,PSOHPHQWORFDOXQLWVRIZRUN
,PSOHPHQWJOREDOXQLWVRIZRUN
Notes:
© Copyright IBM Corp. 2000, 2002 Unit 10. Units of Work 10-3
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
8QLWRI:RUN
3URJUDP 4XHXH0DQDJHU
*(7
SURFHVVLQJ
4XHXH
ORJLF
4XHXH
5(3/<
XQLWRIZRUN
Notes:
In the above example, the program is designed to get a message, process the message
and then respond by putting a reply message. This could then be termed to be our unit of
work, as it encapsulates the total processing required by the program in servicing a
message.
If the program is interrupted before it is able to complete the processing of the message, it
would want the system to reverse the actions that have already been completed. The term
'backout' is used to describe the process of reversing the actions performed within the 'unit
of work'. In this example the action that needs to be reversed is the getting of the message.
The program issued the get request without the browse option, therefore the message was
deleted.
To make this a system managed unit of work, the program would need to enable the
system to reverse that part of the work that has been processed. The system that performs
the management of the unit of work is referred to as the transaction manager or unit of
work manager. The transaction manager treats all work as automatic encapsulations of unit
of work.
Uempty The unit of work is started by the updating of a recoverable resource and is completed by
the closing of the unit of work. For MQSeries the recoverable resource can only be a
message. The closing of the unit of work is done by a method of the MQQueueManager
class. The unit of work can not exceed the program disconnecting from the queue
manager.
© Copyright IBM Corp. 2000, 2002 Unit 10. Units of Work 10-5
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
,PSOHPHQWLQJWKH/RFDO82:3URFHVVLQJ
3URJUDP 4XHXH0DQDJHU
*(7
4XHXH
4XHXH
04*HW0HVVDJH2SWLRQVJP2SW QHZ04*HW0HVVDJH2SWLRQV
JP2SWRSWLRQV 04&04*02B6<1&32,17
P\,QSXW4XHXHJHW \RXU0HVVDJHJP2SW
Notes:
The get method, without the browse option, is a destructive request as the message will be
deleted from the queue, upon successful completion of the get request. The automatic
deletion of the message can be deferred by the inclusion of an option to include this
message in the current unit of work:
MQC.MQGMO_SYNCPOINT
The options variable of the Get Message Options needs to be set to the syncpoint option to
enable the message to be included in the unit of work. The message will be returned to the
program but the deletion of the message from the queue will be deferred until the work unit
is completed. If the program is interrupted before completing the unit of work, the effect of
the get will be reversed and the message will become available for retrieval again.
MQC.MQGMO_SYNCPOINT_IF_PERSISTENT
The options variable of the get message options object can be set to this form of the
syncpoint option. This enables the message to be included in the unit of work, but only if
the message is also marked as persistent. If the message is not marked as persistent then
the message will not be included in the unit of work.
Uempty MQC.MQGMO_NO_SYNCPOINT
If the options variable is set to the no_syncpoint option then the message will be deleted
automatically by the queue manager on the successful completion of the get request. The
message will not be included in the unit of work. The actions performed by the get request
will not be reversible, regardless of the completion status of the program.
These options are also available in the Put Message Options:
MQC.MQPMO_SYNCPOINT
MQC.MQPMO_NO_SYNCPOINT
© Copyright IBM Corp. 2000, 2002 Unit 10. Units of Work 10-7
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
&RPPLW
3URJUDP 4XHXH0DQDJHU
*(7
4XHXH
TPJUFRPPLW 4XHXH
5(3/<
Notes:
qMgr.commit();
The commit method of the queue manager class indicates that the program has completed
the required processing and that the queue manager is to close the current unit of work
held open by this program. The closing of the current unit of work will release the
messages that have been held by the syncpoint option. The issuing of the commit method
indicates to the queue manager that the actions of this program are not to be reversed after
the completion of this request.
Uempty
%DFNRXW
3URJUDP 4XHXH0DQDJHU
*(7
4XHXH
TPJUEDFNRXW
4XHXH
Notes:
qMgr.backout();
The backout method of the queue manager class will reverse all the changes made by this
program that are currently held with the syncpoint option. The affect of this method is to put
messages back on the queues that have been retrieved, and delete from the queues those
messages that have been put. But only if they were processed by this program within the
current unit of work with the syncpoint option.
myMessage.backoutCount
Each time the actions of the get method are backed out and the deletion of a message is
reversed, the backout counter variable of the message is incremented.
This action is dependent on an attribute of the queue definition, named the harden backout
count. If it is set to yes the counter will be incremented automatically. If it is set to no, then
the backout counter will always be zero regardless of the number of times it is backed out.
© Copyright IBM Corp. 2000, 2002 Unit 10. Units of Work 10-9
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
© Copyright IBM Corp. 2000, 2002 Unit 10. Units of Work 10-11
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
,PSOHPHQWLQJWKH*OREDO82:3URFHVVLQJ
*(7 4XHXH0DQDJHU
3URJUDP
TPJUEHJLQ
4XHXH
4XHXH
5(3/<
;$&RRUGLQDWRU
'%
RSHUDWLRQV
'DWDEDVH
;$5HVRXUFH0DQDJHU
Notes:
qMgr.begin();
The begin method of the MQQueueManager class begins a unit of work that is coordinated
by the queue manager, and that may involve external resource managers. The begin
method will establish the queue manager as a global unit of work coordinator with an
external resource manager. This other manager will be an XA compliant client attached
database environment.
This allows the SQL statements to be included within the same unit of work as the
MQSeries requests without the need for a transactional manager. When the commit and
backout requests are issued the effect of the begin method will be to also commit the
database changes made by this program within this unit of work.
Uempty
*OREDO82:([DPSOH&RGH
...
qMgr = new MQQueueManager("QM1");
Connection con = qMgr.getJDBCConnection(xads);
qMgr.begin();
3HUIRUP04DQG'%RSHUDWLRQVWREHJURXSHGLQD8QLWRI:RUN
qMgr.commit() RU qMgr.backout();
con.close();
qMgr.disconnect();
...
Notes:
© Copyright IBM Corp. 2000, 2002 Unit 10. Units of Work 10-13
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
&RQVLGHUDWLRQVIRU*OREDO82:3URFHVVLQJ
3URJUDP 4XHXH0DQDJHU
TPJUEHJLQ *(7
4XHXH
TPJUEDFNRXW
TPJUFRPPLW 4XHXH
5(3/<
Notes:
The begin method can not be requested while connected to the queue manager via the
client bindings.
The begin method can not be requested while a unit of work is current.
The begin method request will fail if no external resource manager is identified to the queue
manager.
The begin, commit and backout methods can not be requested while the program is
managed by a transactional manager, example CICS Transaction Server for OS/390.
If a unit of work is still current when the connection to the queue manager is disconnected,
the unit of work will be backed out.
When the Java program is run under the control of the CICS Transaction Server of OS/390
product the program should issue the com.ibm.cics.server.Task.commit() method to
complete the unit of work or the com.ibm.cics.server.Task.rollback() method to backout the
current unit of work. These requests must be issued before the program terminates, else
the unit of work will be backed out.
© Copyright IBM Corp. 2000, 2002 Unit 10. Units of Work 10-15
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
8QLW&KHFNSRLQW
:KDWLVWKHJHWRSWLRQWKDWZLOOGHIHUWKHGHOHWLRQRIWKHPHVVDJH
WKDWKDVEHHQUHWULHYHGE\WKHJHWUHTXHVW"
:KDWLVWKHQDPHRIWKHPHWKRGWKDWZLOOFRPSOHWHDXQLWRIZRUN"
:KDWLVWKHW\SHRIREMHFWWKDWLVDVVRFLDWHGZLWKWKLVPHWKRG"
Notes:
Uempty
6XPPDU\
<RXVKRXOGQRZNQRZKRZWR
&RGHSURJUDPVXQGHUV\QFSRLQW
,PSOHPHQWORNDOXQLWVRIZRUN
,PSOHPHQWJOREDOXQLWVRIZRUN
Notes:
© Copyright IBM Corp. 2000, 2002 Unit 10. Units of Work 10-17
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
References
SC34-5456 MQSeries Using Java
http://www.ibm.com/software/ts/mqseries/messaging/
WebSphere MQ
2EMHFWLYHV
&RGHXVHUFKDQQHOH[LWV
3URYLGHRZQVHQGUHFHLYHDQGVHFXULW\H[LWV
Notes:
&KDQQHO([LWV
&KDQQHO
40 40
0&$ 0&$
&+$' 0HVVDJH
7UDQVPLVVLRQ UHWU\ $SSOLFDWLRQ
4XHXH 6HFXULW\ 6HFXULW\
4XHXHV
0HVVDJH 0HVVDJH
6HQG 5HFHLYH
5HFHLYH 6HQG
0HVVDJH)ORZ
Notes:
MCAs (Message Channel Agents) are MQSeries applications that transmit messages from
the transmission queue of the sending queue manager to one or more application input
queues belonging to the target queue manager. A pair or MCAs is known as a channel.
MQSeries channels provide six exit points that enable a channel to be customized:
Security Exit
Message Exit
Send Exit
Receive Exit
Message Retry Exit
Channel Auto-definition Exit
Uempty
&OLHQW&KDQQHO([LWV
&KDQQHO
&OLHQW 40
0&$ 0&$
$SSOLFDWLRQ
6HFXULW\ 6HFXULW\
4XHXHV
6HQG 5HFHLYH
0HVVDJH)ORZ
5HFHLYH 6HQG
0HVVDJH)ORZ
Notes:
MQI channels provide three exit points that enable a channel to be customized:
Security Exit
Send Exit
Receive Exit
The MQSeries classes for Java allow you to write your own Send, Receive and Security
exits. To implement an exit, you define a new Java class that implements the appropriate
interface. There are three exit interfaces defined in the MQSeries package:
MQSendExit
MQReceiveExit
MQSecurityExit
046HQG([LW
LQ0\6HQG([LWMDYD
FODVV0\6HQG([LWLPSOHPHQW046HQG([LW^
\RXPXVWSURYLGHDQLPSOHPHQWDWLRQRIWKHVHQG([LWPHWKRG
SXEOLFE\WH>@VHQG([LW
04&KDQQHO([LW FKDQQHO([LW3DUPV
04&KDQQHO'HILQLWLRQ FKDQQHO'HILQLWLRQ
E\WH>@ DJHQW%XIIHU
^
\RXUH[LWFRGHJRHVKHUH
`
`
LQ\RXUPDLQSURJUDP
04(QYLURQPHQWVHQG([LW QHZ0\6HQG([LW
RWKHULQLWLDOL]DWLRQ
044XHXH0DQDJHUT0JU QHZ044XHXH0DQDJHU
Notes:
The send exit interface allows you to examine and possibly alter the data sent to the queue
manager by the MQSeries classes for Java.
Note: This class does not apply when connecting directly to MQSeries in bindings mode.
To provide your own send exit, define a class that implements this interface. Create a new
instance of your class and assign the MQEnvironment.sendExit variable to it before
constructing your MQQueueManager object.
In the example above, note the following parameters:
channelExitParms
Contains information regarding the context in which the exit is being invoked. The
exitResponse member variable is an output parameter that you use to tell the MQSeries
classes for Java what action to take next.
channelDefinition
Contains details of the channel through which all communications with the queue manager
take place.
Uempty
045HFHLYH([LW
LQ0\5HFHLYH([LWMDYD
FODVV0\5HFHLYH([LWLPSOHPHQW045HFHLYH([LW^
\RXPXVWSURYLGHDQLPSOHPHQWDWLRQ
RIWKH5HFHLYH([LWPHWKRG
SXEOLFE\WH>@UHFHLYH([LW
04&KDQQHO([LW FKDQQHO([LW3DUPV
04&KDQQHO'HILQLWLRQ FKDQQHO'HILQLWLRQ
E\WH>@ DJHQW%XIIHU
^
\RXUH[LWFRGHJRHVKHUH
`
`
LQ\RXUPDLQSURJUDP
04(QYLURQPHQWUHFHLYH([LW QHZ0\5HFHLYH([LW
RWKHULQLWLDOL]DWLRQ
044XHXH0DQDJHUT0JU QHZ044XHXH0DQDJHU
Notes:
The receive exit interface allows you to examine and possibly alter the data received from
the queue manager by the MQSeries classes for Java.
Note: This class does not apply when connecting directly to MQSeries in bindings mode.
To provide your own receive exit, define a class that implements this interface. Create a
new instance of your class and assign the MQEnvironment.receiveExit variable to it before
constructing your MQQueueManager object.
046HFXULW\([LW
LQ0\6HFXULW\([LWMDYD
FODVV0\6HFXULW\([LWLPSOHPHQW046HFXULW\([LW^
\RXPXVWSURYLGHDQLPSOHPHQWDWLRQ
RIWKH6HFXULW\([LWPHWKRG
SXEOLFE\WH>@6HFXULW\([LW
04&KDQQHO([LW FKDQQHO([LW3DUPV
04&KDQQHO'HILQLWLRQ FKDQQHO'HILQLWLRQ
E\WH>@ DJHQW%XIIHU
^
\RXUH[LWFRGHJRHVKHUH
`
`
LQ\RXUPDLQSURJUDP
04(QYLURQPHQW6HFXULW\([LW QHZ0\6HFXULW\([LW
RWKHULQLWLDOL]DWLRQ
044XHXH0DQDJHUT0JU QHZ044XHXH0DQDJHU
Notes:
The security exit interface allows you to customize the security flows that occur when an
attempt is made to connect to a queue manager.
Note: This class does not apply when connecting directly to MQSeries in bindings mode.
To provide your own security exit, define a class that implements this interface. Create a
new instance of your class and assign the MQEnvironment.securityExit variable to it before
constructing your MQQueueManager object.
Uempty
04&KDQQHO([LWDQG04&KDQQHO'HILQLWLRQ
SXEOLFFODVV04&KDQQHO([LW
H[WHQGV2EMHFW
SXEOLFFODVV04&KDQQHO'HILQLWLRQ
H[WHQGV2EMHFW
Notes:
MQChannelExit
This class defines context information passed to the send, receive, and security exits when
they are invoked. The exitResponse member variable should be set by the exit to indicate
what action the MQSeries classes for Java should take next.
MQChannelDefinition
The MQChannelDefinition class is used to pass information concerning the connection to
the queue manager to the send, receive and security exits.
Note: These classes do not apply when connecting directly to MQSeries in bindings mode.
([DPSOH&RGH
FODVV0\04([LWVLPSOHPHQWV046HQG([LW045HFHLYH([LW046HFXULW\([LW^
7KLVPHWKRGFRPHVIURPWKHVHQGH[LW
SXEOLFE\WH>@VHQG([LW 04&KDQQHO([LWFKDQQHO([LW3DUPV
04&KDQQHO'HILQLWLRQFKDQQHO'HI3DUPV
E\WHDJHQW%XIIHU>@
^ILOOLQWKHERG\RIWKHVHQGH[LWKHUH`
7KLVPHWKRGFRPHVIURPWKH5HFHLYHH[LW
SXEOLFE\WH>@5HFHLYH([LW 04&KDQQHO([LWFKDQQHO([LW3DUPV
04&KDQQHO'HILQLWLRQFKDQQHO'HI3DUPV
E\WHDJHQW%XIIHU>@
^ILOOLQWKHERG\RIWKHUHFHLYHH[LWKHUH`
7KLVPHWKRGFRPHVIURPWKHVHFXULW\H[LW
SXEOLFE\WH>@6HFXULW\([LW 04&KDQQHO([LWFKDQQHO([LW3DUPV
04&KDQQHO'HILQLWLRQFKDQQHO'HI3DUPV
E\WHDJHQW%XIIHU>@
^ILOOLQWKHERG\RIWKHVHFXULW\H[LWKHUH`
`
Notes:
Each exit is passed an MQChannelExit and an MQChannelDefinition object instance.
These objects represent the MQCXP and MQCD structures defined in the procedural
interface.
The agentBuffer parameter contains the data that is about to be sent (in the case of the
send exit), or has just been received (in the case of the receive and security exits). There
is no need for a length parameter, because the expression agentBuffer.length tells you the
length of the array.
For the Send and Security exits, your exit code should return the byte array that you wish to
be sent to the server. For a Receive exit, your code should return the modified data that
you wish to be interpreted by the MQSeries classes for Java.
The simplest possible exit body is:
{
return agentBuffer;
}
Uempty If your program is to run as a downloaded Java applet, note that under the security
restrictions placed on it you will not be able to read or write any local files. If your exit needs
a configuration file, you can place the file on the web and use the java.net.URL class to
download it and examine its contents.
8QLW&KHFNSRLQW
:KDWLQWHUIDFHDOORZV\RXWRGHILQHDXVHUH[LWWRDOWHUWKHGDWH
UHFHLYHGIURPWKHTXHXHPDQDJHU"
7KH04&KDQQHO([LWFODVVLVXVHGWRSDVVLQIRUPDWLRQFRQFHUQLQJ
WKHFRQQHFWLRQWRWKHTXHXHPDQDJHUWRWKHVHQGUHFHLYHDQG
VHFXULW\H[LW7UXH)DOVH"
7KH046HFXULW\([LWLQWHUIDFHGRHVQRWDSSO\ZKHQFRQQHFWLQJ
GLUHFWO\WR046HULHVLQELQGLQJVPRGH7UXH)DOVH"
Notes:
Uempty
6XPPDU\
<RXVKRXOGQRZXQGHUVWDQGWKHXVHRIXVHUH[LWVLQ
SDUWLFXODU
6HQGH[LWV
5HFHLYHH[LWV
6HFXULW\H[LWV
<RXVKRXOGDOVRXQGHUVWDQGKRZWRXVHWKHFKDQQHO
GHILQLWLRQFODVVHVWRLPSOHPHQWWKHVHH[LWV
Notes:
References
SC34-5456 MQSeries Using Java
http://www.ibm.com/software/ts/mqseries/messaging/
WebSphere MQ
2EMHFWLYHV
+DQGOHPXOWLSOHWKUHDGV
8QGHUVWDQGWKUHDGV\QFKURQL]DWLRQ
Notes:
0XOWLWKUHDGHG3URJUDPV
$SSOLFDWLRQ
7KUHDG 4XHXH0DQDJHU
7KUHDG
Notes:
Multithreaded programs are hard to avoid in Java. Consider a simple program that
connects to a queue manager and opens a queue at startup. The program displays a single
button on the screen and, when the button is pressed, it fetches a message from the
queue.
Because the Java runtime environment is inherently multithreaded, your application
initialization will take place in one thread, and the code that is executed in response to the
button press executes in a separate thread (the user interface thread).
With the "C" based MQSeries client this would cause a problem, since handles cannot be
shared across multiple threads. The MQSeries classes for Java relax this constraint,
allowing a queue manager object (and its associated queue and process objects) to be
shared across multiple threads.
Uempty
7KUHDG6\QFKURQL]DWLRQ
$SSOLFDWLRQ
4XHXH0DQDJHU
Notes:
The implementation of the MQSeries classes for Java ensures that, for a given connection
(queue manager object instance), all access to the target MQSeries queue manager is
synchronized. This means that a thread wishing to issue a call to a queue manager is
blocked until all other calls in progress for that connection have completed. If you require
simultaneous access to the same queue manager from within your program, create a new
queue manager object for each thread requiring concurrent access. (This is equivalent to
issuing a separate MQCONN call for each thread.)
0XOWLWKUHDGLQJ([DPSOH
$SSOLFDWLRQ
4XHXH0DQDJHU
7KUHDG *(7
7KUHDG
352&(66
387
7KUHDG
Notes:
The above example shows you how you can use multiple threads to get a message,
process this message and at the same time get another message.
• Thread #1 connects to a queue to get a message
• Thread #2 processes this message
• Thread #3 puts this message on another queue
When thread 1 has finished getting its message, it passes it on to thread 2 which processes
the message. Thread 1 is now free to get the next message in the queue, without having to
wait for thread 3 to put the message onto the other queue.
There is an important consideration in this case concerning the scope of the unit of work:
you will not be able to do all this as a single UOW. The reason is that all calls to MQ must
be done by the same thread that initiated the MQQueueManager object. The third thread
can initiate another MQQueueManager object but the commit method will only commit work
associated with the connection.
8QLW&KHFNSRLQW
2QHTXHXHPDQDJHUREMHFWFDQEHVKDUHGE\PXOWLSOHWKUHDGV
7UXH)DOVH"
7ZRWKUHDGVFDQKDQGOHVLPXOWDQHRXVDFFHVVHVWRWKHVDPH
TXHXHPDQDJHU7UXH)DOVH"
Notes:
Uempty
6XPPDU\
<RXVKRXOGQRZNQRZKRZWRXVHWKUHDGVWR
V\QFKURQL]HDFFHVVHVRUWRDOORZFRQFXUUHQW
DFFHVVHVWRDTXHXHPDQDJHU
Notes:
Unit 3
1. b
2. True (using the bitwise OR operator)
3. True
4. False
5. a, d
Unit 4
1. reasonCode
2. exceptionSource
Unit 5
1. MQMessage
2. MQPutMessageOptions
3. myMessage
4. writeString
5. seek
6. MQC.MQOO_OUTPUT
7. myOutputQueue
8. MQC.MQOO_INPUT_SHARED
9. resizeBuffer
10. MQGetMessageOptions
11. myInputQueue
Unit 6
1. messageType
2. No
3. MQC.MQMT_REQUEST
4. replyToQueueName
Unit 7
1. MQMessage
2. correlationId
3. MQGetMessageOptions
4. MQC.MQGMO_WAIT
5. 7500
6. messageFlags
7. MQC.MQMF_MSG_IN_GROUP
8. MQC.MQMF_SEGMENTATION_ALLOWED
9. MQC.MQGMO_COMPLETE_MSG
Unit 8
1. No
2. No
3. Yes (priority)
4. No
5. InhibitGet, InhibitPut, TriggerControl, TriggerData, TriggerDepth,
TriggerMessagePriority, TriggerType
6. MQDistributionListItem
7. MQDistributionList
Unit 9
1. accessQueue(), constructor MQQueue(), constructor
MQQueueManager()
2. userId, accountingToken, applicationData, putApplicationType,
putApplicationName, putDateTime, applicationOriginData
3. MQC.MQPMO_NO_CONTEXT
Unit 10
1. MQC.MQGMO_SYNCPOINT
2. commit
3. MQQueueManager
Unit 11
1. MQReceiveExit
2. False (that is MQChannelDefinition)
3. True
Unit 12
1. True
2. True (if you define a different queue manager object for each
thread)
Appendix B. Bibliography
MQSeries cross-platform publications
MQSeries Brochure
The MQSeries Brochure, G511-1908, gives a brief introduction to the benefits of MQSeries.
It is intended to support the purchasing decision, and describes some authentic customer
use of MQSeries.
MQSeries Intercommunication
The MQSeries Intercommunication book, SC33-1872, defines the concepts of distributed
queuing and explains how to set up a distributed queuing network in a variety of MQSeries
environments. In particular, it demonstrates how to (1) configure communications to and
from a representative sample of MQSeries products, (2) create required MQSeries objects,
and (3) create and configure MQSeries channels. The use of channel exits is also
described.
MQSeries Clients
The MQSeries Clients book, GC33-1632, describes how to install, configure, use, and
manage MQSeries client systems.
MQSeries Messages
The MQSeries Messages, GC33-1876, which describes “AMQ” messages issued by
MQSeries, applies to these MQSeries products only:
write, and build and MQSeries application. It also includes full descriptions of the sample
programs supplied with MQSeries.
• AIX
• AS/400
• MQSeries for Compaq Tru64 UNIX
• HP-UX
• OS/2
• MQSeries for OS/390
• Sun Solaris
• Windows NT
• Windows 3.1
• Windows 95 & Windows 98
Softcopy books
Most of the MQSeries books are supplied in both hardcopy and softcopy formats.
BookManager® format
The MQSeries library is supplied in IBM BookManager format on a variety of online library
collection kits, including the Transaction Processing and Data collection kit, SK2T-0730.
You can view the softcopy books in IBM BookManager format using the following IBM
licensed programs:
BookManager READ/2
BookManager READ/6000
BookManager READ/DOS
BookManager READ/MVS
BookManager READ/VM
BookManager READ for Windows
HTML format
The MQSeries documentation is provided in HTML format with these MQSeries products:
PDF files can be viewed and printed using the Adobe Acrobat Reader.
If you need to obtain the Adobe Acrobat Reader, or would like up-to-date information about
the platforms on which the Acrobat Reader is supported, visit the Adobe Systems Inc. Web
site at:
http://www.adobe.com/
PDF versions of relevant MQSeries books are supplied with these MQSeries products:
• MQSeries for AIX V5.2
• MQSeries for HP-UX V5.2
• MQSeries for OS/2 Warp V5.1
• MQSeries for Sun Solaris V5.2
• MQSeries for Windows NT V5.2
• MQSeries link for R/3 V1.2
• MQSeries for Linux V5.2
PDF versions of all current MQSeries books are also available from the MQSeries product
family Web site at:
http://www.software.ibm.com/ts/mqseries/
PostScript format
The MQSeries library is provided in PostScript (.PS) format with many MQSeries Version 2
products. Books in PostScript format can be printed or on a PostScript printer or viewed
with a suitable viewer.
http://www.ibm.com/software/ts/mqseries/
A
administrator commands. MQSeries commands used to manage MQSeries objects,
such as queues, processes, and namelist.
alias queue object. An MQSeries object, the name of which is an alias for a base queue
defined to the local queue manager. When an applicator or a queue manager uses an alias
queue, the alias name is resolved and the requested operation is performed on the
associated base queue.
alternate user security. A security feature in which the authority of one user ID can be
used by another user ID; for example, to open an MQSeries object.
application environment. The software facilities that are accessible by an application
program. On the OS/390 platform, CICS and IMS are examples of application
environments.
application log. In Windows NT, a log that records significant application events.
application queue. A queue used by an application.
asynchronous messaging. A method of communication between programs in which
programs place messages on message queues. With asynchronous messaging, the
sending program proceeds with its own processing without waiting for a reply to its
message. Contrast with synchronous messaging.
attribute. One of a set of properties that defines the characteristics of an MQSeries
object.
authorization checks. Security checks that are performed when a user tries to issue
administration commands against an object, for example to open a queue or connect to a
queue manager.
authorization file. In MQSeries on UNIX systems, a file that provides security definitions
for an object, a class of objects, or all classes of objects.
© Copyright IBM Corp. 2000, 2002 Appendix C. Glossary of terms and abbreviations C-1
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
authorization service. In MQSeries on UNIX systems, MQSeries for OS/2 Warp, and
MQSeries for Windows NT, a service that provides authority checking of commands and
MQI calls for the user identifier associated with the command or call.
B
backout. An operation that reverses all the changes made during the current unit of
recovery or unit of work. After the operation is complete, a new unit of recovery or unit of
work begins. Contrast with commit.
browse. In message queuing, to use the MQGET call to copy a message without
removing it from the queue. See also get.
browse cursor. In message queuing, an indicator used when browsing a queue to
identify the message that is next in sequence.
C
channel. See message channel.
client. A run-time component that provides access to queuing services on a server for
local user applications. The queues used by the applications reside on the server. See also
MQSeries client.
client application. An application, running on a workstation and linked to a client, that
gives the application access to queuing services on a server.
client connection channel type. The type of MQI channel definition associated with an
MQSeries client. See also server connection channel type.
coded character set identifier (CCSID). The name of a coded set of characters and
their code point assignments.
command. In MQSeries, an administration instruction that can be carried out by the
queue manager.
command processor. The MQSeries component that processes commands.
command server. The MQSeries component that reads commands from the
system-command input queue, verifies them, and passes valid commands to the command
processor.
commit. An operation that applies all the changes made during the current unit of
recovery or unit of work. After the operation is complete, a new unit of recovery or unit of
work begins. Contrast with backout.
completion code. A return code indicating how an MQI call has ended.
connect. To provide a queue manager connection handle, which an application uses on
subsequent MQI calls. The connection is made either by the MQCONN call, or
automatically by the MQOPEN call.
connection handle. The identifier or token by which a program accesses the queue
manager to which it is connected.
context. Information about the origin of a message.
context security. In MQSeries, a method of allowing security to be handled such that
messages are obliged to carry details of their origins in the message descriptor.
D
datagram. The simplest message that MQSeries Supports. This type of message does
not require a reply.
dead-letter queue (DLQ). A queue to which a queue manager or application sends
messages that it cannot deliver to their correct destination.
default object. A definition of an object (for example, a queue) with all attributes defined.
If a user defines an object but does not specify all possible attributes for that object, the
queue manager uses default attributes in place of any that were not specified.
distributed application. In message queuing, a set of application programs that can
each be connected to a different queue manager, but that collectively constitute a single
application.
DLQ. Dead-letter queue.
dynamic queue. A local queue created when a program opens a model queue object.
See also permanent dynamic queue and temporary dynamic queue.
E
environment. See application environment.
F
FIFO. First-in-first-out.
first-in-first-out (FIFO).A queuing technique in which the next item to be retrieved i the
item that has been i the queue for the longest time. (A)
G
get. In message queuing, to use the MQGET call to remove a message from a queue.
See also browse.
H
handle. See connection handle and object handle.
hardened message. A message that is written to auxiliary (disk) storage so that the
message will not be lost in the event of a system failure. See also persistent message.
© Copyright IBM Corp. 2000, 2002 Appendix C. Glossary of terms and abbreviations C-3
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
I
in-doubt unit of recovery.In MQSeries, the status of a unity of recovery for which a
syncpoint has been requested but not yet confirmed.
initiation queue. A local queue on which the queue manager puts trigger messages.
input/output parameter. A parameter of an MQI call in which you supply information when
you make the call, and in which the queue manager changes the information when the call
completes or fails.
input parameter. A parameter of an MQI call in which you supply information when you
make the call.
L
listener. In MQSeries distributed queuing, a program that monitors for incoming network
connections.
local definition. An MQSeries object belonging to a local queue manager.
local definition of a remote queue. An MQSeries object belonging to a local queue
manager. This object defines the attributes of a queue that is owned by another queue
manager. In addition, it is used for queue-manager aliasing and reply-to-queue aliasing.
locale. On UNIX systems, a subset of a user's environment that defines conventions for
a specific culture (such as time, numeric, or monetary formatting and character
classification, collation, or conversion). The queue manager CCSID is derived from the
locale of the user ID that created the queue manager.
local queue. A queue that belongs to the local queue manager. A local queue can
contain a list of messages waiting to be processed. Contrast with remote queue.
local queue manager. The queue manager to which a program is connected and that
provides message queuing services to the program. Queue managers to which a program
is not connected are called remote queue managers, even if they are running on the same
system as the program.
logical unit of work (LUW). See unit of work.
M
MCA. Message channel agent.
message. (1) In message queuing applications, a communication sent between
programs. See also persistent message and nonpersistent message. (2) In system
programming, information intended for the terminal operator or system administrator.
message channel. In distributed message queuing, a mechanism for moving messages
from one queue manager to another. A message channel comprises two message channel
agents (a sender at one end and a receiver at the other end) and a communication link.
Contrast with MQI channel.
message channel agent (MCA). A program that transmits prepared messages from a
transmission queue to a communication link, or from a communication link to a destination
queue. See also message queue interface.
message descriptor. Control information describing the message format and
presentation that is carried as part of an MQSeries message. The format of the message
descriptor is defined by the MQMD structure.
message priority. In MQSeries, an attribute of a message that can affect the order in
which messages on a queue are retrieved, and whether a trigger event is generated.
message queue. Synonym for queue.
message queue interface (MQI). The programming interface provided by the MQSeries
queue managers. This programming interface allows application programs to access
message queuing services.
message queuing. A programming technique in which each program within an
application communicates with the other programs by putting messages on queues.
message sequence numbering. A programming technique in which messages are
given unique numbers during transmission over a communication link. This enables the
receiving process to check whether all messages are received, to place them in a queue in
the original order, and to discard duplicate messages.
messaging. See synchronous messaging and asynchronous messaging.
model queue object. A set of queue attributes that act as a template when a program
creates a dynamic queue.
MQI. Message queue interface.
MQI channel. Connects an MQSeries client to a queue manager on a server system,
and transfers only MQI calls and responses in a bidirectional manner. Contrast with
message channel.
MQSeries. A family of IBM licensed programs that provides message queuing services.
MQSeries client. Part of an MQSeries product that can be installed on a system without
installing the full queue manager. The MQSeries client accepts MQI calls from applications
and communicates with a queue manager on a server system.
MQSeries commands (MQSC). Human readable commands, uniform across all
platforms, that are used to manipulate MQSeries objects. Contrast with programmable
command format (PCF).
N
namelist. An MQSeries object that contains a list of names, for example, queue names.
nonpersistent message. A message that does not survive a restart of the queue
manager. Contrast with persistent message.
null character. The character that is represented by X’00’.
© Copyright IBM Corp. 2000, 2002 Appendix C. Glossary of terms and abbreviations C-5
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
O
OAM. Object authority manager.
object. In MQSeries, an object is a queue manager, a queue, a process definition, a
channel, a namelist, or a storage class (OS/390 only).
object authority manager (OAM). In MQSeries on UNIX systems and MQSeries for
Windows NT, the default authorization service for command and object management. The
OAM can be replaced by, or run in combination with, a customer-supplied security service.
object descriptor. A data structure that identifies a particular MQSeries object. Included
in the descriptor are the name of the object and the object type.
object handle. The identifier or token by which a program accesses the MQSeries object
with which it is working.
output parameter. A parameter of an MQI call in which the queue manager returns
information when the call completes or fails.
P
PCF. Programmable command format.
PCF command. See programmable command format.
permanent dynamic queue. A dynamic queue that is deleted when it is closed only if
deletion is explicitly requested. Permanent dynamic queues are recovered if the queue
manager fails, so they can contain persistent messages. Contrast with temporary dynamic
queue.
persistent message. A message that survives a restart of the queue manager. Contrast
with nonpersistent message.
platform. In MQSeries, the operating system under which a queue manager is running.
principal. In MQSeries on UNIX systems, MQSeries for OS/2 Warp, and MQSeries for
Windows NT, a term used for a user identifier. Used by the object authority manager for
checking authorizations to system resources.
process definition object. An MQSeries object that contains the definition of an
MQSeries application. For example, a queue manager uses the definition when it works
with trigger messages.
programmable command format (PCF). A type of MQSeries message used by:
• User administration applications, to put PCF commands onto the system command input
queue of a specified queue manager
• User administration applications, to get the results of a PCF command from a specified
queue manager
• A queue manager, as a notification that an event has occurred
Contrast with MQSC.
Q
queue. An MQSeries object. Message queuing applications can put messages on, and
get messages from, a queue. A queue is owned and maintained by a queue manager.
Local queues can contain a list of messages waiting to be processed. Queues of other
types cannot contain messages— they point to other queues, or can be used as models for
dynamic queues.
queue manager. (1) A system program that provides queuing services to applications. It
provides an application programming interface so that programs can access messages on
the queues that the queue manager owns. See also local queue manager and remote
queue manager. (2) An MQSeries object that defines the attributes of a particular queue
manager.
queuing. See message queuing.
quiescing. In MQSeries, the state of a queue manager prior to it being stopped. In this
state, programs are allowed to finish processing, but no new programs are allowed to start.
R
reason code. A return code that describes the reason for the failure or partial success of
an MQI call.
receiver channel. In message queuing, a channel that responds to a sender channel,
takes messages from a communication link, and puts them on a local queue.
remote queue. A queue belonging to a remote queue manager. Programs can put
messages on remote queues, but they cannot get messages from remote queues. Contrast
with local queue.
remote queue manager. To a program, a queue manager that is not the one to which
the program is connected.
remote queue object. See local definition of a remote queue.
remote queuing. In message queuing, the provision of services to enable applications to
put messages on queues belonging to other queue managers.
reply message. A type of message used for replies to request messages. Contrast with
request message and report message.
reply-to queue. The name of a queue to which the program that issued an MQPUT call
wants a reply message or report message sent.
report message. A type of message that gives information about another message. A
report message can indicate that a message has been delivered, has arrived at its
destination, has expired, or could not be processed for some reason. Contrast with reply
message and request message.
requester channel. In message queuing, a channel that may be started remotely by a
sender channel. The requester channel accepts messages from the sender channel over a
© Copyright IBM Corp. 2000, 2002 Appendix C. Glossary of terms and abbreviations C-7
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
communication link and puts the messages on the local queue designated in the message.
See also server channel.
request message. A type of message used to request a reply from another program.
Contrast with reply message and report message.
resolution path. The set of queues that are opened when an application specifies an
alias or a remote queue on input to an MQOPEN call.
resource. Any facility of the computing system or operating system required by a job or
task. In MQSeries for OS/390, examples of resources are buffer pools, page sets, log data
sets, queues, and messages.
resource manager. An application, program, or transaction that manages and controls
access to shared resources such as memory buffers and data sets. MQSeries, CICS, and
IMS are resource managers.
responder. In distributed queuing, a program that replies to network connection
requests from another system.
return codes. The collective name for completion codes and reason codes.
rollback. Synonym for back out.
S
sender channel. In message queuing, a channel that initiates transfers, removes
messages from a transmission queue, and moves them over a communication link to a
receiver or requester channel.
sequential delivery. In MQSeries, a method of transmitting messages with a sequence
number so that the receiving channel can reestablish the message sequence when storing
the messages. This is required where messages must be delivered only once, and in the
correct order.
sequential number wrap value. In MQSeries, a method of ensuring that both ends of a
communication link reset their current message sequence numbers at the same time.
Transmitting messages with a sequence number ensures that the receiving channel can
reestablish the message sequence when storing the messages.
server. (1) In MQSeries, a queue manager that provides queue services to client
applications running on a remote workstation. (2) The program that responds to requests
for information in the particular two-program, information-flow model of client/server. See
also client.
server channel. In message queuing, a channel that responds to a requester channel,
removes messages from a transmission queue, and moves them over a communication
link to the requester channel.
server connection channel type. The type of MQI channel definition associated with
the server that runs a queue manager. See also client connection channel type.
T
target queue manager. See remote queue manager.
temporary dynamic queue. A dynamic queue that is deleted when it is closed.
Temporary dynamic queues are not recovered if the queue manager fails, so they can
contain nonpersistent messages only. Contrast with permanent dynamic queue.
thread. In MQSeries, the lowest level of parallel execution available on an operating
system platform.
time-independent messaging. See asynchronous messaging.
TMI. Trigger monitor interface.
transmission program. See message channel agent.
transmission queue. A local queue on which prepared messages destined for a remote
queue manager are temporarily stored.
trigger event. An event (such as a message arriving on a queue) that causes a queue
manager to create a trigger message on an initiation queue.
triggering. In MQSeries, a facility allowing a queue manager to start an application
automatically when predetermined conditions on a queue are satisfied.
trigger message. A message containing information about the program that a trigger
monitor is to start.
trigger monitor. A continuously-running application serving one or more initiation
queues. When a trigger message arrives on an initiation queue, the trigger monitor
retrieves the message. It uses the information in the trigger message to start a process that
serves the queue on which a trigger event occurred.
© Copyright IBM Corp. 2000, 2002 Appendix C. Glossary of terms and abbreviations C-9
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
U
undeliverable-message queue. See dead-letter queue.
undo/redo record. A log record used in recovery. The redo part of the record describes
a change to be made to an MQSeries object. The undo part describes how to back out the
change if the work is not committed.
unit of recovery. A recoverable sequence of operations within a single resource
manager. Contrast with unit of work.
unit of work. A recoverable sequence of operations performed by an application
between two points of consistency. A unit of work begins when a transaction starts or after
a user-requested syncpoint. It ends either at a user-requested syncpoint or at the end of a
transaction. Contrast with unit of recovery.