Unit 1. A Review of WebSphere MQ

 

What This Unit is About

 

This unit provides an introduction to WebSphere MQ and its products.

It forms the basis for the remainder of the course.

 

What You Should Be Able to Do

 

After completing this unit, you should be able to:

 

• Describe the features and benefits of WebSphere MQ

• Identify the level of function in each WebSphere MQ queue

Manager

• Classify the application models that WebSphere MQ can support

• Find further information on specific aspects of WebSphere MQ

 

How You Will Check Your Progress

 

Accountability:

 

• Checkpoint questions

• Instructor questions

 

References

 

SC34-6055    WebSphere MQ Script (MQSC) Command Reference

SC34-6068    WebSphere MQ System Administration Guide

 

If using WebSphere MQ for iSeries use:

 

SC34-6070    WebSphere MQ doe iSeries V5.3 System

Administration Guide

 

 

 

 

 

 

Figure 1-1. Unit Objectives

 

Notes:

 

This unit provides an introduction to WebSphere MQ and its products. It forms the basis for the remainder of the course.

 

After completing this unit, the student should be able to:

 

• Describe the features and benefits of WebSphere MQ.

• Identify the level of function of each WebSphere MQ queue manager.

• Classify the application models that WebSphere MQ can support.

• Find further information on specific aspects of WebSphere MQ.

 

 

V2.0

Temp    t 1.1 Facilities and Functions

 

This topic provides an introduction to the facilities and functions of WebSphere MQ and discusses the benefits they provide.

 

 

 

 

 

 

 

 

 

 

Figure 1-2. WebSphere MQ - Commercial Messaging

 

Notes:

 

WebSphere MQ is a means of program-to-program communication using messages and queues. The communicating applications can be on the same system, or they can be distributed across a network of IBM and non-IBM systems.

 

As well as depicting the basic mechanism by which one application communicates with another, the visual also states five major benefits of WebSphere MQ.

 

• There is a common application programming interface, the MQI, that is       consistent across all the supported platforms.

 

• WebSphere MQ can transfer data with assured delivery; messages don't get lost, even in the event of a system failure. Just as important, there is no duplicate delivery.

 

• The communicating applications don't have to be active at the same time. For example, a sending application can still be putting messages on a queue even though the receiving application is not active.

 

• Message driven processing is an style of application design. An application is divided into discrete functional modules which communicate with each other by means of messages. In this way, the modules can execute on different systems, be scheduled at different times, or they can act in parallel.

 

• Application development is made faster by shielding the developer from the

complexities of the network.

 

 

 

 

 

 

 

Figure 1-3. Further Information

 

Notes:

 

The WebSphere MQ publications are listed in the bibliography at the back of these course notes. Some publications describe function that relates to two or more queue managers, the so called cross-platform publications. Other publications are platform-specific.

 

Discover WebSphere MQ on the World Wide Web. The Web address for the WebSphere MQ home page is:

 

http://www.ibm.com/software/ts/mqseries/

V2.0

 

 

 

Figure 1-4. Message and Queue

 

Notes:

 

A message is any information that one application wishes to communicate to another. A message may convey a request for a service, or it may be a reply to such a request. It may also report on the progress of another message; to confirm its arrival or report on an error, for example. A message may also simply carry information for which no reply is expected.

 

A queue is a place to store messages until they can be processed. The time a message has to wait in order to be retrieved and processed could be very short, or it could be a long time if it has to wait for the receiving application to be started. Either way, t he ability to store a message safely is an important characteristic of a queue.

 

 

 

 

 

Figure 1-5. Applications Enabled by WebSphere MQ

 

 

 

V2.0

Figure 1-6. Queue Manager

Notes:

 

• The component of WebSphere MQ software which owns and manages queues       is called  a queue manager.

 

• A queue manager also provides a family of application programming interfaces.

 

- The Message Queue Interface (MQI) enables an application to access its         queues and the messages they contain. The MQI is a simple application programming interface which is consistent across all platforms supported by WebSphere MQ.

 

The MQI effectively protects applications from having to know how a queue

manager physically manages messages and queues. The MQI allows full access to WebSphere MQ messaging support.

 

- The Application Messaging Interface (AMI) is a high-level API that simplifies

programming for application messaging and publish/subscribe. It provides a high

level of abstraction, moving message-handling logic from the application into the

middleware. The AMI allows programmers to use policies and services to define

how and where the messages are sent.

 

- The Java Message Service (JMS) is a specification of a portable API for

asynchronous messaging. JMS has been developed by Sun Microsystems in

collaboration with IBM and other vendors interested in promoting industry wide

standard frameworks. JMS is an object-oriented Java API with a set of generic

messaging objects for programmers to write event-based messaging applications.

JMS supports both request/reply and publish/subscribe models as separate object  models.

JMS is available in WebSphere MQ V5.2.

 

• All three of the APIs can interoperate.

 

 

 

 

 

Figure 1-7. MQI Calls

 

Notes:

 

The most basic calls allow an application to put a message on a queue and get a message from a queue.

 

MQPUT and MQPUT1

 

Put a message on a named queue. Generally, a message is added to the

end of a queue.

 

MQGET Gets a message from a named queue. Generally, a message is  removed from the front of a queue.

 

The other calls are as follows.

 

MQCONN, MQCONNX, and MQDISC

 

Enable an application to connect to a queue manager and disconnect from a queue manager. An application must connect to a queue manager before it can issue any further MQI calls.

 

MQOPEN and MQCLOSE

 

Enable an application to open a queue for specified operations and close the queue when access to it is no longer required. An application must open a queue before it can access it in any way; to put messages on it, or get messages from it, for example.

 

MQINQ and MQSET

 

Inquire on and set the attributes of an object. All WebSphere MQ objects, such as a queue, a process, and the queue manager object, have a set of attributes.

 

MQBEGIN, MQCMIT, and MQBACK

 

Enable an application to put and get messages as part of a unit of work.

 

 

Figure 1-8. Message Descriptor

 

Notes:

 

A message consists of two parts:

 

• Message descriptor

• Application data

 

The message descriptor contains information about the message. The sending application supplies both the message descriptor and the application data when it puts a message on a queue, and both the message descriptor and the application data are returned to the application which gets the message from the queue. Some of the fields in the message descriptor are set by the application which puts the message on a queue; others are set by the queue manager on behalf of the application.

 

 

Figure 1-9. Asynchronous Model

 

Notes:

 

• In the asynchronous model, instead of waiting for a reply to its first message, Program A continues to send further requests to Program B. It is a separate process, Program X, which receives the replies when they arrive.

 

• In this model, Program A is not dependent on Program B to be running when the requests are sent. It can continue to do work even when Program B is stopped.

 

• Of course the application does expect Program X to receive the replies at some time, but not necessarily at the same time that Program A or Program B is running. All this illustrates another of the major benefits of WebSphere MQ, time independence.

 

 

 

 

 

 

 

 

 

 

 

Figure 1-10. Triggering

 

Notes:

 

WebSphere MQ provides an enhancement to the implementation of time-independent processing, triggering. The arrival of a message on an application queue may indicate that it is an appropriate time for another application to be started in order to process the messages on the application queue. When the right conditions are detected by the queue manager, it is the triggering facility which starts the application to service the application queue.

 

We will revisit triggering in some depth later.

 

 

 

 

 

Figure 1-11. Parallel Processes

 

Notes:

 

• This model allows several requests to be sent by a application without the application having to wait for a reply to one request before sending the next. All the requests can then be processed in parallel.

 

• The application can process the replies when they have all been received, and produce a consolidated answer. The program logic might also specify what to do when only a partial set of replies is received within a given period of time.

 

 

 

Figure 1-12. Client/Server

 

Notes:

 

• The server application, Insurance quotations, can handle requests from multiple client applications. The message descriptor identifies the appropriate reply-to queue for each request.

 

 

 

Figure 1-13. Assured Delivery

 

Notes:

 

• Assured delivery is another benefit of WebSphere MQ. It is the result of the protocol used when one queue manager transmits a message to another queue manager. As far as the applications are concerned, this process of transmitting messages is performed asynchronously and transparently, and the protocol ensures that no message is lost, or delivered to its destination queue more than once.

 

 

 

Figure 1-14. Connectionless Communications

 

Notes:

 

• If applications connected to one queue manager are putting messages on multiple queues owned by another queue manager, only one transmission queue is required to stage the delivery of these messages, and only one communications connection is required between the two queue managers.

 

 

 

 

 

 

Figure 1-15. Queue Manager Network

 

Notes:

 

• Applications are shielded from the complexities of the underlying network. The

application programmer does not have to be concerned with writing programs to

interfaces such as APPC, CPI-C, or sockets, nor with writing code to handle

communications errors. Under the covers of the MQI, WebSphere MQ provides all this for you. Applications, and by implication their programmers, do not even need to be aware of the locations of queues where they put messages.

 

 

 

 

Figure 1-16. Distributed Queue Management

 

Notes:

 

• The component of WebSphere MQ software that sends and receives messages across a network is called a message channel agent (MCA).

 

• MCAs work in pairs and communicate with other using a communications protocol such as SNA LU6.2 and TCP/IP. The combination of a pair of MCAs and the communications connection between them (for example, an SNA LU6.2 conversation or a TCP connection) is called a message channel.

 

• A sender MCA gets messages from the transmission queue and sends them to a receiver MCA at the other end of the message channel. The receiver MCA receives the messages and puts them on their respective destination queues.

 

• Messages can only flow in one direction on a message channel. If you need messages to flow in both directions between two queue managers, two message channels are required, one for each direction.

 

• The higher-level WebSphere MQ protocol used by the MCAs in communicating with each other is called the Message Channel Protocol (MCP). It is this protocol which provides the assured delivery property of WebSphere MQ.

 

• The channel control function at each end of a message channel provides facilities for defining, monitoring, and controlling message channels, including the detection of errors.

 

• A transmission queue can be enabled for triggering. Thus, the arrival of messages on a transmission queue can be used to start a message channel automatically.

 

• All aspects of distributed queue management (DQM) are completely hidden from applications which are using the MQI.

 

 

 

 

 

Figure 1-17. Message Driven Processing

Notes:

 

• This is an example of a message lattice structure made possible by WebSphere MQ. The components are simple message-driven programs, and may be running on different systems and at different times. WebSphere MQ enables the rapid

development of complex business transactions like this.

 

 

 

 

Figure 1-18. Separate Processes as Units of Work

 

Notes:

 

• A complex business transaction may be implemented as a number of separate

asynchronous processes where each process constitutes a unit of work. This type of design emphasizes the importance of the assured, once and once only delivery property of WebSphere MQ.

 

 

 

 

Figure 1-19. Multiple, Asynchronous Units of Work

 

Notes:

 

• To implement a business transaction as a single distributed unit of work requires a two-phase commit protocol.

 

• WebSphere MQ encourages a different style of implementation which uses multiple units of work acting asynchronously.

 

 

 

 

Figure 1-20. Message Persistence

 

Notes:

 

• A message is said to be persistent if it survives a queue manager restart. This applies no matter whether the queue manager was stopped by an operator command or because of a system failure. This implies that persistent messages must be written out to a log. If a queue manager is restarted after a failure, it recovers these persistent messages as necessary from the logged data.

 

• A message is said to be nonpersistent if it does not survive a queue manager restart. This applies even if a queue manager finds an intact nonpersistent message on disk during restart; the queue manager will discard it.

 

• Both persistent and nonpersistent messages can be stored on the same queue.

 

• Whether a message is persistent or nonpersistent is determined by the value of a field in its message descriptor.

V2.0

 

 

1.2 WebSphere MQ Products and Platforms

 

This topic reviews the current list of WebSphere MQ queue managers and the applicationplatforms they support. It also identifies which queue managers provide Level 2 function.

 

 

Figure 1-21. WebSphere MQ Queue Managers

 

Notes:

• The visual depicts the list of WebSphere MQ queue managers and their latest release levels offered by IBM as of the date of publication of these course notes.

 

• MQSeries for DYNIX/ptx, SCO Openserver, SCO UnixWare and SGI (Silicon Graphics IRIX) support is available from third-party vendors. They are not available from IBM and are not supported by IBM. Consult the list of platforms available on the IBM WebSphere MQ home page for information about the source of these products.

 

• All WebSphere MQ queue managers can exchange messages with each other and provide the major benefits of WebSphere MQ as discussed in the previous topic.

 

• WebSphere MQ is provided at two functional levels, Level 1 and Level 2. Level 2 queue managers provide some enhancements over the Level 1 queue managers. These include:

 

- Single point of control

- WebSphere MQ framework

- WebSphere MQ clients

- Instrumentation events

- Additional function

— Secure Sockets Layer (SSL)

— More MQI options

— Larger maximum message size

— Model and dynamic queues

— Batched message transfer

• In the remainder of these course notes, the term Version 5 will be used to refer to the following queue managers.

 

- WebSphere MQ for AIX Version 5

- WebSphere MQ for iSeries Version 5

- WebSphere MQ for HP-UX Version 5

- WebSphere MQ for Linus for Intel and zSeries Version 5

- WebSphere MQ for Solaris Version 5

- WebSphere MQ for Windows

- MQSeries for Compaq tru64 UNIX Version 5

- MQSeries for OS/2 Version 5

 

• Similarly, the term UNIX systems will be used to refer to the following operating

systems.

 

- AIX

- Compaq Tru64 UNIX

- DC/OSx

- HP-UX

- Linux

- NCR UNIX

- SINIX

- Sun Solaris

 

• Similarly, the term WebSphere MQ for Windows systems means WebSphere MQ running on the Windows platforms:

 

- Windows NT

- Windows 2000

- Windows XP

 

 

 

Figure 1-22. WebSphere MQ Framework

 

Notes:

 

• The WebSphere MQ Framework allows users, independent software vendors, and IBM to extend or replace queue manager function using defined interfaces.

 

• The components of the WebSphere MQ Framework are as follows:

 

- Trigger monitor interface (TMI)

- Message channel interface (MCI)

- Name service interface (NSI)

- Security enabling interface (SEI)

- Data conversion interface (DCI)

• There are three parts to the SEI.

- Authorization service

- User identifier service

- Channel exits

 

 

 

 

 

Figure 1-23. WebSphere MQ Client

 

Notes:

 

 

• An WebSphere MQ client is a component of WebSphere MQ which allows an

application running on one system to issue MQI calls to a queue manager running on another system.

 

• The client connection receives the input parameters of an MQI call from the application and sends them over a communications connection to the server connection on the same system as the queue manager. The server connection then issues the MQI call to the queue manager on behalf of the application.

After the queue manager has completed the MQI call, the server connection sends the output parameters of the call back to the client connection, which then passes them onto the application.

 

• The combination of a client connection, a server connection, and a communications connection between them (for example, an SNA LU6.2 conversation or a TCP connection) is called an MQI channel.

 

• The full range of MQI calls and options are available to a client application. The

application simply issues an MQCONN call to connect to a queue manager, that is, to start an MQI channel.

 

• Only a Level 2 queue manager can support the connection of a client application.

 

• The only Level 2 queue manager which is not able to support the connection of a client application is WebSphere MQ for Windows.

V2.0

 

 

Figure 1-24. WebSphere MQ Platforms

 

Notes:

 

• An WebSphere MQ platform is a system environment in which an application may issue calls to the MQI.

 

• On the visual, the platforms supported by WebSphere MQ are displayed in three groups.

 

- Those platforms on which an application may issue MQI calls to a queue manager running on the same system, or on another system.

 

- Those platforms on which an application may only issue MQI calls to a queue

manager running on the same system.

 

- Those platforms on which an application may only issue MQI calls to a queue

manager running on another system, that is, as an WebSphere MQ client

application. This is because there is no WebSphere MQ queue manager which runs on any of these platforms.

 

• NCR UNIX was formerly known as AT&T GIS UNIX.

 

• In addition to the queue managers listed earlier available from third party vendors, there are several clients also available from other vendors. Consult the platforms listing at the IBM WebSphere MQ home page for an up to date list.

 

• Some additional clients are available from IBM as SupportPacs, most are AS-IS

(Category 2).

V2.0

Checkpoint

 

Unit 1 Checkpoint

 

1. T/ F WebSphere MQ only supports asynchronous messaging.

2. WebSphere MQ assured delivery means that:

 

a. A report of delivery will always be sent back.

b. Unless the entire system goes down, no messages are lost.

c. Messages may be duplicated but never lost.

d. Messages will be delivered with no loss or duplication.

 

3. Applications place messages on queues by use of the

 

a. WebSphere MQ Program to Program Interface.

b. WebSphere MQ Message Queue Interface.

c. WebSphere MQ command processor.

 

 

 

 

Figure 1-25. Unit Summary

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

V2.0

 

 

 

y Unit 2. Installation and Configuration

 

What This Unit is About

 

The first unit reviewed the role of WebSphere MQ in commercial messaging and some of the facilities and functions that WebSphere MQ provides. WebSphere MQ supports a wide range of platforms and the major benefits of WebSphere MQ apply to all these platforms.

 

However, the Level 2 queue managers provide some enhancements

which, in turn, deliver additional benefits. It is these queue managers

which now become the focus for the remainder of this course. The

only Level 2 queue manager which is excluded is WebSphere MQ for

z/OS which has its own course, MQ20, WebSphere MQ for z/OS

System Administration.

 

This unit commences by looking at what you need to consider, and

what decisions you need to make, when planning to implement

WebSphere MQ. The unit then describes how to create a basic

configuration for a queue manager and provides a practical exercise in

doing this.

 

What You Should Be Able to Do

 

After completing this unit, you should be able to:

 

• Install WebSphere MQ with reference to the relevant

documentation

• Create and configure a queue manager

• Test a queue manager configuration

• Start and stop a queue manager and perform other simple

administration tasks

 

How You Will Check Your Progress

 

Accountability:

 

• Checkpoint questions

• Machine exercises

 

 

 

References

 

SC34-6055    WebSphere MQ Script (MQSC) Command Reference

SC34-6068    WebSphere MQ WebSphere MQ System Administration Guide

 

If using iSeries, use the following manual;

 

SC34-6070  WebSphere MQ for iSeries V5.3 System

Administration Guide

V2.0

 

|\\\\\\\empty

Figure 2-1. Unit Objectives

 

V2.0mpty 2.1 Planning an WebSphere MQ Implementation

 

This topic looks at what you need to consider, and what decisions you need to make, when planning to implement WebSphere MQ. It also contains some hints for getting started.

 

 

 

 

 

 

Figure 2-2. Naming WebSphere MQ Objects MQ157.0

 

Notes:

 

• The names of channels are limited to 20 characters but otherwise follow the standard rules for naming WebSphere MQ objects.

 

• Agree on all names before you start. And remember, names in WebSphere MQ are case-sensitive.

 

 

Figure 2-3. Queue Manager

 

 

Notes:

 

Again, queue manager names are case-sensitive.

 

After installation, the first WebSphere MQ object to be created is a queue manager.

 

Typically, you only need to create one queue manager per system, but you can create others, for example, for testing purposes. The exception is WebSphere MQ for iSeries for which only one queue manager per system is allowed.

 

Every queue manager has a name which should be unique within a network of queue managers exchanging messages with each other. The reason for this is that, when generating a unique message identifier for a message, a queue manager uses the first 12 characters of its name as part of the identifier.

 

 

 

 

Figure 2-4. Queues

 

Notes:

 

Queue names are case-sensitive.

 

There are some useful conventions for naming a queue.

 

• The name of a queue should not contain an indication of its type or location. In this way, if a queue changes from being a local queue to being a remote queue for example, you can still use the same name for the queue and applications referencing the queue require no change, not even a recompilation.

Instead, the name of a queue should describe its function.

 

• Using a common prefix for the names of related queues can aid administration, for example, searching for all queues related to an application.

 

 

 

 

Figure 2-5. Special Local Queues

 

Notes:

 

There are some local queues which have special purposes in WebSphere MQ.

 

• A dead letter queue is a designated queue upon which a queue manager will put messages that cannot otherwise be delivered. It is not mandatory for a queue manager to have a dead letter queue, but it is strongly recommended.

 

• An initiation queue is a queue which is used to implement triggering. We shall be discussing triggering in more detail later in the course.

 

• We have already seen the role of a transmission queue in relation to message

channels.

 

• In this way, a queue manager can be controlled by an administration application

running locally or remotely.

 

• When a queue manager detects an instrumentation event, it puts an event message describing the event on an event queue. An event queue can be monitored by a system management application which can get each message put on the queue and take the appropriate action.

 

• The purpose of the default queues is to identify the default values of the attributes of any new queue you create. There is one default queue for each of the four types of queues, namely, local, alias, remote, and model. Thus, you only need to include in the definition of a queue those attributes whose values are different from the default values.

 

You can change the default value of an attribute simply by redefining the appropriate default queue.

V2.0

 

 

Figure 2-6. Message Channel

 

Notes:

 

• A message channel is a one-way link between two queue managers for the

transmission of messages. It consists of an MCA at the sending end, an MCA at the receiving end, and a communications connection between the two. The

communications connection may be an SNA LU6.2 conversation, a TCP con nection, and so on.

 

• Each end of a message channel has a separate definition. Both definitions contain the name of the message channel. Among other things, the definition at each end of a message channel also indicates:

  - Whether it is the sending end or the receiving end of the channel, and

  - The communications protocol to be used.

 

• A transmission queue is required for each message channel.

  - A transmission queue is really just a local queue, but it has an attribute whose   value indicates its special role.

 - A transmission queue is located at the sending end of a message channel. As a result, only the definition of the message channel at the sending end contains the name of the transmission queue.

 - Any message destined for a remote queue is put by the queue manager onto a

transmission queue. But how does the queue manager know which transmission

queue to use? One way is to give the transmission queue the same name as the

name of the destination queue manager.

V2.0

ptyFigure 2-7. Administration Interfaces MQ157.0

Figure 2-8. WebSphere MQ Windows Administration Interfaces

 

Notes:

 

In addition to the administration interfaces listed on the previous page, WebSphere MQ for Windows offers some additional interfaces to accomplish administration tasks.

 

• The WebSphere MQ Explorer snap-in

This runs under the Microsoft Management Console (MMC), providing a graphical user interface for controlling resources in the network. It allows definition and control of:

 

- Queues

- Channels

- Process definitions

- Namelists

- Clusters

- Client connections

- Queue managers

2.0

With the WebSphere MQ Explorer, you can stop or start a queue manager and its associated tasks (such as channel initiator, listener, and so forth), view queue

managers and the objects it owns and check the status of channels, queue managers and clusters.

 

It is recommended that the WebSphere MQ Explorer not be used with a queue

manager that has a large number of objects defined. Delays can result as the

WebSphere MQ Explorer extracts information to build its view.

 

Large clusters can also cause difficulties because they are presented by the

WebSphere MQ Explorer in a tree structure; large tree structures can be difficult to work with. The built-in message browser displays the first 200 messages on a queue; and, it only formats and displays the first 1000 bytes of user message data on the screen.

Repository queue managers (to be described in greater detail later) can not be

administered with the WebSphere MQ Explorer if they are on WebSphere MQ for z/OS.

 

At least one repository should be on a non-z/OS platform.

 

• The WebSphere MQ Services Snap-in. This also runs under MMC and allows for more advanced tasks, generally setting up and fine tuning the WebSphere MQ environment. Some of the tasks duplicate things that can be done in the WebSphere MQ Explorer while others cannot be done in the Explorer facility.

 

- Start or stop a queue manager.

- Change the default queue manager.

 

Be careful that this does not affect the running of your system. If the current default queue manager is running when this is done, it may still think it is the default queue manager for some things (like the well-known TCP/IP port it is using).

- Start or stop individual processes like a listener or trigger monitor.

- Start or stop the command server.

- Start or stop the service trace.

- Set the queue manager so that it will automatically start when the system is brought up.

The WebSphere MQ Services snap-in uses Component Object Model (COM) and distributed Component Object Model (DCOM) technology to communicate between servers and between processes on a server. The COM server application (AMQMSVRN) is shared among client processes making use of the WebSphere MQ Services snap-in component. It runs under a special user account called "MQAdmin", created when WebSphere MQ is installed. To grant other users access to the WebSphere MQ Services snap-in a tool called DCOMCFNG.EXE must be run to configure their permissions properly.

 

• WebSphere MQ Web Administration

 

Support for Web Administration has been removed. If you have these features installed from a previous release for the product you will lose then when you upgrade.

 

In addition to the above interfaces, there are some functions available in the administration arena for WebSphere MQ for Windows NT V5.1 that will allow you to easily learn to work with the product. These can be seen by looking at the First Steps menu. Included are the ability to create a default configuration, use a postcard function to send instant messages and an API exerciser to test the setup of a queue manager and its queues. In addition, the reference library and a quick tour give you access to additional information.

 

 2.2 Configuring a Queue Manager

 

After a brief look at what you need to consider when installing WebSphere MQ, the topic continues by describing the tasks of creating, configuring, and controlling a queue manager.

 

 

Figure 2-9. Installation

 

Notes:

 

• The general rules are as follows:

  - Installing WebSphere MQ is like installing any other software on the same platform.

  - Always follow the instructions in:

— The appropriate Quick Beginnings Guide for the WebSphere MQ queue

     manager.

— The WebSphere MQ for iSeries V5.3 System Administration Guide.

— The appropriate System Management Guide for each of the remaining                queue managers.

• Pay particular attention to instructions about what to do before installation. For

example:

- For WebSphere MQ on UNIX systems, you must create a user ID with the name mqm whose primary group is mqm.

 

  - For MQSeries for Tandem NonStop Kernel, you must create a user ID in the   group MQM and log on as that user in order to install the product.

 

• Pay particular attention to instructions about what to do before using WebSphere MQ.

 

For example, on some UNIX systems, you are advised to change the values of certain kernel parameters if they are not sufficient to support WebSphere MQ.

 

• You may install WebSphere MQ for AIX using SMIT, or you may choose the easy installation. The easy installation only places a minimal typical set of components on your system. It excludes, for example, the online documentation and the application development support. Further details can be found in WebSphere MQ for AIX, V5.3 Quick Beginnings GC34-6076.

 

• During the installation of MQSeries for Tandem NonStop Kernel, you are prompted to enter the name of the volume to be used for the installation. If you do not enter a name, the default installation volume, $SYSTEM, is used instead. The name $SYSTEM is used in the examples throughout these course notes. If your installation volume is different, you will need to replace the name $SYSTEM with the name of your installation volume wherever appropriate.

 

 

Figure 2-10. Create Queue Manager

 

Notes:

 

• crtmqm, create queue manager, and dltmqm, delete queue manager, are    examples of control commands. The name of the queue manager is a required parameter on both of these commands.

 

• Some of the following optional parameters of the crtmqm command may be useful in the practical exercises.

-q             Specifies that this queue manager is to be made the default queue

                 manager.

-lc             Circular logging is to be used. This is the default logging method.

-ll              Linear logging is to be used. Linear logging is needed for

                 recovery  from media failures.

 

 

 

-lf LogFileSize

 

The size of each of the log files expressed as a multiple of 4 KB.

 

-ld LogPath

 

The directory to be used to hold the log files.

0

• On MQSeries for Tandem NonStop Kernel, the crtmqm command has two additional required parameters besides the name of the queue manager.

 

-n PATHMONProcessName

 

The name of the TS/MP PATHMON process for the queue manager.

 

-o HomeTerminalName

 

The home terminal device name.

 

• The control commands are described in WebSphere MQ System Administration Guide for a Version 5.3 queue manager and in the relevant System Management Guide for each of the remaining queue managers which support control commands.

 

• It is worthwhile to note that there are some prerequisite requirements for WebSphere MQ for Windows that do not exist for other platforms. There is a PREREQS directory on the installation CD which contains the necessary products. It is highly recommended that you determine what prerequisite products you need and install them before starting the WebSphere MQ installation as it will be interrupted if not. If you choose to proceed without the prerequisite products, some WebSphere MQ functions will not be installed.

 

• On WebSphere MQ for iSeries, there are CL commands CRTMQM for creating a queue manager and DLTMQM for deleting a queue manager. Type the CL command on the command line and then press F4 to be prompted for the parameters.

 

 

 

Figure 2-11. Start Queue Manager

 

Notes:

 

• strmqm, start queue manager, and runmqsc, run WebSphere MQ commands, are further examples of control commands.

 

• The supplied file amqscoma.tst contains a sequence of WebSphere MQ commands to create the system and default objects. The precise format of the

runmqsc command to create the system and default objects depends on the system in use and your current position within the file system. You may need to use a fully qualified file name, for example.

 

WebSphere MQ for Compaq OpenVMS

runmqsc QMgrName < MQS_EXAMPLES:AMQSCOMA.TST

 

MQSeries for Tandem NonStop Kernel

runmqsc /IN $SYSTEM.ZMQSSMPL.AMQSCOMA/ QMgrName

 

Websphere MQ on UNIX systems

runmqsc QMgrName < mqmtop/samp/amqscoma.tst

 

 where mqmtop is:

/opt/mqmon AT&T GIS UNIX, DC/OSx, and SINIX.

/usr/mqmon SunOS.

 

• On WebSphere MQ for iSeries V5.3 the system queues and default WebSphere MQ objects are automatically created.

 

CCTMQM

CALL QMQM/AMQSDEF4

 

• Note that, on a Version 5 queue manager, there is no need to issue a command to create the system and default objects. These objects are created automatically when you create a queue manager.

 

 

Figure 2-12. WebSphere MQ MQSC Commands

 

Notes:

 

• The more important syntax rules for writing WebSphere MQ commands are as follows.

 

- Each command starts on a new line.

- The names of the commands and their keywords are not case sensitive.

- A blank line, and a line starting with an asterisk (*), are ignored.

- A line may contain up to 80 characters but, on a Version 5 queue manager, a line may be of any length up to the maximum allowed by the system.

- If the last non-blank character on a line is:

 

        — A minus sign (-), the command is continued from the start of the next line.

        — A plus sign (+), the command is continued from the first

             non-blank   character in the next line.

 

- On a Version 5 queue manager, you can optionally use a semicolon (;) to terminate a command.

V2.0

- An WebSphere MQ command may contain a string of characters. The more

important rules for using strings are as follows:

 

— A string containing blanks, lower case characters, or special characters other

    than those valid in the name of an WebSphere MQ object, must be enclosed in

    single quotation marks. Lower case characters not enclosed in

    single quotation marks are folded to upper case.

— A string containing no characters is not valid.

 

• The WebSphere MQ commands are described in the WebSphere MQ Script (MQSC) Command Reference.

 

 

Figure 2-13. Run WebSphere MQ Commands

Notes:

 

• On MQSeries for Compaq OpenVMS, the runmqsc command reads from the system input device, SYS$INPUT, and writes to the system output device, SYS$OUTPUT.

 

• On MQSeries for Tandem NonStop Kernel, the runmqsc command reads from the standard IN file and writes to the standard OUT file. In order to redirect input and output when using the runmqsc command, you may either use the TACL redirection operators IN and OUT or the command's own parameters for this purpose, -i and -o. For example:

 

runmqsc /IN MQSCIN, OUT MQSCOUT/

or

runmqsc -i MQSCIN -o MQSCOUT

 

• To end interactive input of WebSphere MQ commands, you enter the EOF character for the system you are using. Specifically, you need to do enter the following.

 

Digital OpenVMS

CTRL+Z

V2.0

OS/2 Warp and Windows

Ctrl+Z, and then press Enter (END command on V5)

 

Tandem NonStop Kernel

CTRL+Y

 

 

UNIX systems

 

CTRL+D (END command on V5)

 

Alternatively, on a Version 5 queue manager, you can enter the WebSphere MQ

command END and, on MQSeries for Tandem NonStop Kernel, you may type exit or quit and press Enter.

 

• On a Version 5 queue manager, when issuing WebSphere MQ commands interactively, you can get help by entering command?, where command is the name of the command you are interested in.

 

• On MQSeries on UNIX systems, man pages are provided for all the WebSphere MQ commands.

 

• On WebSphere MQ for iSeries, WebSphere MQ commands are entered by means of the CL command STRMQMMQSC.

 

 

Figure 2-14. Creating a Local Queue

Notes:

 

• The visual depicts two examples of the WebSphere MQ command DEFINE QLOCAL which is used to create a local queue. Note that the second example uses the synonym DEF QL.

 

• The keywords and their values are used to specify the values of attributes of the local queue being created. The values of those attributes which are not explicitly provided by keywords are taken instead from the values of the corresponding attributes of the default local queue whose name is  SYSTEM.DEFAULT.LOCAL.QUEUE.

 

• The keywords REPLACE and LIKE have the following meanings.

 

REPLACE

 

If the queue already exists, replace its definition with the new one. Note that any messages on an existing queue are retained.

 

LIKE

 

Use the named queue for the default values of attributes rather than the

default local queue.

 

• On WebSphere MQ for iSeries, the corresponding CL command is CRTMQMQ. The command prompter will ask for the type of the queue first.

 

 

 

Figure 2-15. Displaying Attributes

 

Notes:

 

• The WebSphere MQ command to display the attributes of a queue is DISPLAY

QUEUE. The synonym is DIS Q.

 

• DISPLAY QUEUE applies to all types of queue: local, alias, remote, and model.

 

• A generic queue name can be specified by the use of a trailing asterisk (*). An asterisk on its own specifies all queues.

 

• On a Version 5 queue manager, there is a DISPLAY QLOCAL command, but it only applies to a local queue.

 

• The keyword ALL causes all the attributes be displayed. On a Version 5 queue

manager, this is the default if you do not specify a generic queue name and do not request any specific attributes.

 

• You can request the display of selected attributes by using the appropriate keywords.

 

• If no attributes are requested on the DISPLAY QUEUE command, and the ALL keyword is not specified or defaulted, only the queue name and queue type are displayed.

V2.0

• The WebSphere MQ command to display the attributes of the queue manager object is DISPLAY QMGR. Note that the name of the queue manager does not appear in the command.

 

• On a Version 5 queue manager, if you do not request any specific attributes on the DISPLAY QMGR command, the default action is to display all the attributes.

 

• If no attributes are requested on the DISPLAY QMGR command, and the ALL keyword is not specified or defaulted, only the queue manager name is displayed.

 

• The commands DISPLAY QUEUE and DISPLAY QMGR are not supported on

WebSphere MQ for Windows Version 2.0.

 

• On WebSphere MQ for iSeries, the corresponding CL commands are DSPMQMQ and DSPMQM, respectively.

 

 

 

Figure 2-16. Other Queue Types

Notes:

 

• An alias queue is an WebSphere MQ object that is used to refer indirectly to another queue. The WebSphere MQ command to create an alias queue is DEFINE QALIAS.

 

The TARGQ keyword specifies the name of the queue to which the alias queue

resolves. This queue may either be:

 

- A local queue, or

- A local definition of a remote queue.

 

• A local definition of a remote queue, or more simply a remote queue definition, is a WebSphere MQ object owned by one queue manager that refers to a queue owned by another queue manager. The WebSphere MQ command to create a local definition of a remote queue is DEFINE QREMOTE. The keyword RNAME specifies the name of the queue as it is known on the remote queue manager, and the keyword RQMNAME specifies the name of the remote queue manager.

 

• A model queue is an WebSphere MQ object whose attributes are used as a template for creating a dynamic queue. When an application opens a model queue, the queue manager creates a dynamic queue. The WebSphere MQ command to create a model queue is DEFINE QMODEL. The DEFTYPE keyword is used to specify whether a dynamic queue created from the model queue is:

 

- A temporary dynamic queue, which is deleted when it is closed and does not survive a queue manager restart, or

 

- A permanent dynamic queue, whose deletion on the MQCLOSE call is optional and which does survive a queue manager restart.

 

• On WebSphere MQ for iSeries, the CL command to create these three types of queue is the same as the one to create a local queue, namely CRTMQMQ. The command prompter will ask for the type of the queue.

 

 

 

Figure 2-17. More WebSphere MQ Commands

 

Notes:

 

• On WebSphere MQ for iSeries, the corresponding CL commands are as follows.

 

- CHGMQMQ, Change MQM Queue

- CHGMQM, Change Message Queue Manager

- DLTMQMQ, Delete MQM Queue

- CLRMQMQ, Clear MQM Queue

V2.0

Figure 2-18. Sample Programs

Notes:

 

• The sample programs may report some conditions as reason codes. A full list of reason codes can be found in Appendix A, “Selected WebSphere MQ Constants”, on page A-1.

 

• By default, the executable versions of the sample programs can be found in the

following locations.

 

MQSeries for Compaq OpenVMS

[.BIN]

under MQS_EXAMPLES

 

MQSeries for OS/2 Warp and WebSphere MQ for Windows

\MQM\TOOLS\C\SAMPLES\BIN

 

MQSeries for Tandem NonStop Kernel

$SYSTEM.ZMQSSMPL

 

WebSphere MQ on UNIX systems

 

mqmtop/samp/bin

Where mqmtop is:

/usr/lpp/mqmon AIX.

/usr/mqmon SunOS.

/opt/mqmon the remaining UNIX systems.

 

• WebSphere MQ for iSeries provides similar sample programs in library QMQMSAMP.

The samples are written in C, COBOL, and RPG, but they are not delivered in compiled form. There is no sample corresponding to amqsbcg, but similar function is available by using the CL command WRKMQMMSG.

 

V2.0

Figure 2-19. End Queue Manager

 

Notes:

 

• The control command to end the operation of a queue manager is endmqm. The command stops the queue manager in one of three modes.

 

Controlled (or quiesced) shutdown

The queue manager stops only after all applications have

disconnected. All new requests to connect to the queue manager fail.

This is the default mode.

 

 

Immediate shutdown

The queue manager stops after it has completed all the MQI calls

currently being processed. Any MQI calls issued after this command

has been entered fail. Any incomplete units of work are rolled back

when the queue manager is next started.

 

Preemptive shutdown

The queue manager stops without waiting for applications to disconnect

or for MQI calls to complete. The use of this mode can lead to

unpredictable results.

 

• On WebSphere MQ for iSeries, the corresponding CL command is ENDMQM. The iSeries has an additional option *WAIT. It quiesces the queue manager in the same way as *CNTRLD option.

V2.0

 

Checkpoint

 

Unit 2 Checkpoint

 

1. T/F Queue manager names can be made up of any printable ASCII characters.

 

2. Alias queues can point to what other queue types?

a. Another alias queue

b. Local queues

c. Model queues

 

3. Any local queue can be a dead letter queue as long as it is manager.

a. Is identified as the dead letter queue to the queue manager.

b. Has put enabled.

c. Is not being used by any other application.

 

4. T/F Altering queue attributes can be done while the queue manager is running and the changes take effect immediately.

 

 

Figure 2-20. Unit Summary

 

Unit 3. The MQI and Triggering

 

What This Unit is About

 

This unit commences with an introduction to some of the more

important features of the MQI and is followed by a description of

triggering in some detail.

 

Finally, WebSphere MQ Publish/Subscribe, which requires application

involvement, is covered from the administrative viewpoint. There is a

practical exercise on configuring WebSphere MQ for triggering and

reply-to queues.

 

What You Should Be Able to Do

 

After completing this unit, you should be able to:

 

• Describe some of the more important features of the MQI

• Configure WebSphere MQ to enable triggering

• Determine the cause if triggering fails to occur

• Explain WebSphere MQ Publish/Subscribe and know the major

  administrative requirements

 

How You Will Check Your Progress

 

Accountability:

 

• Checkpoint questions

• Machine exercises

• Classroom discussion

 

References

 

SC34-6068    WebSphere MQ System Administration Guide

SC34-6055   WebSphere MQ Script (MQSC) Command Reference

If iSeries:

SC34-6070   WebSphere MQ for iSeries V5.3 System Administration

 

 

 

 

 

Figure 3-1. Unit Objectives

 

Notes:

On completion, you will be familiar at a high level with the MQI, the Message Queue Interface, used by applications to manipulate messages and affect their delivery.

 

One of the most common functions used in WebSphere MQ is triggering. It enables message-driven, or event-driven, processing to occur. During this topic, the requirements for triggering will be discussed and you will gain a clear understanding of the advantages, as well as some of the more common pitfalls, associated with triggering.

 

Finally, WebSphere MQ Publish/Subscribe, which requires administration before use by applications is reviewed from the aspect of the installation, setup and operational requirements.

V2.0

3.1 The MQI

 

This topic provides an introduction to some of the more important features of the MQI.

 

 

 

Figure 3-2. Notation .0

 

Figure 3-3. Common Parameters

 

Notes:

A listing of all the reason codes is contained in Appendix A of this student guide.

 

Figure 3-4. Object Descriptor

 

Notes:

The object descriptor is used by an application to identify an WebSphere MQ object that it wishes to open. It is one of the parameters on the MQOPEN call and MQPUT1 call where it is referred to as ObjDesc.

 

Three fields in the object descriptor are needed to identify an object uniquely:

 

• The object type, ObjType, because the name of an object is only unique within its type.

• The name of the object, ObjectName.

• The name of the queue manager which owns the object, ObjectQMgrName.

V2.0

 

Figure 3-5. Connecting and Disconnecting

 

Notes:

 

• An application will normally need authority to connect to a queue manager.

• Options on the MQCONNX call now allows you to create a connection that can be shared by all the threads in a process.

• In the normal MQI environment the default value is

MQCNO_HANDLE_SHARE_NONE.

 

 

 

Figure 3-6. Opening and Closing an Object

 

Notes:

 

• The Options parameter on the MQOPEN call is used by the application to specify which operations it wishes to perform on the object being opened, for example, MQOO_INPUT_SHARED, or to control the action of MQOPEN, for example, MQOO_FAIL_IF_QUIESCING.

 

• An application will normally need authority to open an object for each of the requested operations. These authorities are checked at the time the object is opened.

 

• For getting messages from a queue, an application may request either

MQOO_INPUT_SHARED or MQOO_INPUT_EXCLUSIVE. Alternatively, it may

request MQOO_INPUT_AS_Q_DEF. In the latter case, the queue is opened in the manner specified by the DefInputOpenOption attribute of the local or model queue being opened. The value of this attribute may be

MQOO_INPUT_SHARED or

MQOO_INPUT_EXCLUSIVE.

Another attribute of a local or model queue is Shareability. The value of this attributemay be MQQA_SHAREABLE or MQQA_NOT_SHAREABLE. The latter value takes precedence over any input options specified on the MQOPEN call.

0

• The MQOO_INPUT_ options are for removing messages from the queue. There is a separate option, MQOO_BROWSE, for reading messages on a queue and leaving them there.

 

 

Figure 3-7. Dynamic Queue

 

Notes:

 

• A permanent dynamic queue may also be deleted by using the WebSphere MQ

command DELETE QLOCAL.

V2.0

 

Figure 3-8. Put Message

 

Notes:

 

The MQPUT call puts a message on a queue. In addition to CompCode and Reason, the parameters of the MQPUT call are as follows.

Hconn                        The connection handle.

 

Hobj                The object handle returned from a successful MQOPEN call with the option MQOO_OUTPUT specified.

MsgDesc

 

The message descriptor structure, MQMD. Some of its fields are input

fields to the MQPUT call, some are output, and some are both input and

output. The message descriptor which actually accompanies a message

on a queue has some fields which have been supplied by the application

and some which have been supplied by the queue manager.

 

 

 

 

 

PutMsgOpts

 

The put message options structure, MQPMO. One of the fields in this MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer, CompCode, Reason) structure, Options, is used by the application to specify options that control the action of MQPUT.

BufferLength

 

The length of the message in the Buffer.

 

Buffer              The message data.

 

 

Figure 3-9. Priority

 

 

Figure 3-10. Get Message

 

Notes:

 

The MQGET call gets a message from a queue. In addition to CompCode and Reason, the parameters of the MQGET call are as follows.

 

Hconn                        The connection handle.

Hobj                The object handle returned from a successful MQOPEN call with either of the options MQOO_INPUT_ or MQOO_BROWSE specified.

MsgDesc

The message descriptor structure, MQMD. Some of its fields are input fields to the MQGET call, some are output, and some are both input and output. Essentially, the message descriptor structure returned to the application by an MQGET call is the same as that which accompanied the message on the queue.

GetMsgOpts

The get message options structure, MQGMO. One of the fields in this structure, Options, is used by the application to specify options that control MQGET (Hconn, Hobj, MsgDesc, GetMsgOpts, BufferLength, Buffer, DataLength, CompCode, Reason)

the action of MQGET. The option MQGMO_WAIT indicates that the

application is to wait until a suitable message arrives if one is not already on the queue. The maximum time the application waits is specified in the field Wait Interval. The application may specify an unlimited wait.

Buffer Length

The  length of the Buffer area.

Buffer              The area to contain the message data.

DataLength

The length of the message returned.

 

 

 

Figure 3-11. Reply-to Queue

 

 

V2.0

Figure 3-12. More Fields in the Message Descriptor

 

 

Figure 3-13. Message and Correlation Identifiers

 

Notes:

 

• Both the MsgId and CorrelId fields are treated as bit strings, not character strings, by the queue manager. The implication of this is that neither field is ever subject to data conversion when a message flows from one system to another.

 

• On an MQPUT call, an application may either specify a particular value for the message identifier or it may specify the value MQMI_NONE. In the latter case, the queue manager generates a unique message identifier and places it the message descriptor which accompanies the message. The queue manager also returns the generated message identifier to the application as an output field in the message descriptor. It is important therefore that the application resets the MsgId field to MQMI_NONE prior to each MQPUT call if it wishes the queue manager to generate a unique message identifier.

 

On a Version 5 queue manager, an application can use the put message option

MQPMO_NEW_MSG_ID to request the generation of a unique message identifier. The use of this option relieves the application of the need to reset the MsgId field to MQMI_NONE prior to each MQPUT call.

 

• The correlation identifier is normally used to provide an application with a means of matching a reply or report message with the original message. In a reply or report message therefore, the value of the CorrelId field is normally copied from the MsgId field of the original message. There is a report option to vary this rule however.

 

 

 

Figure 3-14. Retrieving Messages

 

V2.0

Figure 3-15. Order of Retrieving Messages

 

 

Figure 3-16. Message Group

 

Notes:

The function described on this visual is supported by a Version 5 queue manager only.

 

A message group is a group of one or more logical messages.

 

A logical message is a physical message, unless it is split into segments. We shall be looking at message segmentation on a later visual. For the moment therefore, we shall assume that a logical message is a physical message.

A logical message within a group is identified by two fields in the message descriptor, GroupId and MsgSeqNumber. All logical messages belonging to the same group have the same value for the GroupId field. The MsgSeqNumber field has the value 1 for the first logical message, 2 for the second, and so on. There is, therefore, an implied ordering of the logical messages within a group.

A physical message which does not belong to any group has the value MQGI_NONE in the GroupId field, and the value 1 in the MsgSeqNumber field.

There are two main uses of a message group.

 

• To ensure ordering on retrieval in circumstances where this is not already guaranteed. An application is able to put a sequence of messages constituting a message group on a queue by specifying the put message option MQPMO_LOGICAL_ORDER. The queue manager generates a unique group identifier and assigns a message sequence number to each message as it is put on the queue. Another application is then able to get the messages constituting the group from the queue, in the same order they were put, by specifying the get message option MQGMO_LOGICAL_ORDER.

 

• To allow an application to group together related messages.

This may be useful, for example, if it is important for a group of related messages to be processed by the same server instance, or by a particular server instance. By setting the value MQMO_MATCH_GROUP_ID in the MatchOptions field in get message options, an application can retrieve only those messages with a specified group identifier.

 

 

 

Figure 3-17. Message Segmentation

 

Notes:

 

A logical message may consist of two or more physical messages, each of which is called a segment. A segment of a logical message is identified by three fields in the message descriptor, GroupId, MsgSeqNumber, and Offset. All segments of the same logical message have the same values for the GroupId and MsgSeqNumber fields, but the value of the Offset field is different for each segment. The segment offset is the offset of the data in the physical message from the start of the logical message. The offset of the first segment is 0.

Message segmentation is needed when a message is too large for an application, a queue, or a queue manager. Thus, a logical message is essentially the unit of information that needs to be handled by an application, but its size may mean that it has to be split into more than one physical message.

Provided a message is not too large for an application to handle in a single buffer, segmentation and reassembly of a message can be performed by the queue manager. This is the simplest scenario.

 

To ask the queue manager to segment a message if necessary, the putting applicationsimply sets the value MQMF_SEGMENTATION_ALLOWED in the MsgFlags field of the message descriptor and issues one MQPUT call. Similarly, the getting application simply specifies the get message option MQGMO_COMPLETE_MSG in order to request the queue manager only to return a complete logical message on an MQGET call. And if the logical message is segmented, the queue manager reassembles it before returning it to the

application.

 

If a message is too large for an application to handle in a single buffer, the application may perform the segmentation itself by issuing an MQPUT call for each segment. Similarly, an application may issue an MQGET call for each segment of a logical message.

 

 

 

Figure 3-18. Distribution List

 

Notes:

 

A distribution list may contain the name of an alias queue or the name of a local definition of a remote queue. In the example of a distribution list shown on the visual, the following are assumed.

 

• MAIL_IN_HURSLEY is an alias queue which resolves to the local queue    MAIL_IN on queue manager HURSLEY.

 

• MAIL_IN_PARIS is a remote queue definition which resolves to the queue MAIL_IN on queue manager PARIS using transmission queue PARIS.

 

• MAIL_IN_DALLAS is a remote queue definition which resolves to the queue MAIL_IN on queue manager DALLAS using transmission queue DALLAS.

 

• MAIL_IN_SEATTLE is a remote queue definition which resolves to the queue MAIL_IN on queue manager SEATTLE using transmission queue DALLAS.

 

As a result, ObjectQMgrName is to blank for each object record.

 

Once a distribution list has been opened, the application can call MQPUT to put a message on the queues in the list. As a response to the call, the queue manager puts one copy of the message on each local queue, including the transmission queues. Thus, only one copy of the message is put on the transmission queue DALLAS even though the message is ultimately destined for two queues.

 

On the transmission queue, the application data is prefixed by a distribution header, as well as a transmission queue header. Appended to the distribution header are object records for MAIL_IN at DALLAS and MAIL_IN at SEATTLE. Thus, the message that is transmitted between HURSLEY and DALLAS effectively contains a distribution list for the two destinations. Therefore, when the message is received by the receiving MCA at DALLAS, the MCA has sufficient information to open a distribution list and put the message to it. The queue manager will put one copy of the message on the local queue MAIL_IN and another copy on the transmission queue SEATTLE. And so on.

 

You can see therefore that an important property of the implementation is that a message destined for multiple queues is only replicated at the last possible point at each stage of its journey. In this way, network traffic is minimized.

V2.0

 

 

 

 

 

 

3.2 Triggering

This topic describes how triggering works and how to configure a queue manager for triggering.

 

 

 

Figure 3-19. Components of Triggering

 

Notes:

 

• The sequence of actions depicted on the visual are as follows:

 

1. Program A puts a message on an application queue which is enabled for triggering.

 

2. If the conditions for triggering are met, a trigger event occurs, and the queue manager examines the process object referenced by the application queue. The process object identifies the application to be started, viz Program B.

 

3. The queue manager creates a trigger message whose fields contain information copied from certain attributes of the process object and the application queue. The queue manager puts the trigger message on an initiation queue.

 

4. A long running program called a trigger monitor gets the trigger message, examines its contents, and ...

 

5. ... starts Program B, passing the entire trigger message as a parameter.

 

6. Program B opens the application queue and gets messages from it.

 

 

 

Figure 3-20. Queue Attributes Controlling Triggering

 

Notes:

• The parameters of the WebSphere MQ command DEFINE QLOCAL which control triggering are as follows.

 

TRIGGER or NOTRIGGER

Triggering is active or not active respectively.

 

TRIGMPRI(integer)

The threshold message priority for triggers. The queue manager

ignores messages with a priority lower than this when deciding whether a trigger event should occur.

 

TRIGTYPE

The trigger type.

 

FIRST            A trigger event occurs when the queue changes from

being empty to having one message on it.

DEPTH)         A trigger event occurs when the number of messages on the queue reaches the value indicated by the TRIGDPTH parameter.

 

Note that, when triggering by depth, the queue manager disables triggering by setting the application queue to NOTRIGGER after it has created a trigger message. It is the responsibility of the application to reenable triggering by using the MQSET call.

 

TRIGDPTH(integer)

The number of messages that must be on the queue before a trigger event occurs for TRIGTYPE(DEPTH).

 

TRIGDATA(string)

Data that is copied into the trigger message.

 

 

 

Figure 3-21. Process Attributes

 

Notes:

• A process and a queue are allowed to have the same name. The name of an object only has to be unique within an object type.

 

• Other WebSphere MQ commands for processes are as follows:

- ALTER PROCESS

- DELETE PROCESS

- DISPLAY PROCESS

 

• On WebSphere MQ for iSeries , the corresponding CL commands for processes are as follows:

- CRTMQMPRC, Create MQM Process

- CHGMQMPRC, Change MQM Process

- DLTMQMPRC, Delete MQM Process

- DSPMQMPRC, Display MQM Process

 

 

Figure 3-22. Conditions for a Trigger Event

 

Notes:

• All of the conditions shown on the visual must be satisfied for a trigger event to occur.

 

• If a trigger event does not occur when it is expected, check this list.

More conditions are listed on the following page. Each condition has been summarized. A full statement of all of these conditions can be found in the WebSphere MQ Application Programming GuideV2.0

 

 

Figure 3-23. Other Conditions for a Trigger Event

 

Notes:

 

• Each of the conditions shown on the visual may also cause a trigger event provided there are already a sufficient number of messages for the trigger type on the application queue and any other relevant trigger conditions are also satisfied.

 

• The last condition included on the visual allows for the case of a trigger monitor

restarting following a queue manager restart.

 

• A trigger message is always nonpersistent for reasons of performance.

 

Figure 3-24. Fields in the Trigger Message

 

Notes:

The trigger message, structure MQTM, contains the following fields:

 

QName          The name of the application queue.

 

TriggerData

The trigger data. This is for use by the started application. The

WebSphere MQ Version 5 products allows this field to be used to specify the name of the channel to be triggered.

 

ProcessName

The name of the process object identifying the application that can service the application queue.

ApplType

The application type. Examples are MQAT_CICS, MQAT_UNIX,

MQAT_OS2, and MQAT_WINDOWS_NT.

ApplId             The application identifier. This is a character string that identifies the application to be started.

EnvData         The environment data. This is for use by the trigger monitor.

UserData       The user data. This is for use by the trigger monitor or by the started application.

 

 

Figure 3-25. Trigger Monitor

 

Notes:

• A number of trigger monitors are supplied with WebSphere MQ . The trigger monitor runmqtrm is supplied with all queue managers except WebSphere MQ for iSeries.

 

• If the name of an initiation queue is not explicitly specified on the control command runmqtrm, the queue SYSTEM.DEFAULT.INITIATION.QUEUE is used by default.

 

• The command which runmqtrm uses to start the application contains the structure MQTMC2 as a parameter. This structure is similar to the format of the trigger message. The main differences are the following.

- The non-character fields in MQTM are changed to character fields in MQTMC2.

- MQTMC2 has an additional field containing the name of the queue manager which owns the application queue.

 

Thus, the MQTMC2 structure supplies the started application with the name of the queue that caused the trigger event and the name of the queue manager which owns it. The started application is therefore able to connect to the queue manager and open the queue.

 

• Other trigger monitors are supplied by WebSphere MQ .

 

- On OS/2, Compaq Open VMS Alpha, Compaq NonStop Kernel, UNIX systems, and Windows systems, there is a trigger monitor runmqtmc provided for WebSphere MQ clients. It links with the WebSphere MQ client libraries.

- On OS/2 Version 2, Windows NT Version 2, TXSeries for AIX Version 4,

Transaction Server for OS/2 Version 4, and TXSeries for Windows NT Version 4

uses the standard trigger monitor, runmqtrm, but you can run in a different way and it triggers CICS transactions.

- On WebSphere MQ for iSeries, there are two trigger monitor programs supplied in library QMQM.

AMQSTRG4

This submits an OS/400 job to start an application.

AMQSERV4

This starts an application within its own job. It can also call a CICS

transaction.

 

• On WebSphere MQ for iSeries you can use the CL command STRMQMTRM to start the trigger monitor.

 

• On WebSphere MQ for iSeries, the trigger monitor application can pass the MQTM structure directly to the started application, or pass an MQTMC2 structure instead, depending on what is permitted by the started application. The difference in the structure is that the the non-character fields in MQTM are charged in MQTMC2 to character fields, and the queue manager name is added at the end of the structure.

 

• On MQSeries for Tandem NonStop Kernel, as an alternative to using the control command runmqtrm, you may configure a trigger monitor in its own TS/MP server class and start it by using the PATHCOM commands THAW SERVER and START SERVER. A single default trigger monitor is created as the TS/MP server class MQS-TRIGMON00. If you need additional trigger monitors, you can configure them as additional server classes using MSQ-TRIGMON00 as a template. Full details of this option can be found in the MQSeries for Tandem NonStop Kernel System Management Guide.

 

• It is possible to write your own trigger monitor to work in different ways to the ones supplied or to handle different application types.

 

 

Figure 3-26. Trigger Monitor Errors

 

 

V2.0

3.3 WebSphere MQ Publish/Subscribe

 

This topic explains how WebSphere MQ Publish/Subscribe can be implemented and managed. WebSphere MQ Publish/Subscribe is supported on WebSphere MQ for Windows NT, 2000, AIX, Sun Solaris, HP-UX, and Linus V5.2. WebSphere MQ for AIX, Sun Solaris, HP-UX, Linus, or Windows, V5.3 or later.

 

 

Figure 3-27. WebSphere MQ Publish/Subscribe

 

Notes:

WebSphere MQ Publish/Subscribe releases applications from having to know anything about target applications. Essentially, a sending application sends information (publish) to a standard destination that is managed by WebSphere MQ Publish/Subscribe.

 

The distribution is handled by Publish/Subscribe. The receiving application also need only subscribe to a standard location, registering interest and then await the delivery of the information.

 

WebSphere MQ messages are the vehicle used to transport the information between publishers and subscribers. The subject of that information is called a topic. A publishing application would specify a topic when it sends a message. The subscriber application identifies the topics it is interested in. Only information that matches the subscriber's topics will be sent.

 

Obviously, there is a requirement for a middleman to handle the proper routing of

information. This is handled by a broker.

 

Topics that are related can be grouped into streams; allowing for fewer total items that the broker needs to manage. It also makes access control simpler. If topic does not belong to a particular stream, the broker has a default stream.

An example such as the one above is fairly simple. In this basic configuration, depicting a news service, a single stream can be made up of several kinds of information:

• Publisher 1 is publishing data about sports results (Topic:Sport)

• Publisher 2 is publishing data about stock prices (Topic:Stock)

• Publisher 3 is publishing data about film reviews (Topic:Films) and television (Topic:TV)

 

At the bottom, three subscribers have indicated their interest in different topics:

 

• Subscriber 1 will get information about sports results and stock prices

• Subscriber 2 will get film review information

• Subscriber 3 will receive the sports results

 

Since nobody has subscribed to TV, no information will be distributed.

 

Broker configurations can become very complex with many brokers in a network. However

- only one broker is allowed per queue manager.

 

A broker network must be arranged as a hierarchy with the top broker being the root broker. It will have one or more child brokers and is known as a parent broker. The child

brokers may also have child brokers forming the hierarchy. This eases the number of channels required in the network.

 

Brokers can exchange subscription registrations and deregistrations, publications and requests to delete publications as well as information about themselves. The broker is known by the same name as the local queue manager.

 

Publishers and subscribers can reside anywhere in an WebSphere MQ network as long as there is a route from their queue manager to the broker.

 

Figure 3-28. Installing WebSphere MQ Publish/Subscribe

 

Notes:

You will need at least 1 MB of additional disk space for the WebSphere MQ

Publish/Subscribe code and samples. The User's Guide requires another 1.2 MB.

 

Once the package (MA0C) has been downloaded as a SupportPac, depending on the platform, the necessary files are in some type of zipped format. There is a readme that describes this for each of the supported platforms. Once uncompressed, you will need to execute the appropriate installation program. For example, on AIX: tar -xvf /dir/ma0c_ax.tar rm /dir/ma0c_ax.tar

 

The installation will create a number of files in various subdirectories. On completion, it is highly recommended that you run the sample applications to verify the installation.

V2.0

Figure 3-29. Setting Up the Broker MQ157.0

 

Notes:

 

Streams have been mentioned before. They offer a way to consolidate the various topics to make them more manageable. Streams are implemented as  sets of queues, one at each broker that supports the particular stream. The queue at each broker for a specific stream will have the same name.

 

All brokers will have a default stream, using a queue called

SYSTEM.BROKER.DEFAULT.STREAM. This queue receives all publication messages for the default stream. Administrators can create streams by setting up a series of local queues (one on each broker) with the same name. However, streams beginning with SYSTEM.BROKER. are reserved for WebSphere MQ use.

 

Each broker also has a control queue (SYSTEM.BROKER.CONTROL.QUEUE) where all command messages are sent (everything except publications and requests to delete publications). It is a predefined queue that takes its properties from the SYSTEM.DEFAULT.LOCAL.QUEUE.

 

The SYSTEM.BROKER.ADMIN.STREAM queue is used by the broker to publish its own configuration information. It is possible to write an administration application that can use the information published on this stream.

 

If an administrator chooses, stream queues can be created dynamically when they are needed. It is necessary to ensure that a model queue called

SYSTEM.BROKER.MODEL.QUEUE is defined. Its definition is available in a script called amqsfmda.tst which comes with the WebSphere MQ Publish/Subscribe supportpac.

 

Normal WebSphere MQ access control techniques apply to applications and brokers opening queues for Publish/Subscribe messages. There is no topic based security; the access check is for the stream.

 

Updates must be made to the queue manager configuration to enable Publish/Subscribe.

The User's Guide outlines the defaults and what each of the entries mean.

V2.0

Figure 3-30. Controlling the Broker

 

Notes:

Although the broker exists once the WebSphere MQ Publish/Subscribe is installed on a queue manager and the configuration work is done, it needs to be started, displayed, stopped, and so forth, using control commands.

 

The format of each control command is described in detail in the MQSeries

Publish/Subscribe User's Guide. It is important to remember that the brokers run within the realm of a queue manager so you must specify the queue manager it is associated with, unless it is the default queue manager.

 

The endmqbrk command allows for controlled or immediate shutdown. There is no preemptive shutdown as exists for queue managers. All control information is retained and registrations for publishers and subscribers remain in force. Messages are simply queued for the broker until it is restarted.

 

Displaying the broker allows you to see its status. The following are the potential values that will be returned:

 

• Starting

• Running

• Stopping (immediate shutdown)

• Quiescing (controlled shutdown)

• Not active

• Ended abnormally

 

To delete a broker, it must be stopped and the queue manager must be active. In a complex structure of brokers, it would be dangerous to delete a broker as it may be higher up in the hierarchy than others. Therefore, the delete will fail with an error message if this is the case. If a delete is issued, the broker:

 

• Put-inhibits its input queues (SYSTEM.BROKER.CONTROL.QUEUE and all streamqueues)

 

• Deregisters all of its subscribers and publishers

 

• Sends DELETE PUBLICATION commands to its parent for any metatopics

 

• Deregisters all of its subscriptions with the parent

 

• Processes any messages on its input queues according to the MQMD Report Options

 

• Deletes internal queues (purging any messages)

 

• Deletes any empty input queues that were created by the broker

 

• Terminates

 

The clear command (clrmqbrk) clears the broker's memory of a neighboring target broker. It will cancel all subscriptions from the target broker. This can only be done when the broker is stopped. This operation would be required on both sides in order to stop messages from flowing.

 

The final command (migmqbrk) is used to migrate WebSphere MQ Publish/Subscribe broker to an MQSeries Integrator broker. This command is only supported on platforms that supported MQSeries Integrator V2.0 and above. Migration exports the following state to a replacement MQSeries Integrator broker. The broker must reside on the same queue managers the Publish/Subscribe broker. Please read about planning for migration and

integration before deciding to migrate.

V2.0

Figure 3-31. Message Broker Exits

 

Notes:

 

The message broker exit permits customization of a publication at the broker; for instance, causing traffic for different streams to be sent across different channels.

The exit is invoked after the broker determines that it will send a publication to a specific broker or subscriber. The exit can change MQMD values as well as the publication information itself.

 

The exit must be set up as part of the queue manager configuration.

A parameter block is used for input/output. It contains information related to the invocation of the exit as well as results of its invocation. It is possible to issue MQI calls in the exit with some restrictions (for example, never use MQDISC).

One of the sample programs provided with the WebSphere MQ Publish/Subscribe is a routing exit program. It may be useful to understand its operation before attempting to develop other exits.

V2.0

Checkpoint

 

Unit 3 Checkpoint

 

1. T/F The name of the application to be started in triggering is contained in the TRIGDATA property of the application queue.

 

2. A temporary dynamic queue can store:

a. Nonpersistent messages only.

b. Both persistent and non-persistent messages.

c. Reply messages only.

d. Report messages only.

 

3. When an application issues an MQPUT of a message and explicitlysets priority to a 9, which of the following best describes the results?

a. The message will be always be delivered before any lower priority messages.

b. The sequence of delivery for messages is always FIFO so it will be delivered in that order, regardless of priority.

c. It is possible that this message may be delivered after other messages of lower priority.

 

4. T/F If a problem is encountered while using the WebSphere MQ Publish/Subscribe function, it is eligible for support even though it was downloaded and not shipped with the product.

5. Which of the following are valid control commands for controlling a broker? (Choose 2)

 

a. rcrmqbrk

b. dspmqbrk

c. crtmqbrk

d. strmqbrk

 

 

Figure 3-32. Unit Summary MQ157.0

 

Notes:

 

The message queue interface (MQI) is the API used in applications to call on the queue manager and its resources to perform work (putting messages on queues, getting messages from queues, changing queue attributes).

 

Use of message-driven processing enables the starting of applications as they are needed, alleviating the requirement to manually start them. This is accomplished through the use of triggering.

The WebSphere MQ Publish/Subscribe function allows decoupling of information providers from information recipients. The delivery of any information is handled by a network of brokers.

V2.0

 

 

 

 

 

 

 

Unit 4. Robust Messaging

 

 

What This Unit is About

 

This unit contains an overview of how WebSphere MQ is structured and describes how this knowledge can be used to solve several types of problems. The steps to ensure the recovery of messages are also described.

 

What You Should Be Able to Do

 

After completing this unit, you should be able to:

 

• Determine the state of a queue manager and demonstrate how to

recover from a problem

 

• Design procedures to recover messages in the event of a failure

 

• Describe where to look for error messages and other information

which may help to identify the cause of a problem

 

• Start and stop WebSphere MQ tracing function

 

 

How You Will Check Your Progress

 

Accountability:

 

• Checkpoint questions

• Machine exercises

• Classroom discussion

 

References

 

SC34-6068    WebSphere MQ System Administration Guide

SC34-6055    WebSphere MQ Script (MQSC) Command Reference

If iSeries:

SC34-6070   WebSphere MQ for iSeries V5.3 System

Administration Guide

 

 

 

 

Figure 4-1. Unit Objectives

 

Notes:

 

After completing this unit, you will have the ability to describe how to determine the state of a queue manager as well as how to recover from problems by using the logs. Determining what type of logging is most beneficial will be covered.

Error messages are an important part of problem determination. You will learn how to find error messages as well as what other debug facilities are available (such as trace).

 

Syncpoint control will have an impact on logging; its use will be reviewed as well as looking at the additional functional abilities of Version 5 queue managers with respect to global units of work.

V2.0

 

 

4.1 Architecture

 

This topic contains an outline of the WebSphere MQ reference architecture which forms the basis of the implementation of most of the Level 2 queue managers. It is included in order to help you understand certain aspects of problem determination.

 

 

 

 

 

Figure 4-2. Functional View

 

Notes:

 

• The visual depicts the functional architecture which applies to most of the Level 2 queue managers. There are three main areas:

 

    - A local queue manager (LQM) that manages the physical queues.

      Its main interface is the MQI.

    - Some components that are applications that use the local queue manager.

    - Some underlying services.

 

• The functional architecture of WebSphere MQ for iSeries is very similar with only minor differences.

 

• MQSeries for Tandem NonStop Kernel uses substantially the same code as the

remaining Level 2 queue managers, but there are some internal architectural

differences in order to integrate well with the NonStop Kernel operating system. Use is made of TS/MP (PATHWAY), for example.

 

 

 

 

Figure 4-3. Physical View

 

Notes:

 

• On MQSeries for Tandem NonStop Kernel, the internal structure is different in some ways to that depicted on the visual. Each queue manager runs under its own TS/MP (PATHWAY) configuration. Execution controller and local queue manager (LQM) agent processes exist, but there is no logger or checkpoint processor. Instead, logging and recovery function is provided by TM/MP (TMF).

 

The NonStop Kernel operating system does not support the use of shared memory, and so the queue manager uses hard disk where necessary.

 

 

 

Figure 4-4. Processes

 

Notes:

 

• There is one local queue manager agent for each connected application. However, on MQSeries for OS/2 Warp and WebSphere MQ for Windows which use threads internally, a local queue manager agent can typically support 10s of applications.

 

• MQSeries for OS/2 Warp and WebSphere MQ for Windows also have shared memory server processes. There are two processes per queue manager and one per system. The name of the executable on MQSeries for OS/2 Warp is AMQXSSV2.EXE and on WebSphere MQ for Windows it is AMQXSSVN.EXE.

 

• There may also be a trace process on WebSphere MQ for Windows. The name of the executable is AMQZTRCN.EXE.

 

 

 

Figure 4-5. Directory Structure

 

Notes:

 

• The path to the queue manager directory is formed as follows.

 

Prefix

     

      The default prefix for each queue manager is as follows.

 

- MQS_ROOT:[MQM] on MQSeries for Compaq OpenVMS.

- \MQM\ on  MQSeries for OS/2 Warp and WebSphere MQ for Windows.

- /var/mqm/ on  WebSphere MQ on UNIX systems.

 

The long names is supported for the long file system names on WebSphere MQ for Windows.

 

Literal            qmgrs, used for WebSphere MQ for iSeries.

 

Queue manager name

 

The queue manager name or, if necessary, the queue manager name

transformed to a valid directory name.

 

• There is no simple relationship between the name of a queue or a process object and a name in the file system. You can use the control command dspmqfls to determine the mapping between the name of an WebSphere MQ object and a name in the file system.

 

• WebSphere MQ for iSeries does use a directory structure but it is stored on the system in the Integrated File System (IFS). The queue manager also stores data in the a library that is the QMGRlib. Inside this library is also were the journal and journal receivers reside.

 

There is no simple relationship between an WebSphere MQ object name and an

OS/400 object name. Use the CL command DSPMQMOBJN to determine the mapping between them.

 

• MQSeries for Tandem NonStop Kernel does not use this directory structure. The files for a queue manager are distributed over six subvolumes. The volume in which these subvolumes reside is called the queue manager's home volume. The contents of each of the subvolumes are determined by the final character of the subvolume name.

 

For example, if the queue manager name is QMGR and the name of its home volume is $DATA, the following six subvolumes would be present.

 

$DATA.QMGR FFST subvolume

$DATA.QMGRD Data files subvolume

$DATA.QMGRL Error log subvolume

$DATA.QMGRM Message queue subvolume

$DATA.QMGRS Channel synchronization subvolume

$DATA.QMGRX OAM subvolume

 

If necessary, the queue manager name is transformed or shortened in order to form a valid subvolume name.

 

 

 

Figure 4-6. Configuration Files

 

Notes:

• The WebSphere MQ configuration file is used to find a queue manager, to specify system wide default values, and to identify the default queue manager on a system. It is created during the installation of WebSphere MQ.

 

• A queue manager configuration file specifies values used by an individual queue manager. It is created when the queue manager is created.

 

• WebSphere MQ for Windows is different from the other V5.1 queue managers in that it does not have either of the configuration files. All of the information is contained in the Windows NT Registry.

 

• On WebSphere MQ for iSeries the initialization file does exist and resides in the

directory /QIBM/UserData/mqm/QmgrName/. It is created when the queue manager is created.

 

• More information about the contents of the configuration files can be found in the following publications.

 

- WebSphere MQ System Administration Guide for a Version 5 queue manager.

- The appropriate System Management Guide for each of the remaining queue

managers.

- WebSphere MQ Intercommunication.

 

 

 

Figure 4-7. WebSphere MQ Configuration File

 

Notes:

The WebSphere MQ configuration file is created when WebSphere MQ is installed. It has the name mqs.ini on all platforms except on Tandem NonStop Kernel where its name is MQSINI.

 

By default, the WebSphere MQ configuration file is located as follows.

 

• In the MQS_ROOT:[MQM] directory on Digital OpenVMS and WebSphere MQ for Windows.

 

• In the MQM directory of the boot drive on OS/2 Warp and Windows NT prior to V5.1.

 

• In the $SYSTEM.ZMQSSYS subvolume on Tandem NonStop Kernel.

 

• In the /var/mqm/ directory on UNIX systems.

The information in WebSphere MQ Windows is contained in the Windows Registry.

You can view an example of an WebSphere MQ configuration file on the class systems.

 

 

Figure 4-8. MQS.INI Configuration File

 

Notes:

 

WebSphere MQ configuration file, qm.ini, contains information relevant to all the specific queue managers. There is one queue manager configuration file for each queue manager.The qm.ini file is automatically created when the queue manager with which it is associated is created.

 

A qm.ini file is held in the root of the directory tree occupied by the queue manager. For example, the path and the name for a configuration file for a queue manager  called QMNAME is:

 

/var/mqm/qmgrs/QMNAME/qm.ini

 

The queue manager name can be up to 48 characters in length. However, this does not guarantee that the name is valid or unique. Therefore, a directory name is generated based on the queue manager name. This process is known as name transformation.

 

 

Figure 4-9. Queue Manager Configuration File

 

Notes:

 

• On WebSphere MQ for Windows the queue manager configuration information is stored in the Windows Registry

 

• On Webphere MQ for iSeries, the initialization file is called qm.ini and it resides in the Integrated File System (IFS).

 

• On MQSeries for Tandem NonStop Kernel, the queue manager configuration file is called QMINI and is located in the queue manager data files subvolume, that is, the subvolume whose name has the suffix 'D'. For example, if the queue manager name is QMGR and the name of its home volume is $DATA, QMINI would be located in the subvolume $DATA.QMGRD.

 

As before, an example can be found on the class systems.

 

• The Service and ServiceComponent stanzas indicate that the queue manager has an authorization service component installed and provide certain details about it.

 

• The Log stanza specifies the log configuration for the queue manager.

This stanza is not relevant to MQSeries for Tandem NonStop Kernel because there is no MQSeries log. TM/MP (TMF) provides the logging and recovery function instead.

 

A queue manager configuration file may also contain the following stanzas.

Channels

 

This stanza specifies values relating to the operation of channels such as

the maximum number of channels that can be active at any one time.

 

LU62, NETBIOS, TCP, SPX

 

These stanzas contain configuration parameters relating to their respective

communications protocols.

 

On MQSeries for Tandem NonStop Kernel, QMINI has a stanza called

TCPConfig containing similar information relating to TCP/IP. There is no

equivalent stanza for SNA LU6.2.

 

XAResourceManager

 

This stanza identifies an XA compliant resource manager, such as a data

base manager, for which the queue manager can act as a syncpoint

coordinator. This function is only supported by a Version 5 queue

manager.

 

MQSeries for Tandem NonStop Kernel has many more stanzas which are unique to MQSeries on this platform. These are mainly concerned with the internal configuration and process structure of the queue manager. Refer to the MQSeries for Tandem NonStop Kernel System Management Guide for full details.

 

 

 

Figure 4-10. QM.INI Configuration File

 

Figure 4-11. Installable Services

 

 

Notes:

 

• Service components can be chained. If one component cannot perform a requested operation, the queue manager tries the next one.

 

• Installable services are described in WebSphere MQ System Administration Guide.

 

• On WebSphere MQ for iSeries the only installable service available is the authorization service.

 

Figure 4-12. Installable Services and Supplied Components

 

Notes:

 

• The name service allows multiple queue managers to share specified queue definitions. Given the name of a queue, the name service returns the name of the queue manager which owns the queue. The name service is enabled by manually adding a service stanza to the queue manager configuration file.

 

• The name service component supplied with MQSeries for Compaq OpenVMS and the Version 5 queue managers uses the DCE directory. It is identified to the queue manager by manually adding a service component stanza to the queue manager configuration file. Some DCE configuration is also needed.

 

• The authorization service provides access control to queue manager resources. On MQSeries for Compaq OpenVMS, MQSeries for Tandem NonStop Kernel, WebSphere MQ on UNIX systems, and WebSphere MQ for iSeries, and Windows, the supplied authorization service component is Object Authority Manager (OAM).

 

When you create a queue manager, the service stanza to enable the authorization service,  and the service component stanza to identify the OAM to the queue manager, are automatically added to the queue manager configuration file.

 

• By default, the OAM is enabled. It can be disabled by setting the environment variable MQSNOAUT before the queue manager is created.

For MQSeries for Compaq OpenVMS, you set the logical name MQSNOAUT as

follows.

 

$ DEFINE/SYSTEM MQSNOAUT TRUE

 

For MQSeries for Tandem NonStop Kernel, you set MQSNOAUT as follows.

 

PARAM MQSNOAUT 1

 

For WebSphere MQ on UNIX systems, you set MQSNOAUT as follows.

 

export MQSNOAUT=yes

 

For WebSphere MQ for Windows, you set MQSNOAUT as follows.

 

SET MQSNOAUT=yes

 

However, if you do set MQSNOAUT, you cannot in general reenable the OAM later. You can also disable the OAM for testing purposes by removing the relevant service component stanza from the queue manager configuration file.

 

 

Figure 4-13. Stopping a Queue Manager Manually

 

Notes:

 

• If you ever need to stop a queue manager manually as a last resort, stop any residual processes in the following order. The names of the executables depicted are typical of a UNIX implementation.

 

amqc...                      Processes related to channels.

amqhasmx               Logger.

amqharmx                Log formatter (LINEAR logs only).

amqzllp0                   Checkpoint processor.

amazlaa0                  Local queue manager agents.

amqzxma0                Execution controller.

 

• On MQSeries for Compaq OpenVMS, before using this procedure, you are advised first to try stopping the execution controller using the ipc monitor kill command. This should subsequently stop the other subprocesses. Details can be found in the MQSeries for Compaq OpenVMS System Management Guide.

 

• On MQSeries for OS/2 Warp and WebSphere MQ for Windows any residual shared memory processes, executables AMQXSSV2.EXE and AMQXSSVN.EXE, respectively, should be stopped after the execution controller has been stopped.

 

• On WebSphere for MQ for iSeries, the ENDMQM(QMGRNAME) OPTION(*CNTRLD) ENDDCTJOB(*YES) TIMEOUT(15) to stop all WebSphere MQ components. If this command does not complete, other actions are documented in WebSphere MQ for iSeries V5.3 System Administration Guide.

 

• On MQSeries for Tandem NonStop Kernel, the procedure is slightly different because of the different internal process structure of the queue manager. Details can be found in MQSeries for Tandem NonStop Kernel System Management Guide.

 

• On WebSphere MQ for Windows, if there is a residual trace process, executable AMQZTRCN.EXE, it should be stopped after the local queue manager agents have been stopped and before attempting to stop the execution controller.

 

 

 

Figure 4-14. Removing a Queue Manager Manually

 

Notes:

 

• If there are problems, perhaps related to errors on a test system, follow the steps given.

 

- Find the queue manager directory from the WebSphere MQ configuration file.

- Find the queue manager log directory from the queue manager configuration file.

- Delete the queue manager directory, all subdirectories, and files.

- Delete the queue manager log directory, all subdirectories and files

- Remove its stanza from the WebSphere MQ configuration file

- Remove or change the DefaultQueueManager stanza if the queue manager

being deleted is the default queue manager.

 

• The procedure is similar for all the queue managers, but there are minor differences. The full procedure for each queue manager is documented in WebSphere MQ System Administration Guide for a Version 5 queue manager and in the relevant System Management Guide for each of the remaining queue managers.

 

• On WebSphere MQ for iSeries you will use the DLTMQM CL command to remove the queue manager. The procedures are documented in the WebSphere MQ for iSeries V5.3 Quick Beginnings manual.

V2.0

 

 

4.2 Problem Determination

 

This topic describes aspects of problem determination.

 

 

Figure 4-15. Configuration Files and Problem Determination

 

 

Figure 4-16. Error Messages

 

Notes:

 

• Error messages are written to the associated terminal, if any, and are written to an error log file with additional information.

 

• Error messages are only written to an error log file called AMQERR01.LOG. There is an separate error log file with this name in each of three error directories. Which of these directories is used for a specific error message depends on the information available to WebSphere MQ at the time the error occurs.

 

• When the error log file AMQERR01.LOG fills up, its contents are copied to

AMQERR02.LOG and AMQERR01.LOG is then reused. Before the copy,

AMQERR02.LOG is copied to AMQERR03.LOG. The previous contents of

AMQERR03.LOG, if any, are discarded. In this way, AMQERR02.LOG and

AMQERR03.LOG are used to maintain a history of error messages.

 

• On MQSeries for Tandem NonStop Kernel, the corresponding error log files are called MQERRLG1, MQERRLG2, and MQERRLG3.

 

• On WebSphere MQ for iSeries, error messages are written to the appropriate job log. Because WebSphere MQ code is invoked synchronously by a call to the MQI from an application is run in the same process as the application, any error messages written by this code will appear in the job log of the job in which the application is running. However, components of WebSphere MQ which are themselves applications, such as MCAs, run as separate jobs and have their own job logs.

 

 

Figure 4-17. First Failure Support Technology (FFST)

 

Notes:

• WebSphere MQ uses FFST as follows.

- To detect and report software events, for example, internal queue manager failures.

- To collect information about software events, for example, dumps of storage.

- To generate data to help analyze software events, for example, probe IDs.

 

• Each FFST report contains various items of useful information.

- A probe ID which identifies where in the code the error was detected.

- The date and time the error occurred.

- Any associated error message.

- A variable number of dumps including the function stack and trace history.

 

• FFST, information for WebSphere MQ for iSeries is recorded in a stream file in the /QIBM/UserData/mqm/errors directory, and non-threaded jobs, in the problem

database, using OS/400 command WRKPRB. The stream files are named

AMQnnnnnn.mm.FDC.

 

• If you experience frequent FFST reports related to shared memory on a UNIX system, it may mean that you need to change the values of certain kernel parameters in order to support WebSphere MQ. For more details on which kernel parameters may need changing, refer to WebSphere MQ for HP-UX, Sun Solaris, or AIX V5.3 Quick Beginnings, or the relevant System Management Guide for each of the remaining queue managers on UNIX systems.

 

 

 

Figure 4-18. Trace

 

V2.0

 

 

4.3 Transactions and Recovery

This topic describes logging in WebSphere MQ and how messages and WebSphere MQ objects can be recovered in the event of a failure. It also describes the transactional support within WebSphere MQ.

 

 

Figure 4-19. Message Persistence

 

Notes:

• Persistent messages are never lost as a result of a system failure, or as a result of a communications failure when they are being transmitted from one queue manager to another. In order to achieve this, persistent messages are written out to a log. When a queue manager is restarted following a system failure, it recovers persistent messages as necessary from the logged data.

 

• Nonpersistent messages can be used for better performance when it is not critical for messages to be able to survive a queue manager restart.

 

• Both persistent and nonpersistent messages may be stored on the same queue. The only exception to this is a temporary dynamic queue which can only store nonpersistent  messages.

 

 

 

Figure 4-20. Types of Log

 

Notes:

• Unless you request linear logging when you create a queue manager, circular logging is provided by default.

 

• Circular logging is able to recover messages following a system failure but is unable torecover following a media failure. It has the advantage that the amount of disk space required for the log does not increase with time.

 

• A linear log can recover from a media failure but it requires inactive log files to be archived on a regular basis.

 

• Periodically, the queue manager performs a log checkpoint. Information about the last checkpoint, including its location in the log, is held in the checkpoint file, amqalchk.fil.

 

• WebSphere MQ for iSeries implements its log using an OS/400 journal and associated journal receivers. Effectively, the structure of the log is linear but it is not described as such in the publications. Circular logging is not supported. The queue manager does, however, use log checkpoints.

 

Figure 4-21. Recovering Persistent Messages

 

Notes:

 

The queue manager recovers any damaged object that would prevent it from starting, but this would not normally include a local queue which is damaged. Such a queue may only be detected later when an attempt is made to access it.

In order to restart, a queue manager only requires the following:

 

• Log records written since the last checkpoint.

• Log records written by transactions which were still active at the time the queue

manager stopped. Uncommitted persistent messages, put or got inside these

transactions, are rolled back during restart. Hence, recovery can be quite quick.

 

 

 

 

Figure 4-22. Damaged Objects and Media Recovery

 

Notes:

• The control command to record a media image is rcdmqimg. For example, the

following command will record a media image of a local queue.

 

rcdqimg -m QMgrName -t qlocal QName

 

• On WebSphere MQ for iSeries, the equivalent CL command is RCDMQMIMG.

• A damaged object can be re-created by using the rcrmqobj control command. For example, the following command will recreate a local queue.

 

rcrmqobj -m QMgrName -t qlocal QName

 

• On WebSphere MQ for iSeries, the equivalent CL command is RCRMQMOBJ.

 

 

Figure 4-23. Dumping the Log

 

Notes:

 

• The head of the log is the checkpoint that commences the active portion of the log. Normally, this would be the most recent checkpoint. However, the head of the log maybe positioned at an earlier checkpoint if there were transactions that were still active when the queue manager stopped and there are uncommitted persistent messages that were put or got inside these transactions prior to the most recent checkpoint.

 

• The base of the log is the first log record in the log file containing the head of the log.

 

• Each log record is identified by a unique log sequence number (LSN).

 

• Each log file has a file name of the form Snnnnnnn.LOG, where nnnnnnn is the extent number.

 

• Full details, including a sample dump with notes, can be found in WebSphere MQSystem Administration Guide.

 

• The dmpmqlog control command is only supported on a Version 5 queue manager.

 

Figure 4-24. Syncpoint Control

 

Notes:

 

• An application can specify whether an MQPUT call or an MQGET call is within, or outside of, syncpoint control or leave it as the default. But take care, the default is platform dependent.

 

• Note a special case. An application can get a message it has just put in the same unit of work.

 

Figure 4-25. Compensating Transactions

 

Notes:

 

Local syncpoint coordinates messages with data base updates on that system. But the actual processing of the message may take place on a different system, or at a later time. When a message is processed later, the application may find an error, in the data base, that prevents the message from being processed. It is too late to roll back the original unit of work.

 

The answer is to include compensating transactions which send messages to reverse the original request. Some examples are illustrated.

 

Figure 4-26. Coordinating Local Units of Work

 

Notes:

 

• The calls MQCMIT and MQBACK are supported on all queue managers except

WebSphere MQ for iSeries and MQSeries for Tandem NonStop Kernel.

 

• On WebSphere M for iSeries, OS/400 commitment control is used to coordinate local units of work. For CICS transactions, CICS for OS/400 may also be used.

 

• On MQSeries for Tandem NonStop Kernel, TM/MP (TMF) is used to coordinate local units of work. Instead of using the calls MQCMIT and MQBACK, an application making changes to WebSphere MQ resources within syncpoint control uses the calls BEGINTRANSACTION, ENDTRANSACTION, and ABORTTRANSACTION.

 

• A WebSphere MQ client application may also use the MQCMIT and MQBACK calls.

Figure 4-27. Internal Coordination of Global Units of Work

 

Notes:

 

Internal coordination of global units of work is only supported by a Version 5 queue manager. Using the X/Open XA interface, with a two-phase commit protocol, a Version 5 queue manager is able to coordinate changes to its own resources and to those of other resource managers within a unit of work. An external syncpoint coordinator is not required under these circumstances.

 

 

Figure 4-28. Database Coordination

 

Notes:

 

The visual depicts the XA-compliant database managers that are supported by the Version 5 queue managers. These database managers may participate in a global unit of work coordinated by WebSphere MQ.

The visual also lists some restrictions regarding the internal coordination of global units of

work.

 

• An WebSphere MQ client application cannot participate in a global unit of work and cannot therefore issue the MQBEGIN call.

 

• Although a queue manager may be XA-compliant, both as a syncpoint coordinator and as a resource manager, it is not possible to configure two or more queue managers as participants in a global unit of work. This is because an application may only be connected to one queue manager at a time.

 

• Normally, updates to WebSphere MQ resources and to those of a data base manager must be made on the same system. WebSphere MQ does not have the capability to coordinate a distributed unit of work.

 

• However, a database manager may reside on a different system to the queue manager provided it can supply an XA compliant client feature which resides on the same system as the queue manager.

 

 

Figure 4-29. External Coordination of Global Units of Work

 

 

Notes:

 

• Most of the external syncpoint coordinators listed on the visual use the X/Open XA interface for coordinating changes to WebSphere MQ resources and to those of other resource managers. Those that are not XA-compliant are as follows.

 

Transaction Server for OS/2

 CICS for OS/2

OS/400 commitment control

CICS for OS/400

TM/MP (TMF)

CICS for Windows

 

• An WebSphere MQ client application cannot participate in a global unit of work and cannot therefore make use of an external syncpoint coordinator.

 

• There are no supported external syncpoint coordinators for MQSeries for Compaq OpenVMS.

 

• WebSphere is supported on WebSphere MQ V5.2 and after.

As this list occasionally changes, you should check the following url for the latest

Information : www.ibm.com/software/ts/mqseries/platforms/supported.html

 

 

Figure 4-30. CICS Transactions

 

Notes:

 

• On AIX, OS/2 Warp, and Windows only, there is a supplied trigger monitor which runs as a CICS transaction. The process object specifies which transaction to start.

 

APPLTYPE              CICS

APPLICID                 Transaction ID

 

The trigger monitor performs EXEC CICS START and passes MQTMC2 as CICS data. If the trigger monitor is started without data, it gets the trigger messages from SYSTEM.CICS.INITIATION.QUEUE.

 

• One of the trigger monitors supplied with WebSphere MQ for iSeries, AMQSERV4, can also call a CICS transaction.

 

 

Figure 4-31. Independent Coordination

 

Notes:

 

• In this example, the message identifier is saved in the database.

 

• Initialization code has to check whether a failure occurred in the window of opportunity.

 

• The logic depicted on the visual assumes that unique message identifiers are being used and that there is only a single server. The logic could be modified, however, to accommodate multiple servers.

V2.0

Checkpoint

 

Unit 4 Checkpoint

 

1. T/F Authorization Service are not supported on iSeries.

2. The two types of logging supported on HP-UX are:

a. journaling

b. linear

c. circular

d. checkpointing

 

3. A queue manager has just failed. The most recent errors within the

queue manager's directory are contained in a file called:

a. QMGRERR

b. ERRORS

c. amqerr01.log

d. AMQERR.001

 

4. T/F Non-persistent messages will only be recovered if they were

part of a unit of work when the queue manager failed.

 

5. What type of log can a damaged object be re-created from?

a. circular

b. journal receiver

c. linear

d. queue manager log

 

 

 

 

Figure 4-32. Unit Summary

 

Notes:

 

WebSphere MQ has some robust recovery and logging facilities. It is very important to plan ahead and decide what type of logging suits your needs where a choice is involved.

 

As the administrator, you may be called upon to explain the impact of syncpointing and using non-persistent messages may have.

 

 

 

 

 

 

 

 

V2.0

Unit 5. Distributed Queue Management

 

What This Unit is About

 

This unit describes various aspects of distributed queue management.

• Configuring WebSphere MQ for distributed queuing

• Application data conversion

• Remote administration

• Handling exceptions

 

What You Should Be Able to Do

 

After completing this unit, you should be able to:

• Given a WebSphere MQ network, demonstrate how to create the required WebSphere MQ objects

• Given network design goals, select the appropriate channel configuration

 

• Given a scenario containing alias queues, local definitions of remote queues, reply-to queue aliases, and queue manager aliases, predict the final destination of a message

 

• Configure TCP/IP to enable its use by WebSphere MQ and identify where the configuration of other communications protocols is described

 

• Distinguish between the various ways of starting and stopping a message channel

 

• Describe how to start and stop a message channel

 

• Determine the state of a message channel

 

• Given an error on a message channel, determine the possible cause

 

• Give examples of the steps that can be taken to find a messagethat has not arrived on its intended destination queue

 

• List the considerations when writing a data conversion exit

 

• Explain how a remote queue manager's resources can be monitored and changed using the administration features of WebSphere MQ

 

• Describe queue manager clusters

 

• Configure a simple cluster of queue managers

 

How You Will Check Your Progress

 

Accountability:

• Checkpoint questions

• Machine exercises

• Classroom discussion

 

References

 

SC34-6055    WebSphere MQ Script (MQSC) Command Reference

SC34-6059    WebSphere MQ Intercommunication

SC34-6061    WebSphere MQ Queue Manager Clusters

 

 

V2.0

Figure 5-1. Unit Objectives MQ157.0

 

 

Notes:

 

This unit is, perhaps, one of the most important in the entire course. Channel configuration and operations can be confusing. Once you have completed this unit and the practical exercise, you will have a better idea of what is involved.

With additional practice and use when you return to your job, you will find that they are not as difficult as they appear.

V2.0

 

5.1 Configuration for Distributed Queuing

 

This topic describes how to configure WebSphere MQ in order to enable one queue manager to exchange messages with another.

 

 

Figure 5-2. Identifying a Queue in the MQI MQ157.0

 

 

Figure 5-3. Assured Delivery MQ157.0

 

Notes:

 

• Whether an application is putting a message on a local queue or to a remote queue is transparent to the application. However, an application always gets a message from a local queue.

 

 

Figure 5-4. Queue Definitions for Distributed Queuing

 

Notes:

 

• As a general rule, give a transmission queue the same name as the remote queue manager.

 

 

Figure 5-5. Message Channel Combinations

 

Notes:

 

• WebSphere MQ Intercommunication explains the possible combinations in more detail.

 

• A sender can initiate a communications connection with a receiver and then send messages to it. This is the most common combination. A fully defined server may also perform the same role as a sender in this combination.

 

• A requester can initiate a communications connection with a server which then sends messages to the same requester.

 

• A requester can initiate a communications connection with a sender which promptly terminates the connection. The sender then starts a communications connection according to the information in its channel definition and sends messages to the partner it has started. This combination is known as callback.

 

 

Figure 5-6. Attributes of a Message Channel MQ157.0

 

Notes:

 

• The WebSphere MQ command to define a message channel at one end is DEFINE CHANNEL. Related commands are ALTER CHANNEL, DISPLAY CHANNEL, and DELETE CHANNEL.

 

• Attributes not supplied on the DEFINE CHANNEL command are taken from the

appropriate default channel object.

 

- SYSTEM.DEF.SENDER

- SYSTEM.DEF.RECEIVER

- SYSTEM.DEF.SERVER

- SYSTEM.DEF.REQUESTER

• CHLTYPE must be included as the first parameter on both the DEFINE

CHANNEL and ALTER CHANNEL commands.

 

• TRPTYPE is a required parameter on the DEFINE CHANNEL command on all queue managers except a Version 5 queue manager. On a Version 5 queue manager, if TRPTYPE is not specified, the value is taken from the appropriate default channel object.

 

 

Figure 5-7. Example

 

 

• Each message channel has a two channel definitions, one at each end.

 

• In the example, the sending end of each channel has a transmission queue with the same name as the queue manager at the other end of the channel.

 

 

Figure 5-8. Choosing a Transmission Queue MQ157.0

 

 

Figure 5-9. Queue Manager Alias MQ157.0

 

Notes:

 

• The WebSphere MQ command DEFINE QREMOTE is used to define a queue manager alias. The value of the RNAME parameter must be blank, which is the default value in any case.

 

 

 

Figure 5-10. Separating Message Flows MQ157.0

 

Notes:

 

• On each queue manager, the normal transmission queue has the same name as the partner queue manager.

 

• On queue manager QM1, a local definition of a remote queue specifies a alternative transmission queue which can be used for sending messages to queue manager QM2.

 

• A reply-to queue alias is used to set the value of reply-to queue manager QM1A.

 

• There is also a queue manager alias definition which specifies QM1A as an alias of QM1. These three definitions enable request messages to be separated into two flows between queue managers QM1 and QM2, and enable the reply messages to be separated into two flows in the reverse direction.

 

 

 

 

 

Figure 5-11. Configuring TCP/IP for WebSphere MQ MQ157.0

 

Notes:

 

• The visual shows you how to configure TCP/IP for WebSphere MQ on both AIX and MQSeries OS/2 Warp.

 

• The inet daemon, inetd, is available for TCP/IP on UNIX and on OS/2 Warp. It has to be configured for WebSphere MQ.

 

- Change the two files as shown, adjusting path names as appropriate.

- The inet daemon then has to be refreshed. On AIX, issue:

 

inetimp

refresh -s inetd

 

On OS/2 Warp, simply restart the inetd program.

 

• On the remaining UNIX systems, the procedure to configure TCP/IP is very similar to that on AIX with only minor differences.

• On OS/400, and Windows, no inet daemon is supplied and so the WebSphere MQ listener must be used instead. On WebSphere MQ for iSeries, the listener is started by issuing the following CL command.

 

STRMQMLSR

 

• The WebSphere MQ listener, runmqlsr, is available on other queue managers. On MQSeries for OS/2 Warp and WebSphere MQ for Windows, you can use the listener for all the supported communications protocols. For NetBIOS and IPX/SPX on both queue managers, and for TCP/IP on Windows, it is the only option available. On the WebSphere MQ UNIX platforms, runmqlsr is also available.

On MQSeries for Compaq OpenVMS, it is available for use with SNA LU6.2 only and, on MQSeries for Tandem NonStop Kernel, it is available for use with TCP/IP only.

 

• On Digital OpenVMS, there are three supported versions of TCP/IP, viz

 

- Digital TCP/IP Services (UCX) for OpenVMS.

- Cisco MultiNet for OpenVMS.

- Attachmate Pathway for OpenVMS.

 

None of these implemenatations provide an inet daemon. In addition, as stated

previously, the WebSphere MQ listener is not available for use with TCP/IP.

For each version, you first need to create a file consisting of one line, viz

 

$ mcr amqcrsta [-m QMgrName]

 

and place the file in the SYS$MANAGER directory. Then you need to create the

appropriate service (UCX, MultiNet, or Attachmate) to start the receiving MCA

automatically.

 

• On MQSeries for Tandem NonStop Kernel, as an alternative to using the WebSphere MQ listener, you may configure a TCP/IP listener in its own TS/MP server class and start it by using the PATHCOM commands THAW SERVER and START SERVER. By default, one listener is configured in server class MQS-TCPLIS00. If you need an additional listener, you can configure it in its own server class using MQS-TCPLIS00 as a template. Full details of this option can be found in the MQSeries for Tandem NonStop Kernel System Management Guide.

 

• The WebSphere MQ command START LISTENER can also be used to start the WebSphere MQ listener. On OS/400, OS/2 Warp, UNIX Systems and Windows, this command is valid for channels for which the TRPTYPE is TCP.

 

• WebSphere MQ Intercommunication contains full details on how to configure TCP/IP for WebSphere MQ on all platforms except Tandem NonStop Kernel. For Tandem NonStop Kernel consult the System Management Guide.

 

 

Figure 5-12. Starting a Message Channel MQ157.0

 

Notes:

 

• Check the network first, for example, issue a TCP/IP ping.

 

• Use the WebSphere MQ command PING CHANNEL to test a message channel

configuration. It can only be used at the sender or server end of a channel, and only when the channel is not started.

 

• On WebSphere MQ for iSeries, the CL command corresponding to the control

command runmqchl is STRMQMCHL.

 

The START CHANNEL command is still available for users who wish to start an

individual channel.

 

 

Figure 5-13. Channel Initiator MQ157.0

 

Notes:

• The channel initiator is a special trigger monitor for starting a message channel. It alsocontains retry logic for use in case of difficulty in starting a channel or after an error on achannel.

 

Neither the WebSphere MQ command START CHANNEL, nor the control command  runmqchl, contain any retry logic. Thus, you must use the channel initiator if you require this function.

 

- For triggering a channel, the attributes ApplType and ApplId of a process object are not required. Instead, the attribute UserData specifies the name of the channel to be started.

 

- On a Version 5 queue manager only, you do not need to define a process in order to trigger a channel. Instead, the attribute TriggerData of the transmission queue specifies the name of the channel to be started.

 

- If you do not specify a channel name at all, the channel initiator searches the

channel definitions until it finds a channel whose definition contains the name of the transmission queue that has just caused the trigger event.

 

• On WebSphere MQ for iSeries, the corresponding CL command is STRMQMCHLI.

 

• On MQSeries for Tandem NonStop Kernel, as an alternative to using the control command runmqchi, you may use the default channel initiator which is configured in the TS/MP server class MQS-CHANINIT00 and start it by using the PATHCOM commands THAW SERVER and START SERVER. Full details of this option can be found in the MQSeries for Tandem NonStop Kernel System Management Guide.

The WebSphere MQ command START CHINIT is not supported on this queue manager.

 

• The channel control parameters shown on the visual can be specified on the DEFINE CHANNEL command.

 

DISCINT        (SDR and SVR)

 

Maximum time to wait for a message on the transmission queue if it is

empty. If no message arrives within this time, the channel closes down.

 

SHORTRTY, SHORTTMR (SDR and SVR)

 

Short retry count and short retry time interval to control repeated

attempts to establish a communications connection.

 

LONGRTY, LONGTMR (SDR and SVR)

 

Long retry count and long retry time interval to control further repeated

attempts to establish a communications connection.

 

MRRTY, MRTMR (RCVR and RQSTR)

 

Message-retry count and message-retry interval when attempting to put

a message on a destination queue. If every attempt fails, the MCA

decides that it cannot deliver the message.

 

MCATYPE (SDR, SVR, and RQSTR)

 

The value of this parameter may be THREAD or PROCESS. If THREAD is specified, each channel runs as a thread within the channel initiator process. If PROCESS is specified, each channel runs as a separate process.

This parameter is only supported on MQSeries for OS/2 Warp and

WebSphere MQ for Windows.

 

BATCHINT (SDR and SVR)

 

The period of time during which a channel will keep a batch open if  there are no messages on the transmission queue. This should be set to a value considerably less than the value of DISCINT.

 

This parameter is only valid on a Version 5 queue manager.

Of the parameters listed, only the SHORTRTY, SHORTTMR, LONGRTY, LONGTMR, and MCATYPE parameters are used by the channel initiator.

 

 

 

Figure 5-14. Channel States MQ157.0

 

Notes:

 

• The current state of a channel can be determined by using the WebSphere MQ

command DISPLAY CHSTATUS.

 

• The visual shows the possible states of a channel and the possible flows from one state to the next.

When a channel is in one of the six highlighted states, it is consuming resource and is said to be active.

 

START is not really a state. It simply indicates a start point for when the START

CHANNEL command has been issued, or when a transmission queue has been

triggered, or when a channel initiator has decided it is time for another retry  attempt, or when there has been an incoming request to start a channel.

 

INITIALISING

 

A channel initiator is attempting to start a channel. This state only occurs on a Version 5 queue manager, such as Sun Solaris.

 

STARTING

 

A channel waits in this state if there is no active slot available. If there is an active slot immediately available, it remains in this state a very short time.

 

BINDING

 

Establishing a communications connection and performing the initial data exchange.

 

REQUESTING

 

A requester is waiting for callback from a sender.

 

RUNNING

 

Transferring messages, or waiting for messages to arrive on the transmission queue.

 

PAUSED

 

Waiting for the message-retry interval to complete before attempting to put a message on its destination queue.

 

STOPPING

 

An error has occurred, or the STOP CHANNEL command has been issued, or the disconnect interval has expired.

 

RETRYING

 

Waiting until it is time for the channel initiator to make the next attempt to start the channel.

 

STOPPED

 

In this state, the channel is disabled and needs manual intervention to start it again.

 

INACTIVE

 

An inactive channel is one that has never been started or has disconnected normally.

 

 

 

 5.2 The MQI in the Network

 

This topic describes several aspects of the MQI relating to its use in a network of queue managers.

 

• Application data conversion.

 

• Administration, with a particular emphasis on the concept of a "single point of  control" in a larger network.

 

• Detecting and reporting exceptions that require administrator attention.

 

 

Figure 5-15. Data Representation MQ157.0

 

 

 

Figure 5-16. Three Fields in the Message Descriptor MQ157.0

 

 

Figure 5-17. Requesting Application Data Conversion MQ157.0

 

Notes:

 

• No application data conversion is performed by default; it must be requested. It may be requested as follows.

 

- By using the MQGMO_CONVERT option on the MQGET call. This is the preferred approach on a queue manager that supports application data conversion.

- By specifying the parameter CONVERT(YES) on the channel definition at the

sending end of a message channel. This is a useful option if the remote queue

manager does not support application data conversion.

 

• The preferred approach can be described as receiver makes good. The optimal situation is for the application data in a message to be converted only once.

 

 

Figure 5-18. What Application Data Conversion Can Be Done? MQ157.0

 

Notes:

 

• crtmqcvx is the utility to help write a conversion exit.

 

• On WebSphere MQ for iSeries, the CL command corresponding to the control

command crtmqcvx is CVTMQMDTA.

 

 

 

Figure 5-19. Writing a Data Conversion Exit MQ157.0

 

Notes:

 

On WebSphere MQ for AIX, Compaq Tru64 UNIX, HP-UX, Linux, and Solaris the skeleton source file is called amqsvfc0.c. On MQSeries for AT&T GIS UNIX, Compaq OpenVMS Alpha, and SINIX and DC/OSc the skeleton file the skeleton source file is called  amqsvfcx.c.

 

On WebSphere MQ for Windows the data-conversion program should be stored in the Exits subdirectory below the WebSphere MQ data directory

C:\ProgramFiles\IBM\WebSphere MQ\Exits. The registry folder is:

HKEY_LOCAL_MACHINE\SOFTWARE\IBM\MQSeries\CurrentVSersion\Configuration\ClientExitPath\

On WebSphere MQ on UNIX systems and Compaq OpenVMS Alpha the data-conversion program default directory is; /var/mqm/exits On WebSphere MQ for iSeries the data-conversion exit programs should be stored in the QSYS library.

 

 

Figure 5-20. How a Data Conversion Exit Is Used MQ157.0

 

Figure 5-21. What Applications Should Do MQ157.0

 

Figure 5-22. Command Server MQ157.0

 

Notes:

 

• Related control commands are as follows.

endmqcsv Ends the command server.

dspmqcsv Displays the status of the command server.

 

• On WebSphere MQ for iSeries, the corresponding CL commands are:

- STRMQMCSVR, Start MQM Command Server

- ENDMQMCSVR, End MQM Command Server

- DSPMQMCSVR, Display MQM Command Server

 

• On MQSeries for Tandem NonStop Kernel, as an alternative to using the control command strmqcsv, you may use the command server which is configured in the TS/MP server class MQS-CMDSERV00 and start it by using the PATHCOM commands THAW SERVER and START SERVER. Full details of this option can be found in the MQSeries for Tandem NonStop Kernel System Management Guide.

 

• WebSphere MQ for z/OS has a system-command input queue which is monitored by a command server. However, the command server only accepts messages containing WebSphere MQ commands. PCF commands are not supported by WebSphere MQ for z/OS.

 

 

Figure 5-23. Support for PCF Commands MQ157.0

 

Notes:

 

On WebSphere MQ for Windows, AIX, iSeries, Linux, HP-UX, and Solaris and MQSeries for OS/2 Warp support the WebSphere MQ Administration Interface (MQAI). The MQAI is a programming interface to WebSphere MQ that gives you an alternative to the MQI, for sending and receiving PCFs. The MQAI uses data bags which allow you to handle properties (or parameters) of objects more easily than using PCF messages.

 

The MQAI allows you implement self-administering applications and administration tools. An example, the Active Directory Service (ADSI) provided on Windows V5.3. MQAI makes error handling simpler.

 

The WebSphere MQ Programmable Command Formats and Administration Interface describes these functions and their implementation in detail.

 

 

Figure 5-24. Program Example MQ157.0

 

Notes:

 

• The visual describes a utility to purge any queues that have existed beyond their retention interval. A summary of the logic is as follows.

 

  1. Put the MQCMD_INQUIRE_Q command on the command queue.

- The command may either specify the name of a queue or specify a generic queue name in order to inquire about multiple queues.

- The command server responds for each queue that matches the request.

 

2. Get the response for each queue found. Each response contains the values of thefollowing attributes.

 

QName

RetentionInterval

CreationDate

CreationTime

 

3. For each expired queue, put an MQCMD_DELETE_Q command on the command queue.

-The command server deletes the "expired" queues.

 

 

Figure 5-25. Indirect Mode MQ157.0

 

Notes:

 

• The parameter -w WaitTime specifies the indirect mode of using runmqsc. The value of WaitTime is the time in seconds that runmqsc should wait for replies.

 

• Using the indirect mode, you can send an WebSphere MQ command to any queue manager with a command server which accepts PCF commands.

 

You can also send WebSphere MQ commands to an MVS/ESA queue manager by using the -x parameter in conjunction with the -w parameter.

 

 

Figure 5-26. Instrumentation Events MQ157.0

 

Notes:

 

• Instrumentation events are enabled by attributes. Threshold queue depths, like

QDEPTHHI, are specified as a percentage of MAXDEPTH.

 

DEFINE QLOCAL(X) MAXDEPTH(2000) QDEPTHHI(90) QDPHIEV(ENABLED)

ALTER QMGR PERFMEV(ENABLED)

 

• On MQSeries for Tandem NonStop Kernel, a queue manager may generate Event Management Service (EMS) event messages that correspond to instrumentation events, entries in the error logs, and FFST reports. The value of the PARAM MQEMSEVENTS determines which EMS event messages are generated. By default, no EMS event messages are generated. For more details, consult the MQSeries for Tandem NonStop Kernel System Management Guide.

 

• Configuration events are available only on WebSphere MQ for z/OS.

 

Figure 5-27. Responding to an Instrumentation Event MQ157.0

 

 

 

Figure 5-28. Dead Letter Queue MQ157.0

 

Notes:

• When a problem relating to a message is detected asynchronously, an exception report is generated if one has been requested and the report is sent to the specified reply-to queue. The Feedback field in the message descriptor of the report message indicates the reason for the report. The original message is put on the dead letter queue unless MQRO_DISCARD_MSG is requested as a report option.

 

• If a message cannot be delivered, it is put on the dead letter queue at the  receiving end of a message channel, if one is defined.

 

Message-retry at the receiving end of a channel may be useful if the problem is only temporary.

 

• If CONVERT(YES) is specified in the channel definition at the sending end of a

message channel and a message cannot be converted, the message is put on the dead letter queue at the sending end.

 

• If a message cannot be put on the dead letter queue, the channel is stopped and the message remains on the transmission queue. A fast nonpersistent message, however, is just discarded in these circumstances and the channel remains open.

 

Figure 5-29. Dead Letter Queue Handler MQ157.0

 

Notes:

 

The implementation of the dead letter handler is covered in detail in the WebSphere MQ Advanced System Administration course (MQ30).

 

Figure 5-30. Using Dead Letter Queues MQ157.0

 

Notes:

 

Remember that creating means to define the queue and to tell the queue manager the name of its dead letter queue.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

5.3 WebSphere MQ Clusters

 

 

Figure 5-31. What Is a Cluster? MQ157.0

 

Notes:

 

• A cluster is a collection of queue managers that may be on different platforms, but typically serve a common application.

 

• Every queue manager can make the queues that they host available to every other queue manager in the cluster, without the need for (remote) queue definitions.

 

• Cluster specific objects remove the need for explicit channel definitions and

transmission queues for each destination queue manager.

 

• The queue managers in a cluster will often take on the role of a client or a server. The servers will host the queues that are available to the members of the cluster, also running applications that process these messages and generate responses. The clients PUT messages to the servers queues and may receive back response messages.

 

• Queue managers in a cluster will normally communicate directly with each other, although typically, many of the client systems will never have a need to communicate with other client systems.

 

Figure 5-32. Cluster Support Objects MQ157.0

 

Notes:

 

• Cluster Repository (Queue)

 

- A collection of information about the queue managers that are members of a cluster, including queue manager names, their channels, the queues they host and so forth.

- This repository information is exchanged through a queue called

SYSTEM.CLUSTER.COMMAND.QUEUE and stored on a queue with the fixed name  SYSTEM.CLUSTER.REPOSITORY.QUEUE.

- Repositories may be full or partial - more about this on the next foil. Each cluster queue manager must have at least one connection to another queue manager that owns a full repository.

 

• Cluster-sender channel

- A channel definition of the TYPE(CLUSSDR) on which a cluster queue manager can send messages to another queue manager in the cluster that holds a full repository.

This channel is used to notify the repository of any changes of the queue manager's status, for example the addition or removal of a queue. It is only used for the initial contact with the first full repository queue manager. From this one the local queue manager learns whatever it needs to know.

- Note: Application messages will be sent by auto-defined sender channels that are created during operation based on repository information from other cluster queue managers.

 

• Cluster-receiver channel

 

- A channel definition of the TYPE(CLUSRCVR) on which a cluster queue manager can receive messages from within the cluster. Through the definition of this object a queue manager is advertised to the other queue managers in the cluster, thus enabling them to auto-define their appropriate CLUSSDR channels for this queue manager.

You need at least one cluster-receiver channel for each cluster queue manager.

 

• Cluster transmission queue

- All the messages from the queue manager to any other queue manager in the

cluster are locally put to this queue named SYSTEM.CLUSTER.TRANSMIT.QUEUE.

It must exist in each cluster queue manager.

 

• Cluster Queue

- A cluster queue manager is a queue that is hosted by by a cluster queue manager and made available to other queue managers in the cluster. The local queue is either preexisting or created on the local queue manager and to play a role in the cluster the local queue definition specifies the cluster name of the definition. The other queue managers can see this queue and use it to put messages to it without the use of remote queue definition. The cluster queue can be advertised in more than one cluster.

 

• SYSTEM.CLUSTER.COMMAND.QUEUE

- Each queue manager in a cluster had a local queue called

SYSTEM.CLUSTER.COMMAND.QUEUE. This queue is used to carry messages to the full repository. The queue manager uses this queue to send any new or changed information about itself to the full repository queue manager and to send any request for information about queue managers.

 

Figure 5-33. More About Repositories MQ157.0

 

Notes:

 

• Each cluster queue manager has to have a local queue called

SYSTEM.CLUSTER.REPOSITORY.QUEUE where all cluster related information is

stored.

 

• At least one (but for availability reasons preferably two or more) cluster queue

managers have to hold full repositories; that means a complete set of information about every queue manager in the cluster.

 

• For each cluster queue manager, a cluster-sender channel has to be predefined that connects to one of the repository queue managers.

 

• Repository queue managers (sometimes simply called repositories) must be fully interconnected with each other and positioned in the network so as to give a high level of availability.

 

• Normal queue managers build up and maintain a partial repository that contains

information about those queue managers and queues that are of interest to it. This information may be updated and extended during operation through inquiries of a full repository.

 

Figure 5-34. Setting Up a Cluster MQ157.0

 

Notes:

 

The above example is for definitions required on QM1.

 

• The definitions of the cluster transmission and command queues are not shown; they are not associated to a specific cluster by definition.

 

• QM1 is made a full repository queue manager for the cluster named EDUC by the ALTER QMGR REPOS(clustername) command.

 

• A queue manager may be associated to more than one cluster at time . The same is true for queues and channels.

- In this case a NAMELIST object has to be created. with multiple cluster names as single entries.

- Then with all DEFINE commands, the name of this namelist has to be referenced instead of the cluster name, and the REPOS attribute of the ALTER QMGR command changes to REPOSNL.

 

• Note that this full repository is pointing to another repository associated with the cluster EDUC.

 

 

Figure 5-35. DHCP Support in Clusters MQ157.0

 

Notes:

 

WebSphere MQ V5.2 and later includes two enhancements pertaining to the use of clusters.

 

• A cluster-receiver channel can be defined without specifying the queue managers network address. When no CONNAME is defined and TCP/IP is used, WebSphere MQ generates a CONNAME, assuming the default port and using the current IP address of the system.

 

This facility is useful when the systems in the cluster use Dynamic Host Configuration Protocol (DHCP).

 

• A cluster-sender channel can be defined without specifying the name of the repository queue manager.

When the naming conventions used for channels in the cluster includes the name of the queue manager, a CLUSSDR definition can use the +QMNAME+ construction.

 

WebSphere MQ substitutes the correct repository queue manager name in place of +QMNAME+.

V2.0

The above example is for definitions required on QM1.

 

Figure 5-36. Multiple Queue Occurrence - Workload Balancing MQ157.0

 

Notes:

• Cluster support allows more than one queue manager to host an occurrence of the same queue. Thus, two or more queue managers may be clones of each other, capable of running the same applications and having local definitions of the same queues.

There may be two reasons for doing this:

- To increase the capacity available to process messages.

- To introduce an ability to failover work from one server to another and improve

availability of the service.

 

• This can be used to spread the workload between queue managers, if applications allow it to do so.

 

• A built-in workload management algorithm determines the remote queue manager if there are multiple choices, based on availability and channel priorities. A local occurrence always takes precedence.

 

• You may supply your own cluster workload exit and activate it by use of the ALTER QMGR command, as shown above.

 

Figure 5-37. Workload Balancing - Rerouting MQ157.0

 

Notes:

• The cluster workload exit (built-in or user supplied) is called

 

- either when a cluster queue is opened by an MQOPEN or MQPUT1 call

- or when a message is put to a queue using MQPUT.

 

• If the target queue manager chosen at the time of an MQPUT call is unavailable, or fails while the message is still on the transmission queue, the exit is called again to select a new target queue manager.

 

• The queue attribute DEFBIND determines whether or not rerouting will be performed while a queue is opened:

DEFBIND(NOTFIXED)

 

behaves as shown above, with a round-robin distribution of messages to all available TARGET.Qs in the cluster.

 

DEFBIND(OPEN)

the destination queue is selected at MQOPEN time and will not be changed until MQCLOSE.

 

This attribute may be overwritten by the application using appropriate Open Options.

 

• Make sure that all of the instances of the queue have the same priority, default

persistence and defbind values.

 

Figure 5-38. Cluster-Related Queue Manager Attributes MQ157.0

 

Notes:

 

• The list shows the attributes of a queue manager that can be altered to change some cluster management options. You can:

 

- In the repository management section, specify the name of a single cluster or of a cluster namelist for which this queue manager is to provide repository manager

services.

- Determine the name of an optional user exit program that customizes auto-definition of cluster sender channels.

- Determine the name of the cluster workload exit program that will be called

whenever a message is put to a cluster queue.

- Specify a 32-character data string and/or the maximum bytes of message data that can be passed to the workload exit.

 

Figure 5-39. Controlling Clusters - Cluster Commands MQ157.0

 

Notes:

 

SUSPEND QMGR

 

Removes a queue manager from a cluster temporarily, which means that the workload management exit will not route any messages to this qmgr. All information about a suspended queue manager and its objects are preserved in the repositories, but the qmgr is marked suspended.

This function may be used if a queue manager has to be taken down for maintenance.

 

RESUME QMGR     Reinstates a suspended queue manager.

 

REFRESH CLUSTER        Discards all locally held information about a cluster (includingauto-installed channels that are in-doubt) and thus enforces a cold start of this queue manager in that cluster. This command should not be used for regular operation.

 

RESET CLUSTER                        

 

Can only be issued by a repository queue manager and forces a named queue manager off the cluster in the way that all (other) queue managers in the cluster are informed that this queue manager is no longer a part of the cluster.

 

RESET CLUSTER (clustername)

QMNAME(qmname) ACTION(FORCEREMOVE) QUEUES(NO)

or the command:

RESET CLUSTER (clustername)

QMID(qmid) ACTION(FORCEREMOVE) QUEUES(NO)

You cannot specify both QMNAME and QMID.

 

 

Figure 5-40. Controlling Clusters - DISPLAY CLUSQMGR MQ157.0

 

Notes:

 

The DISPLAY CLUSMGR command returns cluster information about queue managers in a cluster which is stored in the local SYSTEM.CLUSTER.REPOSITORY.QUEUE.

 

Definition Type may be:

 

CLUSSDR    as a cluster-sender channel from an explicit definition

CLUSSDRA             as a cluster-sender by auto-definition

CLUSSDRB             as a cluster-sender channel, both from an explicit definition and by

auto-definition

CLUSRCVR             as a cluster-receiver channel.



Figure 5-41. Cluster-Related Queue Considerations MQ157.0

 

Notes:

 

• The CLUSINFO option of the DISPLAY QUEUE command identifies the queue hosting queue manager.

 

• Principally, all types of queues may be defined as cluster queues, and as a

consequence, be advertised to all queue managers in the cluster, just as for local

queues.

 

- Alias Queues may be made available to the cluster simply by adding the CLUSTER keyword to the definition.

 

- Queue Manager Aliases advertised to the cluster may be of the same value as for traditional distributed queueing.

 

- Remote Queues are not intended to be advertised to a cluster - because one of the benefits of clusters is that Remote Queue definitions are no longer required. Remote Queues, however, can have a cluster attribute. They can be used to attach a queue manager that does not support clustering.

 

- Model Queues (and hence temporary dynamic queues) cannot have a cluster

attribute.

 

• Effect of altering queue definitions:

- ALTER QUEUE(XXX) PUT(INHIBITED) will stop messages being put to that

instance of a queue and also mark it as being put inhibited throughout the cluster. If applicable, this will cause messages to be sent to other instances of the queue.

- ALTER QUEUE(XXX) CLUSTER(' ') will take a queue out of its clusters and stop other queue managers from sending messages to it but still allow messages to be put to it from the local queue manager.

 

 

 

Checkpoint

 

Unit 5 Checkpoint

 

1. T/F NPMSPEED(FAST) is a parameter on a SENDER channel that causes the message channel agent to use MQGMO_SYNCPOINT_IF_PERSISTENT.

2. If the SEQWRAP value on a  ENDER channel is different from the value on the RECEIVER, what will happen?

 

a. They negotiate to the lower value at channel startup time.

b. The channel will not start.

c. They negotiate to the higher value at channel startup time.

d. Nothing - this is controlled at the SENDER; RECEIVER can

not specify SEQWRAP.

e. The value from the SENDER definition takes precedence.

3. A sender channel is defined in a script file with REPLACE. The runmqsc control command is run using this script while the channel is active.

a. The channel will fail and won't restart without intervention.

b. The active channel will not be affected by this.

c. Because the channel is active, this command will no beexecuted.

d. The channel will fail and any in-transmit messages will be lost.

4. T/F A queue manager can become part of a cluster and messages will flow to its queues as soon as it is altered to show the name of the cluster it belongs to.

 

Figure 5-42. Unit Summary MQ157.0

 

Notes:

 

This unit described how to configure WebSphere MQ for distributed queuing and there was a practical exercise in getting messages to flow between queue managers. We also discussed other aspects of WebSphere MQ administration in a network, viz application data conversion, remote administration, nstrumentation events, reports, and the dead letter queue.

Finally, for WebSphere MQ V5 queue managers, you were able to complete an exercise that set up a simple cluster and observe the capabilities of this function.

V2.0

 

 

 

 

 

 

 

 

 

 

 

Unit 6. More on Distributed Queuing

 

 

What This Unit is About

 

This unit describes further aspects of distributed queuing.

 

• WebSphere MQ Family SupportPacs

• WebSphere MQ clients

• Security

 

What You Should Be Able to Do

 

After completing this unit, you should be able to:

 

• Describe how to install and configure an WebSphere MQ client

• Identify the security features of WebSphere MQ

• Describe how message context fields and options can be used as

a component of application security

• Describe how Secure Sockets Layer works

• Distinguish one channel exit from another

 

How You Will Check Your Progress

 

Accountability:

 

• Checkpoint questions

• Machine exercises

• Classroom discussions

 

References

SC34-6068 WebSphere MQ System Administration Guide

SC34-6055 WebSphere MQ Script (MQSC) Command Reference

If iSeries:

SC34-6070 WebSphere MQ for iSeries V5.3 System Administration Guide

 

Figure 6-1. Unit Objectives

 

Notes:

 

You will learn where WebSphere MQ clients are supported, how to install and configure them, and where they are best used.

WebSphere MQ offers security features that make the product robust enough for use in a complex production system. In addition, extensions are provided where additional capabilities are desired (for example, SSSL, exits and installable services). You will learn about the various capabilities and how they are implemented.

 

 

 

 6.1 WebSphere MQ Family SupportPacs

 

This topic describes the WebSphere MQ Family SupportPacs which contain material that can enhance the usage of the WebSphere MQ.

 

 

Figure 6-2. Overview of SupportPacs

 

Notes:

WebSphere MQ Family SupportPacs can be found at the following Web address:

www.ibm.com/software/ts/mqseries/txppacs

 

Figure 6-3. Example: MD01

 

Notes:

 

This SupportPac is designed to provide a common base from which all WebSphere MQ personel, like System Administrators, Application Developers, can work.

 

 


Figure 6-4. Example: MO01

 

Notes:

 

This SupportPac contains three utilities, an event queue monitor, a dead letter queue monitor, and a program to remove expired messages. The SupportPac only contains executable code for the AIX and OS/2 Warp platforms. However, it also provides sample source code which could be ported to a variety of other platforms.

 

Event queue monitor

 

This waits on an event queue and alerts the user when an event message

has arrived on the queue. It writes the contents of the message to the standard output device in a readable form. The source code is a useful example of how to parse event messages whose format is based on that of PCF commands.

 

Dead letter queue monitor

 

This waits on the dead letter queue and alerts the user when a message has arrived on the queue. It writes the dead letter header to the standard output device in a readable form. The source code is a useful example of how to read a dead letter header.

 

V2.0

Expired message remover

 

This browses every message that exists within a queue manager so that any message whose expiration time has elapsed is removed. This is useful for keeping queue storage under control and the source code is a good example of how to obtain information from the command server.

 

 

Figure 6-5. Example: MS03

 

Notes:

 

• This SupportPacs provides a utility that allows you to save current queue manager and object definitions in a file, which can be used to recreate the objects.

 

• All objects (queue manager, queue, process, and channel) are supported.

 

6.2 WebSphere MQ Clients

 

Some platforms, without having a queue manager configured on them, can operate as an WebSphere MQ client. This topic describes the configuration and operation of WebSphere MQ clients.

 

 

Figure 6-6. WebSphere MQ Client

 

Figure 6-7. WebSphere MQ Clients Explained

 

Notes:

 

• The full range of MQI calls and options is available to a WebSphere MQ client

application, including the following.

 

- The use of the MQGMO_CONVERT option on the MQGET call. This causes theapplication data of the message to be converted into the numeric and character representation in use on the client system. The server queue manager provides the usual level of support to do this.

- A client application may be connected to more than one queue manager simultaneously. Each MQCONN call to a different queue manager returns a

different connection handle. This does not apply if the application is not running as a WebSphere MQ client.

 

• The MQI stub which is linked with an application when running as a client is different from that used when the application is not running as a client. An application will receive the reason code MQRC_Q_MGR_NOT_AVAILABLE on an MQCONN call if it is linked with the wrong MQI stub.

 

Figure 6-8. Syncpoint Control

 

Notes:

 

A WebSphere MQ client application may participate in a local unit of work involving the resources of the queue manager it is connected to. To do this, it uses the MQCMIT and MQBACK calls in the normal way.

 

A WebSphere MQ client application cannot however participate in a global unit of work. Such an application may issue calls to another resource manager or syncpoint coordinator, on the same system as the application or on another system, and may participate in a unit of work associated with that resource manager or syncpoint coordinator. At the same time, it may also be participating in a local unit of work involving the resources of the queue manager it is  connected to. In which case, the two units of work are completely independent of each other.

 

Figure 6-9. Installation

 

Notes:

• Each Version 5 product supplies a WebSphere MQ Client CD-ROM which contains the software, including an easy installation feature, for clients on the following platforms.

 

• These platforms also include Java client except the Linus platform.

- AIX

- HP-UX

- Linus

- OS/2 Warp

- Solaris

- Windows

• MQSeries for Compaq OpenVMS and WebSphere MQ on UNIX systems other than AIX, HP-UX, and Sun Solaris include the files for the desktop clients and for a client on the same platform as the server platform. The desktop clients are for DOS, OS/2 Warp, and Windows 3.1.

 

• Most WebSphere MQ products supply files for clients on the same platform as the server and for clients on other platforms. WebSphere MQ for iSeries, z/OS and  MQSeries for Compaq Tru64 UNIX and VSE/ESA can supply files for clients on other platfroms only.

 

Figure 6-10. Defining a MQI Channel MQ157.0

 

Notes:

 

• MQI channels do not have to be started. Just run the client application which calls a MQCONN or MQCONNX.

 

• A MQI channel can be used to connect a client to a single queue manager , or to a queue manager that is part of a queue-sharing group.

 

• Do not forget to configure and refresh the inet daemon, or to start the WebSphere MQ listener, on the server system.

 

 

 

Figure 6-11. Two Ways of Configuring an MQI Channel

 

Notes:

 

• Method 1 is the easier of the two methods setting up a client. On the server, you use the DEFINE CHANNEL command to define a server connection. On the client system, you define a simple client connection by setting the environment variable MQSERVER to the following value:

ChannelName/TransportType/ConnectionName

For example, on DOS, OS/2 Warp, Windows, Windows 3.1, or Windows 95:

SET MQSERVER=VENUS.SVR/TCP/9.20.4.56

For example on a UNIX system:

export MQSERVER=VENUS.SVR/TCP/'9.20.4.56'</