`
`
`
`MQSeries for Windows NT
`
`Quick Beginnings
`Version 5.1
`
`IBM
`
`GC34-5389-00
`
`
`
`HP_1026_0001
`
`

`

`
`
`
`
`HP_1026_0002HP_1026_0002
`
`HP_1026_0002
`
`

`

`MQSeries for Windows NT
`
`Quick Beginnings
`Version 5.1
`
`IBM
`
`GC34-5389-00
`
`
`
`HP_1026_0003
`
`

`

` Note
`
`Before using this document, read the general information under Appendix F, “Notices” on page 71.
`
`First edition (March 1999)
`
`This edition applies to Version 5.1 of MQSeries for Windows NT and to all subsequent releases and modifications until
`otherwise indicated in new editions or technical newsletters.
`
`Order publications through your IBM representative or the IBM branch office serving your locality. Publications are
`not stocked at the address below.
`
`IBM welcomes your comments. A form for readers' comments may be provided at the back of this publication.
`form has been removed, you may send your comments to the following address:
`
`If the
`
`
`
`IBM United Kingdom Laboratories,
`Information Development,
`Mail Point 095,
`Hursley Park,
`
` Winchester,
`
`Hampshire,
`
`England,
`
`SO21 2JN
`
`When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way
`it believes appropriate without incurring any obligation to you.
`
` Copyright International Business Machines Corporation 1996,1999. All rights reserved.
`Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is
`subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
`
`HP_1026_0004
`
`

`

` Contents
`
`Contents
`
`Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Welcome to MQSeries
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Conventions
` . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Chapter 1. About MQSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Messages, queues, and queue managers
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`MQSeries configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`MQSeries capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Programming MQSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Managing MQSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`iv
`
` v
`v
`
`1
`1
` 2
`4
`7
`9
`10
`
`Chapter 2. What’s new in MQSeries for Windows NT Version 5.1
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
` 11
`
`Chapter 3. Planning to install MQSeries
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Server hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Server software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`MQSeries components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`The Windows NT client
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Installing MQSeries . . . . . . . . . . . . . . . . . . . . . . . . .
`Chapter 4.
`Preparing for installation
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Setting up communications
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Verifying the installation
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Removing MQSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Installing maintenance updates .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`Chapter 5. Using MQSeries . . . . . . . . . . . . . . . . . . . . . . . . . . .
`MQSeries snap-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Web administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Sample programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Chapter 6. Using MQSeries command sets
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Control commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`MQSeries (MQSC) commands
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`PCF commands
` . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
` 13
`13
`13
`16
` 17
`17
`19
`
`21
` 21
`22
` 24
` 24
`28
` 28
`
`29
`29
`31
`34
`34
`
` 35
`35
` 38
`39
`
` Copyright IBM Corp. 1996,1999
`
`
`
`iii
`
`HP_1026_0005
`
`

`

`Tables
`
`Chapter 7. Using the MQSeries World Wide Web Interface
`Overview of MQSeries Internet Gateway .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`MQSeries Internet Gateway documentation
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`Chapter 8. Obtaining additional information
`The MQSeries library
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Viewing online information
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Printing and ordering books
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Available from the internet
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`
` 41
` 41
` 42
`
` 43
` 43
` 45
` 47
` 48
`
`Appendix A. Preparing to install from a LAN
`
`.
`
`.
`
`Appendix B. Unattended installation . . . . . . . . . . . . . . . . . . . . . .
`Installation response file format
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Installing on the remote machine .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`Appendix C. Removing MQSeries . . . . . . . . . . . . . . . . . . . . . . . .
`Attended removal
` . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Unattended removal
` . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Appendix D. Using Microsoft System Management Server
`Creating SMS packages and jobs for MQSeries
`.
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`
`.
`.
`
`.
`.
`
`.
`.
`
`.
`.
`
`.
`.
`
`.
`.
`
`.
`.
`
`.
`.
`
`Appendix E. Applying maintenance . . . . . . . . . . . . . . . . . . . . . . .
`Applying the maintenance information
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Restoring the previous backup version .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Querying the service level
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`Appendix F. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
` 49
`
`51
` 52
` 57
`
`59
`59
`60
`
` 65
` 65
`
`67
` 67
` 68
` 69
`
`71
`73
`
`75
`
` Tables
`
`1. MQSeries control commands
`.
`.
`.
`.
`.
`2.
`The MQSeries library
`.
`.
`.
`.
`.
`.
`.
`.
`.
`3. MQSeries publications – PDF file names
`
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
` 36
` 43
` 47
`
`iv MQSeries for Windows NT V5.1 Quick Beginnings
`
`
`
`HP_1026_0006
`
`

`

`Conventions
`
`Welcome to MQSeries
`
`This book describes MQSeries and explains how to plan for, install, and use the
`MQSeries for Windows NT Version 5.1 product.
`
` Conventions
`
`Knowing the conventions used in this book will help you use it more efficiently.
`(cid:159) The term “MQSeries” is used to mean the MQSeries for Windows NT product.
`(cid:159) Boldface type indicates the name of an item you need to select or the name of a
`command.
`(cid:159) Italics type indicates new terms, book titles, or variable information that must be
`replaced by an actual value.
`(cid:159) Monospace type indicates an example (such as a fictitious path or file name) or text
`that is displayed on the screen.
`
` Copyright IBM Corp. 1996,1999
`
`
`
`v
`
`HP_1026_0007
`
`

`

`Conventions
`
`vi MQSeries for Windows NT V5.1 Quick Beginnings
`
`
`
`HP_1026_0008
`
`

`

`Introduction
`
` Chapter1. AboutMQSeries
`
`It describes its basic functions and its
`This chapter introduces IBM MQSeries.
`relationships with operating systems, applications, and other middleware products.
`
`The information in this chapter provides a high-level overview and does not cover many
`aspects of the function that MQSeries provides; a more detailed description is given in
`the MQSeries Planning Guide.
`
`You might also like to read the MQSeries: An Introduction to Messaging and Queuing
`book (GC33-0805) to learn about the concepts of MQSeries.
`
` Introduction
`
`MQSeries is a communications system that provides assured, asynchronous, once-only
`delivery of data across a broad range of hardware and software platforms.
`
`These characteristics make MQSeries the ideal infrastructure for
`application-to-application communication and make it an appropriate solution whether
`the applications run on the same machine or on different machines that are separated
`by one or more networks.
`
`MQSeries supports all the important communication protocols and even provides routes
`between networks that use different protocols. MQSeries bridges and gateway
`products allow easy access (with little or no programming) to many existing systems
`and application environments—for example, Lotus Notes, Web browsers, Java
`applets, and many others.
`
`The assured delivery capability reflects the many functions built in to MQSeries to
`ensure that data is not lost because of failures in the underlying system or network
`infrastructure. Assured delivery enables MQSeries to form the backbone of critical
`communication systems and to be entrusted with delivering high-value data. There are
`also options that allow you to select a less robust quality of service, where this is
`appropriate. For example, there might be circumstances where you might prefer faster
`delivery with less emphasis on assured delivery.
`
`The asynchronous processing support in MQSeries means that the exchange of data
`between the sending and receiving applications is time independent. This allows the
`sending and receiving applications to be decoupled so that the sender can continue
`processing, without having to wait for the receiver to acknowledge that it has received
`the data.
`In fact, the target application does not even have to be running when the
`
` Copyright IBM Corp. 1996,1999
`
`
`
`1
`
`HP_1026_0009
`
`

`

`Fundamentals
`
`data is sent. Likewise, the entire network path between the sender and receiver may
`not need to be available when the data is in transit.
`
`Once-only delivery of data is a vital consideration, particularly in financial and business
`applications where duplicate requests to move large sums of money from one account
`to another are precisely what you do not want to happen!
`
`Messages, queues, and queue managers
`
`The three fundamental concepts in MQSeries that you need to understand are:
` (cid:159) Messages
` (cid:159) Queues
` (cid:159) Queue managers
`
` Messages
`
`A message is a string of bytes that has meaning to the applications that use it.
`Messages are used for transferring data from one application to another (or to different
`parts of the same application). The applications can be running on the same platform,
`or on different platforms.
`
`MQSeries messages have two parts; the application data and a message descriptor.
`The content and structure of the application data is defined by the application programs
`that use the data. The message descriptor identifies the message and contains other
`control information, such as the type of message and the priority assigned to the
`message by the sending application.
`
` Queues
`
`A queue is a data structure in which messages are stored. The messages may be put
`on, or got from, the queue by applications or by a queue manager as part of its normal
`operation.
`
`Queues exist independently of the applications that use them. A queue can exist in
`main storage (if it is temporary), on disk or similar auxiliary storage (if it must be kept in
`case of recovery), or in both places (if it is currently being used, and must also be kept
`for recovery). Each queue belongs to a queue manager, which is responsible for
`maintaining it. The queue manager puts the messages it receives onto the appropriate
`queue.
`
`2 MQSeries for Windows NT V5.1 Quick Beginnings
`
`
`
`HP_1026_0010
`
`

`

`Fundamentals
`
`Queues can exist either in your local system, in which case they are called local
`queues, or at another queue manager, in which case they are called remote queues.
`
`Applications send to, and receive messages from, queues. For example, one
`application can put a message on a queue, and another application can get the
`message from the same queue.
`
`Each queue has queue attributes that determine what happens when applications
`reference the queue. The attributes indicate:
`(cid:159) Whether applications can retrieve messages from the queue (get enabled)
`(cid:159) Whether applications can put messages onto the queue (put enabled)
`(cid:159) Whether access to the queue is exclusive to one application or shared between
`applications
`(cid:159) The maximum number of messages that can be stored on the queue at the same
`time (maximum queue depth)
`(cid:159) The maximum size of messages that can be put on the queue (maximum message
`size)
`
` Queuemanagers
`
`A queue manager provides queuing services to applications, and manages the queues
`that belong to it.
`It ensures that:
`(cid:159) Object attributes are changed according to the details received.
`(cid:159) Special events (such as instrumentation events or triggering) are generated when
`the appropriate conditions are met.
`(cid:159) Messages are put on the correct queue, as requested by the application. The
`application is informed if this cannot be done, and an appropriate reason code is
`given.
`
`Each queue belongs to a single queue manager and is said to be a local queue to that
`queue manager. The queue manager to which an application is connected is said to
`be the local queue manager for that application. For the application, the queues that
`belong to its local queue manager are local queues. A remote queue is a queue that
`belongs to another queue manager. A remote queue manager is any queue manager
`other than the local queue manager. A remote queue manager may exist on a remote
`machine across the network or it may exist on the same machine as the local queue
`manager. MQSeries supports multiple queue managers on the same machine.
`
`
`
`Chapter 1. About MQSeries
`
`3
`
`HP_1026_0011
`
`

`

`MQSeries configurations
`
` MQSeriesconfigurations
`
`In the simplest configurations, MQSeries is installed on a machine and a single queue
`manager is created. This queue manager then allows you to define queues. Local
`applications can then use these queues to exchange messages.
`
`Communication by applications with queues managed by another queue manager
`It is not necessary to define a channel
`requires message channels to be defined.
`directly to the target queue manager and it is often appropriate to define one only to the
`next hop (that is, an intermediate queue manager). Message channels available from
`that queue manager will be used to deliver the message to the target queue manager
`(or even to a subsequent hop).
`
`More complex configurations can be created using a client-server structure. The
`MQSeries product can act as an MQSeries server to MQSeries clients. The clients and
`server do not need to be on the same platform. MQSeries supports a broad range of
`client platforms. The MQSeries product includes clients for all the varieties of the
`Windows platform (Windows 98, Windows 95, Windows 3.1, and Windows NT); other
`client platforms are widely available.
`
`In a client-server configuration, the MQSeries server provides messaging and queuing
`services to the clients, as well as to any local applications. The clients are connected
`to the server through dedicated channels (known as client channels) for clients. This is
`a cost-effective deployment method because a server can support hundreds of clients
`with only a single copy of the MQSeries server product. However, the client channel
`must be continuously available whenever the MQSeries applications on the client are
`running. This contrasts with the message channels, which need not be continuously
`available to support MQSeries applications running on the server.
`
`See “Channels” on page 5 for more information.
`
`MQSeries also supports the concept of clusters to simplify setup and operation. A
`cluster is a named collection of queue managers and any one queue manager can
`belong to none, one, or several such clusters. The queue managers in a cluster can
`exist on the same or different machines.
`
`The default configuration that is provided by the installation process for MQSeries can,
`if there is no other queue manager already defined, configure a queue manager that is
`joined to the local default cluster. The queue manager has a name that is based on
`the TCP/IP domain of the machine.
`
`Note: It is not advisable to use clustering in an environment where IP addresses
`change on an unpredictable basis, such as on machines where Dynamic Host
`Configuration (DHCP) is being used.
`
`4 MQSeries for Windows NT V5.1 Quick Beginnings
`
`
`
`HP_1026_0012
`
`

`

`Clients and servers
`
`There are two major benefits from the use of clusters:
`
`1. Communication between members of a cluster is greatly simplified, particularly
`because the channels required for exchanging messages are automatically defined
`and created as needed.
`
`2. Some or all of the queues of participating queue managers can be defined as
`being cluster queues, which has the effect of making them automatically known
`and available to all other queue managers in the cluster.
`
`See “Clusters” on page 6 for more information.
`
` Channels
`
`A channel provides a communication path to a queue manager. There are two types of
`channel: message channels and MQI channels.
`
`A message channel provides a communication path between two queue managers on
`the same, or different, platforms. The message channel is used for transmitting
`messages from one queue manager to another, and shields the application programs
`from the complexities of the underlying networking protocols. A message channel can
`transmit messages in one direction only. Two message channels are required if
`two-way communication is required between two queue managers.
`
`A client channel (also known as an MQI channel) connects an MQSeries client to a
`queue manager on a server machine and is bidirectional.
`
`If you want to read more information about channels and how MQSeries uses them to
`communicate across the systems in your network, see the MQSeries
`Intercommunication book.
`
`Clients and servers
`
`MQSeries supports client-server configurations for MQSeries applications.
`
`An MQSeries client is a part of the MQSeries product that is installed on a machine to
`accept MQSeries calls from applications and pass them to an MQSeries server
`machine. There they are processed by a queue manager. Typically, the client and
`server reside on different machines, but they can also exist on the same machine.
`
`An MQSeries server is a queue manager that provides queuing services to one or more
`clients. All the MQSeries objects (for example, queues) exist only on the queue
`manager machine (that is, on the MQSeries server machine). A server can support
`local MQSeries applications as well.
`
`
`
`Chapter 1. About MQSeries
`
`5
`
`HP_1026_0013
`
`

`

`Clusters
`
`The difference between an MQSeries server and an ordinary queue manager is that the
`MQSeries server can support MQSeries clients, and each MQSeries client application
`has a dedicated communication link with the MQSeries server.
`
`For more information about client support, see the MQSeries Clients book.
`
` Clusters
`
`A cluster is a named collection of queue managers.
`
`Clusters require that at least one of the queue managers in the cluster is defined as a
`repository (that is, a place where the shared cluster information can be held). More
`typically, two or more such repositories are usually designated to provide continued
`availability in the case of system failure. MQSeries makes sure that the information in
`the repositories is kept synchronized.
`
`When a queue is defined as a cluster queue, it can be regarded as a public queue in
`that it is freely available to other queue managers in the cluster. This contrasts with
`non-cluster queues because these are accessible only when a local definition of them is
`available. Thus, a non-cluster queue has the characteristics of a private queue,
`accessible only to those queue managers that have been configured to know about
`them.
`
`If a
`Public queues with the same name in the same cluster are regarded as equivalent.
`message is sent to that queue name, MQSeries (by default) sends it to any one of the
`instances, using a load-balancing algorithm.
`If you do not want this to happen, you can
`use the queue manager and queue name in the address, thus forcing the message to
`be delivered to a specific queue manager. Alternatively, you can replace the
`load-balancing routine with a different implementation. This is typical of MQSeries, in
`that there are many examples of where standard behavior can be changed by
`implementing user code in exits designed for this purpose.
`
`You can read a full explanation in the MQSeries Queue Manager Clusters book.
`
`Note: It is not advisable to use clusters in an environment where IP addresses change
`on an unpredictable basis, such as on machines where Dynamic Host
`Configuration (DHCP) is being used.
`
`6 MQSeries for Windows NT V5.1 Quick Beginnings
`
`
`
`HP_1026_0014
`
`

`

`Transactional support
`
` MQSeriescapabilities
`
`MQSeries can be used to create many different types of solutions. Some exploit the
`platform support, or the bridge and gateway capabilities, to connect existing systems in
`an integrated way or to allow new applications to extract information from, or
`interchange information with, existing systems. Other solutions support business
`application servers, where a central pool of MQSeries applications can manage work
`sent across networks. Complex routing of information for workflow scenarios can be
`supported. Publish/subscribe or “send and forget” are other application scenarios that
`use different message flows. Load balancing and hot-standby systems can be built
`using the power and flexibility of MQSeries, which includes specific functions to support
`many of these diverse scenarios.
`
`See Chapter 6, “Introducing the Message Queue Interface” in the MQSeries Application
`Programming Guide for more information about writing MQSeries applications.
`
` Transactionalsupport
`
`An application program may need to group a set of updates into a unit of work. Such
`updates are usually logically related and must all be successful for data integrity to be
`preserved. Data integrity would be lost if one update in the group succeeded while
`another failed. MQSeries supports transactional messaging.
`
`A unit of work commits when it completes successfully. At this point all updates made
`within that unit of work are made permanent and irreversible. Alternatively, all updates
`are backed out if the unit of work fails. Syncpoint coordination is the process by which
`a unit of work is either committed or backed out with integrity.
`
`A local unit of work is one in which the only resources updated are those of the
`MQSeries queue manager. Here, syncpoint coordination is provided by the queue
`manager itself, using a single-phase commit process.
`
`A global unit of work is one in which resources belonging to other resource managers,
`such as XA-compliant databases, are also updated. Here, a two-phase commit
`procedure must be used and the unit of work may be coordinated by the queue
`manager itself, or externally by another XA-compliant transaction manager such as IBM
`CICS, IBM Transaction Server, IBM TXSeries, Transarc Encina, or BEA Tuxedo.
`
`When the queue manager coordinates global units of work itself it becomes possible to
`integrate database updates within MQSeries units of work. That is, a mixed MQSeries
`and SQL application can be written, and commands can be used to commit or roll back
`the changes to the queues and databases together.
`
`The queue manager achieves this using a two-phase commit protocol. When a unit of
`work is to be committed, the queue manager first asks each participating database
`
`
`
`Chapter 1. About MQSeries
`
`7
`
`HP_1026_0015
`
`

`

`Instrumentation events
`
`manager whether it is prepared to commit its updates. Only if all of the participants,
`including the queue manager itself, are prepared to commit, are all of the queue and
`database updates committed.
`If any participant cannot prepare its updates, the unit of
`work is backed out instead.
`
`Full recovery support is provided if the queue manager loses contact with any of the
`database managers during the commit protocol.
`If a database manager becomes
`unavailable while it is in doubt (that is, it has been called to prepare but has yet to
`receive a commit or backout decision), the queue manager remembers the outcome of
`the unit of work until it has been successfully delivered. Similarly, if the queue manager
`terminates with incomplete commit operations outstanding, these are remembered
`when the queue manager restarts.
`
` Instrumentationevents
`
`You can use MQSeries instrumentation events to monitor the operation of queue
`managers.
`
`Instrumentation events cause special messages, called event messages, to be
`generated whenever the queue manager detects a predefined set of conditions. For
`example, the following condition gives rise to a Queue Full event. Queue Full events
`are enabled for a specified queue, and an application issues an MQPUT call to put a
`message on that queue, but the call fails because the queue is full.
`
`Other conditions that can give rise to instrumentation events include:
`(cid:159) A predefined limit for the number of messages on a queue being reached
`(cid:159) A queue not being serviced within a specified time
`(cid:159) A channel instance being started or stopped
`
`If you define your event queues as remote queues, you can put all the event queues on
`a single queue manager (for those nodes that support instrumentation events). You
`can then use the events generated to monitor a network of queue managers from a
`single node.
`
`MQSeries instrumentation events are categorized as follows:
`
`Queue manager events
`These are related to the definitions of resources within queue managers. For
`example, if an application attempts to open a queue but the associated user ID is
`not authorized to perform that operation, a queue manager event is generated.
`
`Performance events
`These are notifications that a threshold condition has been reached by a resource.
`For example, a queue depth limit has been reached or, following an MQGET
`request, a queue has not been serviced within a predefined period of time. You
`can use the Windows NT performance monitor to check and control certain aspects
`of your queues (for example, the queue depth, percentage queue depth, and how
`many messages have been enqueued and dequeued).
`
`8 MQSeries for Windows NT V5.1 Quick Beginnings
`
`
`
`HP_1026_0016
`
`

`

`MQSeries programming
`
`Channel events
`These are reported by channels as a result of conditions detected during their
`operation. For example, a channel event is generated when a channel instance is
`stopped.
`
` Message-drivenprocessing
`
`When they arrive on a queue, messages can automatically start an application, using a
`mechanism known as triggering.
`If necessary, the application can be stopped when the
`message or messages have been processed.
`
` ProgrammingMQSeries
`
`MQSeries applications can be developed using a variety of programming languages
`and styles. Procedural and object-oriented programming can be done under Visual
`Basic, C, C++, Java, and COBOL. Microsoft Windows NT ActiveX/COM technology is
`also supported.
`
`MQSeries function is logically divided into what is normally required by applications
`(such as putting messages on a queue) and what is necessary for administration (such
`as changing queue or queue manager definitions). Application function is known as the
`MQI (message queue interface). Administration function is known as the MQAI
`(message queuing administration interface). Applications can mix MQI and MQAI
`functionality, as required.
`
`The administration functions can be implemented in two ways:
`1. Most often, using MQAI language bindings or ActiveX classes
`2. Sending messages to administration queues to achieve the same results as above,
`using programmable command formats (PCFs)
`
`
`
`Chapter 1. About MQSeries
`
`9
`
`HP_1026_0017
`
`

`

`Managing MQSeries
`
` ManagingMQSeries
`
`MQSeries is tightly integrated into the Windows NT operating system. The
`management facilities are, therefore, normally to be found alongside their Windows NT
`equivalents and are accessible through a graphical user interface. For example,
`MQSeries events are written to the Windows NT event log and are accessed through
`the event manager. Likewise, performance monitoring or checking the status of queues
`is available through the Windows NT performance monitor.
`
`The operational side of MQSeries can be controlled through the Microsoft Management
`Console (MMC). The MQSeries Explorer, provided as an MMC snap-in, allows you to
`browse queues and change their properties. Both local and remote administration are
`available; thus, a single MQSeries installation on a Windows NT platform can be used
`to manage an entire MQSeries network.
`
`A second MMC snap-in, MQSeries Services, allows you to control the operation of
`MQSeries and its various subcomponents (such as stopping and starting facilities,
`default configurations, and other administration actions).
`
`For compatibility with previous levels of MQSeries, an alternative management method
`is available that uses programs and a command language known as MQSC. These
`can be accessed from a command prompt. Details of MQSC are given in the
`MQSeries Command Reference.
`
`You can also use a Web browser to manage MQSeries. MQSeries includes an
`optional Web server that supports secure management of an MQSeries network from a
`browser.
`It is only necessary to install the Web server on one MQSeries machine
`(although it can, optionally, be installed on many machines within a network). The
`MQSeries Web Administration facility provides a scripting capability that allows
`automatic generation of MQSC.
`
`10 MQSeries for Windows NT V5.1 Quick Beginnings
`
`
`
`HP_1026_0018
`
`

`

`What’s new
`
`Chapter 2. What’s new in MQSeries for
`Windows NT Version 5.1
`
`MQSeries for Windows NT Version 5.1 is an update to the MQSeries for Windows NT
`Version 5.0 product. The main areas of change are:
`(cid:159) Support for clusters (that is, named collections of queue managers). Provided the
`necessary infrastructure is in place, any queue manager can send a message to
`any other queue in the same cluster without the need for a transmission queue,
`channel definition, or remote queue definition. Clusters also simplify the
`implementation of hot-standby and load-balancing configurations.
`(cid:159) A default configuration that allows you to try out MQSeries as soon as you have
`finished installing the product.
`(cid:159) Close integration with Microsoft Windows NT Version 4.0, including exploitation of
`extra function provided by the Microsoft Management Console Version 1.1 and
`Active Directory Services Interface (ADSI) Version 2.0 system updates. The main
`highlights are:
`
`– Graphical tools and applications for managing, controlling, and exploring
`MQSeries:
`
`-
`
`-
`
`IBM MQSeries (also known as MQSeries Explorer)—a Microsoft
`management console (MMC) snap-in that allows you to query, change,
`and create the local, remote, and cluster objects across an MQSeries
`network.
`
`IBM MQSeries Services—an MMC snap-in that controls the operation of
`MQSeries components, either locally or remotely within the Windows NT
`domain.
`It monitors the operation of MQSeries servers and provides
`extensive error detection and recovery functions.
`
`- MQSeries API Exerciser—a graphical application for exploring the
`messaging and queuing programming functions that MQSeries provides.
`It can also be used in conjunction with the MQSeries Explorer to gain a
`deeper understanding of the effects of MQSeries operations on objects
`and messages.
`
`- MQSeries Postcard—a sample application that can be used to verify an
`MQSeries installation, for either local or remote messaging.
`
`– Support for the following features of Windows NT has been added:
`
`- Windows NT performance monitor—used to access and display MQSeries
`information, such as the current depth of a queue and the rate at which
`message data is put onto and taken off queues.
`
`- Active Directory—programmable access to MQSeries objects is available
`through the Active Directory Services Interface (ADSI).
`
` Copyright IBM Corp. 1996,1999
`
`
`
`11
`
`HP_1026_0019
`
`

`

`What’s ne