MQ15 - WebSphere MQ System Administration I

WebSphere MQ
System Administration I for

Distributed Platforms
(Course Code MQ15)
Instructor Guide
ERC 7.0
IBM Certified Course Material

V1.2.2.2
cover
Instructor Guide
The information contained in this document has not been submitted to any formal IBM test and is distributed on an as is basis without
any warranty either express or implied. The use of this information or the implementation of any of these techniques is a customer
responsibility and depends on the customers ability to evaluate and integrate them into the customers operational environment. While
each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will
result elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk.
Copyright International Business Machines Corporation 1996, 2003. All rights reserved.
This document may not be reproduced in whole or in part without the prior written permission of IBM.
Note to U.S. Government Users Documentation related to restricted rights Use, duplication or disclosure is subject to restrictions
set forth in GSA ADP Schedule Contract with IBM Corp.
Trademarks
IBM is a registered trademark of International Business Machines Corporation.
The following are trademarks of International Business Machines Corporation in the United
States, or other countries, or both:
Intel is a trademark of Intel Corporation in the United States, other countries, or both.
Linux is a registered trademark of Linus Torvalds in the United States and other countries.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft
Corporation in the United States, other countries, or both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product and service names may be trademarks or service marks of others.
AIX AS/400 BookManager
CICS DYNIX/ptx Everyplace
FFST First Failure Support
Technology
IBM
IMS iSeries Lotus
Lotus Notes MQSeries MVS/ESA
NetView Notes OS/2
OS/390 OS/400 QMF
RACF SP2 SupportPac
ThinkPad TXSeries VSE/ESA
WebSphere WIN-OS/2 z/OS
zSeries
February 2003 Edition
Instructor Guide
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Copyright IBM Corp. 1996, 2003 Contents iii
V1.2.2.2
TOC
Contents
Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Instructor Course Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Course Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Agenda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Unit 1. A Review of WebSphere MQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Unit Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
1.1 Facilities and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
WebSphere MQ - Commercial Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Further Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Message and Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Applications Enabled by WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15
MQI Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Message Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Asynchronous Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
Triggering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-25
Parallel Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-27
Client/Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-29
Assured Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-31
Connectionless Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-33
Queue Manager Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-36
Distributed Queue Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-38
Message Driven Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-41
Separate Processes as Units of Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-43
Multiple, Asynchronous Units of Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-45
Message Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-47
1.2 WebSphere MQ Products and Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-49
WebSphere MQ Queue Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-50
WebSphere MQ Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-54
WebSphere MQ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-56
WebSphere MQ Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-59
Unit Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-64
Unit 2. Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Unit Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
2.1 Planning an WebSphere MQ Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Naming WebSphere MQ Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Special Local Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
Instructor Guide
iv WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
Message Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17
Administration Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20
WebSphere MQ Windows Administration Interfaces . . . . . . . . . . . . . . . . . . . . . . .2-24
2.2 Configuring a Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-30
Create Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-33
Start Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-36
WebSphere MQ MQSC Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-39
Run WebSphere MQ Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-42
Creating a Local Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-45
Displaying Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-48
Other Queue Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-51
More WebSphere MQ Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-54
Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-56
End Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-59
Unit Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-64
Unit 3. The MQI and Triggering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Unit Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
3.1 The MQI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6
Common Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-8
Object Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-10
Connecting and Disconnecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-12
Opening and Closing an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-15
Dynamic Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18
Put Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-20
Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-23
Get Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-25
Reply-to Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-28
More Fields in the Message Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-30
Message and Correlation Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-32
Retrieving Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-35
Order of Retrieving Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-37
Message Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-40
Message Segmentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-43
Distribution List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-46
3.2 Triggering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-49
Components of Triggering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-50
Queue Attributes Controlling Triggering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-52
Process Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-55
Conditions for a Trigger Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-57
Other Conditions for a Trigger Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-59
Fields in the Trigger Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-61
Trigger Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-64
Trigger Monitor Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-67
3.3 WebSphere MQ Publish/Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-69
Instructor Guide
Copyright IBM Corp. 1996, 2003 Contents v
V1.2.2.2
TOC
WebSphere MQ Publish/Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-70
Installing WebSphere MQ Publish/Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-73
Setting Up the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-75
Controlling the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-78
Message Broker Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-81
Unit Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-84
Unit 4. Robust Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Unit Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
4.1 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Functional View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Physical View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
WebSphere MQ Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
MQS.INI Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
Queue Manager Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26
QM.INI Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-29
Installable Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-31
Installable Services and Supplied Components . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33
Stopping a Queue Manager Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36
Removing a Queue Manager Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39
4.2 Problem Determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-43
Configuration Files and Problem Determination . . . . . . . . . . . . . . . . . . . . . . . . . . 4-44
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-46
First Failure Support Technology (FFST) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-49
Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-52
4.3 Transactions and Recovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-55
Message Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-56
Types of Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-58
Recovering Persistent Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60
Damaged Objects and Media Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-62
Dumping the Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-64
Syncpoint Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-66
Compensating Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-68
Coordinating Local Units of Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-70
Internal Coordination of Global Units of Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-72
Database Coordination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-74
External Coordination of Global Units of Work . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-77
CICS Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-80
Independent Coordination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-82
Unit Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-86
Unit 5. Distributed Queue Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Unit Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
5.1 Configuration for Distributed Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Instructor Guide
vi WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
Identifying a Queue in the MQI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-8
Assured Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-10
Queue Definitions for Distributed Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-12
Message Channel Combinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-14
Attributes of a Message Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-16
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-19
Choosing a Transmission Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-21
Queue Manager Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-23
Separating Message Flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-25
Configuring TCP/IP for WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-27
Starting a Message Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-31
Channel Initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-34
Channel States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-38
5.2 The MQI in the Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-41
Data Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-42
Three Fields in the Message Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-44
Requesting Application Data Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-46
What Application Data Conversion Can Be Done? . . . . . . . . . . . . . . . . . . . . . . . .5-48
Writing a Data Conversion Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-50
How a Data Conversion Exit Is Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-52
What Applications Should Do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-54
Command Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-56
Support for PCF Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-59
Program Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-61
Indirect Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-64
Instrumentation Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-66
Responding to an Instrumentation Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-69
Dead Letter Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-71
Dead Letter Queue Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-74
Using Dead Letter Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-76
5.3 WebSphere MQ Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-79
What Is a Cluster? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-80
Cluster Support Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-82
More About Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-85
Setting Up a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-88
DHCP Support in Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-90
Multiple Queue Occurrence - Workload Balancing . . . . . . . . . . . . . . . . . . . . . . . . .5-93
Workload Balancing - Rerouting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-95
Cluster-Related Queue Manager Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-98
Controlling Clusters - Cluster Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-100
Controlling Clusters - DISPLAY CLUSQMGR . . . . . . . . . . . . . . . . . . . . . . . . . . .5-103
Cluster-Related Queue Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-105
Unit Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-110
Unit 6. More on Distributed Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Unit Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-2
6.1 WebSphere MQ Family SupportPacs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Instructor Guide
Copyright IBM Corp. 1996, 2003 Contents vii
V1.2.2.2
TOC
Overview of SupportPacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
Example: MD01 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Example: MO01 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
Example: MS03 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14
6.2 WebSphere MQ Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
WebSphere MQ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18
WebSphere MQ Clients Explained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20
Syncpoint Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24
Defining a MQI Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-28
Two Ways of Configuring an MQI Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
Channel Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34
Auto-Definition of Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37
6.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-39
WebSphere MQ Security Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-40
WebSphere MQ Access Control Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-42
Object Authority Manager: Installable Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-45
Object Authority Manager: Installable Service... . . . . . . . . . . . . . . . . . . . . . . . . . . 6-48
Object Authority Manager: Access Control Lists... . . . . . . . . . . . . . . . . . . . . . . . . 6-50
Object Authority Manager: The MQSeries 5.2 update . . . . . . . . . . . . . . . . . . . . . 6-52
Object Authority Manager V5.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-54
Security Management: setmqaut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-56
Security Management: dspmqaut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-59
Security Management: dmpmqaut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-61
Access Control for WebSphere MQ Control Programs . . . . . . . . . . . . . . . . . . . . . 6-63
Authority Checking in the MQI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-65
Security and Distributed Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-67
Message Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-69
The Context Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-71
No Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-75
Passing Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-77
Alternate User Authority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-79
Setting Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-81
Channel Exit Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-83
Channel Exit Programs on MQI Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-88
Secure Sockets Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-90
SSL Handshake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-92
SSL Handshake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-94
SSL Handshake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-96
SSL Handshake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-98
SSL Handshake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-100
SSL Handshake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-102
QMGR Attributes for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-104
QMGR Authentication Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-106
Channel Attributes for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-108
Access Control for an WebSphere MQ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-110
Remote Queueing and Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-112
Instructor Guide
viii WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
Supplied Channel Exit Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-114
Unit Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-118
Unit 7. WebSphere MQ for Windows (optional) . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Unit Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2
7.1 WebSphere MQ for Windows (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-6
Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-8
Family Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-10
Channel Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-13
Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-16
Dial-up Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-19
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-22
Administration on Version 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-25
Administration on Version 2.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-29
Supported WebSphere MQ Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-33
Initialization (INI) File on Version 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-36
MQSeries Definition (MQD) File on Version 2.1 . . . . . . . . . . . . . . . . . . . . . . . . . . .7-39
Example of an MQD File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-42
Unit Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-46
Appendix A. Checkpoint Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Appendix B. Selected WebSphere MQ Constants. . . . . . . . . . . . . . . . . . . . . . . . . B-1
Appendix C. Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
Appendix D. Glossary of terms and abbreviations . . . . . . . . . . . . . . . . . . . . . . . . D-1
Instructor Guide
Copyright IBM Corp. 1996, 2003 Trademarks xi
V1.2.2.2
TMK
Trademarks
The reader should recognize that the following terms, which appear in the content of this
training document, are official trademarks of IBM or other companies:
IBM is a registered trademark of International Business Machines Corporation.
The following are trademarks of International Business Machines Corporation in the United
States, or other countries, or both:
Intel is a trademark of Intel Corporation in the United States, other countries, or both.
Linux is a registered trademark of Linus Torvalds in the United States and other countries.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft
Corporation in the United States, other countries, or both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product and service names may be trademarks or service marks of others.
AIX AS/400 BookManager
CICS DYNIX/ptx Everyplace
FFST First Failure Support
Technology
IBM
IMS iSeries Lotus
Lotus Notes MQSeries MVS/ESA
NetView Notes OS/2
OS/390 OS/400 QMF
RACF SP2 SupportPac
ThinkPad TXSeries VSE/ESA
WebSphere WIN-OS/2 z/OS
zSeries
Instructor Guide
xii WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
Instructor Guide
Copyright IBM Corp. 1996, 2003 Instructor Course Overview xiii
V1.2.2.2
pref
Instructor Course Overview
This course is designed to teach the basic skills required by an
administrator for any of the WebSphere MQ Level 2 queue managers
except WebSphere MQ for z/OS. The course does not therefore apply
to the following queue managers.
WebSphere MQ for z/OS
The administration of this queue manager is the subject of the
course MQ20, WebSphere MQ for z/OS System Administration.
Course Strategy
The basic strategy for teaching the course is to use the material in the
order in which it is written. However, you may like to consider the
following variations.
The WebSphere MQ for Windows NT administrative functions can only
be used on the WebSphere MQ for Windows NT and Windows 2000
V5.1 or higher queue manager. Skip the charts referring to that
function if no NT is involved.
Many of the practical sessions can be done using WebSphere MQ for
Windows. In fact it is only practical for session 2 on triggering, the last
part of practical session 3, which is concerned with media recovery,
and the last portion of practical session 4 on clusters that cannot be
done using WebSphere MQ for Windows. If WebSphere MQ for
Windows is made available, and if there are students interested in
using it for the practical sessions, Unit 7 could be taught in a
piecemeal fashion at certain points throughout the course.
Instructor Guide
xiv WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
Instructor Guide
Copyright IBM Corp. 1996, 2003 Course Description xv
V1.2.2.2
pref
Course Description
WebSphere MQ System Administration I for Distributed Platforms
Duration: 3 days
Purpose
To provide the basic skills required by an administrator for any of the
MQSeries Level 2 queue managers except MQSeries for OS/390.
Specifically, the queue managers covered by this course are as
follows:
WebSphere MQ for AIX,V5.3
WebSphere MQ for iSeries
WebSphere MQ for HP-UX, V5.3
WebSphere MQ for Linux for Intel, V5.3
WebSphere MQ for Linus for zSeries, V5.3
WebSphere MQ for Solaris, V5.3 (SPARC and Intel Platform
Editions)
WebSphere MQ for Windows
MQSeries for Compaq OpenVMS Alpha
MQSeries for Compaq OpenVMS VAX
MQSeries for Compaq Tru64 UNIX
MQSeries for OS/2 Warp
MQSeries for SINIX and DC/OSx
MQSeries for Tandem NonStop Kernel
Audience
Technical personnel who require the skills to be an administrator for
any of the MQSeries Level 2 queue managers except WebSphere MQ
for z/OS, or to provide support to others performing this task.
Prerequisites
The course assumes a knowledge of WebSphere MQ to the level
covered by MQ01, A Technical Introduction to MQSeries. The
participant should also be reasonably familiar with, and be able to
invoke simple function within, the operating system environment used
for the practical exercises. A basic knowledge of how SNA LU6.2,
TCP/IP, or NetBIOS is configured would be advantageous.
Instructor Guide
xvi WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
Objectives
After completing this course, you should be able to:
Plan the implementation of WebSphere MQ on a selected platform
Install WebSphere MQ
Perform simple customization and administration tasks
Enable a queue manager to exchange messages with another
Enable a queue manager to support an WebSphere MQ client
Implement basic restart/recovery procedures
Perform basic problem determination
Contents
A Review of WebSphere MQ
Installation and Configuration
The MQI and Triggering
Robust Messaging
Distributed Queue Management
More on Distributed Queuing
WebSphere MQ Everyplace
In theory, the practical exercises may be done using any of the queue
managers covered by the course. In practice, however, the systems
used for a specific class will depend on the equipment available. The
exercise guide is tested for WebSphere MQ for Windows and for
WebSphere MQ on UNIX Systems.
Curriculum relationship
Course providing prerequisite knowledge:
- MQ01: A Technical Introduction to WebSphere MQ
Other WebSphere MQ courses:
- MQ05: WebSphere MQ Application Programming
- MQ20: WebSphere MQ for z/OS System Administration
- MQ30: WebSphere MQ Advanced System Administration
Instructor Guide
Copyright IBM Corp. 1996, 2003 Agenda xvii
V1.2.2.2
pref
Agenda
Day 1
(00:15) Welcome
(00:30) A Review of WebSphere MQ
(01:00) Installation and Configuration
(01:00) Exercise 1 - Working with queues
(02:00) The MQI, Triggering and Publish/Subscribe
(01:15) Exercise 2 - Implementing triggering
Day 2
(01:30) Robust Messaging
(00:45) Exercise 3 - Recovery
(02:15) Distributed Queue Management
(01:30) Exercise 4 - Distributed queuing
Day 3
(00:30) Queue Manager Clusters
(01:15) Exercise 5 - A simple cluster
(01:30) More on Distributed Queuing
(01:00) Exercise 6 - Implementing clients
(00:45) WebSphere MQ for Everyplace
Instructor Guide
xviii WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
Instructor Guide
Copyright IBM Corp. 1996, 2003 Unit 1. A Review of WebSphere MQ 1-1
V2.0
Uempty
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
Instructor Guide
1-2 WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
Figure 1-1. Unit Objectives MQ157.0
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.
Unit Objectives
Review WebSphere MQ concepts
Ensure students have necessary prerequisite knowledge
Establish goals of course
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To highlight the unit objectives.
Details In theory, all students should have attended the course MQ01, A Technical
Introduction to WebSphere MQ, before attending this one, and so this unit should merely
be a revision of previously acquired knowledge.
Transition Statement We start by looking at the benefits that WebSphere MQ can
provide.
Instructor Guide
Instructor Guide
V2.0
Uempty 1.1 Facilities and Functions
This topic provides an introduction to the facilities and functions of WebSphere MQ and
discusses the benefits they provide.
Instructor Topic Introduction
What students will do Students will listen to a review of the facilities and functions of
WebSphere MQ. For all students, it should simply be a revision of what was covered in the
course MQ01, A Technical Introduction to WebSphere MQ.
How students will do it No student activities are planned for this topic.
What students will learn Students will learn the benefits of WebSphere MQ and the
types of applications it can support.
How this will help students on their job This knowledge will help the students to
understand the reasons for selecting WebSphere MQ in the first place.
Instructor Guide
Figure 1-2. WebSphere MQ - Commercial Messaging MQ157.0
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
WebSphere MQ - CommerciaI Messaging
A
B
Q
u
e
u
e
Q
u
e
u
e
Common application programming interface
Assured message delivery
Time independent processing
Application parallelism
Faster application development
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To explain the principle of program to program communication through the use
of messages and queues, and to state the benefits of WebSphere MQ.
Details
Additional Information None.
Transition Statement Next we look at where we can find more information about
WebSphere MQ.
Instructor Guide
V2.0
Uempty
Figure 1-3. Further Information MQ157.0
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/
Further Information
WebSphere MQ publications
Many are cross-platform
For information that is common
For planning and implementing an WebSphere MQ network
Some are platform-specific
http://www.ibm.com/software/ts/mqseries/
Latest news
References
Beta code
SupportPacs
Instructor Guide
Instructor Notes:
Purpose To identify other sources of information about WebSphere MQ.
Details These notes alone don't contain all there is to know, and certainly not the latest
news.
Transition Statement Next we consider two basic questions. What is a message, and
what is a queue?
Instructor Guide
V2.0
Uempty
Figure 1-4. Message and Queue MQ157.0
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, the ability to store
a message safely is an important characteristic of a queue.
Message and Queue
A message is:
A unit of information
A request for a service
A reply
A report
An announcement
A queue is:
A safe place to store messages
Lined up for servicing
Staged for delivery
Instructor Guide
Instructor Notes:
Purpose To clarify what is meant by a message and a queue.
Details
Transition Statement Next we see that a wide range of applications can be built on these
simple concepts.
Instructor Guide
V2.0
Uempty
Figure 1-5. Applications Enabled by WebSphere MQ MQ157.0
Notes:
AppIications EnabIed by WebSphere MQ
Program-to-program communication for:
Message-driven processing
Client/server implementation
Distributed processing
Components of an application can run independently on different
systems and environments
Applications with several processing steps
Some fast
Some slow
Some not immediately available
No loss or duplication of information
Instructor Guide
Instructor Notes:
Purpose To explain how the basic concepts of WebSphere MQ can be applied to a wide
range of business applications.
Details The simple concepts of a message and a queue are not new. They are ones that
enable applications to work in many different ways. The components of an application can
run independently on different systems and environments, and may involve a number of
processing steps.
A key aspect of WebSphere MQ with respect to messages and queues is the assurance
against the loss or duplication of messages.
Transition Statement Next we introduce the concept of a queue manager, and the
application programming interface it provides to an application.
Instructor Guide
V2.0
Uempty
Figure 1-6. Queue Manager MQ157.0
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.
Queue Manager
A queue manager owns and manages queues
Family of application programming interfaces
The Message Queue nterface (MQ)
The Application Messaging nterface (AM)
The Java Message Service (JMS)
Program
MQ
Q1
Q2
Q3
Queue
Manager
Program
AM
Program
JMS
Instructor Guide
- 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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce the concept of a queue manager and the three APIs: The MQI,
the AMI and the JMS.
Details Having a common application programming interfaces across all supported
platforms is one of the major benefits of WebSphere MQ. We shall see later the platforms
which are supported.
Transition Statement Next we look a little more closely at the calls provided by the MQI.
Instructor Guide
Figure 1-7. MQI Calls MQ157.0
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
MQI CaIIs
You can send messages at one end ...
MQPUT
MQPUT1
... and they arrive reliably at the other
MQGET
Other calls
MQCONN, MQCONNX, and MQDSC
MQOPEN and MQCLOSE
MQNQ and MQSET
MQBEGN, MQCMT, and MQBACK
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To introduce the calls in the MQI.
Details The visual lists all the MQI calls. Sample programs illustrating their use are
supplied with WebSphere MQ.
Additional Information We shall discuss the MQI calls in a little more detail later. The
following references provide more information.
The Application Programming Reference describes each call in the MQI and, more
generally, defines the MQI.
The WebSphere MQ Application Programming Reference describes each call in the
MQI and, more generally, defines the MQI.
The WebSphere MQ Application Programming Guide describes all the samples
programs delivered With WebSphere MQ. It also provides the information required to
build an application.
Transition Statement Next we look at a simple application model and introduce the
message descriptor.
Instructor Guide
V2.0
Uempty
Figure 1-8. Message Descriptor MQ157.0
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.
Message Descriptor
Each message has a message descriptor
Application determines message content
Program B Program A
Q1
Q2
Message
descriptor
Application
data
Message
Instructor Guide
Instructor Notes:
Purpose To explain the basic conversational model, and to introduce the message
descriptor.
Details The simplest application model using messages and queues is depicted on the
visual. Program A puts a request message on queue Q1 and then waits for a reply to
appear on queue Q2 before continuing. Program B gets the message from queue Q1 and
puts the required reply message on queue Q2 to complete the process.
In the basic conversational model depicted on the visual, a message descriptor will
accompany the message that is put on queue Q1, and another will accompany the
message that is put on queue Q2.
Transition Statement The basic conversational model is a synchronous one. Next, we
shall look at an asynchronous version.
Instructor Guide
V2.0
Uempty
Figure 1-9. Asynchronous Model MQ157.0
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.
Asynchronous ModeI
Separate process for replies
No need for communicating programs to be
active at the same time
Time independence
Program B
Program A
Q1
Q2
Program X
Instructor Guide
Instructor Notes:
Purpose To explain the asynchronous model and how it leads to the benefit of time
independence.
Details Nothing in addition to the student notes.
Transition Statement Next we look at how triggering enhances the implementation of
time-independent processing.
Instructor Guide
V2.0
Uempty
Figure 1-10. Triggering MQ157.0
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.
Triggering
Triggering allows
nstantiation as required
Conservation of system resources
Automation of flow
Queue Manager
2
6
4
3
Application
Queue
nitiation
Queue
MQPUT A-Q
Program A
MQGET A-Q
MQGET -Q
Trigger Monitor
Program B
5
1
Process
Object
Instructor Guide
Instructor Notes:
Purpose To introduce the concept of triggering.
Details The previous example showed how Program A could continue running even
though its partner, Program B, was stopped. Of course, Program B must start some time.
Transition Statement Next we look at how WebSphere MQ allows parallel processing
within an application.
Instructor Guide
V2.0
Uempty
Figure 1-11. Parallel Processes MQ157.0
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.
ParaIIeI Processes
Requests not serialized
Shorter elapsed time
Consolidate replies
Possibly selective MQGET?
ncomplete set of replies?
Different process to handle replies?
MQPUT ADDR-Q
MQPUT BAL-Q
MQPUT CO-Q
MQGET Reply-to
queue
ADDR
BAL
CO
MQPUT
ADDR-Q
BAL-Q
CO-Q
MQPUT
Reply-to queue
MQPUT
Instructor Guide
Instructor Notes:
Purpose To explain how WebSphere MQ enables applications to be built in which units
of processing can be performed in parallel, and perhaps even on different systems.
Details A more complex application may involve sending a number of requests to
different servers. For example, a travel agent might use an application to arrange a trip for
a customer. The requirements of the customer might mean that the application needs to
make a number of requests - to make an airline reservation, to book a hotel room, to run a
credit check, and so forth.
By using queues, these steps don't have to be performed serially. The requests can be put
on different queues, and processed in parallel.
The application might then wait until it has received all the replies before preparing a
consolidated response. Alternatively, the business logic may define a time limit to wait for
the replies. In which case, the application may present some form of partial response with
limited information after that time has elapsed.
As we have seen previously, the application design may involve having a separate process
to receive and process the replies.
Transition Statement Next we look at how WebSphere MQ can be used to implement
client/server applications.
Instructor Guide
V2.0
Uempty
Figure 1-12. Client/Server MQ157.0
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.
CIient/Server
Queue = service
Message = request
Reply-to queue name in message
descriptor
Multiple instances of server
possible
nsurance
agent
nsurance
quotations
nsurance
data
Clients
Server
nsurance
agent
nsurance
agent
Instructor Guide
Instructor Notes:
Purpose To explain how a queue can be viewed as a service, and how multiple clients
can request the same service.
Details The previous examples have described how a single client application can put
messages on one or more queues in order to request the services of the applications
serving those queues.
In general, multiple applications may put messages on the same queue in order to request
the same service. The application serving the queue gets each message in turn and
responds to it.
The message descriptor of each request message plays an important role here. One of the
fields in the message descriptor is the name of the reply-to queue. This informs the server
application where to put the reply message. In this way, each client application can receive
its replies separately from those of the other client applications.
The message descriptor also has a field to hold an identifier for a message. Furthermore,
the message descriptor of a reply message can contain the identifier of the request
message to which it relates. In this way, a client application can correlate a reply with a
request it sent previously.
Transition Statement Next we look at the benefit of assured message delivery.
Instructor Guide
V2.0
Uempty
Figure 1-13. Assured Delivery MQ157.0
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.
Assured DeIivery
Transmission queue stores message first
Application not stopped if link is inactive
Program B
Program A
Q1
Q2
Qt
Qt
QM1 QM2
Instructor Guide
Instructor Notes:
Purpose To describe how WebSphere MQ stages the delivery of messages to a remote
queue manager through the use of a transmission queue, and to highlight the benefit of
assured delivery.
Details In many cases, communicating applications will reside on different systems.
These applications still communicate with each other using the MQI and they don't need to
know that they are remote from each other.
When an application opens a queue, it is the queue manager to which the application is
connected which recognizes whether the queue is local, that is, a queue it owns, or
whether the queue is remote, that is, a queue owned by another queue manager. If it is a
remote queue, the queue manager stores messages destined for that queue on a staging
queue called a transmission queue. By doing this, the application putting the messages
can continue to operate even if the communications link is down. Like any other queue, a
transmission queue stores messages securely until they can be processed.
Asynchronously and transparently to any applications connected to it, the queue manager
gets each message in turn from the transmission queue and transmits it to the remote
queue manager, which then places the message on its respective destination queue. It is
the protocol used by the two queue managers which ensures that no message is lost or
delivered more than once. This is the assured delivery property of WebSphere MQ, and is
one of the major benefits of WebSphere MQ.
In the example depicted on the visual, Program A puts a message on queue Q1. The
queue manager to which Program A is connected, QM1, knows that Q1 is a remote queue
and so puts the message on a transmission queue, Qt. Asynchronously, queue manager
QM1 transmits the message to queue manager QM2 which puts it on queue Q1. The
message then becomes available for Program B to get. When Program B puts a reply
message on queue Q2, the delivery of the message is likewise staged by the message
being stored on a transmission queue.
Transition Statement Next we look at how the WebSphere MQ approach to program to
program communication can be viewed as connectionless.
Instructor Guide
V2.0
Uempty
Figure 1-14. Connectionless Communications MQ157.0
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.
ConnectionIess Communications
Program C Program B
Q2
Qt
QM1 QM2
Program A Program D
Q1
Transmission queue header
Destination
queue name
Destination
queue manager
name
OriginaI
message
descriptor
AppIication
data
Message
descriptor
Instructor Guide
Instructor Notes:
Purpose To explain why program-to-program communication using WebSphere MQ can
be considered connectionless.
Details You don't have to have a separate transmission queue for every remote queue.
In the example depicted on the visual, Program A and Program B are both putting
messages on remote queues Q1 and Q2. But since the queues are owned by the same
queue manager, QM2, the queue manager to which Program A and Program B are
connected can use the same transmission queue.
Furthermore, only one communications connection is required between queue manager
QM1 and queue manager QM2. A communications connection is an SNA LU6.2
conversation, a TCP connection, and so on.
The implications of all this is as follows:
In order for multiple applications connected to one queue manager to communicate with
multiple applications connected to another queue manager, only one communications
connection between the two queue managers is required. Each pair of communicating
applications does not need its own communications connection. This is what is meant
by connectionless communications using WebSphere MQ.
Only requiring one transmission queue and one communications connection means
less administration.
If only one transmission queue and one communications connection are required, how
does queue manager QM2 know on which queue to put each message it receives?
The answer is as follows:
When queue manager QM1 puts a message on a transmission queue, it places a
transmission queue header in front of the application data. The transmission queue header
contains, among other things, the following information.
The name of the destination queue, for example, Q1 or Q2.
The name of the destination queue manager, for example, QM2.
The original message descriptor, that is, the one supplied by the application which put
the message.
Effectively, queue manager QM1 concatenates the transmission queue header with the
application data to form an extended version of the application data which has its own
message descriptor. It is this extended application data which is ultimately transmitted to
queue manager QM2.
When queue manager QM2 receives the extended application data, it is able to
reconstitute the original message descriptor and application data. And from the destination
queue name and destination queue manager name, queue manager QM2 is able to
determine on which destination queue the message should be put.
Instructor Guide
V2.0
Uempty
Transition Statement Next we look at how this means that applications are decoupled
from the network.
Instructor Guide
Figure 1-15. Queue Manager Network MQ157.0
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.
Queue Manager Network
Applications shielded from the network
MQPUT calls identical
No remote MQGET call
Undeliverable messages ?
Program C Program A
MQ
Program B
System 1 System 2
Queue
manager
Network
Q 1
Q 2
MQPUT Q2 MQPUT Q1 MQGET Q1 MQGET Q2
Queue
manager
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how the MQI shields applications, and application programmers,
from the complexities of the underlying network.
Details An application which puts a message on a queue using the MQI does not need
to be aware of whether the queue is local or remote. This and other properties of the MQI
mean that the detail and complexities of the underlying network are hidden from
applications and their programmers.
The visual depicts two examples.
Program A puts two messages, one on a local queue Q1 and one to a remote queue
Q2. The two MQPUT calls it uses to do this are essentially identical.
Program B gets a message from queue Q1 and Program C gets a message from queue
Q2. Again, the two MQGET calls are essentially identical and in no way depend on
where the respective messages originated. Note, however, that an application can only
use an MQGET call to get a message from a local queue.
With WebSphere MQ, all the communications programming and error handling has been
done for you.
Transition Statement Next we look in a little more detail at how messages are
transmitted from one queue manager to another.
Instructor Guide
Figure 1-16. Distributed Queue Management MQ157.0
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.
Distributed Queue Management
Transmission
queue
Destination
queues
Channel
control
function
Sender
M
C
A
M
C
A
SNA LU6.2, TCP/IP, etc.
Message channel
Receiver
Channel
control
function
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To identify some of the main components of distributed queue management
(DQM).
Transition Statement Next we look at how a complex business transaction can be
implemented using the simple messaging and queuing model.
Instructor Guide
V2.0
Uempty
Figure 1-17. Message Driven Processing MQ157.0
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.
Message Driven Processing
Loan
Request
Loan Terms
Security
Indemnity
Customer
Information
Loan
Response
Account
BaIance
Credit
Card
Status
Risk
AnaIysis
Q1
Q7
Q6
Q5
Q4
Q3
Q2
Credit
History
Bank
Funds
Availability
Instructor Guide
Instructor Notes:
Purpose To explain how WebSphere MQ and the message driven paradigm may be
used to build certain types of application which would be more difficult to build in other
ways.
Details The scenario depicted on the visual is a fairly simple example of a lattice
structured application, but is one which illustrates how well WebSphere MQ is suited for
implementing such a complex business transaction.
The facilities of WebSphere MQ enable a different style of application design, one where
the application is modularized into a number of separate processes. Each process is
driven by messages on a queue, and can be independently managed. Individual
components can be changed without affecting the others.
Processes may be triggered by the arrival of new messages, or they can remain active for
some time. They can be distributed across different systems and environments, and can
run in parallel, or at different times, as required.
WebSphere MQ thus provides an adaptable framework that can be used to build complex
business transactions. In summary, this type of application design can be characterized as
follows.
Applications are designed as a network of separate processes.
Processes are message driven instead of terminal driven.
Processes may be viewed as "objects".
A process may be started when a request message arrives.
Applications may be composed of many processes that run in sequence or in parallel,
on different systems and in different environments, and at different speeds.
Transition Statement Next, we investigate the role of syncpoint control in this type of
design.
Instructor Guide
V2.0
Uempty
Figure 1-18. Separate Processes as Units of Work MQ157.0
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.
Separate Processes as Units of Work
MQGET Ioan request
VaIidate fieIds
Update request fiIe
Format two requests
MQPUT credit history request
MQPUT bank funds
avaiIabiIity request
Commit
MQGET customer information
request
Update data base
MQPUT account baIance
request
MQPUT credit status request
Commit
Instructor Guide
Instructor Notes:
Purpose To explain how a complex business transaction may be implemented as a
number of separate asynchronous processes where each process constitutes a unit of
work.
Details The visual depicts two processes which form part of a larger business
transaction. The processes are separated and may in fact execute on different systems.
However, even though they form part of a larger business transaction, each process
operates as a unit of work, not as part of a single distributed transaction.
Each process gets a message from the queue which drives its function, puts messages on
queues which drive other processes, and makes changes to other resources, all under
syncpoint control. The process finally commits the changes to all the resources. If there is
a system failure during the execution of the process, all changes made under syncpoint
control are rolled back, including the reinstatement of the message on the queue which is
driving its function.
The importance of the assured, once and once only delivery property of WebSphere MQ in
this kind of design can clearly be seen. This property, in conjunction with the ability to
make changes to WebSphere MQ resources as part of a unit work, means that the
separate processes can operate safely and independently without the need to hold
complex locks across a network.
Transition Statement Next we look in little more detail at how a business transaction can
be implemented as multiple asynchronous units of work.
Instructor Guide
V2.0
Uempty
Figure 1-19. Multiple, Asynchronous Units of Work MQ157.0
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.
MuItipIe, Asynchronous Units of Work
2 phase
commit
Unit of work
Write
Send
Syncpoint
Receive
Write
Syncpoint
Synchronous
modeI
DB
DB
Unit of work 1
Unit of work 3
Write
Put
Syncpoint
Get
Write
Syncpoint
Unit of work 2
q Q
Asynchronous
modeI
DB
DB
Instructor Guide
Instructor Notes:
Purpose To show how a business transaction can be implemented as multiple
asynchronous units of work using WebSphere MQ, and to compare this with the more
traditional approach of using a single, distributed unit of work.
Details Some implementations of the conversational style of program-to-program
communication support the implementation of a distributed unit of work using a two phase
commit protocol. However, this kind of function is only necessary when there is an
absolute business requirement to maintain two or more distributed data bases in step at all
times, right down to the last fraction of a second. Such a requirement is encountered only
rarely in practice. And if the requirement does not really exist, using a single, distributed
unit of work can be resource consuming and complex, particularly if many process are
involved. In this case, WebSphere MQ offers a simple solution involving multiple units of
work acting asynchronously.
The WebSphere MQ solution is depicted in the lower half of the visual.
The first application writes to a database, puts a message on a queue, and then issues
a syncpoint to commit the changes to the two resources. The message contains data
which is to be used to update a second data base on a separate system. As the queue
is a remote queue, the message gets no further than the transmission queue within this
unit of work. When the unit of work is committed, the message becomes available for
retrieval by the sending MCA.
In the second unit of work, the sending MCA gets the message from the transmission
queue and sends it to the receiving MCA on the system containing the second data
base. The receiving MCA then puts the message on the destination queue. All this is
performed reliably because of the assured delivery property of WebSphere MQ. When
this unit of work is committed, the message becomes available for retrieval by the
second application.
In the third unit of work, the second application gets the message from the destination
queue and updates the data base using the data contained in the message.
If the business transaction is a more complex one, many units of work may be involved. It
is the assured delivery property of WebSphere MQ that ensures the integrity of the
complete business transaction.
Transition Statement Next we look at a property of a message called its persistence.
Instructor Guide
V2.0
Uempty
Figure 1-20. Message Persistence MQ157.0
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.
Message Persistence
AppIication
Program
Queue
Manager
Queue
MQPUT
CC/RC
Queue
MQPUT
CC/RC
Log
Persistent message
Nonpersistent message
Instructor Guide
Instructor Notes:
Purpose To introduce the concept of message persistence and the requirement for a
log.
Transition Statement End of the topic. Next we look briefly at the family of WebSphere
MQ queue managers and the platforms they support.
Instructor Guide
V2.0
Uempty 1.2 WebSphere MQ Products and Platforms
This topic reviews the current list of WebSphere MQ queue managers and the application
platforms they support. It also identifies which queue managers provide Level 2 function.
What students will do Students will listen to a presentation on the WebSphere MQ
products and platforms.
What students will learn Students will learn the names of the WebSphere MQ queue
managers and application platforms they support. They will also learn which queue
managers provide Level 2 function.
understand the range of WebSphere MQ implementations and the opportunities they
present for applications.
Instructor Guide
Figure 1-21. WebSphere MQ Queue Managers MQ157.0
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
WebSphere MQ Queue Managers
Linus for InteI, V5.3
Linus for zSeries, V5.3
NCR UNIX V2.2.1
OS/2 Warp V5.1
z/OS, V5.3
SINIX and DC/OSx V2.2.1
SoIaris, V5.3
Tandem NSK V2.2.0.1
VSE/ESA V2.1.1
Windows V5.3
WebSphere MQ for . . .
LeveI 2
Instructor Guide
V2.0
Uempty
- 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
Instructor Guide
Instructor Notes:
Purpose To list the WebSphere MQ queue managers and to identify which provide
Level 2 function.
Details For simplicity, the visual only depicts the latest release level of each of the queue
managers. For some of the queue managers, previous release levels may still be
obtainable, but these are not shown.
Some of the features of the Level 2 queue managers were not present in the Level 1 queue
manager. There are no Level 1 queue managers left.
The Level 2 queue managers support a number of additional options in the MQI.
The Level 2 queue managers are less restrictive regarding the maximum length of
message that can be handled.
The Level 2 queue managers support model and dynamic queues.
A Level 2 queue manager has an important performance option whereby a batch of
messages can be transmitted from one queue manager to another within the scope of a
single unit of work.
The Level 2 queue managers support instrumentation events. An instrumentation event
is a logical combination of conditions that is detected by a queue manager during its
operation. When the queue manager detects an instrumentation event, it puts a special
message, called an event message, on an event queue.
Each Level 2 queue manager in a network of queue managers can be controlled from
just one of the queue managers. This concept is known as a single point of control.
The Level 2 queue managers also support the WebSphere MQ Framework. This
framework offers users and independent software vendors the opportunity to extend or
replace queue manager function using defined interfaces. It is also a basis by which
IBM can exploit new technology faster. We shall look at the framework in a little more
detail on the next visual.
A Level 2 queue manager can support the connection of an WebSphere MQ client
application. This is an application running on a different system to that on which the
queue manager is running.
The Version 5 queue managers have additional function compared to the remaining
Level 2 queue managers.
WebSphere MQ for Windows is considered to be a Level 2 queue manager even though
some Level 2 function is not supported in order to position it as a lightweight, single user
queue manager.
The level 2 queue manager can support SSL. SSL is the Internet standard for secure
communications, involving encryption, authentication, and integrity of data.
Instructor Guide
V2.0
Uempty
A more detailed functional comparison of the WebSphere MQ queue managers can be
found in the MQSeries Planning Guide, and an even more detailed one in the WebSphere
MQ Application Programming Guide.
Additional Information The list is subject to frequent change. There is always the
possibility of a recent announcement requiring a modification to this list.
Transition Statement Next we look at the WebSphere MQ framework.
Instructor Guide
Figure 1-22. WebSphere MQ Framework MQ157.0
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
WebSphere MQ Framework
DCE
name
service
Object
authority
manager
Data
conversion
interface
Security
enabIing
interface
Name
service
interface
Trigger
monitor
interface
Message
channeI
interface
AppIication
Messaging
and
queuing
kerneI
MQI
DCI
SEI
NSI
TMI
MCI
Other
SNA
TCP/P
other WebSphere MQ Systems
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce the WebSphere MQ Framework as supported by the Level 2
queue managers.
Details
The trigger monitor interface (TMI). A queue manager is supplied with one or more
trigger monitors to support triggering. The TMI allows you to write your own trigger
monitor.
The message channel interface (MCI). This interface allows you to write your own MCA
for moving messages from one queue manager to another. However, the interface does
not include the MCP and so it is not possible for you to write an MCA to communicate
with an MCA supplied by WebSphere MQ.
The name service interface (NSI). The name service provides support for looking up
the name of the queue manager that owns a specified queue. The DCE name service
component uses this interface and is supplied with the Version 5 queue managers.
However, the NSI allows you to write your own name service component.
The security enabling interface (SEI). The SEI has three parts.
- Authorization service. This provides support for access control to WebSphere MQ
resources. The object authority manager (OAM) uses this interface and is supplied
with MQSeries on UNIX systems and MQSeries for Windows NT and Windows
2000. However, the existence of the interface means that you can write your own
authorization service component.
- User identifier service. The user identifier service is used by the queue manager to
obtain a user ID. It is really only required on OS/2 where it is not necessary for a
user to log on to the system.
- Channel exits. These allow you to extend the way a channel works. However, they
are of particular relevance to security, and are therefore considered to be part of the
SEI.
The data conversion interface (DCI). When a message is moved from one queue
manager to another, WebSphere MQ can convert the application data in the message
from one representation to another provided the format of the data conforms to one of
the built-in formats. If the format of the data does not conform in this way, the
conversion can be performed by a user exit program. The DCI allows you to write a
data conversion exit.
Transition Statement Next we review the concept of an WebSphere MQ client.
Instructor Guide
Figure 1-23. WebSphere MQ Client MQ157.0
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.
WebSphere MQ CIient
Assured delivery
Queue storage
Data conversion
Administration
Recovery
Syncpoint
control
Communications
stack
CIient
connection
WebSphere
MQ
appIication
CIient system
Communications
stack
Server
connection
WebSphere
MQ queue
manager
Server system
MQI channeI
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To review the concept of an WebSphere MQ client.
Details
Notice the difference between an MQI channel, which operates synchronously from the
point of view of the application, and a message channel, which operates asynchronously.
We shall be learning more about the implementation of WebSphere MQ clients later in the
course.
Transition Statement Finally, we look at the range of application platforms supported by
WebSphere MQ.
Instructor Guide
V2.0
Uempty
Figure 1-24. WebSphere MQ Platforms MQ157.0
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.
WebSphere MQ PIatforms
AIX
Compaq OpenVMS AXP
Compaq OpenVMS VAX
Compaq Tru64 UNIX
HP-UX (incIuding Stratus Continuum)
Linux
NCR UNIX
OS/2 Warp
SINIX and DC/OSx
SoIaris
Windows
iSeries
z/OS
Batch
CICS
IMS
TSO
Tandem NonStop KerneI
VSE/ESA
Not as an
WebSphere
MQ
cIient
DOS
Java
SunOS
TPF
VM/ESA
Others (see student notes)
OnIy as an
WebSphere
MQ
cIient
Instructor Guide
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).
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To review the range of platforms supported by WebSphere MQ.
Transition Statement End of the topic. Let us review what we have done so far.
Instructor Guide
Instructor Guide
V2.0
Uempty Checkpoint
Unit 1 Checkpoint
1. T/ F WebSphere MQ only supports asynchronous messaging.
Correct Answer: False
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.
Correct Answer: d
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.
Correct Answer: b
Instructor Guide
Figure 1-25. Unit Summary MQ157.0
Notes:
Unit Summary
Commercial Messaging
Benefits for all platforms
Common application programming interface
Assured message delivery
Time-independent processing
Application parallelism
Faster application development
Level 2 enhancements
SSL
Additional function
nstrumentation events
Single point of control
WebSphere MQ Framework
WebSphere MQ clients
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To summarize the unit.
Details We have reviewed the features and benefits of WebSphere MQ. The major
benefits of WebSphere MQ apply across the whole range of supported platforms, but the
Level 2 queue managers provide enhancements which deliver additional benefits.
In the remainder of this course, we shall focus on the administration of all the Level 2 queue
managers with the exception of WebSphere for z/OS which has its own course for this
purpose.
We have also noted the main sources of information about WebSphere MQ.
Transition Statement End of the unit. Next we shall look at how to install WebSphere
MQ and configure a queue manager.
Instructor Guide
Instructor Guide
Copyright IBM Corp. 1996, 2003 Unit 2. Installation and Configuration 2-1
V2.0
Uempty
Unit 2. Installation and Configuration
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.
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
Accountability:
Machine exercises
References
Instructor Guide
SC34-6068 WebSphere MQ WebSphere MQ System
If using iSeries, use the following manual;
SC34-6070 WebSphere MQ for iSeries V5.3 System
Instructor Guide
V2.0
Uempty
Notes:
Unit Objectives
List various administration interfaces
Explain which interfaces are available on various platforms and
how to use them
Describe naming rules and recommended conventions
Queue Managers
Queues
Create and start queue managers
Create queues
Use sample programs to test new objects
Instructor Guide
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details 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.
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.
Transition Statement First, some hints on the planning an WebSphere MQ
implementation.
Instructor Guide
Instructor Guide
V2.0
Uempty 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.
What students will do Students will listen to a presentation on what considerations are
needed when planning to implement WebSphere MQ.
How students will do it No student activities are planned for this topic. They will have an
opportunity to use what they learn in the later practical exercise.
What students will learn Students will learn what decisions they need to make prior to
implementing WebSphere MQ and will acquire some hints for a successful implementation.
How this will help students on their job This knowledge will help the students to be more
effective in planning an WebSphere MQ implementation. In particular, it will help them
avoid the common mistake of failing to agree naming conventions for WebSphere MQ
objects on an installation wide basis.
Instructor Guide
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.
Naming WebSphere MQ Objects
Allowable character set
A-Z, a-z, 0-9
. / _ %
Maximum of 48 characters for the names of:
Queues
Processes
Queue managers
Maximum of 20 characters for the names of:
Channels
No implied structure in a name
Note: Names in WebSphere MQ are case-sensitive
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To provide the rules for naming an WebSphere MQ object, viz a queue, a
process, the queue manager object, and a channel.
Details The rules for naming WebSphere MQ objects are the same on all supported
platforms. There is no implied structure in a name such as you might find in the rules for
file names on many operating systems.
Transition Statement After installation, the first WebSphere MQ object to be created is a
queue manager.
Instructor Guide
Figure 2-3. Queue Manager MQ157.0
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.
Queue Manager
Generally one per system
May create additional ones, that is, for a test environment
Name
Usually short
For example, same as the TCP/P host name, the Windows
system name, or an SNA LU alias
Should be unique within a network
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To indicate some of the considerations that apply when creating a queue
manager.
Details Although a longer name is allowed, a queue manager is usually given a short
name. Common options are to give a queue manager the same name as the TCP/IP host
name, the Windows NT system name, or the LU alias of the SNA LU which is supporting it,
and so on.
Additional Information WebSphere MQ V5.3 supports queues over 2GB in size. Limit
now 2 TB. Minimum queue footprint in memory is reduced from 250KB to 64KB. This
allows more queues to be opened.
On AIX, HP-UX, and Sun Solaris you will need to enable large queues to be used. This
process must be performed before you create queues with large sizes.
Transition Statement Next we look at the various types of queues and some naming
conventions for them.
Instructor Guide
Figure 2-4. Queues MQ157.0
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.
Queues
A local queue stores messages
Other queue types
Alias queue
Local definition of a remote queue
Model queue and dynamic queue
Queue type is transparent to the application
Model and dynamic queues are the exception
Useful naming conventions
The name of a queue should describe its function, not its type
or location
A common prefix for the names of related queues simplifies
administration
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To identify the different types of queue and to provide some recommendations
for naming a queue.
Details Every queue is owned by a queue manager and possesses a name. An
application identifies a queue by its name, but this may need to be qualified by the name of
the owning queue manager if the queue does not have a local definition.
Generally, the type of a queue is transparent to an application. The exceptions are when
opening a model queue and closing a dynamic queue as these may require some special
processing.
Transition Statement Next we look at some special local queues that are used by
WebSphere MQ.
Instructor Guide
Figure 2-5. Special Local Queues MQ157.0
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.
SpeciaI LocaI Queues
Dead letter queue
One per queue manager
Designated queue for messages that cannot be delivered
Always set up a dead letter queue
nitiation queues
Used for triggering
Transmission queues
Command queue
Event queues
Default queues
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To introduce some special local queues that are used by WebSphere MQ.
Details
Transition Statement Next we look at message channels.
Instructor Guide
V2.0
Uempty
Figure 2-6. Message Channel MQ157.0
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 connection,
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.
Message ChanneI
Q
MQGET
M
C
A
MQPUT
M
C
A
tQ
SNA LU6.2, TCP/P, and
so forth
Instructor Guide
- 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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the need to define a message channel at both ends of the channel
and to define its associated transmission queue.
Transition Statement Next we look at the various administration interfaces provided by
WebSphere MQ.
Instructor Guide
Figure 2-7. Administration Interfaces MQ157.0
Notes:
Administration Interfaces
WebSphere MQ commands (MQSC)
Entered by means of a supplied interface
Programmable Command Format (PCF) commands
Put on the command queue by an application, and got by the command server
Escape PCF to encapsulate an WebSphere MQ command
MQSeries control commands
Entered at a command prompt
Administration application
Panel application on WebSphere MQ for Tandem NonStop Kernel
GU on WebShpere MQ for Windows
Administration nterfaces on Windows
OS/400 CL commands
N file and MQD file on WebSphere MQ for Windows
Event messages
Put on an event queue by the queue manager, and gotten by an application
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To identify the interfaces available for the administration of a queue manager.
Details The visual depicts all the administration interfaces provided by WebSphere MQ.
WebSphere MQ commands (MQSC)
WebSphere MQ commands can only entered by means of an
interface supplied with WebSphere MQ.
There are two modes of entering WebSphere MQ commands:
- Interactively, by typing an WebSphere MQ command at the
keyboard and waiting for the result. This mode is not available
on WebSphere MQ for iSeries.
- Using a text editor, you can create a file containing a sequence
of WebSphere MQ commands and then submit the file for
execution.
The WebSphere MQ commands are described in the WebSphere
MQ Script (MQSC) Command Reference.
Programmable Command Format (PCF) commands
PCF commands have a highly structured format and contain binary
information as well as character information. The structured format
makes it easier for an application to generate the components of a
PCF command dynamically. A reply to a PCF command has a
similar format which makes it easier for an application to parse.
An application can construct a message containing a PCF
command and put it on the command queue of a queue manager.
The message is then got by the command server of the queue
manager, the PCF command in the message is executed, and the
reply is put on the specified reply-to queue.
The existence of a command queue and a command server on
each queue manager in a network of queue managers enables
each queue manager to be managed from just one system in the
network. This concept is known as a single point of control.
The Escape PCF command is used to submit an WebSphere MQ
command which is held as text within the PCF command. This
command can be useful for managing up-level queue managers or
queue managers with unique features.
PCF commands are described in WebSphere MQ Programmable
Command Formats and Administration Interfaces.
Instructor Guide
WebSphere MQ Administrative Interface (MQAI)
The MQAI is a programming interface to WebSphere MQ, using C
language and also Visual Basic for Windows. It performs
administrative tasks on a WebSphere MQ queue manager using
data bags. Data bags allow you to handle properties (or
parameters) of objects in a way that is easier than using the other
administrative interface, PCFs.
You can use MQAI to:
Implement self administering applications and administration tools.
Simplify the use of PCF messages. You dont have to write your
own PCG messages and thus avoid problems associated with
complex data structures.
Handle error conditions more easily. It is difficult to get return codes
back from the WebSphere MQ script (MQSC) commands, but
MQAI makes it easier.
Control commands
Control commands are entered at a command prompt of the
operating system in use, or they can be included in an operating
system command file such as a shell script on a UNIX system.
Control commands are described in MQSeries System
Administration for a Version 5 queue manager and in the relevant
System Management Guide for each of the remaining queue
managers.
Administration application
MQSeries for Tandem NonStop Kernel also has a panel driven
administration facility, but it can only be used to manage a queue
manager on the system you are working on. Its use is described in
the MQSeries for Tandem NonStop Kernel System Management
Guide.
WebSphere MQ for Windows NT and Windows 2000 V5.1 and
higher has some additional administration interfaces.
No other queue manager covered by this course has an
administration application.
OS/400 CL commands
The WebSphere MQ CL commands are only supported on
WebSphere MQ for iSeries and can be entered anywhere an
OS/400 CL command can be entered.
Instructor Guide
V2.0
Uempty
The WebSphere MQ CL commands are described in the
WebSphere MQ for iSeries V5.3 System Administration Guide.
INI file and MQD file on WebSphere MQ for Windows
An initialization (INI) file or an WebSphere MQ definition (MQD) file
is used to define all the WebSphere MQ components required on a
Windows workstation in preparation for running applications.
An INI file is only used on WebSphere MQ for Windows Version 2.0
and is processed by the Create and Go utility. An MQD file is only
used on WebSphere MQ for Windows Version 2.1 and may be
processed when WebSphere MQ is installed, or when WebSphere
MQ starts, or by selecting Run MQD file now from the WebSphere
MQ icon menu, depending on the requirement.
Event messages
When a queue manager detects an instrumentation event during
its operation, it puts an event message on an event queue. The
event message contains information about the event that has
occurred.
Event messages have a format similar to PCF commands and are
therefore intended to be processed by applications. An event
queue can therefore be monitored by a system management
application which can get each message put on the queue and
take the appropriate action, for example, by putting a message
containing a PCF command on the command queue of the queue
manager.
Event messages are supported by all the queue managers covered
by this course except WebSphere MQ for Windows Version 2.0.
Transition Statement With the introduction of WebSphere MQ for Windows V5.1, there
are several new available interfaces.
Instructor Guide
Figure 2-8. WebSphere MQ Windows Administration Interfaces MQ157.0
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
Additional to previously listed
WebSphere MQ Explorer
WebSphere MQ Services snap-in under Microsoft Management
Console (MMC)
WebSphere MQ Web Administration
WebSphere MQ Windows
Administration Interfaces
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce WebSphere MQ for Windows Administration interfaces.
Details The visual shows a high level review of the additional interfaces introduced for
Windows.
If the system setup allows, the following is a recommended demonstration to show students
some of the new functions:
Take the time to bring up the WebSphere MQ First Steps and show students how to use
the DEFAULT CONFIGURATION to set up a queue manager.
Using the default setup, demonstrate the use of POSTCARD.
Create a local queue for the default queue manager and show the use of the API
EXERCISER
Transition Statement End of the topic. Now we are ready to create and configure a
queue manager.
Instructor Guide
Instructor Guide
V2.0
Uempty 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.
What students will do Students will listen to a presentation on configuring a queue
manager.
How students will do it Following the presentation, the students will have an practical
exercise in configuring a queue manager.
What students will learn Students will learn how to create a queue manager, how to
provide a basic configuration for it, and how to start and stop it.
How this will help students on their job These are the first steps in using WebSphere
MQ within an actual installation.
Instructor Guide
Figure 2-9. Installation MQ157.0
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.
InstaIIation
GeneraIIy, . . .
. . . Iike instaIIing other software on the same pIatform
SINIX and DC/OSx
pkgadd (DC/OSx)
sysadm (SNX)
SunOS
Run the supplied installation script from the
CD-ROM
Sun SoIaris
pkgadd
Tandem NonStop KerneI
RESTORE, then run the supplied installation
utility, instmqm
Windows
AIX
SMT
Also an "easy installation"
NCR UNIX
sysadm or pkgadd
Compaq OpenVMS
VMSNSTAL
HP-UX
swinstall
OS/2 Warp
NSTALL
CD enabled
OS/400
GO LCPGM
Linux
Red Hat Package Manager
MQSeries for . . .
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To highlight the more important points to bear in mind when installing
WebSphere MQ.
Details During the installation of WebSphere MQ for Windows, the local group mqm is
created automatically if it does not already exist on the system.
The installation of WebSphere MQ for iSeries creates a special user profile QMQM which
cannot have a password allocated to it. WebSphere MQ for iSeries libraries and objects
are owned by this user profile.
During installation, WebSphere MQ automatically creates an WebSphere MQ configuration
file which contains information relevant to all queue managers that will be created on the
system. There is only one WebSphere MQ configuration file per system.
When a queue manager is created, a queue manager configuration file is automatically
created at the same time. This file contains information that is relevant to a specific queue
manager. There is one queue manager configuration file for each queue manager.
Both of these files contain text and are therefore readable. Their contents may be changed
by certain commands and, in special circumstances, you may need to edit them, but this is
the exception rather than the rule. They are described more fully later on. At this stage, it
is enough to be aware that they exist and that they are used by WebSphere MQ.
Additional Information For WebSphere MQ V5.3 both WebSphere MQ base Java and
WebSphere MQ JMS are installed with WebSphere MQ. Please refer to the WebSphere
MQ using Java manual for prerequisites to fully support WebSphere MQ for Java.
Transition Statement Next we look at how to create a queue manager.
Instructor Guide
V2.0
Uempty
Figure 2-10. Create Queue Manager MQ157.0
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.
Create Queue Manager
crtmqm -q QMgrName
dItmqm QMgrName
You need authority to use a control command
QMgrName is a required parameter
-q specifies the default queue manager
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how to create a queue manager and, for much later, how to delete it.
Details The first task after installing WebSphere MQ is to create a queue manager using
the crtmqm control command.
You need the following authority to use a control command.
On MQSeries for Compaq OpenVMS, your user ID must hold the OpenVMS MQM
rights identifier.
On MQSeries for Tandem NonStop Kernel, your user ID must belong to the group
MQM.
For WebSphere MQ on UNIX systems, your user ID must belong to the group mqm, but
not necessarily as its primary group.
On WebSphere MQ for Windows, your user ID must belong either to the mqm local
group or to the Administrators local group. Of course, it is possible for your user ID to
belong to a global group which, in turn, belongs to either of these local groups.
Note that, on WebSphere MQ for Windows, V5.3, the authority required to issue
WebSphere MQ control commands no longer depends on whether your user ID was
authenticated locally or by the domain controller.
You are recommended to give your queue manager a short name which is unique within a
network of interconnected queue managers. Using the TCP/IP host name, the Windows
system name, or an SNA LU alias would be a reasonable convention.
For the first queue manager you create on a system, use the -q parameter to make it the
default queue manager.
Only the basic form of the crtmqm command is depicted on the visual. You will need to
refer to the appropriate publication for a complete description of all the parameters. For
some of the parameters, you can accept the default values and change them later by using
the ALTER QMGR WebSphere MQ command.
If you are creating a queue manager for some simple tests, use a small circular log and
accept the default values for all the parameters unless there is a reason to use different
ones.
The dltmqm command deletes a queue manager and all its associated objects.
Transition Statement The next step is to start the queue manager.
Instructor Guide
Figure 2-11. Start Queue Manager MQ157.0
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
runmqsc /IN $SYSTEM.ZMQSSMPL.AMQSCOMA/ QMgrName
Websphere MQ on UNIX systems
runmqsc QMgrName < mqmtop/samp/amqscoma.tst
Start Queue Manager
strmqm QMgrName
runmqsc QMgrName < amqscoma.tst
f started for the first time, create the system and default objects
...
... but not on a Version 5 queue manager
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To describe how to start a queue manager and, when necessary, how to
create the system and default objects for the queue manager.
Details After you have created a queue manager, the next two tasks you would normally
perform are to start the queue manager and then to create the system and default objects
for the queue manager. Note that the latter task is not required for a Version 5 queue
manager.
A queue manager has to be started before applications can connect to it and before any
commands can be issued to it.
It is often useful to include control commands in the operating system initialization
procedure. In the procedure, you could include a strmqm command for each queue
manager you wish start at system startup.
As a result of issuing strmqm, WebSphere MQ starts a process called the execution
controller. You should not kill the execution controller; always use the endmqm control
command.
Additional Information On WebSphere MQ for Windows, the scmmqm program is no
longer supported. For migration of scmmqm please refer to the WebSphere MQ for
Windows, V5.3 Quick Beginnings Guide.
Transition Statement Next we look at some WebSphere MQ commands.
Instructor Guide
V2.0
Uempty
Figure 2-12. WebSphere MQ MQSC Commands MQ157.0
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.
WebSphere MQ MQSC Commands
DEFINE QLOCAL(MY_DEAD_LETTER_Q) REPLACE
ALTER QMGR DEADQ(MY_DEAD_LETTER_Q)
DEF QL(another) REPLACE +
descr('This is a test queue')
Instructor Guide
- 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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce the WebSphere MQ commands and the rules for writing them.
Details The visual depicts three examples of WebSphere MQ commands.
The first command creates a local queue with the name MY_DEAD_LETTER_Q.
The second command alters the queue manager object by declaring
MY_DEAD_LETTER_Q to be dead letter queue of the queue manager.
The third command creates another local queue. Note the following:
- Most WebSphere MQ commands have synonyms. DEF QL is the synonym for
DEFINE QLOCAL.
- The command creates a queue called ANOTHER. Because the string "another" is
not enclosed in single quotation marks, the characters in it are folded to upper case.
- A keyword, like DESCR, can be in lower case or upper case.
- The single quotation marks enclosing the string "This is a test queue" are required
because the string contains blanks.
There are other ways in which local queues can be created and the queue manager object
altered. We have already encountered these.
By means of PCF commands.
By means of the administration applications on MQSeries for Tandem NonStop Kernel.
By means of CL commands on WebSphere MQ for iSeries.
Transition Statement Next we look at how WebSphere MQ commands are entered.
Instructor Guide
Figure 2-13. Run WebSphere MQ Commands MQ157.0
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
Run WebSphere MQ Commands
runmqsc QMgrName
runmqsc -e QMgrName
runmqsc < mqsc.in > mqsc.out
Standard input device -> runmqsc -> standard output
device
OptionaI parameters
-e Don't copy the source text to the output report
-v Perform a syntax check onIy
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To describe how to enter WebSphere MQ commands.
Details On all queue managers except WebSphere MQ for iSeries, the administration
interface for entering WebSphere MQ commands is the control command runmqsc.
The input to runmqsc is zero, one, or more WebSphere MQ commands and the output is
the results of executing those commands, including operator and error messages.
runmqsc reads from the standard input device, also known as stdin, and writes to the
standard output device, also known as stdout. Typically, the standard input device is the
keyboard and the standard output device is the display. However, by using redirection
operators, input can be taken from a file and output can be directed to a file.
In this way, you can enter WebSphere MQ commands interactively at the keyboard and see
the results on the display. Alternatively, you can create a file containing a sequence
WebSphere MQ commands and then have them executed with the results directed to a file.
Or you can even mix the two approaches.
It is useful to maintain WebSphere MQ command files, particularly for the following
reasons.
For replicating a queue manager configuration on multiple systems.
To recover a queue manager configuration.
When going through a number of iterations in testing a queue manager configuration.
Additional Information Although an interface is provided on WebSphere MQ for iSeries
for entering WebSphere MQ commands, any OS/400 users in the class may be happier
using CL commands instead.
Transition Statement Next we look at creating queues.
Instructor Guide
V2.0
Uempty
Figure 2-14. Creating a Local Queue MQ157.0
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.
Creating a LocaI Queue
DEFINE QLOCAL(MY_QUEUE) REPLACE +
DESCR('This is a test queue') +
PUT(ENABLED) GET(ENABLED) +
DEFPSIST(YES) SHARE +
MAXDEPTH(1000) MAXMSGL(2000)
DEF QL(XXX) LIKE(MY_QUEUE)
Instructor Guide
On WebSphere MQ for iSeries, the corresponding CL command is CRTMQMQ. The
command prompter will ask for the type of the queue first.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how to create a local queue.
Transition Statement Next we see how to display the attributes of the WebSphere MQ
objects we have created so far.
Instructor Guide
Figure 2-15. Displaying Attributes MQ157.0
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.
DispIaying Attributes
DispIay seIected attributes of a queue
DISPLAY QUEUE(XXX) DESCR GET PUT
DISPLAY QUEUE(YYY) MAXDEPTH CURDEPTH
DispIay aII the attributes of a queue
DISPLAY QUEUE(XXX) ALL
DISPLAY QLOCAL(XXX) - V5 and AS/400 queue managers onIy
DIS Q(SYSTEM*)
Generic queue names are allowed
DISPLAY QMGR ALL
DISPLAY QMGR - V5 and AS/400 queue managers onIy
DispIay aII the attributes of the queue manager object
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To explain how to display the attributes of a queue and the queue manager
object.
Details Attributes of a queue whose values change dynamically, or whose values are set
by the queue manager, can also be displayed. The following are examples.
CreationDate
CreationTime
CurrentQDepth
OpenInputCount
OpenOutputCount
Transition Statement Next we look at the other types of queue.
Instructor Guide
V2.0
Uempty
Figure 2-16. Other Queue Types MQ157.0
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
Other Queue Types
LocaI definition of a remote queue (remote queue definition)
DEFINE QREMOTE(BBB) +
RNAME(YYY) RQMNAME(QM2)
AIias queue
DEFINE QALIAS(AAA) TARGQ(XXX)
DEFINE QMODEL(ANSQ) DEFTYPE(TEMPDYN)
ModeI queue
TEMPDYN, dynamic queue deIeted when cIosed
PERMDYN, dynamic queue may hoId persistent messages
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how to create the other three types of queue.
Details Of the four types of queue, only a local queue can store messages.
Alias queues, and the queues to which they resolve, can be created in any order.
Of the two types of dynamic queue, only a permanent dynamic queue can store persistent
messages. A typical use of a dynamic queue is as a reply-to queue for a client program
which is sending requests to a server.
The WebSphere MQ command to display the attributes of any type of queue is DISPLAY
QUEUE. However, on a Version 5 queue manager, you can also use DISPLAY QALIAS,
DISPLAY QREMOTE, and DISPLAY QMODEL.
Transition Statement Next we look at some more WebSphere MQ commands that we
can use.
Instructor Guide
Figure 2-17. More WebSphere MQ Commands MQ157.0
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
More WebSphere MQ Commands
AIter seIected attributes
ALTER QLOCAL(XXX) PUT(DISABLED)
ALTER QALIAS(AAA) TARGQ(YYY)
ALTER QMGR DESCR('New description')
DELETE QLOCAL(XXX)
DELETE QREMOTE(BBB)
The foIIowing are onIy vaIid if the queue is not in use
DeIete a queue
CLEAR QLOCAL(XXX)
DeIete aII messages on a IocaI queue
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe some other useful WebSphere MQ commands.
Details ALTER QLOCAL, ALTER QALIAS, ALTER QREMOTE, ALTER QMODEL, and
ALTER QMGR only alter the specified attributes of the object to which the command is
applied. The remaining attributes of the object are left unchanged.
The commands DELETE QLOCAL, DELETE QALIAS, DELETE QREMOTE, and CLEAR
QLOCAL will fail if the queue to be deleted or cleared is still in use.
Transition Statement Next we look at some useful sample programs that are supplied
with WebSphere MQ.
Instructor Guide
Figure 2-18. Sample Programs MQ157.0
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
$SYSTEM.ZMQSSMPL
WebSphere MQ on UNIX systems
SampIe Programs
What's avaiIabIe ...
C and COBOL source
C executabIes
Get messages and write to the standard output device
amqsget QName [QMgrName]
DispIay messages, incIuding message descriptors
amqsbcg QName QMgrName
amqsput QName [QMgrName]
Read from the standard input device and put messages
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To list some sample programs supplied with WebSphere MQ that will be useful
in testing a configuration.
Details Sample programs, including their executables, are available in C on all queue
managers.
Some of the samples are useful for performing simple tests and will be used in the practical
exercises.
amqsput
reads lines of text from the standard input device, converts them to
messages, and puts the messages on the named queue.
amqsget
gets messages from the named queue, and writes the text within each
message to the standard output device.
amqsbcg
browses the messages on the named queue and writes their contents, in
both hex and character format, to the standard output device. It also
displays, in a readable format, the message descriptor of each message.
Transition Statement Finally, we describe how to end the operation of a queue manager.
Instructor Guide
V2.0
Uempty
Figure 2-19. End Queue Manager MQ157.0
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.
End Queue Manager
endmqm QMgrName
ControIIed (or quiesced)
AIIows connected appIications to end, but no new ones
Immediate
CompIetes aII current MQI caIIs, but no new ones
endmqm -i QMgrName
endmqm -p QMgrName
Preemptive
Stops without waiting for appIications to disconnect,
or for MQI caIIs to compIete
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the different modes of ending the operation of a queue manager.
Details The normal mode of stopping a queue manager is the controlled, or quiesced,
mode. In this mode, applications can continue to do work, but well behaved applications
will disconnect as soon as convenient. To detect that a queue manager is quiescing, a
well-behaved application should use the fail if quiescing option on the MQOPEN, MQPUT,
MQPUT1, and MQGET calls. The use of this option means that the call fails if the queue
manager is quiescing.
Once an application has detected that a queue manager is quiescing, it should terminate
cleanly. In doing this, it may possibly issue further calls that ignore the quiescing state. It
may either complete and commit a unit of work in progress, or it may back it out, before
terminating.
Some components of WebSphere MQ are applications which are well behaved in this
manner.
The immediate mode of stopping a queue manager should only be used if you need to stop
it quickly with predictable results.
The preemptive mode should only be used as a last resort.
Additional Information On WebSphere MQ for iSeries, the ENDMQM CL command
allows has two new parameters as of V5.2. They are the ENDDCTJOB and TIMEOUT. You
are now able to quiesce all queue mangers.
The ENDDCTJOB(*YES) option does the following:
Starts command sever and stops all channels
Ends command Server
Records all media images
Ends the Queue Manager
Ends any Listener
Kills any processes with dangling connections to Queue manger
Reclaims the QMQM activation group
Cleans up shared memory and semaphores
Issues message AMQ8004 if successful
Transition Statement End of the topic. Now there is a practical exercise on creating and
configuring a queue manager.
Instructor Guide
Instructor Guide
V2.0
Uempty 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
Correct Answer: b
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.
Correct Answer: a
4. T/F Altering queue attributes can be done while the queue
manager is running and the changes take effect immediately.
Correct Answer: True
Instructor Guide
Notes:
mplementation planning
Configuring a queue manager
Exercise 1
Unit Summary
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details We commenced the unit by looking at what you need to consider, and what
decisions you need to make, when planning to implement WebSphere MQ. You should not
underestimate the importance of this activity. Above all, be sure to agree naming
conventions for WebSphere MQ objects.
We then looked at how to create a queue manager and configure it ready for use, and there
was a practical exercise in performing these tasks.
Transition Statement End of the unit. Next we shall look at the MQI and triggering.
Instructor Guide
Instructor Guide
Copyright IBM Corp. 1996, 2003 Unit 3. The MQI and Triggering 3-1
V2.0
Uempty
Unit 3. The MQI and Triggering
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.
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
Accountability:
Machine exercises
Classroom discussion
References
If iSeries:
Administration
Instructor Guide
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.
Unit Objectives
Provide an overview of the Message Queuing nterface
Describe the triggering process
Enable triggering for a local queue
Explain conditions that cause triggering to fail
Examine publish/subscribe and know where it is supported
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose Highlight the unit objectives.
Details This unit commences with an introduction to some of the more important
features of the MQI and ends by describing triggering in some detail. There is a practical
exercise on configuring WebSphere MQ for triggering.
Describe some of the more important features of the MQI.
Configure WebSphere MQ to enable triggering.
Determine the cause if triggering fails to occur.
Define the purpose of WebSphere MQ Publish/Subscribe and its benefits.
List the control commands used to operate Publish/Subscribe brokers.
Transition Statement We start by looking at the notation used to describe the MQI using
the MQPUT1 call as an example.
Instructor Guide
Instructor Guide
V2.0
Uempty 3.1 The MQI
This topic provides an introduction to some of the more important features of the MQI.
What students will do Students will listen to a presentation on the MQI.
What students will learn Students will learn about the more important features of the
MQI.
understand:
How an MQI application works, including the supplied sample programs which are
useful for testing.
The requirements of an executing application in terms of the objects it references.
The error messages and reason codes that can be produced.
Instructor Guide
Figure 3-2. Notation MQ157.0
Notes:
Notation
MQPUT1 (Hconn, ObjDesc, MsgDesc, PutMsgOpts, BufferLength, Buffer,
CompCode, Reason)
WebSphere MQ AppIication Programming Reference
CALL "MQPUT1" USNG HCONN, OBJDESC, MSGDESC, PUTMSGOPTS,
BUFFERLENGTH, BUFFER, COMPCODE, REASON.
EquivaIent in COBOL
MQPUT1 (Hconn, &ObjDesc, &MsgDesc, &PutMsgOpts, BufferLength, Buffer,
&CompCode, &Reason);
EquivaIent in C
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce the notation used in the publications to define the MQI.
Details The WebSphere MQ Application Programming Reference defines the MQI. The
visual shows an example of the notation used in that publication and others.
MQPUT1 is an example of an MQI call and the items in parentheses following it, namely,
Hconn, ObjDesc, and so forth, are referred to as its parameters.
Examples of an MQPUT1 call in both C and COBOL are also shown on the visual.
Transition Statement Next we look in more detail at three of the parameters of the
MQPUT1 call; parameters which are common to all the MQI calls.
Instructor Guide
Figure 3-3. Common Parameters MQ157.0
Notes:
A listing of all the reason codes is contained in Appendix A of this student guide.
Common Parameters
Hconn, connection handle
Returned by the MQCONN and MQCONNX calls
nput parameter on all other MQ calls
CompCode, completion code
MQCC_OK
MQCC_WARNNG
MQCC_FALED
Reason, reason code
MQRC_. . .
MQRC_NONE
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe three parameters that are common to all MQI calls.
Details The three parameters shown on the visual are common to all MQI calls.
When an application connects to a queue manager by means of an MQCONN or
MQCONNX call, the queue manager returns a connection handle to the application.
This handle represents the connection to the queue manager on all subsequent MQI
calls to that queue manager.
All MQI calls return a completion code to enable the application to determine quickly
whether the call:
- Completed successfully, MQCC_OK,
- Completed partially, MQCC_WARNING, or
- Failed, MQCC_FAILED.
All MQI calls also return a reason code to provide more information to the application
when a call completes partially or fails. A successful call returns MQCC_OK and
MQRC_NONE.
MQCC_OK, MQCC_WARNING, and so forth, are examples of WebSphere MQ constants.
WebSphere MQ constants are documented in the WebSphere MQ Application
Programming Reference and other publications. They are also defined in the C include
files and COBOL copy files supplied with WebSphere MQ and so can be used in the
program source code.
Some WebSphere MQ constants are listed in Appendix A, Selected WebSphere MQ
Constants on page A-1.
Transition Statement Next we look at the object descriptor, another parameter on the
MQPUT1 call and an example of a structure in the MQI.
Instructor Guide
Figure 3-4. Object Descriptor MQ157.0
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.
Object Descriptor
ObjectType
MQOT_Q - queue
MQOT_PROCESS - process
MQOT_Q_MGR - queue manager
ObjectName
Must be blank if ObjectType is MQOT_Q_MGR
Every object defined to a queue manager has a unique name
within its type
ObjectQMgrName
Blank denotes the local queue manager
DynamicQName
Specifies the name of the dynamic queue to be created
AlternateUserId
Alternative user identifier for checking the authorization to open
the object
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the object descriptor as an example of a structure in the MQI.
Details There are a number of structures defined in the MQI. Every structure has:
A structure name
A more descriptive name and
A set of fields with permissible values
The visual depicts the object descriptor as an example of a structure. The structure name
is MQOD, the more descriptive name is "object descriptor", and a subset of its fields,
including some of their permissible values, are shown on the visual.
Transition Statement Next we look more closely at the MQI calls starting with
MQCONN, MQCONNX, and MQDISC.
Instructor Guide
Figure 3-5. Connecting and Disconnecting MQ157.0
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.
Connecting and Disconnecting
MQCONN (QMgrName, Hconn, CompCode, Reason)
MQCONNX (QMgrName, ConnectOpts, Hconn, CompCode, Reason)
- WebSphere MQ queue managers
version 5.1 cIients onIy
Connect queue manager
MQDSC (Hconn, CompCode, Reason)
Disconnect queue manager
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the MQCONN, MQCONNX, and MQDISC calls.
Details An application must first connect to a queue manager before it can access any of
the queue manager's resources. It issues an MQCONN or MQCONNX call in order to do
this.
In addition to CompCode and Reason, the parameters of the MQCONN call are as follows.
QMgrName
The name of the queue manager to which the application wishes to
connect. If the parameter consists entirely of blanks, the application
connects to the default queue manager.
Hconn The connection handle that is returned to the application. This handle
represents the connection to the queue manager and it must be specified
on all subsequent MQI calls to the queue manager.
A second attempt to connect to a queue manager to which an application is already
connected does not fail, but the existing connection handle is returned with an
MQCC_WARNING completion code and an MQRC_ALREADY_CONNECTED reason
code. A called program can use this device in order to discover what its connection handle
is.
The difference between the MQCONN and MQCONNX call is that the MQCONNX call has
an additional parameter, ConnectOpts, the connect options structure, MQCNO.
Normally, an application and the local queue manager agent, a component of the queue
manager, run as separate units of execution. This maintains the integrity of the queue
manager. However, the connect options structure allows a trusted application to specify
the fastpath binding option, MQCNO_FASTPATH_BINDING, on the MQCONNX call. By
using this option, an application and the local queue manager agent become part of the
same unit of execution. The advantage of such an arrangement is that fewer system
resources are required to run the application. The disadvantage is that the integrity of the
queue manager is compromised as there is no protection from overwriting its storage.
The environment variable MQ_CONNECT_TYPE can be used in conjunction with the type
of binding specified on the MQCONNX call. If the environment variable is defined, it should
have the value STANDARD or FASTPATH. An application will only run as a trusted
application if it has specified the fastpath binding option on the MQCONNX call and either
the environment variable is undefined or it has the value FASTPATH.
The MQCONNX call is supported on a Version 5 queue manager only.
Although MQSeries for Compaq OpenVMS does not support the MQCONNX call, it is still
possible to run an application as a trusted one. This is accomplished by defining the logical
name MQ_CONNECT_TYPE as FAST and running the application under the
MQS_SERVER UIC. Full details can be found in the MQSeries for Compaq OpenVMS
System Management Guide.
Instructor Guide
An application uses the MQDISC call to disconnect from a queue manager. At which point
the connection handle ceases to be valid.
There's a new MQI option to allow Hconns to be shared across threads of a process. This
has to be explicitly requested during MQCONNX by an application. These options are
available for both client and local binding applications. Lets look at a possible example with
a shared Hconn:
1. Thread 1 issues MQCONNX and gets a shared Hconn h1
2. Thread 1 opens a queue and issues a get request using h1.
3. Thread 2 issues a put request using h1.
4. Thread 3 issues a put request using h1.
5. Thread 2 issues MQDISC using h1.
There will still be one operation allowed on the Hconn at any one time, this includes the
MQGET(WAIT). Simultaneous request from 2 threads will either be serialized by the
queue manager or the second request will be rejected, depending on the connection
options used. In circumstances where it is feasible for one thread to wait for another thread
to complete, use MQCONNX with the option MQCNO_HANDLE_SHARE_BLOCK.
Any object handles (Hobj) created by opening an object are associated with an Hconn; so
for a shared Hconn, the Hobjs are also shared and usable by any thread using the Hconn.
Shared Hconns cannot be used within a global unit of work.
Any thread can call MQDISC to disconnect a shared Hconn, not just the thread that called
the corresponding MQCONNX. The MQDISC will terminate the Hconn making it
unavailable to all threads.
Transition Statement Next we look at the MQOPEN and MQCLOSE calls.
Instructor Guide
V2.0
Uempty
Figure 3-6. Opening and Closing an Object MQ157.0
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 attribute
may be MQQA_SHAREABLE or MQQA_NOT_SHAREABLE. The latter value takes
precedence over any input options specified on the MQOPEN call.
Opening and CIosing an Object
MQOPEN (Hconn, ObjDesc, Options, Hobj, CompCode, Reason)
Open object
The object handIe, Hobj, identifies the object in Iater caIIs
Open options can be added together; for exampIe, in C . . .
MQCLOSE (Hconn, Hobj, Options, CompCode, Reason)
CIose object
Options = MQOO_NPUT_SHARED + MQOO_FAL_F_QUESCNG;
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the MQOPEN and MQCLOSE calls.
Details The MQOPEN call establishes access to a WebSphere MQ object for specified
operations on the object. In addition to CompCode and Reason, the parameters of the
MQOPEN call are as follows.
Hconn The connection handle.
ObjDesc
The object descriptor. This identifies the object which the application
wishes to open.
Options Options which specify the operations the application wishes to perform on
the object being opened, for example, MQOO_INPUT_SHARED and
MQOO_OUTPUT, or which control the action of MQOPEN, for example,
MQOO_ALTERNATE_USER_AUTHORITY and
MQOO_FAIL_IF_QUIESCING.
Hobj The object handle returned to the application by MQOPEN. This handle
represents the access that has been established to the object and it must
be specified on all subsequent MQI calls that operate on the object.
An application may open an object multiple times. A different object handle is returned on
each MQOPEN call and each handle has to be closed.
If more than one option is required, the values can be added together or combined using
the bitwise OR operation. The only point to remember is that contradictory combinations of
options are not allowed, for example, MQOO_INPUT_SHARED and
MQOO_INPUT_EXCLUSIVE.
Note that the values of the attributes InhibitPut and InhibitGet of a queue are checked at the
time of a MQPUT call and a MQGET call respectively, and not at the time of an MQOPEN
call.
The MQCLOSE call relinquishes access to the queue. After the call, the object handle
ceases to be valid.
When an application issues an MQDISC call, it ends normally or abnormally. Any objects
that were opened by the application and are still opened are closed automatically.
However, it is good programming practice to close an object explicitly by issuing an
MQCLOSE call.
Transition Statement Next we look at the dynamic queue which is created by an
MQOPEN call.
Instructor Guide
Figure 3-7. Dynamic Queue MQ157.0
Notes:
A permanent dynamic queue may also be deleted by using the WebSphere MQ
command DELETE QLOCAL.
Dynamic Queue
Created when a model queue is opened
Following fields in the object descriptor are set before the
MQOPEN call
ObjectName identifies the model queue
DynamicQName specifies the name of the dynamic queue to
be created
After the MQOPEN call
ObjectName contains the name of the dynamic queue
Temporary dynamic queue
Deleted when the queue is closed
Does not survive a queue manager restart
Can store nonpersistent messages only
Permanent dynamic queue
Can be deleted by an option on the MQCLOSE call
Survives a queue manager restart
Can store persistent messages
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how a dynamic queue is created and deleted, and to compare the
two types of dynamic queue.
Details If the last non-blank character in the DynamicQName field is an asterisk (*), the
queue manager replaces the asterisk with a string of characters that guarantees that the
name generated for the dynamic queue is unique. If the asterisk is the only character in the
field, the name consists entirely of characters generated by the queue manager.
There are two types of dynamic queues, temporary and permanent.
A temporary dynamic queue is deleted automatically when it is closed using the same
object handle returned by the MQOPEN call which created it. As a result, a temporary
dynamic queue cannot be used to store persistent messages.
A permanent dynamic queue is not automatically deleted when it is closed and so is able to
store both persistent and nonpersistent messages. There are options on the MQCLOSE
call which can be used to delete it, but it may also be deleted by using the WebSphere MQ
command DELETE QLOCAL.
Transition Statement Next we look at the scope of the handles that are returned by the
MQCONN and MQOPEN calls.
Instructor Guide
Figure 3-8. Put Message MQ157.0
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.
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
Put Message
MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer,
CompCode, Reason)
MsgDesc
Message descriptor
nput fields set by the
application, output fields
by the queue manager
PutMsgOpts
Options, for example
MQPMO_SYNCPONT
MQPMO_FAL_F_QUESCNG
BufferLength
Length of the message in
Buffer
Buffer
Message data
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To describe the MQPUT call.
Details The MQPUT1 call opens a queue, puts one message on it, and then closes the
queue; that is, it encapsulates the MQOPEN, MQPUT, and MQCLOSE calls within a single
call. It should be used when the application only needs to put one message on a queue.
By contrast, the MQPUT call should be used when an application needs to put multiple
messages on the same queue.
You cannot use the MQPUT1 call with a model queue. However, once a dynamic queue
has been created, you can use the MQPUT1 call to put a message on that queue.
Transition Statement Next we look at message priority.
Instructor Guide
V2.0
Uempty
Figure 3-9. Priority MQ157.0
Notes:
Priority
Priority
FieId in the message descriptor, set by an appIication to one of
the foIIowing
A vaIue in the range 0 (Iowest) to 9 (highest)
MQPR_PRORTY_AS_Q_DEF
MsgDeliverySequence
Attribute of a local or model queue with values
MQMDS_PRORTY - messages returned by MQGET in priority
order
MQMDS_FFO - messages returned by MQGET in FFO order
DefPriority
Attribute of a queue specifying the default message priority
Used when an application sets Priority to
MQPR_PRORTY_AS_Q_DEF
Conventions
n general, use the default priority
Use the same priority as the original message for a reply or a report
Instructor Guide
Instructor Notes:
Purpose To explain how message priority is implemented.
Details When the message is put on a queue, the application may set the Priority field in
the message descriptor to a value in the range 0 (lowest priority) to 9 (highest priority).
This value determines the priority of the message which in turn may determine when the
message is retrieved from the queue by an MQGET call.
The way message priority is used depends upon the value of the MsgDeliverySequence
attribute of the queue. The permissible values of this attribute, and the effect of each one,
are as follows.
MQMDS_FIFO
Messages are returned by successive MQGET calls in FIFO (first in, first
out) order, regardless of priority.
MQMDS_PRIORITY
Messages are returned by successive MQGET calls in priority order.
Within each priority level, messages are returned in FIFO order.
On an MQPUT call, an application may also set the Priority field to the value
MQPRI_PRIORITY_AS_Q_DEF. In which case, the priority of the message is taken from
the DefPriority attribute of the queue.
From the point of view of administration, it is important to note that the position of a
message, in relation to the other messages on the queue, is determined by the values of
the MsgDeliverySequence and DefPriority attributes in force at the time the message
arrives on the queue. Thus, if you change either of these attributes, the relative order of the
messages already on the queue does not change.
If a message is put on a queue with a priority greater than the maximum, the MQPUT call
completes with an MQCC_WARNING completion code, the message is enqueued at the
maximum priority, but the Priority field retains the value specified by the application.
The recommended conventions allow some flexibility for priority tuning without having to
change application code.
Transition Statement Next we look at how to get a message from a queue.
Instructor Guide
V2.0
Uempty
Figure 3-10. Get Message MQ157.0
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.
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
Get Message
MQGET (Hconn, Hobj, MsgDesc, GetMsgOpts, BufferLength, Buffer,
DataLength, CompCode, Reason)
GetMsgOpts
Options, for example,
MQGMO_ACCEPT_TRUNCATED_MSG
MQGMO_BROWSE
MQGMO_CONVERT
MQGMO_FAL_F_QUESCNG
MQGMO_SYNCPONT
MQGMO_WAT
WaitInterval
BufferLength
Length of the Buffer area
Buffer
Area to contain the
message
data
DataLength
Length of the message
Instructor Guide
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 WaitInterval. The application may specify an unlimited wait.
BufferLength
The length of the Buffer area.
Buffer The area to contain the message data.
DataLength
The length of the message returned.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the MQGET call.
Details If the message on the queue is longer than BufferLength, the queue manager
moves as much of the message as possible into Buffer. Whether the message is actually
removed from the queue depends on whether the get message option
MQGMO_ACCEPT_TRUNCATED_MSG was specified or not. DataLength is always set to
the actual length of the message on the queue.
Transition Statement Next we look at the role of the reply-to queue.
Instructor Guide
Figure 3-11. Reply-to Queue MQ157.0
Notes:
RepIy-to Queue
The queue to which reply and report messages should be sent
Message descriptor fields set by the application prior to an MQPUT
call:
ReplyToQ
Can be the name of a dynamic queue or a reply-to queue alias
ReplyToQMgr
Can be set to blank
Queue name resolution may occur on an MQPUT call:
If ReplyToQMgr is bIank then
if ReplyToQ is a repIy-to queue aIias then
ReplyToQ and ReplyToQMgr are set to vaIues from the repIy-to queue
aIias definition
eIse
ReplyToQMgr is set to the name of the IocaI queue manager
endif
endif
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the use of a reply-to queue.
Details When an application puts a request message on a queue, it may set two fields in
the message descriptor to indicate where the reply message, or any requested report
messages, should be sent.
Note that a reply-to queue may be a dynamic queue.
Note also that the ReplyToQ field may be set by the application to the name of a reply-to
queue alias. Provided the ReplyToQMgr field is set to blank, the reply-to alias is resolved at
the time of the MQPUT call. The logic associated with this is depicted on the visual. The
resolution of a reply-to queue alias is the only time that queue name resolution takes place
other than when a queue is opened by an MQOPEN or MQPUT1 call.
Transition Statement Next we look at some more fields in the message descriptor.
Instructor Guide
Figure 3-12. More Fields in the Message Descriptor MQ157.0
Notes:
More FieIds in the Message Descriptor
MsgType
MQMT_DATAGRAM
MQMT_REQUEST
MQMT_REPLY
MQMT_REPORT
Report
Report options, for exampIe:
MQRO_EXCEPTON
MQRO_EXPRATON
MQRO_COA
MQRO_COD
MQRO_DSCARD
MQRO_PAN
MQRO_NAN
Expiry
Expiry time
Feedback
Used in a report message
Feedback or reason code, for
exampIe:
MQFB_EXPRATON
MQFB_COA
MQFB_COD
MQRC_Q_FULL
MQRC_NOT_AUTHORZED
MQFB_QUT
MQFB_PAN
MQFB_NAN
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe four more fields in the message descriptor.
Details The four fields shown on the visual are as follows:
MsgType
Four message types are currently defined by WebSphere MQ but other
types may be defined in the future. You can however define your own
types.
Expiry This is a period of time set by the application. The message becomes
eligible to be discarded if it has not been removed from the destination
queue before this period of time has elapsed.
Report This field is used by the application to specify which types of report
messages are required. Seven examples are shown on the visual.
Feedback
This field is only used in a report message. It indicates the nature of the
report or, for an exception report, the reason for the report. Some values of
this field are defined by WebSphere MQ but you can define your own
values as well. In exception reports, this field may also contain certain
reason codes. One special value, viz MQFB_QUIT, indicates that the
application should end.
Transition Statement Next we look at message and correlation identifiers.
Instructor Guide
Figure 3-13. Message and Correlation Identifiers MQ157.0
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.
Message and CorreIation Identifiers
Two fields in the message descriptor
MsgId, message identifier
f an application specifies MQM_NONE on an MQPUT call, the
queue manager generates a unique message identifier
CorrelId, correlation identifier
n a reply or report message, it is normally copied from the MsgId
of the original message
Both fields are treated as bit strings by the queue manager
Not subject to any data conversion
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To describe the message and correlation identifiers and their use.
Details When a queue manager generates a unique message identifier, it uses the first
12 characters of the queue manager name as part of the identifier.
Transition Statement Next we look at the role of the MsgId and CorrelId fields when
messages are being retrieved from a queue.
Instructor Guide
V2.0
Uempty
Figure 3-14. Retrieving Messages MQ157.0
Notes:
Retrieving Messages
With selection criteria
Set MsgId and/or CorrelId prior to an MQGET call
Also ensure that MatchOptions in get message options is set to
MQMO_MATCH_MSG_D + MQMO_MATCH_CORREL_D
(Version 5 and iSeries queue managers only)
Without selection criteria
Reset MsgId and CorrelId to MQM_NONE and MQC_NONE
respectively before each MQGET call
Or, set MatchOptions in get message options to MQMO_NONE
(Version 5 and iSeries queue managers only)
On return from an MQGET call, MsgId and CorrelId are set to the
values for the message retrieved
Instructor Guide
Instructor Notes:
Purpose To explain how the fields MsgId and CorrelId are used when retrieving
messages from a queue.
Details Using the MQGET call, an application may retrieve messages from a queue in
the order determined by the MsgDeliverySequence attribute of the queue. Alternatively, an
application may retrieve only selected messages from a queue according to the values in
their MsgId and/or CorrelId fields.
To retrieve a message with a specific message identifier and/or correlation identifier, the
application sets the MsgId and/or CorrelId fields in the message descriptor prior to an
MQGET call.
On a Version 5 queue manager, the field MatchOptions in get message options controls the
selection criteria used for an MQGET call. The initial value of this field is
MQMO_MATCH_MSG_ID + MQMO_MATCH_CORREL_ID which signifies that the values
in the MsgId and CorrelId fields are to be used as the selection criteria. An application may
therefore need to ensure that the MatchOptions field does indeed have this value if there is
a possibility that it has been changed.
In order to retrieve messages from a queue without selection criteria, the application needs
to set MsgId to MQMI_NONE and CorrelId to MQCI_NONE before each MQGET call. The
reason for this is that they are output fields on an MQGET call; they contain respectively the
message identifier and correlation identifier of the message just retrieved. Alternatively, on
a Version 5 queue manager, the MatchOptions field can be set to MQMO_NONE. This
relieves the application of the need to reset the MsgId and CorrelId fields prior to each
MQGET call.
Transition Statement Normally, when an application is retrieving messages from a
queue without using selection criteria, the order in which the messages are returned is not
important. But let us now look at what must be done if there is a strict requirement for the
messages to be returned in the same order as they were put by another application.
Instructor Guide
V2.0
Uempty
Figure 3-15. Order of Retrieving Messages MQ157.0
Notes:
Order of Retrieving Messages
Messages on a queue can be retrieved by an application in the
same order they were put by another application, provided:
The messages all have the same priority
The messages were all put within the same unit of work, or all
put outside of a unit of work
No other application is getting messages from the queue
The queue is local to the putting application
But they may be interspersed with messages put by other
applications
f the queue is not local to the putting application, the order of
retrieval is still preserved provided:
The first three conditions above still apply
Only a single path is configured for the messages
No message is put on a dead letter queue
No nonpersistent messages are transmitted over a fast message
channel
Instructor Guide
Instructor Notes:
Purpose To explain the circumstances under which an application can retrieve
messages from a queue in the same order as they were put by another application.
Details Most applications do not have a strict need for messages to be processed in
exactly the same order as they were created. But some applications may have such a
requirement, perhaps even a legal obligation to do so.
WebSphere MQ therefore documents the conditions under which an application can
retrieve a sequence of messages from a queue in the same order they were put by another
application. The conditions assume that the application retrieving the sequence of
messages is not using selection criteria.
The first set of conditions shown on the visual is concerned with the case that the
application putting the messages and the application getting the messages are both
connected to the same queue manager, that is, no remote queuing is involved. These
conditions are discussed more fully in the WebSphere MQ Application Programming
Guide.
The second set of conditions shown on the visual is concerned with the case that each
application is connected to a different queue manager and so remote queuing is involved.
These conditions are discussed more fully in WebSphere MQ Intercommunication.
Note that the facility of a fast message channel is only supported by the following queue
managers.
WebSphere MQ for AIX, iSeries, HP-UX, Linus, Solaris, Windows
WebSphere MQ for z/OS without CICS
MQSeries V5.1 for Compaq Tru64 UNIX, OS/2 Warp
In MQSeries for Compaq Open VMS Alpha fast messages are enabled differently.
Version 5 queue managers
MQSeries for OS/390 Version 1.2, when not using CICS for distributed queuing
MQSeries for Windows Version 2.1
On a fast message channel, nonpersistent messages may overtake persistent messages
on the same channel and so arrive out of sequence. This is because the receiving MCA
commits a nonpersistent message on its destination queue as soon as it receives it instead
of waiting for the end of the batch.
Note: Although WebSphere MQ for z/OS is outside the scope of this course, it is
referenced here because a message channel can only support fast nonpersistent
messages if the queue manager at each end of the channel can support them.
If the conditions depicted on the visual are not met, applications must either include
sequencing information in the application data of a messages or establish a means of
acknowledging receipt of a message before the next one is sent.
Instructor Guide
V2.0
Uempty
Transition Statement However, on a Version 5 queue manager, WebSphere MQ
provides additional function to support this requirement if these conditions are not met. We
shall look at this next.
Instructor Guide
Figure 3-16. Message Group MQ157.0
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.
Message Group
A message group:
Consists of one or more logical messages
A logical message is:
A physical message (unless it is split into segments)
dentified by the GroupId and MsgSeqNumber fields in the
message descriptor
Needed:
To ensure ordering on retrieval (where it is not already
guaranteed)
To allow an application to group together related messages
Version 5 and iSeries queue managers only
Message group
Logical message 1 Logical message 2 Logical message 3
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To explain the concepts of a message group and a logical message, and why
they are needed.
Details Nothing additional.
Transition Statement Next, we look at the concept of message segmentation.
Instructor Guide
V2.0
Uempty
Figure 3-17. Message Segmentation MQ157.0
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.
Message Segmentation
A segment is:
A physical message
dentified by the GroupId, MsgSeqNumber, and Offset fields in
the message descriptor
Segmentation is needed when a message is too large for an
application, a queue, or a queue manager
A message can be segmented and reassembled:
By the queue manager
By an application
Version 5 and iSeries queue managers only
Message group
Logical message 1 Logical message 2 Logical message 3
Segment 1 Segment 2
Instructor Guide
To ask the queue manager to segment a message if necessary, the putting application
simply 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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the concept of message segmentation and why it is needed.
Details The function described on this visual is supported by a Version 5 queue
manager only.
Transition Statement To finish the topic, we shall now look at how a distribution list
works.
Instructor Guide
Figure 3-18. Distribution List MQ157.0
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
Distribution List
DALLAS
PARIS
CALL MQOPEN . . .
ObjectName
MAIL_IN_HURSLEY
MAIL_IN_PARIS
MAIL_IN_DALLAS
MAIL_IN_SEATTLE
ObjectQMgrName
Distribution list
CALL MQPUT . . .
HURSLEY
SEATTLE
?
DALLAS
?
MAIL_IN
MAIL_IN
Version 5 and iSeries
queue managers only
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To explain what a distribution list is and how it works.
Details The function described on this visual is supported by a Version 5 queue manager
only.
A distribution list allows an application to put a message to multiple destinations using a
single MQPUT call. It works in the following way.
The application first opens a distribution list using an MQOPEN call. A distribution list is a
set of object records, where each object record has two fields, ObjectName and
ObjectQMgrName, specifying respectively the queue name and the queue manager name
of a single destination queue. When opening an a distribution list, the object descriptor's
own fields with the names ObjectName and ObjectQMgrName are both set to blank by the
application. A distribution list may therefore be thought of as an extension to the object
descriptor, or even as a variable length object descriptor.
Transition Statement End of the topic. The next topic is about triggering.
Instructor Guide
V2.0
Uempty 3.2 Triggering
This topic describes how triggering works and how to configure a queue manager for
triggering.
What students will do Students will listen to a presentation on triggering.
How students will do it A practical exercise on configuring a queue manager for
triggering follows the presentation.
What students will learn Students will learn how triggering works and how to configure a
queue manager for triggering.
understand the requirements of triggering from the point of view of administration.
Instructor Guide
Figure 3-19. Components of Triggering MQ157.0
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.
Components of Triggering
Queue Manager
2
6
4
3
Application
Queue
nitiation
Queue
MQPUT A-Q
Program A
MQGET A-Q
MQGET -Q
Trigger Monitor
Program B
5
1
Process
Object
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce the components of triggering.
Details An application does not have to be running when a message is sent to it; it can
start later. WebSphere MQ provides a facility that enables an application to be started
automatically when there are messages available for retrieval. This facility is known as
triggering.
A trigger monitor may start the application synchronously within its own unit of execution, or
asynchronously as a separate unit of execution.
Trigger monitors are supplied with WebSphere MQ but users may write their own.
Additional Information Triggering is supported by WebSphere MQ Clients running in
these environments:
Compaq Open VMS Alpha
OS/2
UNIX systems
Windows systems
Transition Statement Next we look at how to define an application queue for triggering.
Instructor Guide
Figure 3-20. Queue Attributes Controlling Triggering MQ157.0
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.
Queue Attributes ControIIing Triggering
DEFINE QLOCAL(MY_SERVER) TRIGGER +
PROCESS(ECHO) +
INITQ(SYSTEM.DEFAULT.INITIATION.QUEUE)
TRGGER
NOTRGGER
TRGMPR(integer)
TRGTYPE(FRST)
TRGTYPE(DEPTH)
...
TRGDPTH(integer)
TRGDATA(string)
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To describe how to define an application queue for triggering.
Details To define an application queue for triggering, the WebSphere MQ command
DEFINE QLOCAL must contain the following parameters.
TRIGGER
Triggering is enabled.
PROCESS(string),
The name of the process object which identifies the application that can
service the application queue.
INITQ(string)
The name of the initiation queue.
Additional parameters which control triggering may be specified. These are shown on the
visual.
For most purposes, trigger type FIRST is the most appropriate choice.
One example where trigger type DEPTH would be more appropriate is when an application
is expecting a fixed number of related reply messages and has created a dynamic queue to
receive them. The dynamic queue can be enabled for triggering by depth with TRIGDPTH
set to the number of reply messages expected.
For completeness, there are two more possible values for the TRIGTYPE parameter.
NONE No trigger event occurs. This has the same effect as NOTRIGGER.
EVERY A trigger event occurs for every message put on the application queue.
Additional Information The action of disabling triggering is not under syncpoint control,
so triggering cannot be reenabled simply by backing out a unit of work. If, a program backs
out a put request or if a program abends, that caused the triggered event, you must
re-enable triggering by using the MQSET call or the ALTER QLOCAL command.
Transition Statement Next we look at how to define a process object.
Instructor Guide
V2.0
Uempty
Figure 3-21. Process Attributes MQ157.0
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
Process Attributes
DEFINE PROCESS(ECHO) +
APPLICID('/opt/mqm/samp/bin/amqsech')
APPLCD(string)
Name of the application to be started
APPLTYPE(OS2)
APPLTYPE(UNX)
...
ENVRDATA(string)
For use by the trigger monitor
USERDATA(string)
For use by the trigger monitor or the started application
Instructor Guide
Instructor Notes:
Purpose To describe how to define a process object.
Details A process object identifies the application that can service an application queue.
What appears on the APPLICID parameter depends on the APPLTYPE parameter. The
following are two examples.
A fully qualified file name of an executable object for APPLTYPE(UNIX), as depicted on
the visual.
A CICS transaction ID for APPLTYPE(CICS).
Remember that for all MQSeries or WebSphere MQ Version 5 products, if you want to
trigger the start of a channel, you do not need to define a process definition object. The
transmission queue definition can determine the channel to be triggered.
Transition Statement Next we look at the conditions for a trigger event to occur.
Instructor Guide
V2.0
Uempty
Figure 3-22. Conditions for a Trigger Event MQ157.0
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 Guide.
Conditions for a Trigger Event
1. A message is put on a queue
2. Priority of the message is not below TRGMPR
3. Number of messages previously on the queue is correct for
TRGTYPE
4. Queue is not already open for input (FRST and DEPTH only)
5. Queue is enabled for get requests
6. Process object exists
7. nitiation queue exists, and is enabled for put and get requests
8. Trigger monitor has the initiation queue open for input
9. Queue is defined as TRGGER
10. Queue is not defined as TRGTYPE(NONE)
Instructor Guide
Instructor Notes:
Purpose To explain the conditions for a trigger event to occur.
Details The following is a list of the conditions for a trigger event to occur. Each
condition has been summarized.
1. A message is put on a queue.
2. The priority of the message is greater than or equal to the value of the
TriggerMsgPriority attribute of the queue.
3. The number of messages on the queue with priority greater than or equal
TriggerMsgPriority was previously:
Zero, for trigger type FIRST.
Any number, for trigger type EVERY.
TriggerDepth minus 1, for trigger type DEPTH.
4. For triggering of type FIRST or DEPTH, no program has the application queue open for
removing messages (the OpenInputCount of the local queue attribute is zero).
5. The queue is enabled for get requests.
6. The process object identified by the queue attribute ProcessName exists.
7. The initiation queue identified by the queue attribute InitiationQName exists, and is
enabled for put and get requests.
8. A trigger monitor currently has the initiation queue open for removing messages (the
OpenInputCount of the local queue attribute is greater than zero).
9. Trigger control for the application queue is enabled; that is, the attribute TriggerControl
is set to MQTC_ON.
10. The value of the attribute TriggerType of the application queue is not MQTT_NONE.
Note that all the above conditions must be satisfied for a trigger event to occur.
Additional Information If all of the above required conditions are met, and the message
that caused the trigger condition is part of a unit of work, the trigger message does not
become available for retrieval by the trigger monitor application unit the unit of work
completes, whether the unit of work is committed or, the trigger type FIRST or DEPTH, is
backed out.
Transition Statement Next we look at some other situations in which a trigger event can
occur.
Instructor Guide
V2.0
Uempty
Figure 3-23. Other Conditions for a Trigger Event MQ157.0
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.
Other Conditions for a Trigger Event
For each of the above conditions, a trigger event wiII onIy occur if:
A sufficient number of messages for the trigger type are aIready on the
queue
Other reIevant trigger conditions are aIso satisfied
A message is put on the queue which:
Was not previously empty (FRST)
Had TRGDPTH or more messages (DEPTH)
and, for trigger type FRST, a sufficient interval has elapsed since the last
trigger event as determined by the TriggerInterval attribute of the queue
manager object (FRST and DEPTH only)
Only application serving the queue closes it (FRST and DEPTH only)
Attribute of the queue controlling triggering is changed
nitiation queue changes from being disabled to being enabled for
put requests
Queue changes from being disabled to being enabled for get
requests
Trigger monitor opens the initiation queue
Instructor Guide
Instructor Notes:
Purpose To describe the other conditions for a trigger event to occur.
Details So far we have looked at the usual set of conditions under which a trigger event
occurs.
However, situations can occur in which there are already a sufficient number of messages
for the trigger type on an application queue but not all the trigger conditions are satisfied.
And so, without the additional conditions shown on the visual, a trigger event might never
occur.
For example, when a trigger monitor opens an initiation queue for input, the queue
manager generates a trigger message for each application queue whose definition
references the initiation queue. This is provided an application queue already has a
sufficient number of messages on it for its respective trigger type and any other relevant
trigger conditions are also satisfied. Such a situation might occur following a queue
manager restart and there are still persistent messages on the application queues.
Note that each of the conditions shown on the visual may cause a trigger event. Each
condition has been summarized. A full statement of each condition can be found in the
WebSphere MQ Application Programming Guide.
Transition Statement Next we look at the contents of a trigger message.
Instructor Guide
V2.0
Uempty
Figure 3-24. Fields in the Trigger Message MQ157.0
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.
FieIds in the Trigger Message
Copied from the corresponding attributes of the application queue
QName
TriggerData
ProcessName
Copied from the corresponding attributes of the process object
ApplType
ApplId
EnvData
UserData
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the contents of a trigger message.
Details A trigger message is put on an initiation queue when a trigger event occurs. The
trigger message structure has the name MQTM and is documented in the WebSphere MQ
Application Programming Reference.
Some of the fields in a trigger message are derived from certain attributes of the
application queue and some are derived from certain attributes of the process object
referenced by the definition of the queue.
From the point of view of the trigger monitor, the main purpose of a trigger message is to
identify the application to be started.
Transition Statement Next we look more closely at the trigger monitor and what it does
when it gets a trigger message.
Instructor Guide
Figure 3-25. Trigger Monitor MQ157.0
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.
Trigger Monitor
<ApplId> "<MQTMC2>" <EnvData>
Command issued by trigger monitor to start the application
Other trigger monitors
Client trigger monitor (AX, Digital OpenVMS, and OS/2 Warp
only)
CCS (AX, OS/2 Warp, and Windows only)
AMQSTRG4 and AMQSERV4 (iSeries only)
runmqtrm -m QMgrName -q InitiationQName
To start a trigger monitor
Instructor Guide
V2.0
Uempty
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 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.
Instructor Guide
Instructor Notes:
Purpose To explain how a trigger monitor works.
Details A trigger monitor is a long running program which gets a trigger message from
an initiation queue and starts an application to service the application queue.
Note the following regarding the command used by the supplied trigger monitor runmqtrm
to start an application.
In order to run the started application in the background on OS/2 or Windows, the value
of the ApplId attribute of the process object should contain the program name preceded
by the START command. For example:
START AMQSECH
In order to run the started application in the background on UNIX systems, the value of
the EnvData attribute of the process object should terminate with the ampersand (&)
symbol.
The C source of a sample trigger monitor, amqstrg0, is supplied for OS/2 Compaq NonStop
Kernel, UNIX systems, and Windows Systems. On WebSphere MQ for iSeries the C
source of the trigger monitors AMQSTRG4 and AMQSERV4 is supplied. You can therefore
use any of these samples as a basis for writing your own trigger monitor, if required.
For more information on the trigger monitors supplied with WebSphere MQ, see the
WebSphere MQ Application Programming Guide.
Transition Statement Next we look at how trigger monitor errors are handled.
Instructor Guide
V2.0
Uempty
Figure 3-26. Trigger Monitor Errors MQ157.0
Notes:
Trigger Monitor Errors
Messages are produced by the following
Normal activities, for example,
Trigger monitor started
Waiting for a trigger message
Trigger monitor ended
Abnormal conditions, for example
nitiation queue could not be opened
Use of trigger monitor not authorized
Error starting triggered application
A message may be written to:
The standard output device
An error log
A trigger message is written to the dead letter queue if, for example:
The trigger message structure is not valid
The trigger message specifies an unsupported application type
The trigger message can not be converted
Instructor Guide
Instructor Notes:
Purpose To describe how trigger monitor errors are handled.
Details Messages relating to the operation of a trigger monitor are produced for two
reasons.
There are messages to report on normal activities such as when a trigger monitor starts
and when it ends. These messages do not normally require any user action.
There are messages to report on abnormal conditions such as when a trigger monitor
fails to open the initiation queue or when it fails to start the specified application. These
messages normally indicate that user action is required to correct the condition.
A message may be written to the standard output device and to an error log with more
information. Error logs will be discussed later in the course.
If the RUNMQTRM trigger monitor in MQSeries for OS/2 Warp and WebSphere MQ on
UNIX detects an error, the trigger monitors may put a trigger message on the dead-letter,
having added a dead-letter headere structure (MQDLH) to the message. It uses the a
feedback code in the Reason field of the structure to explain why it put the message on the
dead-letter queue. This does not apply to WebSphere MQ for iSeries; neither AMQSTRG4
nor AMQSERV4 put trigger messages on the dead-letter queue.
Transition Statement End of the topic. There is now a practical exercise on configuring
a queue manager for triggering.
Instructor Guide
V2.0
Uempty 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.
What students will do Students will listen to a presentation on WebSphere MQ
Publish/Subscribe.
How students will do it Through classroom discussion and checkpoint questions.
What students will learn Students will learn how Publish/Subscribe works as well as
how to set it up and manage it.
understand the benefits of using Publish/Subscribe as well as what is necessary to work
with it.
Instructor Guide
Figure 3-27. WebSphere MQ Publish/Subscribe MQ157.0
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.
WebSphere MQ PubIish/Subscribe
BROKER
PubIisher 2
Topic:Stock
Subscriber 1
Topic:Sport, Stock
PubIisher 3
Topic:FiIms
Subscriber 2
Topic:FiIms
Subscriber 3
Topic:Sport
PubIisher 1
Topic:Sport
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To introduce WebSphere MQ Publish/Subscribe.
Transition Statement Next, a look at the installation of WebSphere MQ
Publish/Subscribe.
Instructor Guide
V2.0
Uempty
Figure 3-28. Installing WebSphere MQ Publish/Subscribe MQ157.0
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.
InstaIIing MQSeries PubIish/Subscribe
MQSeries or WebSphere MQ for AX, HP-UX, Sun Solaris, Linux,
and Windows V5.0 or later
CSDs required for V5.0
Obtain via download as a SupportPac MA0C
Category 3
Separate files for each platform
MA0D - Getting Started with MQSeries Publish/Subscribe
document (Category 2)
Print User Guide and follow instructions to run VP.
Instructor Guide
Instructor Notes:
Purpose To describe how to obtain and install the WebSphere MQ Publish/Subscribe.
Details It might be handy to have a copy of the MQSeries Publish/Subscribe User's
Guide and to review it before class at a minimum.
Transition Statement The major piece that requires administrative support is setting up
the broker.
Instructor Guide
V2.0
Uempty
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.
Setting Up the Broker
Queues for each broker automatically defined when broker starts if
they do not exist
SYSTEM.BROKER.CONTROL.QUEUE
SYSTEM.BROKER.DEFAULT.STREAM
SYSTEM.BROKER.ADMN.STREAM
SYSTEM.BROKER.MODEL.STREAM
SYSTEM.BROKER...
Created by the broker for internal use
Authorize applications to use these queues
Update configuration information
n qm.ini or Windows NT Registry depending on platform and
release level
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how to configure the broker.
Details If someone wants to dig into each of the parameters in the broker stanza, it
would be useful to have a copy of the MQSeries Publish/Subscribe User's Guide. This is
not the level of detail for this course though.
Additional Information For MQSeries for Windows NT and 2000, V5.2 or Windows NT
V5.1, you can use the broker configuration tool. This tool has a graphical user interface for
setting up the broker configuration parameters. To start the tool issue cfgmqbrk, on the
command line.
Transition Statement Once the broker is set up, control commands are used to operate
it.
Instructor Guide
Figure 3-30. Controlling the Broker MQ157.0
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
ControIIing the Broker
Starting - strmqbrk
Can be triggered
Stopping - endmqbrk
Displaying - dspmqbrk
Deleting - dltmqbrk
Clearing - clrmqbrk (exceptionaI condition)
Migrating - migmqbrk
Instructor Guide
V2.0
Uempty
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 stream
queues)
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.
Instructor Guide
Instructor Notes:
Purpose Describe the control commands used to manage the broker.
Details
Transition Statement It is possible to extend the capability of the broker with regard to
publications.
Instructor Guide
V2.0
Uempty
Figure 3-31. Message Broker Exits MQ157.0
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.
Message Broker Exits
Allow customization of publications at broker
Can alter publication and MQMD
Configured in qm.ini (or Windows NT Registry)
Sample exit provided
Changes destination queue or queue manager
Instructor Guide
Instructor Notes:
Purpose To describe the basic concepts of a broker exit.
Details Again - not too much detail. This is a bit heavy for this course.
Transition Statement Now it is time to review the things learned in this unit and to do a
practical exercise.
Instructor Guide
V2.0
Uempty 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.
Correct Answer: a
3. When an application issues an MQPUT of a message and explicitly
sets 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.
Correct Answer: c
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
Correct Answer: b, d
Instructor Guide
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.
Unit Summary
The MQ
The major calls
MQCONN and MQDSC
MQOPEN and MQCLOSE
MQPUT and MQGET
Some of the more common parameters, fields, and options
Message group and message segmentation
Distribution list
Triggering
Focus on administration tasks
Publish/subscribe enables applications to get at data without
knowing the source or destination of it
Exercise 2
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details In the first topic of this unit, we reviewed the main MQI calls and some of the
more common parameters, fields, and options.
In the second topic, we looked at how triggering works and how to configure a queue
manager for triggering.
There was then a practical exercise on configuring a queue manager for triggering.
Although no practical exercise is included, the information on WebSphere MQ
Publish/Subscribe should assist anyone wishing to use it.
Transition Statement End of the unit. Next, we discuss robust messaging.
Instructor Guide
Instructor Guide
Copyright IBM Corp. 1996, 2003 Unit 4. Robust Messaging 4-1
V2.0
Uempty
Unit 4. Robust Messaging
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.
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
Accountability:
Machine exercises
References
If iSeries:
Instructor Guide
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.
Unit Objectives
Explain WebSphere MQ architecture and framework at a high level
Describe problem determination aids and how to use them
Define message persistence
Detail logging options on various queue managers
Explain the purpose of transactional processing
Contrast local and global units of work
List external transaction managers and where supported
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details
The structure of WebSphere MQ is described as a basis for what follows.
Aids for problem determination.
Recovery and transactional support.
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.
Transition Statement First, a look at the functional components of a WebSphere MQ
implementation.
Instructor Guide
Instructor Guide
V2.0
Uempty 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.
What students will do Students will listen to a presentation on the WebSphere MQ
reference architecture.
What students will learn Students will learn how WebSphere MQ is structured on most
of the Level 2 queue managers.
How this will help students on their job This knowledge will help the students
understand more readily the problem determination tools described in the following topic.
Instructor Guide
Figure 4-2. Functional View MQ157.0
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.
FunctionaI View
Application
Local Queue
Manager
Trigger
Monitor
Message
Channel
Agent
Common
Services
Command
Server
OAM
MQI AppIication Interface
DAP
C
o
m
m
s
Q
Q
Q
Q
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the functional components of a typical WebSphere MQ
implementation. The amount of detail can be adjusted to suit the audience.
Details The following is more information on specific components.
Application interface (AI)
Provides the entry points for the MQI and internal calls used by other
WebSphere MQ components. It also provides the language bindings for
calls from C and COBOL.
Its main purpose is to isolate queue manager resources from the
applications.
Queue manager kernel
Implements the functions of the MQI and the control commands. For
example:
MQPUT, MQGET, MQOPEN
Trigger events
Management of object handles
Authorization via the OAM
Object Authority Manager (OAM)
Provides access control to the queue manager resources.
Data abstraction and persistence (DAP)
This component provides the following function.
Storage and manipulation of objects
Message operations
Message persistence
Transactional support
Logging changes to queue manager resources
Common services
Provides low level services to other WebSphere MQ components.
Message channel agent (MCA)
Provides the function to move messages from one queue manager to
another over a network. To avoid the loss of any persistent messages, an
MCA communicates with its partner MCA using a defined set of
WebSphere MQ formats and protocols.
Communications
An MCA uses a communications protocol such as SNA LU6.2 or TCP/IP in
order to send data over the network to its partner MCA and receive data
from its partner.
Instructor Guide
Transition Statement This was a functional description. Next we look at the physical
structure.
Instructor Guide
V2.0
Uempty
Figure 4-3. Physical View MQ157.0
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.
Application
MQ stub
IPCC
Execution
ControIIer
Queue
Manager
Resources
LQM
Agent
Logger
Checkpoint
Processor
MQCONN
MQOPEN
MQGET
PhysicaI View
Instructor Guide
Instructor Notes:
Purpose To describe the physical structure of most of the Level 2 queue managers.
Details The previous visual depicted the functional components. We now look at the
physical structure in terms of the processes that are run.
The execution controller is the first process to start when the queue manager is started.
It oversees all other processes, controls start up and shutdown, and manages
connection requests. IPCC provides local interprocess communications between the
queue manager components. It abstracts underlying operating system facilities and is
based on shared memory and synchronization primitives.
A local queue manager (LQM) agent performs work on behalf of applications. It is
where the queue manager kernel and the DAP run and is assigned by the execution
controller during MQCONN.
On MQSeries for OS/2 Warp and WebSphere MQ for Windows, the local queue
manager agent is thread based and so a single agent process can support a number of
connected applications.
The MQI stub provides the language binding to the application. It first manages the
connection of an application to a queue manager and, once that has been
accomplished, it packages subsequent MQI calls and sends them to the local queue
manager agent.
WebSphere MQ components like MCAs, which are themselves applications, also have a
local queue manager agent assigned by the execution controller.
This arrangement, which separates the applications from the queue manager, is used to
protect queue manager resources from inadvertent or malicious update by applications.
Each major element runs in its own process with protected addressing. Queue manager
resources are shared amongst the components of the queue manager using shared
memory, with protected access where available.
However, if better performance is required, we have already seen that, on MQSeries for
Compaq OpenVMS and on a Version 5 queue manager, a trusted application can connect
to a queue manager using fastpath binding. In this mode, an application and the local
queue manager agent become part of the same unit of execution.
The remaining processes depicted on the visual are as follows.
The logger records information in the log which is used in the coordination of units of
work and in the recovery of persistent messages and WebSphere MQ objects.
The checkpoint processor performs regular checkpoints on the log. Checkpoints
reduce queue manager restart time by minimizing the amount of the log which has to be
scanned.
On WebSphere MQ for iSeries, WebSphere MQ code invoked synchronously by a call to
the MQI from an application runs in the same process as the application. For performance
reasons, no process switching occurs. The isolation is provided instead by the WebSphere
Instructor Guide
V2.0
Uempty
MQ code running with adopted authority. In this way, only the WebSphere MQ code can
access and modify libraries and objects owned by WebSphere MQ.
Transition Statement Next we look at the resulting process structure.
Instructor Guide
Figure 4-4. Processes MQ157.0
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.
Processes
Execution
ControIIer
LQM
Agent
Logger
Checkpoint
Processor
amqzxma0
amqzlaa0
amqhasmx amqzllp0
Log
Formatter
amqharmx
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the processes of a queue manager.
Details The number of local queue manager agents varies with the number of
concurrently connected applications. On queue managers which do not use threads
internally, such as on UNIX systems, there is one local queue manager agent per
connected application.
The operation of MQSeries for OS/2 Warp and WebSphere MQ for Windows requires some
additional processes which are not needed on the other queue managers. They are
background processes to manage shared memory. WebSphere MQ for Windows also has
an extra trace process.
The names of the executables illustrated on the visual are typical of a UNIX
implementation. The names may be slightly different on other queue managers.
The process structure on MQSeries for Tandem NonStop Kernel is different as each queue
manager runs under its own TS/MP (PATHWAY) configuration.
Transition Statement Next we look at the way that data associated with a queue
manager is organized.
Instructor Guide
Figure 4-5. Directory Structure MQ157.0
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.
Directory Structure
Path to the queue manager directory
Prefix
MQS_ROOT:[MQM] (MQ Series for Compaq OpenVMS)
\MQM\ (MQ Series for OS/2 Warp and WebSphere for Windows)
/var/mqm/ (MQ Series for Unix Systems)
Literal
qmgrs
Queue manager name
Transformed name if not a valid file system name
Name of a queue or a process object
No simple transformation to a file system name
Use the control command dspmqfIs to determine the mapping
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To describe the directory structure where WebSphere MQ manages its data.
Details The directory contents for each of the queue managers are listed in the following
publications.
WebSphere MQ for iSeries V5.3 System Administration Guide for a Version 5 queue
manager.
The relevant System Management Guide for each of the remaining queue managers.
The names of the libraries where WebSphere MQ for iSeries holds its data are listed in the
WebSphere MQ for iSeries V5.3 SYstem Administration Guide. A full description of the
contents of the queue manager subvolumes for MQSeries for Tandem NonStop Kernel can
be found in the MQSeries for Tandem NonStop Kernel System Management Guide.
Since the rules for naming a queue manager are not the same as the rules for forming a file
system name, a queue manager name may need to be transformed in order to form a valid
name for the queue manager directory. The rules for transforming a queue manager name
are as follows.
Transform individual characters.
. becomes !
/ becomes &
If the name is still invalid:
- Truncate to eight characters.
- Append a three character numeric suffix.
For example, assuming the default prefix:
queue.manager ---> /var/mqm/qmgrs/queue!manager
On MQSeries for Compaq OpenVMS, the rules for transforming a queue manager name
are the same except that individual characters are transformed as follows.
. becomes $
/ becomes _
% becomes _
The transformation algorithm also allows for distinguishing between names which differ
only in case on case insensitive file systems such as FAT and HPFS.
A more complex transformation algorithm is used to form the names of files representing
queues and process objects because there are more of them. There is no simple
relationship between an WebSphere MQ name and a transformed name. Use the
dspmqfls control command to convert between an WebSphere MQ name and a
transformed name.
WebSphere MQ for Windows does not need to transform the names of WebSphere MQ
objects because of the support for long names.
Instructor Guide
V2.0
Uempty
Transition Statement Next we look at configuration files.
Instructor Guide
Figure 4-6. Configuration Files MQ157.0
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.
Configuration FiIes
Purpose
To define values for individual queue managers and for
WebSphere MQ as a whole
To tailor a specific queue manager
Mechanism
Configuration files containing human readable information
Creation
During installation and queue manager creation
Modification
By commands
For specific purposes, by editing
Recommendation
Back up after significant changes
Instructor Guide
V2.0
Uempty
- The appropriate System Management Guide for each of the remaining queue
managers.
- WebSphere MQ Intercommunication.
Instructor Guide
Instructor Notes:
Purpose To introduce the two kinds of configuration files.
Details WebSphere MQ uses two types of configuration file.
Purpose
- To define values for individual queue managers and for WebSphere MQ as a whole.
- To tailor a specific queue manager.
Mechanism
- Configuration files, also referred to as ini files or stanza files, containing human
readable information.
Creation
- During installation.
- During queue manager creation.
Modification
- By commands.
- Occasionally, and for specific purposes, by editing.
Recommendation
- Back up the WebSphere MQ configuration file after installation and after creating a
new queue manager.
- Back up a queue manager configuration file after creating the queue manager.
Transition Statement Next we look at the WebSphere MQ configuration file.
Instructor Guide
V2.0
Uempty
Figure 4-7. WebSphere MQ Configuration File MQ157.0
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.
WebSphere MQ Configuration FiIe
Created when WebSphere MQ is installed
mqs.ini
Default location
MQS_ROOT:[MQM] (MQ Series for Compaq OpenVMS)
MQM directory of boot drive (MQ Series for OS/2 Warp)
$SYSTEM.ZMQSSYS.MQSN (MQ Series for Tandem NSK)
/var/mqm (WebSphere MQ for Unix systems)
Content
Path to files associated with each queue manager
Default log parameters (not on MQ Series for Tandem
NonStop KerneI or WebSphere MQ, Windows NT V5.1)
Stanza for each queue manager
Name of the default queue manager
WebSphere MQ for Windows stores similar information in the
Windows Registry ( no mqs.ini)
Instructor Guide
Instructor Notes:
Purpose To describe some uses of the WebSphere MQ configuration file and to explain
where to find the file.
Details
AllQueueManagers
This stanza specifies the path to the qmgrs directory, effectively indicating
where the files associated with any newly created queue manager will be
located.
On MQSeries for Tandem NonStop Kernel, there is no qmgrs directory, but
the stanza still contains the equivalent information by specifying the default
queue manager volume for any newly created queue manager. You are
prompted to enter the name of the default queue manager volume during
the installation. If you wish to create a queue manager with a home volume
which is not the default queue manager volume, you may specify the home
volume by means of a parameter on the crtmqm command.
LogDefaults
The values in this stanza are the default log parameters for the system.
They can be overridden by parameters on the crtmqm command. Each
queue manager configuration file contains a similar stanza specifying the
values actually in effect for that queue manager.
The LogDefaultPath is particularly important. For greater data integrity,
the queue manager and its log should be on separate physical volumes.
The values of DefaultPrefix and LogDefaultPath allow for the
separation of these two although the default values cause them to be
placed together. On a UNIX system, it may also be possible to achieve this
separation by creating and mounting a /var/mqm file system and a
/var/mqm/log file system on separate physical volumes. Read the
instructions on what to do before installation in the relevant publication.
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.
DefaultQueueManager
This stanza specifies the name of the default queue manager.
QueueManager
There is one such stanza for each queue manager. It specifies the name of
the queue manager and the location of the files associated with the queue
manager.
The path to the files is formed from the value of Prefix, the literal qmgrs,
and the value of Directory.
Instructor Guide
V2.0
Uempty
On MQSeries for Tandem NonStop Kernel, a stanza for a queue manager
specifies the name of the queue manager, its home volume, and the
subvolume prefix, that is, the transformed or shortened queue manager
name if it has been necessary to form one.
Transition Statement Next we look an example of the WebSphere MQ configuration file.
Instructor Guide
Figure 4-8. MQS.INI Configuration File MQ157.0
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.
#***********************************************************************#
#* Module Name: mqs.ini *#
#* Type : WebSphere MQ Configuration File *#
#* Function : Define WebSphere MQ resources for the node *#
#***********************************************************************#
AllQueueManagers:
#***********************************************************************#
#* The path to the qmgrs directory, below which queue manager data *#
#* is stored *#
#***********************************************************************#
DefaultPrefix=/var/mqm
LogDefaults:
LogPrimaryFiles=3
LogSecondaryFiles=2
LogFilePages=1024
LogType=CIRCULAR
LogBufferPages=0
LogDefaultPath=/var/mqm/log
QueueManager:
Name=saturn.queue.manager
Prefix=/var/mqm
Directory=saturn!queue!manager
QueueManager:
Name=pluto.queue.manager
Prefix=/var/mqm
Directory=pluto!queue!manager
DefaultQueueManager:
Name=saturn.queue.manager
|
MQS.INI Configuration FiIe
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To view the WebSphere MQ config file.
Details
Additional Information
Transition Statement Next we will look at the queue manager configuration file.
Instructor Guide
Figure 4-9. Queue Manager Configuration File MQ157.0
Notes:
On WebSphere MQ for Windows the queue manager configuration information is stored
in the Windows Registry
On WebSphere 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.
Queue Manager Configuration FiIe
Created when the queue manager is created
qm.ini
n the queue manager directory
Content
The queue manager log configuration
(not on WebSphere MQ for Tandem NonStop KerneI)
Details of installable service components
Values relating to the operation of channels
Communications protocol configuration parameters
XA resource manager information
(Version 5 queue managers onIy)
WebSphere MQ for Windows stores similar information in the
Windows Registry ( no qm.ini)
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To describe the queue manager configuration file.
Details Editing a configuration file should only be done in special cases. Some
examples of when you may need to do this are given below.
If you lose a configuration file, or if it becomes damaged. Recover from a backup if
possible.
If you need to move one or more queue managers to a new directory.
When instructed to do so by IBM Service personnel.
When implementing an installable service component.
Transition Statement We will look at an example of the queue manager configuration
file.
Instructor Guide
V2.0
Uempty
Figure 4-10. QM.INI Configuration File MQ157.0
Notes:
QM.INI Configuration FiIe
#*******************************************************************#
#* Module Name: qm.ini *#
#* Type : WebSphere MQ queue manager configuration file *#
# Function : Define the configuration of a single queue manager *#
#*******************************************************************#
ExitPath:
ExitsDefaultPath=/var/mqm/exits
Service:
Name=AuthorizationService
EntryPoints=9
ServiceComponent:
Service=AuthorizationService
Name=MQ.UNIX.auth.service
Module=/opt/mqm/bin/amqzfuno.o 1
ComponentDataSize=0
Service:
Name=NameService
EntryPoints=5
ServiceComponent:
Service=NameService
Name=MQ.DCE.name.service
Module=/opt/mqm/lib/amqzfa 2
ComponentDataSize=0
Log:
LogPrimaryFiles=3
LogSecondaryFiles=2
LogFilePages=1024
LogType=CIRCULAR
LogBufferPages=0
LogPath=/var/mqm/log/saturn!queue!manager/
XAResourceManager:
Name=DB2 Resource Manager Bank
SwitchFile=/usr/bin/db2swit
XAOpenString=MQBankDB
XACloseString=
ThreadOfControl=THREAD
CHANNELS:
MaxChannels = 20 ; Maximum number of Channels allowed.
MaxActiveChannels = 100 ; Maximum number of Channels allowed to be
; active at any time.
TCP: ; TCP/IP entries.
KeepAlive = Yes ; Switch KeepAlive on
Instructor Guide
Instructor Notes:
Purpose To view the queue manager config file
Details
1. /usr/mqm/bin/amqfuno.o on AIX
2. /usr/mqm/lib/amqzfa on AIX
Transition Statement Next we will look at installable services.
Instructor Guide
V2.0
Uempty
Figure 4-11. Installable Services MQ157.0
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.
InstaIIabIe Services
Formal interfaces, more than exits
Multiple entry points
For example:
Name Service
nitialize
Terminate
nsert
Delete
Lookup
Service components can be chained
WebSphere MQ System Administration Guide
Instructor Guide
Instructor Notes:
Purpose To introduce the concept of an installable service and a service component.
Details This is a formalized way of providing certain extensions to WebSphere MQ.
Unlike exits, they have multiple entry points.
Transition Statement Next we look at the three installable services and the supplied
service components.
Instructor Guide
V2.0
Uempty
Figure 4-12. Installable Services and Supplied Components MQ157.0
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.
InstaIIabIe Services and SuppIied Components
Name service
Supplied component uses DCE
WebSphere MQ for Compaq OpenVMS and the Version 5
queue managers
Authorization service
Supplied component is the Object Authority Manager (OAM)
WebSphere MQ for Windows, iSeries, and on UNX systems
(Nonstop Kernel, MQSeries for Compaq, Tandem)
User identifier service
Supplied component on MQ Series for OS/2 Warp
DEFINE QLOCAL('ServiceQ') SCOPE(CELL)
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce the three installable services and their supplied components.
Details
The figure below depicts the service and service component stanzas which added
automatically to the queue manager configuration file on a UNIX system in order to enable
the authorization service and identify the OAM to the queue manager.
Service This stanza enables the authorization service. It specifies:
The name of the service. This is defined by the service.
The number of entry points defined for the service.
ServiceComponent
This stanza identifies the OAM to the queue manager. It specifies:
The name of the service for which the OAM is a component.
A unique descriptive name for the component.
The name of the module containing the code for the component.
The size in bytes of the component data area passed to the component
on each call.
Transition Statement Next we look at how to stop a queue manager manually in case it
is ever necessary to do it.
Service:
Name=AuthorizationService
EntryPoints=8

ServiceComponent:
Service=AuthorizationService
Name=MQSeries.UNIX.auth.service
Module=mqmtop/bin/amqzfu.o
ComponentDataSize=0
Instructor Guide
Figure 4-13. Stopping a Queue Manager Manually MQ157.0
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.
Normally use endmqm
May take time
Give it a chance!
LAST RESORT
Find the processes that are still running
Stop them in the following order
amqc... Channel processes first
..............
amqzxma0 Execution controller last
Stopping a Queue Manager ManuaIIy
ps -ef | grep amq
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To explain how to stop a queue manager manually if endmqm does not
succeed in doing so.
Details The normal way of stopping a queue manager is to use the endmqm control
command. You may still encounter problems which are often caused by the way
applications are written, for example, by not checking completion codes and reason codes
properly, or by not using the "fail if quiescing" option.
The use of endmqm -p should stop a queue manager under any circumstances. You may
have to wait a minute or so. Give it a chance!
There may be occasions when the use of endmqm does not stop everything. If you really
have to stop any residual processes manually, do it in the recommended sequence.
Transition Statement Next we look at how to remove a queue manager manually in case
it is ever necessary to do it.
Instructor Guide
V2.0
Uempty
Figure 4-14. Removing a Queue Manager Manually MQ157.0
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.
Normally:
f there are problems:
Delete the queue manager directory and its contents
Delete the associated log directory and its contents
Remove the queue manager's stanza from the
WebSphere MQ configuration file
Remove or change the DefaultQueueManager stanza if
required
WebSphere MQ for Windows requires manual changes in the
Windows Registry
Removing a Queue Manager ManuaIIy
dItmqm QMgrName
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how to remove a queue manager manually if an error prevents
dltmqm from working.
Details Under normal circumstances, the control command dltmqm should succeed in
removing a queue manager from a system. It should remove all objects associated with
the queue manager and will delete a partially created/deleted queue manager.
If there are problems, follow the steps given.
Transition Statement End of the topic. The next topic is about problem determination.
Instructor Guide
Instructor Guide
V2.0
Uempty 4.2 Problem Determination
This topic describes aspects of problem determination.
What students will do Students will listen to a presentation on WebSphere MQ aids for
determining the cause of a problem.
How students will do it No student activities are planned specifically for this topic. The
students may of course have occasion to use these aids during the practical sessions.
What students will learn Students will learn what aids for problem determination are
provided with WebSphere MQ.
diagnose problems more readily.
Instructor Guide
Figure 4-15. Configuration Files and Problem Determination MQ157.0
Notes:
Configuration and ProbIem Determination
Errors can stop a queue manager being found
QUEUE MANAGER UNAVALABLE
What to check
The configuration files exist
They have the appropriate permissions
The WebSphere MQ configuration file (or Windows Registry)
references the queue manager with the correct information for
locating its files
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how some problems can be caused by errors in the configuration
files.
Details If you receive an error message indicating that the queue manager is
unavailable, the cause could be something simple like the queue manager has not been
started or an application specified an incorrect queue manager name. If the cause is not
anything obvious like these, check the items listed on the visual. Errors in a configuration
file can typically prevent a queue manager from being found.
Ensure that the configuration files exist.
Ensure that they have the appropriate permissions. For example, on a UNIX system,
the WebSphere MQ configuration file should have the following permissions.
-rwxrwxr-x 1 mqm mqm 1371 Sep 17 14:32 /var/mqm/mqs.ini
Ensure that the WebSphere MQ configuration file references the queue manager and
has the correct information for locating the files associated with it.
Additional Information Another thing to check if you get this error is that the application
is bound with the correct MQI stub.
Transition Statement Next we look at error messages.
Instructor Guide
Figure 4-16. Error Messages MQ157.0
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.
Error Messages
"Normal" errors, including some by users
ncorrect parameter on a control command
NLS enabled
Written to the associated terminal, if any, and to an error log file
Error log file
AMQERR01.LOG
One in each of three error directories
Two previous error log files are also kept
AMQERR02.LOG
AMQERR03.LOG
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To explain how WebSphere MQ reports error conditions. This applies only to
the types of error that WebSphere MQ can anticipate.
Details Messages identify normal errors, typically caused by users, such as the use of
an invalid parameter on a control command. The messages are national language enabled
through the use of message catalogs installed in standard locations.
The error logs files are found in the following 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.
For MQSeries for Compaq OpenVMS.
If the queue manager name is known and the queue manager is available.
MQS_ROOT:[MQM.QMGRS.QMgrName.ERRORS]
If the queue manager name is not known or the queue manager is not available.
MQS_ROOT:[MQM.QMGRS.$SYSTEM.ERRORS]
Early errors.
MQS_ROOT:[MQM.ERRORS]
For MQSeries for OS/2 Warp and WebSphere MQ for Windows, the corresponding
directories are as follows.
\MQM\QMGRS\QMgrName\ERRORS
\MQM\QMGRS\@SYSTEM\ERRORS
\MQM\ERRORS
For MQSeries for Tandem NonStop Kernel, the corresponding locations of the error log
files are as follows, assuming the queue manager name is QMGR and the name of its
home volume is $DATA.
$DATA.QMGRL.MQERRLG1
$SYSTEM.ZMQSSYS.MQERRLG1
$SYSTEM.ZMQSSYS.MQERRLG1
Note that the error log files are called MQERRLG1, MQERRLG2, and MQERRLG3.
For WebSphere MQ on UNIX systems, the corresponding directories are as follows.
/var/mqm/qmgrs/QMgrName/errors
/var/mqm/qmgrs/@SYSTEM/errors
/var/mqm/errors
Remember to check both systems in the case of errors related to message channels.
Transition Statement Next we look at unexpected errors.
Instructor Guide
V2.0
Uempty
Figure 4-17. First Failure Support Technology (FFST) MQ157.0
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.
First FaiIure Support TechnoIogy (FFST)
Unexpected errors
nternal queue manager failure
But not automatically an APAR
May have associated storage dumps
Data to help analyze software events
f an error occurs:
Note a description of the problem
Look for any related error log entries
dentify any FFST reports
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how WebSphere MQ uses FFST (First Failure Support Technology)
for unexpected errors.
Details Note that the generation of an FFST report does not automatically indicate an
APAR and does not necessarily bring down the queue manager.
Note also that, on a UNIX system, if you did not set certain kernel parameters to the
minimum recommended values before starting to use WebSphere MQ, you may
experience frequent FFST reports related to shared memory.
FFST is used to record an internal problem at the point at which it is discovered. Its use is
described in WebSphere MQ System Administration for a Version 5 queue manager and in
the relevant System Management Guide for each of the remaining queue managers.
A probe ID, as used in an FFST report, has the following structure. For probe ID xc012010:
Component Function Probe
xc 012 010
The notes below identify what information to collect if you ever need to report a problem.
Record the circumstances of the problem and any external symptoms.
Look for error log entries which might be relevant and collect them.
Identify any FFST report produced.
If you need to report a problem, include:
- A description of the problem.
- Any relevant error log entries.
- Any relevant FFST reports.
Transition Statement Next we look at tracing.
Instructor Guide
Figure 4-18. Trace MQ157.0
Notes:
Trace
Extra information may be needed to find a problem
Files can be very large
Can be limited by time or component
Can also trace the MQ
Useful aid to application debugging
For details on how to produce a trace:
WebSphere MQ System Adminstration Guide for a Version 5
queue manager
WebSphere MQ for iSeries V5.3 System Administration
Guide
The relevant System Management Guide for each of the
remaining queue managers
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the tracing function available in WebSphere MQ.
Details IBM Service personnel may ask for a problem to be re-created with trace
enabled. The files produced by a trace can be very large and so it can be important to limit
a trace by time or trace only specified components.
It is also possible to limit tracing to the MQI and, in this form, it can be a useful aid to
diagnosing application problems.
Transition Statement End of the topic. The next topic is about transactions and
recovery.
Instructor Guide
Instructor Guide
V2.0
Uempty 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.
What students will do Students will listen to a presentation on the WebSphere MQ log,
recovery, and the transactional support provided by WebSphere MQ.
How students will do it There is a practical exercise on recovery following the
presentation. The extent of the exercise may depend on the facilities available. A class
that is relying on the shared use of a production queue manager may not be able to do any
of it.
What students will learn Students will learn about recovery in WebSphere MQ and the
transactional support provided by WebSphere MQ.
How this will help students on their job This knowledge will help the students to design
and implement some basic restart/recovery procedures.
Instructor Guide
Figure 4-19. Message Persistence MQ157.0
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.
Message Persistence
AppIication
Program
Queue
Manager
Queue
MQPUT
CC/RC
Queue
MQPUT
CC/RC
Log
Persistent message
Nonpersistent message
Persistent messages are recovered on
restart, if necessary
Nonpersistent messages are expressIy
discarded on restart
Logging has a performance impact
DefPersistence attribute of a queue
Any queue may store both persistent
and nonpersistent messages, except a
temporary dynamic queue
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the persistence property of a message.
Details A message may either be persistent or nonpersistent. This is determined by the
value of the field Persistence in its message descriptor. All Level 2 queue managers
support both persistent and nonpersistent messages.
Logging is an integral part of the queue manager.
The log is a sequential repository of log records.
The log configuration for a queue manager is specified in the queue manager
configuration file.
The default log parameters for the system are specified in the WebSphere MQ
configuration file.
The parameters include the number of primary and secondary log files, the type of the
log, and the path to the log directory.
The log must have sufficient disk space. The operation of a queue manager will be
affected if disk space becomes exhausted.
Primary log files are files that are allocated when a queue manager is created and their
number remains constant subsequently. Secondary log files are only allocated when the
primary log files fill up. The concepts of primary and secondary log files do not apply to
WebSphere MQ for iSeries.
MQSeries for Tandem NonStop Kernel, unique amongst the Level 2 queue managers, does
not possess its own logging function. On this queue manager, queues are implemented as
audited ENSCRIBE files and TM/MP (TMF) is used to log changes to these and recover the
changes when necessary. As a result, none of the information on this and subsequent
visuals regarding the configuration and administration of an MQSeries log applies to
MQSeries for Tandem NonStop Kernel.
Transition Statement Next we look at the types of logging available.
Instructor Guide
Figure 4-20. Types of Log MQ157.0
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 to
recover 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.
Types of Log
CIRCULAR
Log files viewed as a
closed loop
Amount of disk space
required for the log does
not increase with time
LINEAR
Log files viewed as a
sequence
Log file never deleted BUT
Becomes inactive when it
contains no entries
required to restart the
queue manager
Can be archived when
it becomes inactive
Needed for media
recovery
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the two types of logging available and their capability.
Details The type of logging is selected when a queue manager is created. At the same
time, you may also specify the size and location of the log files if you do not wish to accept
the default values as specified in the WebSphere MQ configuration file.
CIRCULAR
Used when media recovery is not required.
The log files are viewed as a closed ring.
A log file becomes available for reuse when it contains no active log
records. An active log record is one that is still required in order to
restart the queue manager.
The amount of disk space required for the log does not increase
with time.
LINEAR
Needed to support media recovery.
The log files are viewed as a sequence.
A log file is never deleted but ...
... it becomes inactive when it contains no active log records.
New log files are added to the sequence as required. Space is not
reused.
Inactive log files can be archived to release disk space but ...
... there is no automatic mechanism for doing this.
Messages are issued to indicate which log files are active.
A log checkpoint is taken periodically and provides a point of consistency for the queue
manager data. A checkpoint is recorded in the log as a series of checkpoint records.
Checkpoints reduce restart time by minimizing the log replay required.
Transition Statement Next we look at how persistent messages are recovered when
necessary.
Instructor Guide
Figure 4-21. Recovering Persistent Messages MQ157.0
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.
Recovering Persistent Messages
f necessary, persistent messages are recovered
automatically when the queue manager is restarted
A damaged local queue may only be detected later
Reported as "object damaged"
Normally needs to be recovered manually
n order to restart, a queue manager only requires:
Log records written since the last checkpoint
Log records written by transactions that were still active at the
time the queue manager stopped
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how persistent messages are recovered following a system failure.
Details When a queue manager is restarted following a system failure, it will
automatically recover persistent messages from the logged data. It is a rule, however, that
nonpersistent messages are not recovered at this time and are deliberately discarded.
Transition Statement Next we look at media recovery.
Instructor Guide
Figure 4-22. Damaged Objects and Media Recovery MQ157.0
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.
rcdmqimg -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.
Damaged Objects and Media Recovery
WebSphere MQ objects can be marked as damaged
Corrupt data in the queue file
Missing queue file
Disk failure
Damaged objects can be deleted
A damaged object can be re-created from a LNEAR log
Known as media recovery
Media images of some objects are recorded automatically by the
queue manager at certain times
Record the media image of a local queue on a regular basis
using the control command rcdmqimg
Media recovery
Automatic if a damaged object is detected during restart
For a local queue, it is normally done by using the control
command rcrmqobj
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how to recreate a damaged object.
Details A queue manager does not normally detect that a local queue is damaged
during restart. It would only detect a damaged local queue if it were storing uncommitted
persistent messages that were put or got inside a transaction which was still active when
the queue manager stopped. In which case, the queue manager would automatically
recreate the local queue as it needs to be able to roll back the transaction which did not
complete.
As a result, a damaged local queue is normally only detected when an attempt is made to
access it. When this occurs, the local queue can be re-created from a linear log by using
the rcrmqobj control command. You are advised to record a media image of a local queue
on a regular basis so that the time needed to re-create it, if it becomes necessary to do so,
does not become too long.
This discussion has focused on local queues. Although you can use the control commands
rcdmqimg and rcrmqobj with other types of WebSphere MQ object, the simplest way to
recreate such an object, if it becomes necessary to do so, is to rerun the WebSphere MQ
command that created it in the first place. This advice applies to an alias queue, a model
queue, a local definition of a remote queue, a process object, and a channel.
Transition Statement Next we look at how to dump a formatted version of the log on a
Version 5 queue manager.
Instructor Guide
Figure 4-23. Dumping the Log MQ157.0
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 may
be 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 MQ
System Administration Guide.
The dmpmqlog control command is only supported on a Version 5 queue manager.
Dumping the Log
Use dmpmqlog to dump a formatted version of the log
Queue manager must not be running
By default, the dump commences from the head of the log.
Optionally, the dump can commence from:
The base of the log
A log record identified by a specified log sequence number
(LSN)
A log file identified by a specified extent number (linear logs
only)
Log records formatted include:
Put and get of persistent messages
Transaction events
Creation, alteration, and deletion of WebSphere MQ objects
Version 5 queue managers only
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how to dump a formatted version of the log.
Details This function applies to a Version 5 queue manager only.
The dmpmqlog control command can be used to dump a formatted version of the log. It
can only be used when the queue manager is not running.
By default, the dump commences from the head of the log. 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 may be 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.
Because a queue manager takes a checkpoint during a normal shutdown, the active
portion of the log would only contain a small number of log records under these
circumstances. However, there are options on the dmpmqlog command which allow you
to specify a different starting point for the dump.
The dump may commence at the base of the log. The base of the log is the first log
record in the log file containing the head of the log.
The dump may commence at an individual log record identified by a specified log
sequence number (LSN). Each log record is identified by a unique LSN.
The dump may commence at the log file identified by a specified extent number. All log
files have a file name of the form Snnnnnnn.LOG, where nnnnnnn is the extent number.
This option is only available for linear logging.
The information that is formatted includes the following.
Header information about the log, for example, whether the log is circular or linear, the
LSN of the log record at the head of the log, and so forth.
Start queue manager and stop queue manager log records.
Start checkpoint and end checkpoint log records.
Put message and get message log records. These are for persistent messages only
and contain a hex dump of both the application data and the message descriptor.
Various types of log records for events associated with transactions, for example, start
transaction, prepare transaction, commit transaction, and so forth.
Log records associated with the creation, alteration, and deletion of WebSphere MQ
objects.
Full details, including a sample dump with notes, can be found in WebSphere MQ System
Administration.
Transition Statement Next we turn to transactions and the support for syncpoint control.
Instructor Guide
Figure 4-24. Syncpoint Control MQ157.0
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.
Syncpoint ControI
MQGET (customer order)
Update DB
MQPUT (dispatch request)
MQPUT (delivery confirmation)
Commit
Option on MQPUT and MQGET calls
NO_SYNCPONT - message is added or removed immediately
SYNCPONT - result of an MQPUT or an MQGET call only
becomes visible when the unit of work is committed
Default is platform dependent
Additional option on an MQGET call
SYNCPONT_F_PERSSTENT - a message is only got within
syncpoint control if it is persistent
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how a message can be put on a queue or got from a queue within,
or outside of, syncpoint control.
Details Specifying whether a message is to be put on a queue or got from a queue
within, or outside of, syncpoint control is an option on the MQPUT and MQGET calls.
Using the NO_SYNCPOINT option, a message is added to a queue or removed from a
queue immediately.
Using the SYNCPOINT option, the result of an MQPUT or MQGET call only takes effect
when the unit of work is committed.
A message put on a queue within syncpoint control is not available for another application
to get until the unit of work is committed. Similarly, a message got from a queue within
syncpoint control does not cause the message to be removed from the queue until the unit
of work is committed.
On a Version 5 queue manager only, there is an additional option on an MQGET call,
MQGMO_SYNCPOINT_IF_PERSISTENT. Using this option, a message is only got from a
queue within syncpoint control if it is persistent. If it is nonpersistent, it is got outside of
syncpoint control.
Transition Statement Next we look at the design implications of implementing a
business transaction as multiple asynchronous units of work.
Instructor Guide
Figure 4-25. Compensating Transactions MQ157.0
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.
Compensating Transactions
MQSeries Asynchronous ModeI
ExampIes:
1. Debit account,
Send credit message
2. Update travel itinerary,
Send flight reservation
3. Confirm order,
Send shipping request
1. Account not known,
Send debit reversal
2. Fully booked,
Send nearest alternative
3. Out of stock so reorder,
Send revised delivery date
LocaI syncpoint participation = committed changes
Unit of work 1
Unit of work 3
Write
Put
Syncpoint
Get
Write
Syncpoint
Unit of work 2
q Q
Asynchronous
modeI
DB
DB
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the design implications of implementing a business transaction as
multiple asynchronous units of work.
Transition Statement Now we look more closely at the options for syncpoint coordination
when using WebSphere MQ. We start with local units of work.
Instructor Guide
Figure 4-26. Coordinating Local Units of Work MQ157.0
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.
Coordinating LocaI Units of Work
A IocaI unit of work is one in which the onIy
resources being updated are those of the queue
manager
MQGET message from server
queue
MQPUT extra requests
MQPUT reply message
if error ...
MQBACK
if OK ...
MQCMT
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the function provided by WebSphere MQ for coordinating local units
of work.
Details A local unit of work is one in which the only resources being updated are those of
the queue manager to which the application is connected.
To support the coordination of local units of work, WebSphere MQ provides two MQI calls,
MQCMIT and MQBACK. The MQCMIT call commits changes to WebSphere MQ
resources that have been made since the last syncpoint. The MQBACK call rolls back
changes to WebSphere MQ resources that have been made since the last syncpoint. Only
changes to resources made under syncpoint control are affected by the MQCMIT and
MQBACK calls.
The visual shows an example of a server program which gets a request message from a
queue and puts a reply message on a reply-to queue within a local unit of work. This
guards against the possibility of losing the request message if there is a system failure
whilst the server program is processing it.
Transition Statement We now look at global units of work and the options for
coordinating them.
Instructor Guide
Figure 4-27. Internal Coordination of Global Units of Work MQ157.0
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.
InternaI Coordination of GIobaI Units of Work
A gIobaI unit of work is one in which the
resources of other resource managers are aIso
being updated
MQBEGN
MQGET message from server queue
EXEC SQL NSERT data base record
MQPUT reply message
if error ...
MQBACK
if OK ...
MQCMT
Version 5 queue managers onIy
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain what is meant by a global unit of work, to understand the options for
coordinating a global unit of work, and to introduce the MQBEGIN call.
Details A global unit of work is one in which the resources of other resource managers
are being updated as well as those of a queue manager. The coordination of global units of
work may be internal or external to the queue manager. We shall look at the external
coordination of global units of work a little later. On this visual, we shall focus on internal
coordination.
The visual depicts an example of a global unit of work in which changes are made to
WebSphere MQ resources and to those of a relational database within a unit of work. The
calls MQCMIT and MQBACK are used to commit and roll back changes, as with local units
of work. However, when coordinating global units of work, the MQBEGIN call is needed in
order to start a unit of work.
Transition Statement Next we look at which XA-compliant database managers are
supported by the Version 5 queue managers.
Instructor Guide
Figure 4-28. Database Coordination MQ157.0
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.
Database Coordination
Supported database managers
DB2
AX, HP-UX, Linux, OS/2 Warp, Sun Solaris, Windows
Oracle
AX, Compaq Tru64 UNX, HP-UX, Sun Solaris
Sybase
AX, Sun Solaris, Windows
Restrictions
An WebSphere MQ client cannot participate in a global unit of
work
Only one queue manager may participate in a global unit of work
Normally, updates to WebSphere MQ and database resources
must be made on the same system
Database server may be on a different system provided it can
supply an XA compliant client feature
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To indicate which XA-compliant database managers are supported by the
Version 5 queue managers and to explain the restrictions which apply to the internal
coordination of global units of work.
Transition Statement Next we look at the choices available for the external coordination
of global units of work.
Instructor Guide
V2.0
Uempty
Figure 4-29. External Coordination of Global Units of Work MQ157.0
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.
ExternaI Coordination of GIobaI Units of Work
*** SingIe phase commit protocoI onIy
AX
TXSeries for AX
BEA Tuxedo
WebSphere
iSeries
iSeries commitment control
***
CCS/400 ***
Compaq Tru64 UNX,
DC/OSx, NCR UNX, SNX
BEA Tuxedo
HP-UX
TXSeries for HP9000
BEA Tuxedo
WebSphere
Linux
WebSphere
OS/2 Warp
CCS Transaction Server for
OS/2
Sun Solaris
TXSeries for Sun Solaris
BEA Tuxedo
Transarc Encina Monitor
WebSphere
Tandem NonStop Kernel
TM/MP (TMF)
Windows
TXSeries for Windows
BEA Tuxedo
Microsoft Transaction Server
Instructor Guide
As this list occasionally changes, you should check the following url for the latest
information: www.ibm.com/software/ts/mqseries/platforms/supported.html
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To list the external syncpoint coordinators supported by WebSphere MQ.
Details In a transaction environment, an external syncpoint coordinator can be used to
coordinate changes to WebSphere MQ resources and, if required, to those of other
resource managers as well. The external syncpoint coordinators supported by WebSphere
MQ are shown on the visual.
An external syncpoint coordinator will also be required for coordinating global units of work
if you are not using a Version 5 queue manager.
Transition Statement Next we look at how WebSphere MQ can be used with CICS
transactions.
Instructor Guide
Figure 4-30. CICS Transactions MQ157.0
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.
CICS Transactions
A CCS transaction may issue MQ calls
A CCS trigger monitor can start a CCS transaction
when a message arrives on a queue
(AX, OS/2 Warp and Windows only)
Only one queue manager can be accessed at a time from a single
CCS region
(using CCS with a two phase commit protocol on AX, HP-UX, SNX, Sun Solaris,
and Windows)
A CCS transaction can access any queue manager on a
system, but can connect to only one at a time
(using CCS with a single phase commit protocol on OS/2 Warp and Windows)
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe how WebSphere MQ can be used in CICS environments.
Details CICS transactions may issue calls to the MQI.
On AIX, OS/2 Warp, and Windows, there is a separate trigger monitor, itself a CICS
transaction, that can be used for starting CICS transactions. This means that CICS
transactions and native applications must be triggered using separate initiation queues.
The trigger monitor issues EXEC CICS START but otherwise behaves like runmqtrm.
If no data is passed to the CICS trigger monitor, the default CICS initiation queue is used.
Another initiation queue can be used by starting another instance of the trigger monitor. In
this case, the trigger monitor needs to receive the MQTMC2 structure as data in order
know which initiation queue to use instead of the default.
When using CICS with a two-phase commit protocol, only one queue manager can be
accessed at a time from a single CICS region. In addition, the queue manager must be
started before you attempt to start CICS. These comments apply to AIX, HP-UX, SINIX,
Sun Solaris, and Windows.
When using CICS with a single phase commit protocol, a transaction can access any
queue manager on the system, but can only connect to one queue manager at a time. This
comment applies to OS/2 Warp and Windows.
Transition Statement What happens if you have no syncpoint coordinator but still need
to coordinate changes to WebSphere MQ resources and to those of a data base manager?
Instructor Guide
Figure 4-31. Independent Coordination MQ157.0
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.
Independent Coordination
MQGET message from server queue (note Msgd)
Process message
MQPUT messages
DB updates
DB update special record (store current Msgd)
DB commit
?????
MQCMT
DB read special record
MQGET specific Msgd from server queue
if present, there was a failure in the
window
MQPUT messages without DB updates
MQCMT
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the technique for coordinating a unit of work without a syncpoint
coordinator.
Details Suppose an application requirement is to be able to get a message from a queue
and to use the information within the message to make updates to a data base, all within a
single unit of work, but without the use of a syncpoint coordinator. The visual illustrates
how some applications have approached this requirement.
Having separate commitment points for changes to data base resources and changes to
WebSphere MQ resources means that there is a window of opportunity for a failure to leave
the two sets of resources in an inconsistent state. As a result, following a failure, separate
initialization logic is required in order to detect whether any inconsistency exists and to
recover if necessary.
Variations on this technique are possible but it is usually illustrated in this form. In practice,
the implementation of this kind of technique is not as easy as it might at first appear. The
visual depicts a very simple example.
You may need to use this kind of technique in the following situations.
When running an WebSphere MQ client application because such an application may
not participate in a global unit of work.
When using MQSeries for Compaq OpenVMS there is no external syncpoint
coordinator supported by the queue manager.
Transition Statement Next there is a practical exercise on recovery.
Instructor Guide
Instructor Guide
V2.0
Uempty 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
Correct Answer: b, c
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
Correct Answer: c
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
Correct Answer: c
Instructor Guide
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.
Unit Summary
Architecture
Problem determination
Message persistence, logging, and recovery
Transactional support
Exercise 3
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details
There was a description of the structure of WebSphere MQ as it applies to most of the
Level 2 queue managers. It was included in order to provide a general understanding.
We described the main WebSphere MQ aids for problem determination.
We discussed message persistence, logging, and recovery, and there was a practical
exercise involving recovery.
We described the transactional support within WebSphere MQ.
Transition Statement End of the unit. Next, we will look at connecting queue managers
and the implications for applications.
Instructor Guide
Instructor Guide
Copyright IBM Corp. 1996, 2003 Unit 5. Distributed Queue Management 5-1
V2.0
Uempty
Unit 5. Distributed Queue Management
This unit describes various aspects of distributed queue management.
Configuring WebSphere MQ for distributed queuing
Application data conversion
Remote administration
Handling exceptions
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 message
that 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
Instructor Guide
Configure a simple cluster of queue managers
Accountability:
Machine exercises
References
SC34-6059 WebSphere MQ Intercommunication
SC34-6061 WebSphere MQ Queue Manager Clusters
Instructor Guide
V2.0
Uempty
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.
Unit Objectives
Learn how to configure WebSphere MQ channels
Define other required objects for distributed queuing
Explain how to start and stop channels
Describe steps necessary to determine source of channel
problems
List considerations for data conversion
Describe instrumentation events and their use
Explain dead letter queues and their use
mplement a configuration that uses dynamic workload
management - CLUSTERS
Instructor Guide
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose Highlight unit objectives.
Details This unit describes how to configure WebSphere MQ for distributed queuing. It
also discusses other aspects of WebSphere MQ administration in a network, namely
application data conversion, remote administration, and handling exceptions.
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 message that 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.
Define WebSphere MQ queue manager clusters
Implement a simple cluster.
Transition Statement We start by reviewing the way in which a queue is identified in the
MQI.
Instructor Guide
Instructor Guide
V2.0
Uempty 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.
What students will do Students will listen to a presentation on how to configure
WebSphere MQ for distributed queuing.
How students will do it There will be a practical exercise to connect two queue
managers at the end of the unit.
What students will learn Students will learn how to configure a message channel and
ensure that it works. They will also learn about other aspects of the administration of
message channels.
How this will help students on their job This knowledge will help the students design and
support a network of queue managers.
Instructor Guide
Figure 5-2. Identifying a Queue in the MQI MQ157.0
Notes:
Identifying a Queue in the MQI
A queue is identified by:
The name of the queue
The name of the queue manager which owns the queue
A queue may be referenced in two places
Object descriptor, on an MQOPEN or MQPUT1 call
ObjectName
ObjectQMgrName
Message descriptor, to specify a reply-to queue
ReplyToQ
ReplyToQMgr
n an object descriptor, if ObjectQMgrName is blank, the queue
with the name specified in ObjectName must be defined in one of
the following places
The local queue manager
The name service
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To review how a queue is identified in the MQI.
Details In the MQI, a queue is identified by two pieces of information, the name of the
queue and the name of the queue manager which owns the queue.
There are two places where a queue may be referenced, in the object descriptor on an
MQOPEN or MQPUT1 call, or in a message descriptor to identify a reply-to queue. In an
object descriptor, a queue is identified by the contents of the ObjectName and
ObjectQMgrName fields whereas, in a message descriptor, it is identified by the contents of
the ReplyToQ and ReplyToQMgr fields.
In an object descriptor, if ObjectQMgrName is blank, the queue with the name specified in
ObjectName must either have a definition at the local queue manager or be defined by the
name service, using the DCE name service component, for example.
As regards a reply-to queue referenced in a message descriptor, we saw earlier in the
course that a reply-to queue alias is resolved at the time of an MQPUT call. It should be
noted now, however, that the name service is never invoked in order to resolve a reply-to
queue alias.
Transition Statement Next a reminder of the components of assured delivery.
Instructor Guide
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.
Assured DeIivery
MQPUT
if cc=OK
continue
.
.
Transmission
queue
MQGET
DECnet
PX/SPX
NetBOS
TCP/P
SNA LU6.2
UDP
M
C
A
M
C
A
QM1 QM2
Destination
queue
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To review the way in which a message is delivered to a remote queue.
Details All queue managers use a common protocol for assured message delivery. A
message is not lost in the event of a communications or system failure, nor is it ever
delivered twice.
A message destined for a remote queue manager is stored locally on a transmission queue
until the MCA can send it.
Transition Statement Next we look at how to define queues that are used in distributed
queuing.
Instructor Guide
Figure 5-4. Queue Definitions for Distributed Queuing MQ157.0
Notes:
As a general rule, give a transmission queue the same name as the remote queue
manager.
Local definition of a remote queue
A transmission queue must be created at the sending end of each
message channel
USAGE(XMTQ) indicates its purpose
Otherwise, it may have any of the attributes of a local queue
Queue Definitions for Distributed Queuing
DEFINE QREMOTE(BBB) + RNAME(YYY) RQMNAME(QM2)
DEFINE QLOCAL(QM2) USAGE(XMITQ)
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the definition of queues that are used in distributed queuing, viz
the local definition of a remote queue and the transmission queue.
Details The location of a remote queue can be made transparent to an application by
creating a local definition of a remote queue using the WebSphere MQ command DEFINE
QREMOTE. When an application issues an MQOPEN call, in the object descriptor, it can
set ObjectName to the name of the local definition of the remote queue and
ObjectQMgrName to blank. Subsequently, the local definition of the remote queue can be
redefined without requiring any change to the application code.
You will also need to create a transmission queue at the sending end of each message
channel. A transmission queue is defined in the same way as a local queue except that
that the DEFINE QLOCAL command should contain the parameter USAGE(XMITQ) to
indicate its purpose.
On a Version 5 queue manager, there is an attribute of a local queue which only has a
meaning for a transmission queue. The name of the attribute is DistLists and the
corresponding keyword on an WebSphere MQ command is DISTL. When a message
channel is started, the sending MCA of a Version 5 queue manager determines whether
the partner queue manager supports distribution lists or not. If it does, the sending MCA
sets the value of the DistLists attribute of the transmission queue to MQDL_SUPPORTED.
Otherwise, the attribute is set to MQDL_NOT_SUPPORTED. This in turn informs the
queue manager whether a distribution list message can be put on the transmission queue
or not. In general, you are advised not to change the value set by the sending MCA.
The normal convention is to give a transmission queue the same name as the remote
queue manager at the other end of the message channel. The transmission queue may
store messages destined for any queue owned by that queue manager.
Transition Statement Next we look a little more closely at the ends of a message
channel.
Instructor Guide
Figure 5-5. Message Channel Combinations MQ157.0
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.
Message ChanneI Combinations
SENDER
SERVER
SENDER
RECEIVER
REQUESTER
REQUESTER
SERVER
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the possible combinations for a message channel.
Details A message channel agent (MCA) is a program that is instrumental in moving
messages from one queue manager to another. A pair of MCAs act together to form a
message channel.
A channel definition provides the parameters controlling the way an MCA operates. Every
message channel has two definitions, one at each end of the channel. The name of the
channel must be the same in both definitions.
Each end of a channel has a type and the definition of a channel at one end specifies the
type of the channel at that end. The four possible types are:
Sender
Receiver
Server
Requester
A sender or server gets messages from a transmission queue and sends them over the
network. A receiver or requester receives messages from the network and puts them on
their respective destination queues.
The definition of a channel at one end must specify a type which is compatible with the type
specified in the definition at the other end. The four possible combinations of types are
depicted on the visual.
An MCA at one end of a channel initiates the communications connection and "attaches" its
partner MCA at the other end. A communications connection is an SNA LU6.2
conversation, a TCP connection, and so forth.
Transition Statement Next we look more closely at the attributes of a message channel.
Instructor Guide
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
Attributes of a Message ChanneI
Required for definition
(channel-name) Up to 20 characters
CHLTYPE SDR, RCVR, SVR, RQSTR
TRPTYPE DECNET, LU62, NETBOS,
SPX, TCP (but not required on a Version
5 queue manager)
UDP - AX only
CONNAME(string) (for SDR and RQSTR only, optional for SVR)
XMTQ(string) (for SDR and SVR only)
Required for SNA LU6.2 (on MQSeries for OS/2 Warp, SunOS, and
Tandem NonStop Kernel only)
MODENAME(string)
TPNAME(string)
Instructor Guide
V2.0
Uempty
TRPTYPE is not specified, the value is taken from the appropriate default channel
object.
Instructor Guide
Instructor Notes:
Purpose To introduce some of the attributes of a message channel and to indicate
which must be specified when defining a channel.
Details The rules for naming a channel are the same as those for naming a queue
except that the name of a channel is limited to 20 characters. The channel definition at
each end of a channel must specify the same channel name.
On the DEFINE CHANNEL command, the channel type must be specified before any other
parameter. Of the remaining parameters, some are required and others are optional. The
values of the attributes not specified are taken from the appropriate default channel object.
The parameters that must be specified are shown on the visual.
Channel name - up to 20 characters.
Channel type (CHLTYPE) - SDR, RCVR, SVR, RQSTR.
Transport type (TRPTYPE) - DECNET, LU62, NETBIOS, SPX, UDP, Transport, TCP.
This parameter is optional on a Version 5 queue manager but is required on all the
remaining queue managers.
Connection name (CONNAME) - required for SDR or RQSTR, optional for SVR.
The value of this parameter depends on the communications protocol being used and,
in some cases, on the platform as well. For TCP/IP, it may be the IP address or the host
name of the system on which the remote queue manager is running. For SNA LU6.2, it
is a fully qualified partner LU name or partner LU alias on OS/2 Warp and the name of a
CPI-C side object on OS/400, UNIX systems, and Windows. Both the WebSphere MQ
(MQSC) Command Reference and WebSphere MQ Intercommunication contain full
details on how to code this parameter.
Transmission queue name (XMITQ) - required for SDR or SVR.
For SNA LU 6.2 on OS/2 Warp and Tandem NonStop Kernel, there are additional required
parameters.
Mode name (MODENAME)
Transaction program (TP) name (TPNAME)
Transition Statement Next we look at an example containing some channel definitions.
Instructor Guide
V2.0
Uempty
Figure 5-7. Example MQ157.0
Notes:
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.
ExampIe
Hursley Dallas
DEF CHL('HursIey_DaIIas') +
CHLTYPE(SDR) TRPTYPE(TCP) +
CONNAME('9.84.100.1(1414')) +
XMITQ('DaIIas')
DEF CHL('DaIIas_HursIey') +
CHLTYPE(SDR) TRPTYPE(TCP) +
CONNAME('9.20.31.5(1414')) +
XMITQ('HursIey')
DEF CHL('HursIey_DaIIas') +
CHLTYPE(RCVR) TRPTYPE(TCP)
DEF CHL('DaIIas_HursIey') +
CHLTYPE(RCVR) TRPTYPE(TCP)
Instructor Guide
Instructor Notes:
Purpose To provide an example containing some channel definitions.
Details The example contains two pairs of channel definitions.
Note the following.
The definition of a channel at each end of the channel must specify the same channel
name.
Most users follow the convention depicted in the example for naming a channel or adopt
some minor variation of it.
For TCP/IP, you can use either the IP address or the host name on the CONNAME
parameter.
The example follows the convention that the name of a transmission queue is the same
as the name of the queue manager at the other end channel.
Transition Statement Next we look at how a queue manager decides which transmission
queue to use for a message destined for a remote queue.
Instructor Guide
V2.0
Uempty
Figure 5-8. Choosing a Transmission Queue MQ157.0
Notes:
Choosing a Transmission Queue
1. A local definition of a remote queue can specify
2. The name of the transmission queue is inferred from the
name of the remote queue manager
3. A default transmission queue can be specified by an
attribute of the queue manager object
DEFINE QREMOTE(BBB) RNAME(YYY) +
RQMNAME(QM2) XMITQ('Express')
ALTER QMGR DEFXMITQ(HOST)
Instructor Guide
Instructor Notes:
Purpose To explain how a queue manager chooses which transmission queue to use
for a message destined for a remote queue.
Details A queue manager attempts to apply one of the following rules in the stated order
in order to determine which transmission queue to use.
1. Use the transmission queue named explicitly in a local definition of a remote queue.
2. Use the transmission queue with the same name as the remote queue manager.
3. Use the default transmission queue.
A default transmission queue is useful in a larger network. If the destination queue
manager is not known at the local queue manager, the basic strategy is to send it to a
queue manager that does know about it.
A error is reported if the queue manager cannot find a transmission queue by attempting to
apply the above rules.
Transition Statement Next we look at the queue manager alias.
Instructor Guide
V2.0
Uempty
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.
Queue Manager AIias
QMA QMB
QMC
QMD QMF
QME
A defauIt transmission queue aIIows a message to be
deIivered through muItipIe queue managers
A queue manager aIias may aIso be needed
For exampIe, in QMA:
DEFINE QREMOTE(QMF) +
RQMNAME(QMF) XMITQ(QMB)
Instructor Guide
Instructor Notes:
Purpose To explain the use of a queue manager alias.
Details The DEFINE QREMOTE command with a blank remote queue name is used to
define a queue manager alias.
By using default transmission queues and queue manager aliases, a message can be
delivered through successive queue managers in a larger network. For example, the
following will enable a message originating at queue manager QMC to be delivered to
queue manager QMF.
On QMC, create a transmission queue called QMA and make it the default transmission
queue.
On QMA, create a transmission queue called QMB and define QMF as a queue
manager alias specifying QMB as the transmission queue to use.
On QMB, create a transmission queue called QMF.
Transition Statement A queue manager alias can also be used when you need to
separate message flows between two queue managers.
Instructor Guide
V2.0
Uempty
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.
Separating Message FIows
DEF QR(QR.SERV) +
RNAME(QL.SERV) RQMNAME(QM2) +
XMITQ(QM2A)
DEF QR(QR.REPLY/A) +
RN(QL.REPLY) RQMNAME(QM1A)
DEF QR(QM1A) RQMNAME(QM1)
QM1
QM2
QM2
QM1
QM2A
QM1A
QL.REPLY
QL.SERV
X
Y
Reply_to_Q alias
QM alias (Reply Msg)
Local Def. of Rem Q
Instructor Guide
Instructor Notes:
Purpose To explain how you can separate message flows between two queue
managers.
Details Ask the students to suggest reasons why you might want to separate message
flows between two queue managers.
The following explains how request messages can be separated into two flows between
queue managers QM1 and QM2, and how the reply messages can also be separated into
two flows in the reverse direction. Each flow requires a separate message channel.
1. Program X puts a request message on queue QR.SERV. QR.SERV is a local definition
of a remote queue which specifies QL.SERV as the remote queue name and QM2A as
the transmission queue to be used. The message is therefore sent on the channel
serving transmission queue QM2A, not on the "normal" channel which serves
transmission queue QM2.
In the message, Program X specifies the reply-to queue as QR.REPLY/A which is
resolved by using a reply-to-queue alias to reply-to queue QL.REPLY on reply-to queue
manager QM1A.
2. Program Y gets request messages from queue QL.SERV potentially from several client
programs. Each request message includes, in its message descriptor, the name of the
reply-to queue and reply-to queue manager. Program Y specifies these names in the
object descriptor when opening the queue on which to put the reply message.
There is no local definition of a remote queue on queue manager QM2 which explicitly
identifies a transmission queue. As a result, a reply message is put on the transmission
queue whose name is the same as that of the reply-to queue manager, viz QM1A in our
example. Thus the reply message is sent on the channel serving transmission queue
QM1A, not on the normal channel which serves transmission queue QM1.
3. On queue manager QM1, there is a also queue manager alias definition which specifies
QM1A as an alias of QM1. When a reply message arrives at queue manager QM1
addressed to QM1A, the queue manager resolves the queue manager alias and the
message is put on queue QL.REPLY for Program X to get.
Transition Statement Next we look at how to configure TCP/IP for WebSphere MQ.
Instructor Guide
V2.0
Uempty
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.
Configuring TCP/IP for WebSphere MQ
Configure the inet daemon, inetd, . .
WebSphere MQ 1414/tcp #MQSeries
OS/2 Warp AX
\MPTN\ETC\SERVCES
/etc/inetd.conf
\MPTN\ETC\NETD.LST
/etc/services
WebSphere MQ stream tcp nowait mqm /usr/mqm/bin/amqcrsta amqcrsta [-m QMgrName]
WebSphere MQ tcp c:\mqm\bin\amqcrsta [-m QMgrName]
. . . or use the WebSphere MQ Iistener, runmqIsr
Instructor Guide
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 implementations 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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe how to configure TCP/IP for WebSphere MQ - at least enough for
the students to do the practical exercises.
Details Full details for every platform can be found in the following publications.
WebSphere MQ Intercommunication, for all platforms except Tandem NonStop Kernel
MQSeries for Tandem NonStop Kernel System Management Guide
Using TCP/IP, in order to start a message channel at one end of the channel, there must be
a listener process running at the other end. On UNIX, the standard listener process is the
the inet daemon, inetd, but it is also available for use on OS/2 Warp. It must be configured
for WebSphere MQ as shown on the visual.
Add a line to /etc/services on AIX, or to \MPTN\ETC\SERVICES on OS/2 Warp.
#
# MQSeries
#
MQSeries 1414/tcp #MQSeries
On AIX, add a line to /etc/inetd.conf
On AIX, enter the command refresh -s inetd
WebSphere MQ stream tcp nowait mqm /usr/mqm/bin/amqcrsta amqcrsta [-m
QMgrName]
On OS/2 Warp, add a line to \MPTN\ETC\INETD.LST
MQSeries tcp c:\mqm\bin\amqcrsta [-m QMgrName]
Port number 1414 is assigned by the Internet Assigned Numbers Authority to WebSphere
MQ and, by default, WebSphere MQ uses this port number. However, if you are running
multiple queue managers on a system, each needing to be able to respond to incoming
requests to start a channel, you will need to specify additional port numbers.
One advantage of using runmqlsr is that a channel runs as a thread within the listener
process. If you use inetd, on the other hand, a separate process is required for each
channel. This applies only to MQSeries for OS/2 Warp and WebSphere MQ for Windows.
On MQSeries for OS/2 Warp and WebSphere MQ for Windows, there is also an endmqlsr
control command to end all listener processes for a specified queue manager.
Additional Information Using TCP/IP to establish a UDP connection:
runmqlsr -m QMgrName -t UDP p9
The START LISTENER MQSC command is not usable.
runmqlsr command implies you must not add entries to /etc/ services and
/etc/inetd.conf file
Instructor Guide
When receiving on TCP, a maximum number of outstanding connection requests is set.
This can be considered a backlog of requests waiting on the TCP port for the listener to
accept the request.
These are the default outstanding connection requests
OS/2 - 10
Windows Server - 100
Windows Workstation
If the backlog value shown is reached the TCP/IP connection is rejected and the channel
will not be able to start. To avoid this add an entry in qm.ini TCP: ListenerBacklog = n
For more information on the TCP/IP listener backlog option, using the RUNMQLSR
command, consult the WebSphere MQ System Administration Guide.
Transition Statement Next we look at how to start a message channel.
Instructor Guide
V2.0
Uempty
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.
Starting a Message ChanneI
WebSphere MQ commands
Control command
Channel attributes compared
BATCHSZ
MAXMSGL
SEQWRAP
HBNT (WebSphere MQ for z/OS, iSeries and Version 5 queue managers only)
NPMSPEED (WebSphere MQ for z/OS, iSeries, and Version 5 queue managers)
PING CHANNEL(QMA_QMB)
START CHANNEL(QMA_QMB)
runmqchI -c QMA_QMB
Instructor Guide
Instructor Notes:
Purpose To explain how to start a message channel.
Details One of the commonest problems in WebSphere MQ is getting your very first
message channel to work. Once this has been accomplished, things become much
simpler.
Always check that the network is working before you attempt to start a channel.
Take particular care that the channel definitions are correct.
There are several reasons why a channel might fail to start. Some common problems are
listed below.
The definitions at both ends of a channel do not specify the same channel name.
Remember, in particular, that the names of channels, like the names of queues, are
case sensitive.
A channel is not defined at both ends with compatible types.
There is a sequence number mismatch, often caused by deleting a channel definition at
one end of a message channel and then redefining it, or deleting and re-creating a
queue manager, and so forth.
Some attributes specified in the channel definition at each end of a message channel are
compared when the channel is started.
BATCHSZ
Maximum number of messages sent before a syncpoint is taken. A larger
maximum batch size can improve throughput. The lower value from the
two channel definitions is used.
MAXMSGL
Maximum message length that can be transmitted by the channel. The
lower value from the two channel definitions is used.
SEQWRAP
Highest message sequence number before wrapping. The SEQWRAP
values in the two channel definitions must match otherwise the channel will
fail to start. Messages are numbered internally in the Message Channel
Protocol and the sequence numbers used will restart at 1 after reaching the
value specified on the SEQWRAP parameter. Do not specify a low value.
HBINT This is the time between heartbeat flows that are sent from a sending MCA
to a receiving MCA when there are no messages on the transmission
queue. A heartbeat flow can unblock a receiving MCA for which the STOP
CHANNEL command has been issued. The higher value from the two
channel definitions is used.
This parameter is only valid on a queue manager which supports heartbeat
flows, namely, WebSphere MQ for AIX, iSeries, HP-UX, Linux, Sun Solaris,
and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and
Instructor Guide
V2.0
Uempty
OS/2 Warp and for WebSphere MQ for z/OS without CICS. Heartbeat flows
only occur when there is a queue manager that supports them at both ends
of a channel.
NPMSPEED
The speed at which nonpersistent messages are to be sent. You can
specify NORMAL or FAST. The default is FAST, which means that a
nonpersistent message is sent outside of a batch and so becomes
available for retrieval as soon as it is put on its destination queue. If the
definitions at the sending and receiving ends of a channel do not specify
the same value, or if one end does not support fast nonpersistent
messages, then NORMAL is used.
This parameter is only valid on WebSphere MQ for AIX, HP-UX, iSeries,
Solaris, and Windows systems, WebSphere MQ for z/OS with CICS
MQSeries V5.1 for Compaq Tru64 UNIX and OS/2 Warp. However,
MQSeries for Compaq OpenVMS also supports fast nonpersistent
messages but, on this queue manager, it is enabled on a particular channel
by coding the following parameter immediately after the CHLTYPE
parameter in the channel definition.
DESCR('>>> whatever') +
It is the first three characters of the description, namely, ">>>", which
enables fast nonpersistent messages.
If a message cannot be delivered, it is put on the local dead letter queue. If it cannot be put
there, the channel is stopped. However, if a fast nonpersistent message cannot be
delivered and cannot be put on the dead letter queue, it is discarded and the channel
remains open.
Additional Information WebSphere MQ for z/OS is referenced on this visual and in the
instructor notes because, when deciding to code the HBINT or NPMSPEED parameter on
DEFINE CHANNEL command, it is clearly useful to know whether the queue manager at
the other end of the channel supports heartbeat flows or fast nonpersistent messages.
Transition Statement Next we look at the channel initiator, a means of automating the
task of starting a message channel.
Instructor Guide
Figure 5-13. Channel Initiator MQ157.0
Notes:
The channel initiator is a special trigger monitor for starting a message channel. It also
contains retry logic for use in case of difficulty in starting a channel or after an error on a
channel.
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.
ChanneI Initiator
START CHINIT INITQ('ChanneI.InitQ')
runmqchi -q ChanneI.InitQ
MRRTY, MRTMR (not MQSeries for Windows)
MCATYPE (MQSeries for OS/2 Warp and
WebSphere MQ for Windows onIy)
BATCHINT (Version 5 and z/OS onIy)
DISCINT
SHORTRTY, SHORTTMR
LONGRTY, LONGTMR
Trigger monitor for transmission queues
Starts an MCA at the sending end of a message channel
UserData attribute of the process object specifies the channel
name
Or, Triggerdata attribute of the transmission queue specifies the
channel name (Version 5 and iSeries queue managers only)
Also a control command
Channel control parameters
Instructor Guide
V2.0
Uempty
- 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.
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
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.
Instructor Guide
Of the parameters listed, only the SHORTRTY, SHORTTMR, LONGRTY, LONGTMR,
and MCATYPE parameters are used by the channel initiator.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the use of the channel initiator.
Details You can start a message channel manually by issuing a command or
automatically by means of a special purpose trigger monitor called a channel initiator.
The disconnect interval and retry parameters enable some automation in the operation of
channels. Channels can stop during periods of inactivity and be restarted when more
messages arrive. The channel initiator will also attempt to restart a channel after a failure.
Transition Statement End of topic. Next, there are some considerations for applications
in a mixed network, starting with data representation.
Instructor Guide
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.
ChanneI States
STOPPING
STARTING
INACTIVE
RETRYING
START
INITIALISING
STOPPED
RUNNING
BINDING
REQUESTING
PAUSED
Status
OK
Disconnect
interval
expires
Error, or STOP, or
disc. int. expires
Bind fails
Retryable error
Time for
next
attempt
STOP, or non-retryable
error, or retry limit reached
START
CHANNEL
runmqchl
Instructor Guide
V2.0
Uempty
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.
Instructor Guide
Instructor Notes:
Purpose To explain the various states of a channel.
Details Explain the state diagram. The diagram is only a simplified representation of
what actually happens. It should not be interpreted too literally.
An error may cause a channel to go into the RETRYING state if it is possible that the
problem may clear itself. Otherwise it goes into the STOPPED state.
A STOP CHANNEL command also takes a channel into the STOPPED state. Only the
expiry of the disconnect interval will cause a channel to end normally and thus become
INACTIVE.
A channel that is in the STOPPED state can only be started by manual intervention.
Additional Information The STOP CHANNEL command can be issued against any type
of channel except the CLNLTCONN channel. You now can target to STOP a channel by
specifying the CHANNEL-NAME and the partner CONNAME or the partner QMNAME.
Understanding the state of the channel after the STOP CHANNEL command has been
added for availability. If you specify either QMNAME or CONNAME, the STATUS of the
channel must be INACTIVE. DO NOT specify QMNAME or CONNAME
STATUS(STOPPED), it is not possible to have a channel stopped for one partner and not
for others.
Transition Statement End of the topic. Next, there are some considerations for
applications in a mixed network, starting with data representation.
Instructor Guide
V2.0
Uempty 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.
What students will do Students will listen to a presentation on using the MQI in a
network.
How students will do it No specific student activities are planned for this topic although
some aspects may arise in the practical exercise on distributed queuing depending on the
classroom configuration.
What students will learn Students will learn how the MQI is used in a network.
How this will help students on their job This knowledge will help the students to support
applications effectively in a network.
Instructor Guide
Figure 5-15. Data Representation MQ157.0
Notes:
Data Representation
Messages in a heterogeneous network
Character fields may need translation
Numeric fields may need transformation
Message descriptor accompanies every message
Delivered to the receiving application
Always converted by WebSphere MQ
Application data
Fields in the message descriptor describe the format and
representation
Data conversion support is available
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce the WebSphere MQ approach to application data conversion in a
heterogeneous network of queue managers.
Details When messages are being routed through a heterogeneous network of queue
managers, there is a requirement to be able to handle different data representations.
Some character fields may require translation from one character set to another.
Some numeric fields may require transformation, such as byte reversal for integers.
A message descriptor accompanies every message and is delivered to the receiving
application along with the application data. The message descriptor is always converted to
the representation of the destination system by all queue managers. When a message
channel is started between two queue managers, the two MCAs determine what
conversion is required and decide which of them will do it.
The conversion of the application data in a message, on the other hand, requires more
attention.
Transition Statement Next we look at the three fields in the message descriptor which
are concerned with application data conversion.
Instructor Guide
Figure 5-16. Three Fields in the Message Descriptor MQ157.0
Notes:
Three FieIds in the Message Descriptor
Encoding
Representation of the numeric data in the message
iSeries, Windows , and so forth
MQENC_NATVE
CodedCharSetId
Representation of the character data in the message
MQCCS_Q_MGR
Format
ndicates the nature of the data in the message
Values MQ . . . are reserved for WebSphere MQ
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the fields in the message descriptor which are concerned with
application data conversion.
Details There are three fields in the message descriptor which are used to support
application data conversion. The first two fields specify the numeric and character
representations of the application data. A message which is put with the initial values of
these fields will be correctly described. The Format field indicates the nature of the
application data in a message.
Transition Statement Next we look at how application data conversion is requested.
Instructor Guide
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.
Requesting AppIication Data Conversion
Request data conversion on the MQGET call
MQGMO_CONVERT
Encoding and CodedCharSetId
On input, requested representation of the message
On output, what the application actually receives
Conversion performed, if necessary, on the basis of what is
contained in the Format field
A warning, and the message returned in its original form, if the
conversion cannot be done
Otherwise, request data conversion at the sending end of a
message channel
CONVERT(YES)
Unconverted messages are put on the dead letter queue at the
sending end
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how to request application data conversion where it is required.
Details An application can request application data conversion on the MQGET call.
Conversion only occurs if the representation of the stored message and the representation
requested on the MQGET call are different. The approach can be described as "receiver
makes good". It means that the application data in a message need only be converted
once even if a message has to pass through several queue managers.
If a message is destined for a queue manager that does not support application data
conversion, you can request the sending end of a message channel to perform the
conversion. This always converts a message to the representation of the queue manager
at the remote end of the channel. If the sending end of a channel fails to convert a
message, the message is written to the dead letter queue at the sending end.
Transition Statement Next, what kinds of application data conversion can WebSphere
MQ perform?
Instructor Guide
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.
What AppIication Data
Conversion Can Be Done?
Some formats are built-in, and the data conversion is
performed by a built-in conversion routine
A message consisting entirely of characters
A message structure defined by WebSphere MQ
A user written data conversion exit is required when:
The format of a message is defined by the application, not by
WebSphere MQ
A message with a built-in format fails to convert
There is an WebSphere MQ utility to help write a data conversion exit
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe what application data conversion WebSphere MQ can perform.
Details A message consisting entirely of characters can be converted by a built-in
conversion routine, and so can a message with a structure defined by WebSphere MQ.
If the format of a message is application defined, the conversion must be performed by a
user written data conversion exit. There is a utility supplied with WebSphere MQ to help in
the writing of a data conversion exit.
Transition Statement Next we look at how to create a conversion exit.
Instructor Guide
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\Cli
entExitPath\
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.
Writing a Data Conversion Exit
Name your message format
Create C structure definitions to represent the message
Pass the C structure definitions through a utility
Complete the program
Rename the supplied skeleton source file
mbed the code fragments generated by the utility
f necessary, add any specialized code
Build the program into an executable
Watch the link options!
crtmqcvx format.in convcode.out
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To outline the procedure for writing a data conversion exit.
Details
A summary of the procedure to write a data conversion exit is provided below. See the
WebSphere MQ Application Programming Guide for full details.
1. Name your message format.
2. Create a C structure definition to represent the application data in your message. If
your message contains more than one structure, you will need to create a C structure
definition for each one.
3. Pass the C structure definitions through the supplied utility.
crtmqcvx format.in convcode.out
4. Complete the program.
Rename the supplied skeleton source file with the name of your message format in
step 1.
Imbed the code fragments generated by the utility.
If necessary, add any specialized code, or any code to glue the generated fragments
together.
5. Build the program into an executable.
Watch the link options!
On Sun Solaris, if you are running applications connected to the same queue
manager in both the Posix V10 and the DCE threading environments, you will need
two versions.
The name of the exit must be FORMAT, where FORMAT is the value of the Format field in
the message descriptor. For applications running in the DCE threading environment, the
name of the exit must be FORMAT_d.
There are some general rules that apply when writing a data conversion exit.
No MQI calls are allowed, but there is an MQXCNVC call to convert characters.
The code must be reentrant.
An exit should not attempt to use static storage to communicate between invocations.
It is a convention that no partial conversion of the application data should take place.
Either all of it is converted, or none of it is.
Transition Statement Next, we look at how a queue manager uses a data conversion
exit.
Instructor Guide
Figure 5-20. How a Data Conversion Exit Is Used MQ157.0
Notes:
How a Data Conversion Exit Is Used
The queue manager detects whether data conversion is required
For a built-in format, the queue manager performs the
conversion
For a format that is not built in, or if a built-in conversion routine
fails, the queue manager invokes the relevant data conversion
exit
The data conversion exit is:
nvoked according to the call definition MQDATACONVEXT
Passed the MQDXP structure as one of its parameters
The queue manager checks the ExitResponse field in MQDXP
OK - delivers the converted message to the application
FALED - propagates CompCode and Reason from the exit and
delivers the unconverted message to the application
Application data delivered may depend on the truncation option
specified
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how a queue manager responds to a request for application data
conversion.
Details
Detecting whether application data conversion is required is independent of any data
conversion exit. If conversion is required and the message format is one that can be
handled by one of the built-in conversion routines, no data conversion exit is needed.
If a data conversion exit is needed, it is invoked according to the definition of the
MQDATACONVEXIT call, receiving the MQDXP structure as one of its parameters. Both
the call definition MQDATACONVEXIT and the structure MQDXP are documented in the
WebSphere MQ Application Programming Reference.
On return from the exit, the queue manager checks the ExitResponse field in MQDXP.
If its value is MQXDR_OK, the queue manager delivers the converted message to the
application.
If its value is MQXDR_CONVERSION_FAILED, the queue manager propagates the
values of the CompCode and Reason fields returned by the exit in MQDXP and delivers
the unconverted message to the application.
The application data delivered to the application may depend on the truncation option
specified. It is possible for a message to expand during conversion, for example.
If application data conversion is requested at the sending end of a message channel and
the conversion fails, the message is put on the local dead letter queue, a channel event
occurs and, if requested, an exception report is generated.
Transition Statement Next we review what applications should do in a heterogeneous
network of queue managers.
Instructor Guide
Figure 5-21. What Applications Should Do MQ157.0
Notes:
What AppIications ShouId Do
Put messages with the following values in the Encoding and
CodedCharSetId fields
MQENC_NATVE - for native encoding
MQCCS_Q_MGR - for the same CCSD as the queue
manager
Put all messages with a format name
MQFMT_STRNG - for a message consisting entirely of
characters
Use the MQGMO_CONVERT option on the MQGET call
Check what is delivered by the call
f necessary, use CONVERT(YES) at the sending end of
a message channel
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To review what applications should do in a heterogeneous network of queue
managers.
Details The first two recommendations shown on the visual apply to all applications, not
just those that run on a platform on which support for application data conversion is
available.
Put every message with the following values in the Encoding and CodedCharSetId
fields of the message descriptor.
- MQENC_NATIVE, for native encoding.
- MQCCSI_Q_MGR, for the same CCSID as the queue manager.
Put every message with a format name in the Format field of the message descriptor,
for example,
- MQFMT_STRING, for a message consisting entirely of characters.
Use the MQGMO_CONVERT option on the MQGET call. Check what is delivered by
the MQGET call; the message may not have been converted.
And, for completeness, one action for the administrator.
If messages are being sent to a queue manager which does not support application
data conversion, use the CONVERT(YES) option at the sending end of a message
channel.
Successful conversion clearly depends on the sender of a message correctly setting the
Encoding, CodedCharSetId, and Format fields in the message descriptor. Application
programmers should get into the habit of doing this even if currently the destination of the
message is such that no conversion is necessary.
Transition Statement Next we look at the command server.
Instructor Guide
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
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
Command Server
Command queue
SYSTEM.ADMN.COMMAND.QUEUE
Messages contain Programmable Command Format (PCF)
commands
Command server processes the messages in this queue
Enables network administration applications
Single point of control
strmqcsv QMgrName
Instructor Guide
V2.0
Uempty
WebSphere MQ commands. PCF commands are not supported by WebSphere MQ for
z/OS.
Instructor Guide
Instructor Notes:
Purpose To introduce the command server.
Details All queue managers have a command queue which is system queue designed to
support remote administration from a single point of control The message format (PCF) is
documented for external use. Messages can be sent to a remote command queue.
A queue manager provides a command server to process the messages on the command
queue. The control command strmqcsv starts the command server which must be
running for a queue manager to be enabled for remote administration.
Transition Statement Next we look at the range of PCF support.
Instructor Guide
V2.0
Uempty
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.
Support for PCF Commands
All queue managers have a command server which accepts PCF
commands, except:
WebSphere MQ for OS/390
Level 1 queue managers
Administration utilities which issue PCF commands
SupportPacs for WebSphere MQ for AX, Windows, and MQ
Series for OS/2 Warp
Vendor products
runmqsc -w (indirect mode)
Applications using the MQA (V5.1 and later)
(WebSphere MQ Administration nterface)
Instructor Guide
Instructor Notes:
Purpose To describe the support for PCF commands.
Details All queue managers have a command server which accepts PCF commands
except WebSphere MQ for z/OS, and the Level 1 queue managers. Any queue manager
that has a command server which accepts PCF commands can be controlled by an
application which issues them.
For WebSphere AIX, iSeries, HP-UX, Linux, Sun Solaris and MQSeries for OS/2 Warp,
there are Administration Interfaces as part of the product that simplifies the use of PCF
messages.
Additional Information Look for information about vendor products on the WebSphere
MQ home page on the World Wide Web.
Transition Statement Next we look at an example of a program which uses PCF
commands.
Instructor Guide
V2.0
Uempty
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 the
following attributes.
QName
RetentionInterval
CreationDate
CreationTime
3. For each expired queue, put an MQCMD_DELETE_Q command on the command
queue.
Program ExampIe
Application Command Server
MQPUT
MQPUT
MQPUT
MQGET
MQGET
MQGET
MQCMD_INQUIRE_Q
generic queue name
Inquire attributes of
seIected queues
Response for each
matching queue
queue name
retention intervaI
creation date
creation time
MQCMD_DELETE_Q
queue name
Determine which
queues have expired,
and for each one ...
DeIete named queue
Instructor Guide
-The command server deletes the "expired" queues.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To provide an example of a program which uses PCF commands to automate
a specific administration task.
Details The example automates an activity that would otherwise require successive
operator action.
RetentionInterval is an attribute of a queue that can be tested but a queue manager never
takes any action based on this attribute. A retention interval could, for instance, be
specified on a model queue and hence be set for any dynamic queue created from it. A
program based on this example could be used to purge any permanent dynamic queues
that are deemed to be out of date.
Transition Statement Next we look at the indirect mode of using runmqsc.
Instructor Guide
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.
Indirect Mode
runmqsc -w 5 QMgrName
Each WebSphere MQ command is sent within an Escape PCF
command to the command queue of the named queue manager
Connects to the default queue manager
Escape PCF command processed at the target queue manager
Waits for the replies
Time limit for the wait
Writes a report based on the replies received
Can also send a WebSphere MQ command to the
system-command input queue of an z/OS queue manager
-x parameter
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how to send WebSphere MQ commands to the command server of
another queue manager.
Details Previous class use of the runmqsc command has been in direct mode.
runmqsc connects to the target queue manager, issues WebSphere MQ commands, and
produces a report of the results.
There is also an indirect mode of using runmqsc in which WebSphere MQ commands are
sent to a command queue instead and the command server sends replies which are used
to format a report.
In indirect mode, an WebSphere MQ command is encapsulated within an Escape PCF
command. The syntax of the command is checked, the command is executed, and the
response is generated at the target queue manager. It is therefore possible to send an
WebSphere MQ command in this manner even when it would not be recognized by the
local queue manager.
In indirect mode, runmqsc works as follows.
runmqsc reads WebSphere MQ commands ...
... sends them within Escape PCF commands to the command queue of the target
queue manager, which can be remote, ...
... waits for the replies (up to 5 seconds in the example on the visual) ...
... and writes a report based on the replies received.
An WebSphere MQ command can also be sent to an MVS/ESA queue manager by using
the -x parameter in conjunction with the -w parameter. In this case, the WebSphere MQ
command is sent as a message in a format which is acceptable to the WebSphere MQ for
z/OS command server, not within an Escape PCF command. An WebSphere MQ
command which is unique to WebSphere MQ for z/OS can be sent in this way.
Transition Statement Next we look at instrumentation events.
Instructor Guide
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.
Instrumentation Events
Have a queue manager report a problem condition immediately
Number of messages on a queue is increasing
Get requests are inhibited for a queue
Message channel has stopped
Enabled events are reported as event messages on
event queues
SYSTEM.ADMN.QMGR.EVENT
SYSTEM.ADMN.PERFM.EVENT
SYSTEM.ADMN.CHANNEL.EVENT
SYSTEM.ADMN.CONFG.EVENT
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe how instrumentation events are reported to an application.
Details An instrumentation event is a logical combination of conditions that is detected
by the queue manager. There are four categories of instrumentation event.
Queue manager events
Examples are:
When an attempt is made to put a message on a queue for which
put requests are disabled.
When an attempt is made to open a queue without the required
authority.
Performance events
Examples are:
When the depth of a queue has reached a predefined threshold.
When a queue is full.
Channel events
Examples are:
When a channel starts.
When a channel stops.
When application data conversion fails at the sending end of a
message channel.
Configuration events
Examples are:
When a object is created.
When a channel stops.
When a object is deleted
When a namelist is created
When an instrumentation event occurs, the queue manager puts an event message on an
event queue. Each category of instrumentation event has its own event queue.
This event queue: Contains event messages from:
SYSTEM.ADMIN.QMGR.EVENT Queue manager events
SYSTEM.ADMIN.PERFM.EVENT Performance events
SYSTEM.ADMIN.CHANNEL.EVENTChannel events
SYSTEM.ADMIN.CONFIG.EVENT Configuration events
Channel events are always enabled. The other categories are enabled by queue and
queue manager attributes.
It is a common requirement to be able to detect when the depth of a queue, including a
transmission queue, has reached a predefined threshold so that corrective action can be
Instructor Guide
taken before the queue actually becomes full. Using instrumentation events for this
purpose is more appropriate than using DEPTH triggering. Such a threshold is specified
as a percentage of the maximum depth of a queue.
The format of an event message is based on that of a PCF command.
An application to read event messages is not provided by WebSphere MQ but there is a
SupportPac which provides this function.
Additional Information Configuration events are notification about the attributes of an
object. They are generated automatically when the object is created, changed, or deleted,
and also generated by explicit requests.
Transition Statement Next we look at how an application monitoring an event queue
might respond to an instrumentation event.
Instructor Guide
V2.0
Uempty
Figure 5-27. Responding to an Instrumentation Event MQ157.0
Notes:
Responding to an Instrumentation Event
Queue manager events
Enable a queue for put or get requests if it is not intentionally
disabled
Correct the authorizations for a queue, or stop unauthorized
users trying to put messages on the queue
Performance events
Start a process to clear the backlog of messages
Suspend a process that is putting too many messages on a
queue
Channel events
Restart a channel
Process the dead letter queue
Instructor Guide
Instructor Notes:
Purpose To discuss some of the actions an application might take when it has just got
an event message from an event queue.
Details Here are some suggestions for actions that an application might take after it has
just got an event message from an event queue. The lists are open ended and students
may have additional ideas. But do not spend much time on it if not.
Transition Statement Next we look at the dead letter queue.
Instructor Guide
V2.0
Uempty
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.
Dead Letter Queue
Used when problems are detected asynchronously
Destination queue not available
Application data conversion fails at the sending end of a message channel
Message channel stops if the local dead letter queue is not
available when it is required
MQPUT
to Q1
M
C
A
M
C
A
tQ
DLQ
Q1
DLQ
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain when a message may be put on a dead letter queue.
Details Always create a dead letter queue. If it does not exist when a message cannot
be delivered, the channel will stop.
If a message is received which cannot be delivered, the channel is stops and the message
remains on the transmission queue at the sending end. There is one exception to this. If
the message which cannot be delivered is a fast nonpersistent message, it is discarded
and the channel remains open.
This last observation applies to all queue managers which support fast nonpersistent
messages. If such a message cannot be delivered and cannot be put on the dead letter
queue for whatever reason, the message is discarded, an error message is written, and the
channel remains open.
Channel activity is reported in the error logs discussed previously. If there is a problem on
a message channel, look in the error logs at both ends of the channel.
Transition Statement Next we look at a facility to process the undelivered messages.
Instructor Guide
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).
Dead Letter Queue HandIer
DESTQM(QM17) ACTION(FWD) FWDQ(&DESTQ) FWDQM(QM17A)
MSGTYPE(MQMT_REPORT) FEEDBACK(MQFB_EXPIRATION) +
ACTION(DISCARD)
REASON(MQRC_Q_FULL) ACTION(RETRY)
DESTQ(XYZ*) ACTION(FWD) FWDQ(XYZ_DEADQ) FWDQM(' ')
runmqdIq < RuIes_TabIe
Rules table contains a set of rules
Each rule consists of pattern matching keywords and an action
For each message on the dead letter queue, each rule whose
pattern matches the message is attempted in turn
A message can be retried, forwarded, discarded, or ignored
A message can be forwarded with, or without, the dead letter
header
Can have multiple instances, each with a different rules table
Source of a sample dead letter queue handler is supplied as well
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe the dead letter queue handler.
Details The purpose of a dead letter queue handler is to provide an automated way of
handling messages on the dead letter queue.
The dead letter queue handler is invoked using the runmqdlq control command. It can
have a queue name and a queue manager name as parameters, otherwise it assumes the
dead letter queue of the default queue manager.
It is driven by a rules table which is read from the standard input device. There must be at
least one rule in the table.
A rule can match the destination queue name, the message type, the contents of the
Feedback field, and so forth.
The action of a rule may indicate that the dead letter queue handler should try again to
put a message on its destination queue, or forward it to another queue, or discard it, or
simply leave it on the dead letter queue.
It is possible to have multiple instances of the dead letter queue handler running
concurrently against the same queue, each with a different rules table. However, it is more
usual to have a one-to-one relationship between a queue and a dead letter queue handler.
As well as runmqdlq, the source of a sample dead letter queue handler is also supplied
with WebSphere MQ. The function of this sample is similar to that provided by runmqdlq.
Transition Statement Next we look at a possible strategy for using dead letter queues.
Instructor Guide
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.
Using Dead Letter Queues
Create a dead letter queue on all queue managers
Use message-retry on message channels for transient conditions
Consider "return to sender"
Use a dead letter queue handler
Trigger when a message arrives on the dead letter queue
Possibly attempt further retries
f unsuccessful, forward to an application dead letter queue
associated with:
The destination queue
The application specified by the PutApplName field in the
message descriptor
Don't allow an application dead letter queue to become full
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe a possible strategy for using dead letter queues.
Details Create a dead letter queue on all queue managers. However, the use of the
following function might mean that some messages avoid being put on the dead letter
queue that might otherwise have been put there.
Use message-retry on message channels in order to allow for transient conditions.
Consider the combination of report options that implements "return to sender" as an
alternative to putting a message on the dead letter queue, viz
MQRO_PASS_MSG_ID +
MQRO_PASS_CORREL_ID +
MQRO_EXCEPTION_WITH_FULL_DATA +
MQRO_DISCARD_MSG
Use the dead letter queue handler triggered by the arrival of a message on the dead letter
queue. If there is no reasonable retry option, forward the message to an application dead
letter queue.
An application dead letter queue must not be allowed to fill up.
Note that runmqdlq cannot accept the MQTMC2 structure as a parameter. If you wish to
trigger the start of the DLQ handler therefore, you will need to write a program that can be
started by the trigger monitor, receive the MQTMC2 structure as a parameter, and then
invoke runmqdlq passing it the required parameters.
Transition Statement There is now an practical exercise on distributed queuing.
It is enough for students to work with pairs of systems at this stage. Variations with more
queue managers can be attempted in the next practical session.
The instructor may need to organize the systems into pairs if the students cannot agree
among themselves and will have to determine what happens when an odd number of
systems is available.
Instructor Guide
Instructor Guide
V2.0
Uempty 5.3 WebSphere MQ Clusters
What students will do Students will learn about the Cluster function that was added to
WebSphere MQ V5 product.
How students will do it Students will listen to a lecture and participate in classroom
discussion and will use their knowledge in a machine exercise.
What students will learn Students will learn:
About the basic idea of MQ clusters and their benefits
What WebSphere MQ objects are used to support clusters
How a simple cluster is defined / set up
About administrative functions available to control clusters
How this will help students on their job Students will be able to use this new and
interesting function in their home environments. They will be able to explain the benefits of
clustering and to administer the migration from common distributed queuing.
Instructor Guide
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.
What Is a CIuster ?
QM2
QM3
QM1
QM4
CLUSTER
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose Just to introduce WebSphere MQ clusters.
Details Refer to chapters 1 and 2 of WebSphere MQ Queue Manager Clusters.
Clustering is supported on WebSphere MQ for AIX, iSeries, HP-UX, z/OS, Solaris,
Windows and Linux for Intel and zSeries and MQSeries for Compaq Tru64 UNIX, OS/2
Warp and Sun Solaris V5.1 platforms.
The supported communication protocols that you can use to connect these queue
managers are: TCP, LU 6.2, NetBIOS, SPX, OS/2 or Windows, and UDP for AIX only.
Additional Information We only want to explain the concepts of clustering and their basic
benefit, which is reduced administration. You could use a short calculation sample as to the
number of channel and remote queue definitions that may be managed for a network of,
let's say 20 queue managers (which isn't too much).
Transition Statement In order to provide these goodies, WebSphere MQ introduces
some special objects.
Instructor Guide
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
CIuster Support Objects
QM2
QM3
QM4
LocaI
AppIication
Queues
CIuster
Transmission
Queue
CIuster-
Sender ChI
CIuster-
Receiver ChI
CIuster
Command Queue
QM1
CIuster
Repository Queue
Instructor Guide
V2.0
Uempty
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 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.
Instructor Guide
Instructor Notes:
Purpose To introduce the special objects related to clusters and to explain how they
support the cluster function.
Details Refer to chapter 1 of WebSphere MQ Queue Managers Clusters - Concept and
terminology.
Additional Information This is probably the most important page of this topic.
Understanding what the single objects are used for is the basis of understanding the whole
function.
Note that we have another visual that explains the details about repositories, so you should
only say here that there are repository queues where the cluster info is stored.
Transition Statement There are some details to describe about these repositories, as
they play an important role in the cluster function.
Instructor Guide
V2.0
Uempty
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
More About Repositories
QM1
CLUSSDR
FULL
REPOSITORY
QM4
FULL
REPOSITORY
QM3
partiaI
repository
QM2
partiaI
repository
If QM1 faiIs, QM2 wouId connect to QM4
as its fuII repository system.
Instructor Guide
information may be updated and extended during operation through inquiries of a full
repository.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce and explain FULL and PARTIAL repositories
Details None.
Additional Information You could refer back to the first unit, where we told that some
information that isn't available in form of messages is stored in "system queues" by
WebSphere MQ. Repository queues are of this type.
They need to understand that one of the first decisions that have to be made when setting
up a cluster, is to determine the qmgrs that are to have a full repository. All other qmgrs
must have a predefined CLUSSDR channel to one of the full repository qmgrs in the
cluster.
You may call QM1 the primary repository, and QM4 the secondary, but this is true only from
QM2's point of view. Both full repository QMGRs have completely equal rights and
functions, as to the cluster.
The full and partial repositories store queue manager information like the creation of a new
queues for 30 days. To prevent this data from expiring the queue manager resends
information about themselves after 27 days. When data expires it is not immediately
removed, but instead it has a grace period of 60 days. If during the grace period no
changes occur then the data is removed. This grace period provides a queue manager that
was temporarily out of service at the expiry date the right to rejoin just as long as it does not
stay disconnected from the cluster for 90 days. Then that queue manager no longer is part
of the cluster.
Transition Statement After we know the base elements of a cluster and how they are
used, we need to see how a cluster is really set up.
Instructor Guide
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.
Setting Up a CIuster
ON QM1:
ALTER QMGR REPOS(EDUC)
DEFINE CHANNEL(TO.QM1) +
CHLTYPE(CLUSRCVR)CONNAME(...) +
CLUSTER(EDUC)
CHLTYPE(CLUSSDR) CONNAME(...) +
CLUSTER(EDUC) +
DESCR('To Other Full Repository')
DEFINE QLOCAL(QUEUE1) +
CLUSTER(EDUC)
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To show the definition steps necessary to start setting up a cluster.
Details Refer to chapter 3 of WebSphere MQ Queue Manager Clusters manual.
Additional Information State again that (as with most functions in WebSphere MQ) a
concept has to be developed and agreed upon as to how and for what main reasons a
cluster is needed.
Try to make clear: If you know WHAT you want to create and WHERE you finally want to go
to, it's quite easy to DO the initial setup of the cluster.
Transition Statement So you can see that the first benefit of clusters is the reduction of
network related object definitions, namely channels and transmission queues. WebSphere
MQ V5.2 and later supports DHCP in queue manager clusters with two enhancements.
Instructor Guide
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+.
DHCP Support in CIusters
WebSphere MQ V5.2 enhancements to support DHCP in clusters
Define a cluster-receiver channel without specifying the queue
managers network address
CHLTYPE(CLUSRCVR) TRPTYPE(TCP) +
CLUSTER(EDUC)
Define a cluster-sender channel without specifying the name of
the repository queue manager
DEFINE CHANNEL(TO.+QMNAME+) +
CHLTYPE(CLUSSDR) TRPTYPE(TCP) +
CONNAME(...) CLUSTER(EDUC)
Instructor Guide
V2.0
Uempty
The above example is for definitions required on QM1.
Instructor Guide
Instructor Notes:
Purpose To show the support for DHCP in queue manager clusters on WebSphere MQ
V5.2 and later.
Details Only the generated CONNAME is stored in the repositories. Other queue
managers in the cluster do not know that the CONNAME was originally blank. If the queue
manager is stopped and restarted with a different IP address, because of DHCP,
WebSphere MQ generates the CONNAME and updates the repository accordingly.
If you use the same naming convention for all channels, be aware that only one
+QMNAME+ definition can exist at one time.
Additional Information It is not possible to define CLUSSDR channel using the
+QMNAME+ construction to a queue manager on an earlier version of WebSphere MQ.
The queue manager would not recognize the construction and would not be able to find the
channel.
Transition Statement WebSphere MQ V5.2 and later includes enhancements for DHCP
support, but there is another interesting function available with clusters, that may be of
benefit to some of your applications.
Instructor Guide
V2.0
Uempty
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.
MuItipIe Queue Occurrence -
WorkIoad BaIancing
QM1
CLUSTER "EDUC"
QM2
TARGET.Q
QM4
TARGET.Q
QM3
TARGET.Q
MQOPEN
QNAME(TARGET.Q)
CLW
EXIT
DEF QL(TARGET.Q)
CLUSTER(EDUC)
ALTER QMGR
CLWEXIT(myexit)
Instructor Guide
Instructor Notes:
Purpose To introduce the workload management capabilities of the WebSphere MQ
cluster function.
Additional Information You need to state from the beginning that this is a feature that is
not suitable to all applications, but only to those who allow for parallel processing of
requests.
Transition Statement There are some options that allow to control when the
determination of the target queue manager takes place.
Instructor Guide
V2.0
Uempty
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.
WorkIoad BaIancing - Rerouting
CLUSTER "EDUC"
QM1
QM2
QM3
"MQOPEN(TARGET.Q)
MQOO_BIND_NOT_FIXED"
MQPUT
MQPUT
MQPUT
channeI to QM2
faiIs
TARGET.Q
TARGET.Q
Instructor Guide
Make sure that all of the instances of the queue have the same priority, default
persistence and defbind values.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the reroute options available as a queue definition attribute and as
an MQI open option.
Additional Information Make it clear that rerouting will only take place at the system
where the originating (message putting) application executes. Once a message has been
transmitted and reaches its destination, there will be no rerouting if the message cannot be
placed to the queue for whatever reason.
Transition Statement You can determine and control some cluster related functions from
the MANAGER's object definition.
Instructor Guide
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.
CIuster-ReIated Queue Manager Attributes
REPOS (ClusterName)
REPOSNL (NamelistName)
CLWLDATA (Data to be passed to the workload exit) 32 char max string
CLWLEXT (Cluster User workload exit name)
CLWLLEN (max # of bytes of message data passed to
cluster workload exit)
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose QMGR attributes that address cluster management.
Details
Transition Statement Finally we want to have a look at the command functions that are
available to inquire on and control clusters.
Instructor Guide
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 (including
auto-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.
ControIIing CIusters - CIuster Commands
SUSPEND QMGR
RESUME QMGR
REFRESH CLUSTER(clustername)
RESPOS(NO/YES)
RESET CLUSTER(clustername)
QMNAME(qmname) ACTON(FORCEREMOVE)
QUEUES(NO/YES)
Instructor Guide
V2.0
Uempty
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:
QMID(qmid) ACTION(FORCEREMOVE) QUEUES(NO)
You cannot specify both QMNAME and QMID.
Instructor Guide
Instructor Notes:
Purpose To introduce the cluster control commands shown.
Details Refer to chapter 6 of the WebSphere MQ Queue Manager Clusters manual.
REFRESH CLUSTER(clustername)
REPOS(NO) Default action for the queue manger is to retain a knowledge of
all cluster queue manager and cluster queues marked as locally
defined, and all cluster queue manger that are full repository. If
a full repository it will retain knowledge of the other cluster
queue mangers in the cluster.
RERESH CLUSTER (clustername)
REPOS(YES) In addition to default action objects represent full repository
queue cluster queue managers are also refreshed. You can not
use this option if the queue managers is a full repository.
REFRESH CLUSTER(*) This refreshes the queue manager in all of the cluster it is a
remember of.
QMNAME(qmname) ACTION(FORCEREMOVE) QUEUES(NO)
QMID(qmid) ACTION(FORCEREMOVE) QUEUES(NO)
You cannot specify both QMNAME and QMID. This command can
only be issued from the full repository queue manager. To
determine when to use QMNAME and QMID is when there is
more than one queue manager in the cluster with the same name
QMNAME and you want to forcibly moved remove that queue
manager from the cluster. Do not use this command as a shortcut
to remove a queue manager from a cluster.
RESET CLUSTER(clustername)
QUEUES(NO)
This is the default.
RESET CLUSTER(clsutername)
QUEUES (YES)
Means that any references to a cluster queue or queues owned
by a the queue manager being forced removed are removed
from the cluster in addition to the cluster queue manger itself.
Transition Statement At any time, you may inquire on the current status of a queue
manager with respect to the clusters to which it belongs.
Instructor Guide
V2.0
Uempty
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.
ControIIing CIusters - DISPLAY CLUSQMGR
DSPLAY CLUSQMGR(*) CLUSTER(name) CHANNEL(name)
returns :
CLUSDATE the date and time, when the definition became
CLUSTME available to the local qmgr
DEFTYPE how the cluster qmgr was defined
QMTYPE the function of the qmgr in the cluster -
whether it provides full or partial repository
service
QMD internally generated unique qmgr name
STATUS the current status of the channel for this qmgr -
may be any valid channel status
SUSPEND yes | no - as a result of a SUSPEND QMGR cmd
Additionally, channel attributes are returned for all or the
(generically) named channels.
Instructor Guide
Instructor Notes:
Purpose To introduce the DISPLAY CLUSMGR command.
Details
If issued from a full repository qmgr, the information returned pertains to every queue
manager in the cluster.
Otherwise, it pertains only to queue managers to which the local qmgr has tried to send
a message.
For more details, refer to WebSphere MQ Queue Manager Clusters manual.
Additional Information It might be helpful to explain that this command just displays the
contents of the REPOSITORY.QUEUE.
Transition Statement Finally, we want to think about the use of other than LOCAL queue
definitions in a cluster.
Instructor Guide
V2.0
Uempty
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.
CIuster-ReIated Queue Considerations
Special Display option
DSPLAY QUEUE CLUSNFO
Cluster Alias Queues
DEF QA(PUBLC) TARGET(LOCAL.Q) +
CLUSTER(TALY)
Cluster Queue Manager Aliases
DEF QR(ROME) RNAME() RQMNAME(PSA) +
XMTQ(XQ) CLUSTER(TALY)
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To give some idea of how to use QALIAS and other types of definitions in a
cluster environment.
Details There are some nice samples in the Chapter 3, Using alias and remote queue
definitions with clustering, in the WebSphere MQ Queue Manager Clusters manual. But be
sure you really understand the use of the objects before you present one of these samples
here.
Additional Information Be cautious: this issue may provoke lively discussions, and there
is a danger that everybody will be more confused at its end.
Transition Statement End of topic - introduce the cluster exercise here.
Instructor Guide
Instructor Guide
V2.0
Uempty 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 SENDER 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.
Correct Answer: b
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 be
executed.
d. The channel will fail and any in-transmit messages will be lost.
Correct Answer: a
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.
Instructor Guide
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, instrumentation 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.
Unit Summary
Configuration for distributed queuing
The MQ in the network
Remote administration
nstrumentation events
Reports
Dead letter queue
Cluster support available with WebSphere MQ V5.1
Exercises 4 and 5
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details The students should have established some connections between systems in
the class. The practical session at the end of the next unit will provide an opportunity to
extend these connections into a larger network.
Transition Statement End of the unit. Next, some more about distributed queuing.
Instructor Guide
Instructor Guide
Copyright IBM Corp. 1996, 2003 Unit 6. More on Distributed Queuing 6-1
V2.0
Uempty
Unit 6. More on Distributed Queuing
This unit describes further aspects of distributed queuing.
WebSphere MQ Family SupportPacs
Security
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
Accountability:
Machine exercises
Classroom discussions
References
If iSeries:
Instructor Guide
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.
Unit Objectives
Describe SupportPacs and how to get them
Explain WebSphere MQ clients
Set up a simple WebSphere MQ client configuration
Describe the access control features available on various
WebSphere MQ queue managers
Describe how Secure Sockets Layer (SSL) works
List channel exits and define their use
Know where to find information on writing security exits
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details This unit describes the WebSphere MQ Family SupportPacs, WebSphere MQ
clients, and security.
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.
Understand how Secure Sockets layer fits in the scheme of security.
Distinguish one channel exit from another.
Transition Statement The first topic is about WebSphere MQ Family SupportPacs.
Instructor Guide
Instructor Guide
V2.0
Uempty 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.
What students will do Students will listen to a presentation on WebSphere MQ Family
SupportPacs.
What students will learn Students will learn how additional function can be added to
WebSphere MQ products.
How this will help students on their job This knowledge will help the students be more
effective users of WebSphere MQ.
Instructor Guide
Figure 6-2. Overview of SupportPacs MQ157.0
Notes:
WebSphere MQ Family SupportPacs can be found at the following Web address:
www.ibm.com/software/ts/mqseries/txppacs
Overview of SupportPacs
Transaction Processing SupportPacs
Specific functions or services
Contributors throughout BM
Available world wide
Enhance CCS and WebSphere MQ products
Available in four categories
Fee-based services
Not available for download
Freeware
Provided AS-S with no warranty or defect correction
Product Extensions
Fully supported
Third Party Contributions
Provided AS-S with no warranty or defect correction
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To provide an overview of SupportPacs.
Details The IBM WebSphere MQ Family SupportPacs library consists of material that
complements the family of CICS and WebSphere MQ products marketed by IBM. Each
SupportPac supplies a particular function or service that can be used with one or more of
the CICS and WebSphere MQ products. Many SupportPacs are freely available for
download while others have to be purchased as fee based services from IBM.
The SupportPacs are grouped into the following categories.
Category 1 - Fee-based services
SupportPacs in this category provide material to be used by IBM Systems
Specialists as the basis for fee earning services contracts with customers.
They are advertised in the SupportPacs library but their content is only
available to IBM personnel. Customers interested in obtaining services
based on the material should contact their IBM representative.
Category 2 - Freeware
SupportPacs in this category are provided free to all users of CICS and
WebSphere MQ products. They typically provide material covering areas
such as:
Background education on CICS and WebSphere MQ products.
Sample utilities to assist in the development of CICS and
WebSphere MQ based applications.
Sample utilities to assist in the operation and management of CICS
and WebSphere MQ based systems.
The material is provided AS-IS and the license agreement under which
these SupportPacs are made available does not provide for warranty or
defect correction.
Category 3 - Product Extensions
Product Extensions are provided free to all users of CICS and WebSphere
MQ products. They are supplied under the standard terms and conditions
provided by the IBM International Program License Agreement (IPLA) and
thus provide for warranty and/or defect correction.
The terms and conditions under which a SupportPac is supplied are contained in a file
which is delivered with the SupportPac.
Category 3 SupportPacs are available free from the World Wide Web. Their quality and
support are the same as the WebSphere MQ products they are used with.
The following comments refer mainly to category 1 and category 2 SupportPacs.
Instructor Guide
Quality
IBM strives for the highest quality but does rely primarily on the
professionalism and experience of the authors.
Every SupportPac is reviewed by a member of the WebSphere MQ
Technical Support team.
Users are asked for feedback.
Support
SupportPacs are provided in good faith and on an AS-IS basis. No
warranty or support is implied or committed.
The sample code is not supported by the IBM Service organization.
Price
No charge for a category 2 (or category 3) SupportPac.
The charge for a category 1 SupportPac depends on its use.
Suggestions and criticism
Use the SupportPacs forum.
Comments are forwarded promptly to the author.
Availability
Most are now available for download on the World Wide Web.
Category 1 SupportPacs can only be obtained by IBM personnel
using an internal delivery mechanism.
Additional Information Function that is initially delivered as an WebSphere MQ
SupportPac is sometimes included in a later release of the WebSphere MQ product to
which it applies.
Transition Statement Next we look at some examples of WebSphere MQ SupportPacs.
Instructor Guide
V2.0
Uempty
Figure 6-3. Example: MD01 MQ157.0
Notes:
This SupportPac is designed to provide a common base from which all WebSphere MQ
personnel, like System Administrators, Application Developers, can work.
ExampIe: MD01
WebSphere MQ - Standards and conventions
This SupportPac aims to recommend some standards and hints,
encompassing all aspects of WebSphere MQ, and allowing
WebSphere MQ to be exploited the way it was designed.
This SupportPac applies to all WebSphere MQ platforms
Instructor Guide
Instructor Notes:
Purpose To illustrate the kind of function provided by a category 2 SupportPac.
Details The benefits of this support pac are as follows:
Consistency in applications and administration processes
Maximum availability of applications
Avoiding common mistakes made by beginners
Assistance to those in the early stages of becoming WebSphere MQ experts
General assurance of a smooth start for successful WebSphere MQ projects
Acceptance and implementation of these standards is at the users discretion. The
recommendations in this support pac have been built up to incorporate wide experience
with WebSphere MQ. The user should change these suggestions by adding house
standard as needed.
Transition Statement Next we look at a SupportPac which can be used on a variety of
platforms.
Instructor Guide
V2.0
Uempty
Figure 6-4. Example: MO01 MQ157.0
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.
ExampIe: MO01
WebSphere MQ for AX and MQSeries for OS/2 Warp Utilities
Three sample utilities
Event queue monitor
Dead letter queue monitor
Program to remove expired messages
Useful sample source code:
To parse an event message
To read a dead letter header
To obtain information from the command server
Instructor Guide
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.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe another SupportPac.
Additional Information Most SupportPacs include source code that can be used as
examples when creating similar function.
Transition Statement Next we look at another SupportPac that allows you to save
Queue Manager definitions.
Instructor Guide
Figure 6-5. Example: MS03 MQ157.0
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.
ExampIe: MS03
WebSphere MQ saves Queue Manager object definitions using
PCFs
nterrogates the attributes of all the objects defined to a queue
manager (either local or remote) and saves them to a file
Suitable for use with RUNMQSC
Can be used with any of the WebSphere MQ family that supports
PCFs
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To illustrate the kind of utilities provided by a SupportPac.
Details
This is an enhancement of a previous SupportPac, and now supports all non-MVS
specific WebSphere MQ objects (queue manager, queue, process and channels).
It functions with RUNMQSC, allowing you to rebuild saved objects if necessary.
This is a cross-platform SupporPacs, and is suitable for any of the WebSphere MQ
family that supports PCF messages.
Some understanding of C programming is needed to implement this SupportPac.
Additional Information None
Transition Statement End of the topic. Next we look at WebSphere MQ clients.
Instructor Guide
Instructor Guide
V2.0
Uempty 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.
What students will do Students will listen to a presentation on WebSphere MQ clients.
How students will do it Depending on the systems available, a WebSphere MQ client
may be configured in the practical exercise at the end of the unit.
What students will learn Students will learn what function is provided by a WebSphere
MQ client and how a WebSphere MQ client is configured.
support a WebSphere MQ network which exploits this facility.
Instructor Guide
Figure 6-6. WebSphere MQ Client MQ157.0
Notes:
WebSphere MQ CIient
Assured delivery
Queue storage
Data conversion
Administration
Recovery
Syncpoint control
Communications
stack
CIient
connection
WMQ
appIication
CIient system
Communications
stack
Server
connection
WMQ
queue
manager
Server system
MQI channeI
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To review the concept of an WebSphere MQ client.
Details This visual was first shown in Unit 1. Use it to revisit the concept of a
WebSphere MQ client ensuring that the following are understood.
What a WebSphere MQ client application can do, that is, issue MQI calls to a queue
manager that is on another system.
The concepts of a client system and a server system.
The roles of the client connection and the server connection.
The concept of an MQI channel, distinguishing it from a message channel.
How an MQI channel is started, that is, by the WebSphere MQ client application issuing
an MQCONN call.
Transition Statement Next we look in a little more detail at how a WebSphere MQ client
application operates.
Instructor Guide
Figure 6-7. WebSphere MQ Clients Explained MQ157.0
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 the
application 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.
WebSphere MQ CIients ExpIained
Server
Connection
MQCONN(..)
MQOPEN(..)
MQGET(..)
MQPUT(..)
MQCLOSE(..)
MQDISC(..)
Application
Code
MQCONN(..)
MQOPEN(..)
MQGET(..)
MQPUT(..)
MQCLOSE(..)
MQDSC(..)
Client
Connection
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To provide more detail relating to the operation of a WebSphere MQ client
application.
Details When an application is running as a WebSphere MQ client, an MQI call acts like
a remote procedure call to the server queue manager on another system. Most of the code
that is executed in servicing an MQI call resides on the server system.
This can mean that some delay may be involved in servicing an MQI call if there is a
communications failure. Any failure is subsequently reported to the application by means
of a reason code.
The input parameters of an MQI call are sent by the client connection over the network to
the server connection which is running on the server system. The server connection acts
as a surrogate for the client application and issues the MQI call to the server queue
manager on behalf of the application. When the call has been executed, the server
connection sends the output parameters of the call over the network to the client
connection which passes them on to the application.
Although the full range of MQI calls and options are available to an application running as a
WebSphere MQ client, there may be restrictions relating to system resources in certain
environments, for example, memory constraints.
Additional Information It is possible to configure a WebSphere MQ client application so
that it can connect to a queue manager running on the same system, that is, a loopback
connection. This would allow, for example, a Windows application, running under
WIN-OS/2, to connect to an OS/2 Warp queue manager on the same system.
Transition Statement Next we review the rules concerning syncpoint control in relation
to a WebSphere MQ client application.
Instructor Guide
Figure 6-8. Syncpoint Control MQ157.0
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.
Syncpoint ControI
Application
Code
MQGET(..)
MQPUT(..)
Syncpoint
MQ
CICS
DB
A WebSphere MQ client application may participate in a local unit
of work involving WebSphere MQ resources
Uses the MQCMT and MQBACK calls for this purpose
A WebSphere MQ client application cannot participate in a global
unit of work involving WebSphere MQ resources
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To review the rules concerning syncpoint control in relation to a WebSphere
MQ client application.
Details The rules concerning syncpoint control in relation to a WebSphere MQ client
application were covered earlier in the course. This visual should therefore be a revision of
what was taught previously. It may be necessary to review the concepts of a local unit of
work and a global unit of work.
Transition Statement Next we look at how a WebSphere MQ client is installed.
Instructor Guide
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.
InstaIIation
Method 1 (Version 5 only)
nstall from the WebSphere MQ Client CD-ROM supplied with the
product
Method 2
For a client platform which is the same as the server platform
Select the required client component during the standard install
Method 3
nstall the client component on the server system
Copy the files of the client component to the client system
Modify CONFG.SYS, AUTOEXEC.BAT, and so forth
Method 4
nstall from a SupportPac
Instructor Guide
V2.0
Uempty
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
platforms only.
Instructor Guide
Instructor Notes:
Purpose To describe the methods that can be used in install an WebSphere MQ client.
Details
Method 1
This applies to Version 5 products only. The installation uses the
WebSphere MQ Client CD-ROM 1 which is supplied with the product. If
you are installing AIX, HP-UX, Solaris or Windows, you will use this
CD-ROM except for Windows. Each platform CD-ROM contains two
separate directories for the client components, one with WebSphere MQ
SSL support and one without. If you are installing a WebSphere MQ client
and server on the same system, you do not use this method. Instead you
will use the WebSphere MQ CD-ROM supplied with the product and follow
Method 2.
Refer to the WebSphere MQ Clients manual, or the relevant WebSphere
MQ Quick Beginnings Guide, for full details of this method.
Method 2
You use this method in either of the following cases.
For a WebSphere MQ V5.3 product, if you are installing a client
and server on the same system.
For MQSeries for Compaq Open VMS Alpha, AT&T GIS UNIX,
and SINIX and DC/OSx client components, if you are installing
a WebSphere MQ client on the same platform as the server
platform, or if you are installing a WebSphere MQ client and
sever on a different platform. Clients for DOS, OS/2 Warp, and
Windows 3.1 are supplied with MQSeries for Compaq Open
VMS Alpha, SINIX and AT&T GIS UNIX.
Essentially, you follow the standard installation procedure for the server
and at the appropriate point, elect to install the client component.
Refer to the relevant System Management Guide or the WebSphere MQ
Quick Beginnings Guide for your platform.
Method 3
This method is only relevant to MQSeries for Compaq OpenVMS Alpha
and UNIX systems other than, AIX, HP-UX, and Solaris. It applies if you
wish to install any of the desktop clients supplied with these products, for
example, DOS, OS/2 Warp and Windows 3.1. Essentially you follow the
standard procedure for installing the server and, at the appropriate point,
elect to install the required client component files. You then need to copy
these files to the target system and make changes to CONFIG.SYS and
AUTOEXEC.BAT to aid in defining the paths to the WebSphere MQ client
directories.
Instructor Guide
V2.0
Uempty
Method 4
Most WebSphere MQ clients are now available as a category 3 IBM
Transaction Processing SupportPac. You can download these clients from
the World Wide Web. Full instructions for installation are included in each
SupportPac.
Additional Information WebSphere MQ clients cannot run on z/OS, MQSeries for
Compaq NonStop Kernel, or VSE/ESA. No WebSphere MQ Clients flies are provided on
these platforms.
Transition Statement Next we look at how to define an MQI channel.
Instructor Guide
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.
Defining an MQI ChanneI
Use the DEFNE CHANNEL command with parameters:
CHLTYPE
CLNTCONN or SVRCONN
TRPTYPE
DECNET, LU62, NETBOS, SPX, or TCP
CONNAME(string)
For a client connection only
QMNAME(string)
For a client connection only
No operational involvement on an MQ channel
An MQ channel starts when a client application issues
MQCONN (or MQCONNX call on V5.1 clients).
An MQ channel stops when a client application issues MQDSC
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe how to define an MQI channel.
Details As with a message channel, an MQI channel requires a definition at both ends of
the channel and each end of an MQI channel has a type. The two permissible types are:
CLNTCONN Client connection, for the end of the MQI channel on the client system.
SVRCONN Server connection, for the end of the MQI channel on the server system.
Remember, however, than an MQI channel is bidirectional in terms of the flow of
information, that is, the input parameters of an MQI call flow in one direction and the output
parameters in the reverse direction. You do not therefore need to define two channels, one
for each direction.
There is no direct operational involvement required for an MQI channel. It is started simply
by a client application issuing an MQCONN or MQCONNX call and it is stopped by the
client application issuing an MQDISC call.
Additional Information Considerations for defining a TCP/IP connection are the TCP/IP
connection limits. There is a limit to the number of outstanding connection requests that
can be queued at a single TCP/IP port. This is not the same as the maximum number of
clients you can attach to a WebSphere MQ server. You can connect more clients to a
server, up to the level determined by the server system resources.
Examples of backlog values for connection request are:
Server Max connection requests
AIX 100
HP-UX 20
Linus 100
OS/400 255
Solaris 100
Windows Server 100
Windows Workstation 100
AIX - 100
Transition Statement Next we look at the concept of a channel instance.
Instructor Guide
Figure 6-11. Two Ways of Configuring an MQI Channel MQ157.0
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'
Method 2 is a more complex method which involves a definition of a client connection
and a server connection on the server system.
Two Ways of Configuring an MQI ChanneI
Method 1
On the server system, define a server connection
On the client system, set the environment variable
MQSERVER=ChannelName/TransportType/ConnectionName
Method 2
On the server system, define a client connection and a server
connection
f not on a file server, copy the client channel definition table
from the server system to the client system
On the client system, set the environment variables:
MQCHLLB= Path to the directory containing the client channel
definition table
MQCHLTAB= Name of the file containing the client channel
definition table
Instructor Guide
V2.0
Uempty
The client connection definition is stored in the client channel definition table, file name
AMQCLCHL.TAB. This table must either be accessible from the client system by
residing on a file server, or it must be copied to the client system.
On the client system, the environment variables MQCHLLIB and MQCHLTAB are then
set in order to specify the location and the name of the client channel definition table.
For example, on DOS, OS/2 Warp, Windows, Windows 3.1, or Windows 95:
SET MQCHLLIB=C:\MQM
SET MQCHLTAB=AMQCLCHL.TAB
For example you can set the environment variables on a UNIX system:
export MQCHLLIB=/mqmtop/qmgrs/QUEUEMANAGERNAME/@ipcc
export MQCHLTAB=AMQCLCHL.TAB
WebSphere MQ z/OS platform is the only platform that can not store the client channel
definition table associated with the queue manager running on the server. They are
stored with WebSphere MQ objects in page set zero.
It is not possible to define a client channel table on an iSeries.
On MQSeries for Tandem NonStop Kernel, the client channel definition table is in the
file CCHDEFS which is located in the queue manager data files subvolume, that is, the
subvolume whose name has the suffix 'D'. Before using the file, it must first be
converted into a form which is acceptable to an WebSphere MQ client. This is
accomplished by means of the cnvclchl control command. This command is unique to
MQSeries for Tandem NonStop Kernel and is described in the MQSeries for Tandem
NonStop Kernel System Management Guide.
A third method is available for V5.1 clients only. An application can control the definition
of the client connection channel by providing an MQCD channel definition structure that
contains the values required. This is then passed using an MQCONNX call instead of
MQCONN.
With this option available, the client application can specify the ChannelName,
TransportType, and ConnectionName attributes of a channel at run time and this
enables the client application to connect to multiple server queue managers
simultaneously. If MQServer environment variable is used this is not possible.
A client application can specify other attributes such as MaxMsgLength and
SecurityExit allowing non-default values to be used and called at the client end of the
MQI channel. Lastly if a channel uses Secure Sockets Layer (SSL) a client application
can also provide information relating to SSL in the MQCD structure.
Instructor Guide
Instructor Notes:
Purpose To explain the two ways of configuring an MQI channel.
Details
Although method 1 is the simpler approach, method 2 provides more flexibility. For
example, using method 1, only one MQI channel can be made available to an client
application because the environment variable MQSERVER can only be set to one value.
Using method 2, the client channel definition table may contain multiple client connection
definitions and so a client application may have access to multiple MQI channels. Also,
method 1 does not support the use of queue manager groups (see later).
Using method 2, there is no problem in issuing the DEFINE CHANNEL command twice
with the same channel name as long as one command is defining a client connection and
the other is defining a server connection.
When a client application issues an MQCONN call, the following happens.
If the MQSERVER environment variable is set
The value of MQSERVER determines the MQI channel that is used. The queue
manager that the client application connects to is the same as that to which the
listener program on the server system is connected. If the MQCONN call specifies
a queue manager other than the one to which the "listener" program is connected
to, the call fails with the reason code, MQRC_Q_MGR_NAME_ERROR.
If the MQSERVER environment variable is not set
The client channel definition table is used instead.
If the client application specifies a queue manager name on the MQCONN call
The client channel definition table is searched, in channel name order, for an MQI
channel whose queue manager name field (QMNAME) contains the same name
as specified on the MQCONN call. If an MQI channel is found, an attempt is made
to start it using the value in the connection name field (CONNAME). If the attempt
fails, the search of the client channel definition table continues for a further match.
If there is no match, or if there are no more entries in the client channel definition
table, the MQCONN call fails.
Note that for an MQI channel to be started successfully, the queue manager
specified on the MQCONN call must be the same as the one to which the listener
program is connected on the server system.
If the client application specifies a queue manager name which is all blanks
This does not mean that it is attempting to connect to the default queue manager.
Instead, the same procedure as described above is followed, but the client
channel definition table is searched for an MQI channel whose queue manager
name is all blanks. The only difference is that there is no check against the name
of the queue manager to which the client application eventually connects. In other
words, specifying a queue manager name of all blanks signifies that the client
application is not concerned about which queue manager it connects to.
Instructor Guide
V2.0
Uempty
Additional Information A client application may prefix an asterisk (*) to a queue manager
name on the MQCONN call, for example,
MQCONN("*STOCK")
In the example, the name STOCK specifies a group of queue managers, not the name of the
queue manager to which the client application is attempting to connect. In this case, the
client channel definition table is searched for an MQI channel whose queue manager name
field contains the name of the queue manager group specified on the MQCONN call. See
the sample client channel definition table below.
By specifying a queue manager group on the MQCONN call, the client application is
indicating that it is not concerned about which queue manager it eventually connects to and
no check is made against the name of this queue manager. In the example, therefore, the
client application may eventually be connected to a queue manager whose name is not
STOCK.
A client application may simply specify an asterisk (*) for the name of the queue manager
on an MQCONN call. This has exactly the same effect as specifying a queue manager
name consisting entirely of blanks.
Only an WebSphere MQ client application can use queue manager groups.
If you are using MQCNO structure on an MQCONNX call there is a sample program called
amqscnxc which demonstrates the use of this function.
Transition Statement Next we look at the concept of a channel instance.
Channel 1 Queue Manager Protocol Connection Name
Stock.A Stock TCP/IP STOCKQMA
Stock.B SALES NetBios STOCKQMB
Stock.C STOCK LU6.2 STOCKDEF
Stock.D SALES NetBios STOCKQMA
Stock.E Stock TCP/IP STOCKDEF
Stock.F SALES TCP/IP STOCKDEF
Instructor Guide
Figure 6-12. Channel Instances MQ157.0
Notes:
Each of the four MQI channels shown on the visual is an instance of the same MQI
channel. The main points to note are as follows.
- The environment variable MQSERVER has an identical value on each of the client
systems with host names IO, EUROPA, GANYMEDE, and CALLISTO.
- On the server system, host name JUPITER, the queue manager requires just one
server connection definition for the MQI channel JUPITER.SVR.
- Each client application is using a different instance of the MQI channel
JUPITER.SVR.
Message channels can have instances as well. If you have multiple queue managers,
each sending messages to the same queue manager, only one receiver channel
definition is required on the receiving queue manager as multiple instances of the same
message channel can be used. You still need to define the channel on each of the
sending queue managers, but the definitions could be identical. The important point is
that the name of the channel must be identical in each of the definitions.
ChanneI Instances
MQSERVER=JUPITER.SVR/TCP/JUPITER
IO
DEFINE CHANNEL(JUPITER.SVR) +
CHLTYPE(SVRCONN) +
TRPTYPE(TCP)
JUPITER
EUROPA
GANYMEDE
CALLISTO
MuItipIe instances
of the same
MQI channeI
Instructor Guide
V2.0
Uempty
However, if you need to send messages from one queue manager to multiple queue
managers, you will need a different channel definition for each destination.
Instructor Guide
Instructor Notes:
Purpose To introduce channel instances.
Transition Statement Next we look at how a channel can be defined dynamically on
WebSphere MQ products.
Instructor Guide
V2.0
Uempty
Figure 6-13. Auto-Definition of Channels MQ157.0
Notes:
The auto-definition of channels is supported on WebSphere MQ for AIX, iSeries,
HP-UX, Linus, Solaris and Windows systems and MQSeries V5.1 for OS/2 Warp, or
later queue managers.
To enable the automatic definition of channels, the attribute ChannelAutoDef of the
queue manager object must be set to MQCHAD_ENABLED. The corresponding
parameter on the ALTER QMGR command is CHAD(ENABLED).
Once a channel definition has been created in this way and stored, the definition may
be used subsequently as though it had always existed.
Channel auto-definition events can be enabled by setting the attribute
ChannelAutoDefEvent of the queue manager object to MQEVR_ENABLED. The
corresponding parameter on the ALTER QMGR command is CHADEV(ENABLED).
The partner may be any queue manager or MQSeries client; it does not have to be at
Ver 5 level.
Auto-definition of ChanneIs
Applies only to the end of a channel with type:
Receiver
Server connection
Function invoked when an incoming request is received to start a
channel but there is no channel definition
Channel definition is created automatically using the model:
SYSTEM.AUTO.RECEVER
SYSTEM.AUTO.SVRCONN
Partner's values are used for:
Channel name
Sequence number wrap value
WebSphere MQ and MQSeries Version 5.1 or later
Instructor Guide
Instructor Notes:
Purpose To explain how a channel may be defined automatically if there is no existing
channel definition.
Details The auto-definition of channels is supported on a Version 5 queue manager only.
Only the end of a channel of type receiver or server connection can be defined
automatically.
The function is invoked if there is an incoming request to start a message channel or MQI
channel but no channel definition exists for the specific channel. In addition, the attribute
ChannelAutoDef of the queue manager object must be set to MQCHAD_ENABLED.
The definition is created using relevant system object as a model:
SYSTEM.AUTO.RECEIVER
SYSTEM.AUTO.SVRCONN
number wrap value are derived from the partner's definition of the channel. Other
attributes, such as the batch size and maximum message length for a message channel,
are negotiated with the partner as normal.
Once a channel definition has been created in this way and stored, the definition may be
used subsequently as though it had always existed.
Channel auto-definition events can be enabled by setting the attribute
ChannelAutoDefEvent of the queue manager object to MQEVR_ENABLED.
The partner may be any queue manager or WebSphere MQ client; it does not have to be at
the Version 5 level.
Additional Information A channel exit program can be used to alter values created by the
auto-definition.
Transition Statement Next we look at how errors are handled on the DOS and Windows
3.1 clients.
Instructor Guide
V2.0
Uempty 6.3 Security
This topic describes the security features of WebSphere MQ.
What students will do Students will listen to a presentation on WebSphere MQ security.
How students will do it No direct student activities are planned although, depending on
the systems available, security may be a necessary consideration in the practical session
that follows.
What students will learn Students will learn about the security features of WebSphere
MQ and how they are supported on different queue managers.
support an WebSphere MQ network where security is a requirement.
Instructor Guide
Figure 6-14. WebSphere MQ Security Implementations MQ157.0
Notes:
Security is one of the most important aspects for a distributed system and WebSphere MQ
provides a flexible security framework that allows the appropriate security architecture to be
implemented to meet your specific requirements.
Authorization for using MQI calls, commands and access to objects is provided by the
Object Authority Manager (OAM), which by default is enabled. Access to WebSphere MQ
entities is controlled through WebSphere MQ user groups and the OAM. We provide a
command interface to enable administrations to grant or revoke authorizations as required.
The supplied channel-exit programs address the Distributed Computing Environment
(DCE) considerations for security services and encryption facilities. You can not use
supplied channel-exit programs queue manager that also has SSL parameters set. This
applies to WebSphere MQ queue managers on AIX, HP-UX and Solaris.
The Secure Sockets Layer (SSL) protocol provides industry-standard channel security, with
protection against eavesdropping, tampering, and impersonation.
WebSphere MQ Security ImpIementations
Object Authority Manager (OAM) facility
Distributed Computing Environment (DCE) Security
Channel Security using Secure Sockets Layer (SSL)
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To discuss the security implementation available for WebSphere MQ.
Details
Transition Statement Next lets look at WebSphere MQ access control.
Instructor Guide
Figure 6-15. WebSphere MQ Access Control Overview MQ157.0
Notes:
The primary security component provided by WebSphere MQ is access control. This allows
WebSphere MQ to control which users are granted which types of access to which
WebSphere MQ resources. The resources which may be controlled in this way are the
queue manager, queues and processes.
All distributed queue managers provide access control facilities to control which users have
access to which WebSphere MQ resources. The distributed queue managers use the
Installable Services component of WebSphere MQ - the Authorization Service - to provide
access control for WebSphere MQ resources.
WebSphere MQ supplies an Object Authority Manager (OAM) as an authorization service
which conforms to the Installable Services interface. The OAM provides a full set of access
control facilities for WebSphere MQ including both the access control checking and
commands to set, change and inquire on WebSphere MQ access control information. The
OAM, like all Installable Services components, is replaceable by any component - user or
vendor supplied - that conforms to the Authorization Service interface.
WebSphere MQ Access ControI Overview
Granular access control facilities
Provided via WebSphere MQ nstallable Services
Which user? Which resource? What types of access?
WebSphere MQ access control at user and/ or group level
UNX use groups only
Username must exist, everyone is in nobody
Windows uses userids and/or groups
System-level userids only are supported
No support for DCE principals, TXSeries userids, and so forth
Alternate userids may be specified
When suitably authorized
First level name only is controlled:
Alias Queues, Remote Queues
Resolved name is not significant
Instructor Guide
V2.0
Uempty
WebSphere MQ captures the userid associated with an application at MQCONN. This
userid is used for the above access control checks. It is possible for suitably authorized
users to use an alternate userid instead of the logged on userid. When WebSphere MQ
checks to see if a user is permitted to access a particular resource, it is the name specified
in the MQ API command which is used for the check.
For the case of an Alias or Remote queue definition, it is still the name of the queue
specified in the MQ API command and not the resolved- to name. Thus, a user needs
access to the first named resource and not the resolved- to resource. For model queues,
there may be instances where WebSphere MQ will generate the name of the dynamic
queue. Because of this, the userid creating a dynamic queue is automatically given full
access rights to the queue.
Instructor Guide
Instructor Notes:
Purpose To discuss WebSphere MQ access control.
Details
Transition Statement Next we look at what access control function is provided with each
queue manager.
Instructor Guide
V2.0
Uempty
Figure 6-16. Object Authority Manager: Installable Service MQ157.0
Notes:
The Object Authority Manager (OAM) component conforms to the WebSphere MQ
Installable Services interface.
This provides an open, documented interface (documented in the WebSphere MQ System
Administration Guide).
The OAM is, therefore, user-replaceable, meaning that any component which conforms to
the documented interface, may replace the existing OAM.
Further, the OAM (or any component replacing it) may be augmented - having more than
one component simultaneously (actually - sequentially) running at the Installable Service
interface.
Access
Control
lists
Object Authority Manager
WebSphere MQ
QMgr
Object Authority Manager: InstaIIabIe Service
Documented nterface
(User) replaceable
Extendable
Common ACL manager for distributed queue managers
UNX
Windows
Tandem, OpenVMS, and so forth
iSeries (at 5.1 level)
Instructor Guide
Instructor Notes:
Purpose
Details
On MQSeries for OS/2 Warp, the authorization installable service is
supported, as are the control commands setmqaut and dspmqaut.
However, there is no supplied component for the authorization service.
WebSphere MQ for iSeries uses the WebSphere MQ Object Authority
Manager (OAM) in conjunction with OS/400 object level security. By
default, the OAM is active and works the control commands WRKMQMAUT
(work with authority), WRKMQMAUTD (work with authority date)
DSPMQMAUT, (display object authority), RVKMQMAUT (revoke object
authority), and RFRMQMAUT (refresh authority) and GRTMQMAUT (grant
object authority).
WebSphere MQ for iSeries maintains the mapping between a WebSphere
MQ object and an OS/400 object. Given the name of an WebSphere MQ
object, the CL command DSPMQMOBJN can be used to determine the
name of the corresponding OS/400 object, and vice versa.
On WebSphere MQ for iSeries a Principal is an OS/400 system user profile
and a Group is an OS/400 system group profile. Authorizations can be
granted or revoked at the group level only. A request to grant or revoke a
users authority updates the primary group for that user.
The remaining queue managers
On the remaining queue managers, the authorization installable service is
supported and the Object Authority Manager (OAM) component is
supplied.
The OAM maintains authorizations at the level of groups. However, on
WebSphere MQ for Windows, authorizations may also be held at the level
of individual user IDs.
Although there is a concept of a group on Digital OpenVMS, the OAM does
not use it. Instead, for the purposes of the OAM, a group is defined as the
set of all user IDs that have been granted a specific rights identifier.
The control command setmqaut is used to grant and revoke authorizations
to an WebSphere MQ object. Using the command, you may grant or
revoke authorizations for an individual user ID or for a group. Similarly, the
control command dspmqaut can be used to display the authorizations to
an WebSphere MQ object for an individual user ID or for a group. The
control command dmpmquat enables you to dump the current
authorizations associated with a specified profile, dspmqmaut (display
Instructor Guide
V2.0
Uempty
object authority), grtmqmaut (grant object authority), and rukmqmaut
(revoke object authority).
On MQSeries for Compaq OpenVMS and WebSphere MQ, if you use
setmqaut to set authorizations for an individual user ID, the authorizations
are actually held at the level of the individual user ID. For WebSphere MQ
on UNIX systems however, such authorizations are held at the level of the
user ID's primary group and so all members of that group acquire the same
authorizations. On MQSeries for Tandem NonStop Kernel, unless
SAFEGUARD is being used, a user ID may only belong to one group. The
implementation is therefore similar to that on UNIX systems; if you use
setmqaut to set authorizations for an individual user ID, all members of the
group to which the user ID belongs acquire the same authorizations.
The supplied OAM could be replaced by a user written authorization
service component.
Additional Information See SupportPac MS07 for a sample and enhanced
documentation if you are thinking about writing your own Authorization capability.
Transition Statement Next we look at how the OAM is implemented in each queue
manager.
Instructor Guide
Figure 6-17. Object Authority Manager: Installable Service... MQ157.0
Notes:
The implementation of the OAM has a set of associated access control lists.
There is a set of access control lists per queue manager, meaning that the ACLs cannot be
(automatically) shared across multiple queue managers.
The OAM provides access control facilities only for WebSphere MQ objects. These are the
queue manager itself, all queues, processes and namelists.
It does not include channels, which are not WebSphere MQ objects.
It is possible to disable access control checking. This is done by setting the appropriate
environment variable or deleting the authorization service stanza in the queue manager
configuration file qm.ini (or Registry on Windows systems).
This is not recommended;
If the OAM is disabled, then access permissions which are normally automatically set when
objects are created are no longer created. If the OAM is enabled at some later time, these
permissions will not exist and will have to be created manually.
Object Authority Manager: InstaIIabIe Services
Access control lists are WebSphere MQ specific
Not integrated with system-level security
Changes to user's OS authority isn't recognized until QMgr restart
New REFRESH SECURTY command
One ACL set per queue manager
Not shared between queue managers
Access control for WebSphere MQ objects
Queue manager
Queues
Processes
Namelists
Not channels
OAM can be disabled
Not recommended
Very difficult to reestablish uniform authority checking
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To discuss the implementation of the OAM.
Details
Transition Statement Next we look at how OAM is using access control lists with
WebSphere MQ.
Instructor Guide
Figure 6-18. Object Authority Manager: Access Control Lists... MQ157.0
Notes:
Each file contains a set of access control stanzas. There is one stanza per principal for
which access is to be controlled, where a principal is either a userid or a group.
The principals (userids and/ or groups) which have access to the appropriate object are
listed in this file, along with a bit string (in hex) which represents the access rights
associated with that entity.
For each principal which is granted access to an object, there is a permission bit pattern,
where each bit corresponds to a particular permission. These permissions are documented
in the WebSphere MQ System Administration book.
Object Authority Manager:
Access ControI Lists
One authority file per object
Plus global permissions files
Each file has one stanza per principal
Principal:
Authority='bit pattern'
Windows NT OAM bypasses auth files for certain classes of principal
SYSTEM, local Administrators group, local mqm group
MQ object permissions
19 permissions
Global permissions, for example, connect, altusr, setall, setid
Object permissions, for example, browse, put, get ... and allmqi
Administration permissions, for example, crt, dlt, chg, dlt ... and alladm
Used mostly for PCF commands
Plus all and none
Each permission corresponds to a bit in the permission bit pattern
Connect = 0x000001
Put = 0x000008
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose
Details The access control lists for the OAM are implemented as a set of system files,
using one file per WebSphere MQ object.
As there are some permissions which span a single MQ object, there is also a small set of
files which are not related to any particular MQ object.
The supplied OAM does not support generic profiles - this is mostly because of the
one-to-one correspondence between system files and MQ objects.
The ACLs are not classed as recoverable objects by the queue manager. If the ACLs are to
be recoverable then they should be backed up or Supportpac MS63 should be used as an
ACL regeneration tool.
Each ACL file is named according to the object with which it is associated (with the
exception of the 'special' files). Where an object name has been mangled, the name of the
associated ACL file is also mangled.
Transition Statement Next we look at changes introduced by MQSeries V5.2
Instructor Guide
Figure 6-19. Object Authority Manager: The MQSeries 5.2 update MQ157.0
Notes:
The new OAM is the default, although the older OAM is still supplied and can be used if you
rely on the format of the old auth files.
To reactivate the old OAM, edit the qm.ini file to point at the older module.
Performance of authorization checks has been substantially improved by the new OAM.
Removal of the auth files also improves the integrity of the ACL data as it is managed in the
same way as the contents of queues.
The new OAM supports the MQSC "REFRESH SECURITY" command. The old OAM does
not.
Object Authority Manager:
The MQSeries 5.2 Update
WebSphere MQ V5.2 has a new default OAM implementation
This has the same access control function
But ...
The auth files have been removed
Configuration is now stored in WebSphere MQ messages
Which means ...
There is no need to independently backup the auth files
Recovery of ACLs is automatic at queue manager restart
Existing auth files are automatically migrated to new format
New command (amqoamd) dumps the ACLs in readable format
New OAM also supports the "REFRESH SECURTY" MQSC
command
Changes to a user's OS authorities (that is, the groupset) can now
be read without restarting a queue manager
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To discuss MQSeries V5.2 OAM Security.
Details
Until V5.1 the OAM maintains its own access control lists called authorization files. These
are held in the auth directory within the queue managers directory. On MQSeries for
Tandem NonStop Kernel, they are held in the queue manager OAM subvolume, that is, the
subvolume whose name has the suffix 'X'.
The new OAM is the default, although the older OAM is still supplied and can be used if you
rely on the format of the old auth files. You can edit the qm.ini or (Registry for Windows) to
point at the older module. Performance of authorization checks has been substantially
improved by the new OAM. Removal of the auth files also improves the integrity of the ACL
data as it is managed in the same way as the contents of queues.
On MQSeries V5.2 queue managers authorization data is provided on a local queue, called
SYSTEM.AUTH.DATA.QUEUE. So OAM's authorization group can be updated
immediately, without needing to stop and restart the queue manager.
Transition Statement Next we look at WebSphere MQ V5.3 enhancements.
Instructor Guide
Figure 6-20. Object Authority Manager V5.3 MQ157.0
Notes:
All authorization data is migrated from the authorization files to the authorization queue the
first time that you restart the queue manager after migrating from WebSphere MQ. You can
continue to store authorization data in files, but it affects the performance of the OAM.
OAM generic profiles enable you to set the authority a user has to many objects at once,
rather than having to issue separate setmqaut commands. New objects will inherit these
definitions automatically. The wildcard matching, based on qualifiers with '.' separators is
based on RACF.
The control commands that are available with the new OAM are; DSPMQAUT (display
authority), DMPMQAUT (dump object authority), and SETMQAUT (set and reset authority).
WebSphere MQ for iSeries CL commands for managing objects are; DSPMQMAUT
(display object authority) GRTMQMAUT (grant object authority), and RVKMQMAUT
(revoke object authority).
Authorization Files
Seamless migration of auth files for existing queue managers
Auth files can be maintained
Generic Profiles
Ability to use wildcards in ACL specifications
?, *, **
setmqaut -n AB.* -t +put -p fred
'Best-match' algorithm used to select which profile applies
Reduces number of admin actions
Permissions can be established before queues defined
New commands and options for displaying information
To dump complete configurations for easy viewing
Who has access to what
Based on RACF profile definitions
Object Authority Manager V5.3
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To discuss the new features of WebSphere MQ V5.3 security enhancements.
Details Storing authorization data on a local queue reduces time to check
authorizations. You can not use generic profiles if auth data files are used.
The use of wildcards makes a profile generic. For example the ? wildcard character
matches any single character in a name. The use of an asterisk (*) as:
A qualifier - a profile name to match any one qualifier in an object name. A qualifier is
the part of an object name delimiter by a period. For example, ABC.DEF.GHI.
A character - within a qualifier in a profile name to match zero or more characters
within the qualifier in an object name.
Lastly the use of a double asterisk (**) once in a profile name as:
The entire profile name to match all objects names. For example, if use -t prcs to
identify processes, then use ** as the profile name, you change the authorizations for all
processes.
As either the beginning, middle, or ending qualifier in a profile name to match zero or
more qualifiers, in an object name. For Example, **.ABC identifies all objects with the
final qualifier of ABC.
Generic profiles on UNIX systems require you enclose the profile name in quotes.
The USER ID that creates a WebSphere MQ object has all authorities to the object. If you
remove the user from the mqm group or Administrators group that does not completely
revoke authorities to this object. You must also issue the SETMQAUT command to revoke
full access of the object from the user that created the object.
Transition Statement Next we look at several of WebSphere MQ control commands that
provide the management vehicle for WebSphere MQ objects.
Instructor Guide
Figure 6-21. Security Management: setmqaut MQ157.0
Notes:
There are three control commands which provide control of the security environment for
WebSphere MQ, setmqaut, dspmqaut, dmpmqaut.
These programs require a connection to the authorization service and so may only be used
when the target queue manager is active and the OAM is enabled. All of the responses to
these commands are displayed on the screen. These commands are documented in the
WebSphere MQ System Administration Guide.
Setmqaut is used to set the access that a principal or group has to a particular resource.
This can be used to add or remove privileges.
Note that there are certain principals/ groups which are granted automatic access to
resources. These are:
mqm (user/group)
For Windows:
- Administrator (user/local group)
- SYSTEM (userid)
Security Management: setmqaut
Change the authorizations
qmgr
queues
processes
namelists
authinfo (SSL channel security)
Principal or group level control
User level or group level control
Granular control of access
No generic functions
Supports generic profiles
setmqaut -m QMgr -t Objtype -n Profile [-p principalname | -g groupname]
permissions
stemqaut -m JUPITER -t queue -n MOON.*
-g VOYAGER +browse +get
Instructor Guide
V2.0
Uempty
The user (or principal group) which creates a resource
All other principals and groups must be granted access to a resource using the utility.
Setmqaut can utilize generic profiles. In the example above, the setmqaut control
command allows members of the group VOYAGER to get and browse messages on the
queue whose name commences with the characters MOON. That is owned by the queue
manager JUPITER. MOON.* is the generic profile.
Instructor Guide
Instructor Notes:
Purpose To discuss the setmqaut control command.
Details
Transition Statement Next we look at displaying WebSphere MQ security.
Instructor Guide
V2.0
Uempty
Figure 6-22. Security Management: dspmqaut MQ157.0
Notes:
This program requires a connection to the authorization service and so may only be used
when the target queue manager is active and the OAM is enabled. All of the responses to
these commands are displayed on the screen. This command is documented in the
WebSphere MQ System Administration Guide.
Dspmqaut does support of generic profiles. If a user ID is a member of one or more
groups, this command displays the combined authorizations of all the groups.
Only one group or principal can be specified.
On WebSphere MQ for Windows you can specify a local group.
Security Management: dspmqaut
Display current authorizations
qmgr
queues
processes
namelists
authinfo ( SSL channel security)
User level or group level control
dspmqaut -m QMgr -t ObjType -n ObjName [- p Principal | -g Group ]
dspmqaut -m SATURN -t q -n APPL.Q1 -p mquser
Entity mquser has the following authorizations for object APPL.Q1:
get
browse
put
...
Instructor Guide
Instructor Notes:
Purpose To discuss the dspmqaut control command.
Details
Transition Statement Next we look at WebSphere MQ control command that allows the
administrator to dump the current authorizations associated with a specified profile.
Instructor Guide
V2.0
Uempty
Figure 6-23. Security Management: dmpmqaut MQ157.0
Notes:
The WebSphere MQ control command enables you to dump the current authorizations
associated with a specified profile. The WebSphere MQ System Administration Guide
provides documentation on this command.
Dmpmqaut can be used to dump authority records for a generic profile.
The -l parameter allows you to dump only the profile name and the type. The listing will be
a terse list of all profiles names and types.
Group names must exist and you can only specify one group name on the dmpmqaut
command. WebSphere MQ for Windows allows the use of local groups only.
Dump current authorizations
qmgr
queues
processes
namelists
authinfo (SSL channel security)
dmpmqaut -m Qmgr -t Objtype -n Profile [-p principalname | -g groupname]

dmpmqaut -m qm1 -n a.b.c -t q -p user1
The resulting dump would display:
profile: a.b.*
object type: queue
entity: user1
type: principal
authority: get, browse, put ,inq
Security Management: dmpmqaut
Instructor Guide
Instructor Notes:
Purpose To discuss the dmpmqaut control command.
Details
Transition Statement Next we will look at WebSphere MQ control program security.
Instructor Guide
V2.0
Uempty
Figure 6-24. Access Control for WebSphere MQ Control Programs MQ157.0
Notes:
Access ControI for
WebSphere MQ ControI Programs
Most WebSphere MQ control programs
For example, crtmqm, strmqm, runmqsc, setmqaut
Have restricted access
UNX restricts users to the mqm group
Configuration as a part of WebSphere MQ installation
Control imposed by the operating system, not OAM
OpenVMS restricts users to those granted the MQM identifier
Tandem NSK allows:
MQM group
SUPER.SUPER D
Windows allows
mqm group
Administrators group
System userid
runmqsc needs to be restricted
As channels are not controlled by WMQ administration ACLs
Instructor Guide
Instructor Notes:
Purpose To discuss how WebSphere MQ is handled for various platforms.
Details
Transition Statement Next we look at security checking in the MQI.
Instructor Guide
V2.0
Uempty
Figure 6-25. Authority Checking in the MQI MQ157.0
Notes:
When attempting to access an alias queue, authority checking occurs at the level of the
alias queue, not at the level of the queue to which it resolves. The same is true for a
local definition of a remote queue. It is therefore possible to grant no access to a local
queue and only grant access to an alias queue which resolves to it.
Limit the ability to define queues to privileged users. Otherwise, normal access control
could be bypassed simply by creating an alias queue.
The MQCLOSE is generally not checked because the close options are usually none.
However, if the close options are set to MQCO_DELETE or MQCO_DELETE_PURGE (this
is only valid for permanent dynamic queues) then, unless the queue was created using the
current handle, there is a check to determine if the user is authorized to delete the queue.
Authority Checking in the MQI
MQ calls with security checking
MQCONN / MQCONNX
MQOPEN
MQPUT1 (implicit MQOPEN)
MQCLOSE (sometimes)
MQCLOSE
For Dynamic queues
WebSphere MQ events as audit records
Events written to SYSTEM.ADMN.QMGR.EVENT queue
Documeneted in WebSphere MQ Event Monitoring manual
Reason code MQRC_NOT_AUTHORZED returned if not
authorized
Instructor Guide
Instructor Notes:
Purpose To explain how access to WebSphere MQ resources is controlled.
Details Although there is a lot in common in the way access control to WebSphere MQ
resources is implemented on each queue manager, there are some differences.
When an application is attempting to access an WebSphere MQ object, the general rule is
that its authority is checked on the first object in the resolution path. For example, if the
object descriptor supplies the name of a remote queue and the name of a remote queue
manager, authority checking occurs at the level of the transmission queue which has the
same name as that of the remote queue manager. If, on the other hand, the application
attempts to open a local definition of a remote queue, authority checking occurs against
that object. In the case of an alias queue, authority checking occurs at the level of the alias
queue, not at the level of the queue to which it resolves.
Because of this, it is a good idea to restrict the ability to create queues to privileged users
only. The use of the +crt authorization on the setmqaut control command allows you to
specify which users are allowed to create queues. For example:
setmqaut -m QMgrName -t queue -g GROUPB +crt
Normally, authority checking for an application only occurs when it issues an MQCONN,
MQCONNX (Version 5 queue managers only), MQOPEN, or MQPUT1 call. There is one
exception to this rule however. When an MQCLOSE call is issued to delete a permanent
dynamic queue, using an object handle other than the one returned by the MQOPEN call
that created the queue, a check is made that the user identifier which was used the validate
the MQOPEN call is authorized to delete the queue.
If an application is not authorized to access an WebSphere MQ object for a requested
operation, the reason code MQRC_NOT_AUTHORIZED is returned by the MQI call.
Additional Information The Queue Manager generates audit records when there is an
attempt to access a resource for which permission has not been generated by the OAM.
There are four different types of audit records, as illustrated. In general, there is little point
in establishing an access control schema if there is no monitoring of access control
violations. That stated it is very important to enable the audit records, via the queue
manager object, and to have someone monitor these audit records for violations.
Transition Statement Next we look at some aspects of security related to distributed
queuing.
Instructor Guide
V2.0
Uempty
Figure 6-26. Security and Distributed Queuing MQ157.0
Notes:
When defining the receiving end of a message channel, there is an option which allows you
to specify which user identifier is to be used for checking the authority of the receiving MCA
to open a destination queue in order to put a message on it. You can choose one of the
following.
Default user identifier
The receiving MCA's default user identifier is used. This user identifier may
be changed by a security exit, or by setting the MCAUSER parameter in the
channel definition at the receiving end of the message channel.
Context user identifier
The user identifier in the context of the message is used.
You should only allow special system programs to put messages directly on a transmission
queue.
Security and Distributed Queuing
Put authority
Option for the receiving end of a message channel
Default user identifier is used
Context user identifier is used
Transmission queue
Messages destined for a remote queue manager are put on a
transmission queue by the local queue manager
An application should not normally need to put messages directly on a
transmission queue, or need authority to do so
Only special system programs should put messages directly on a
transmission queue and should have the authority to do so
Instructor Guide
Instructor Notes:
Purpose To explain some aspects of security that apply to messages destined for a
remote queue manager.
Transition Statement Next we look at message context which allows the identity of the
sender to flow with a message.
Instructor Guide
V2.0
Uempty
Figure 6-27. Message Context MQ157.0
Notes:
Message context information allows for the application that retrieves a message to find out
about the originator of the message. The retrieving application may want to:
Check that the sending application has the correct level of authority.
Keep an audit trail of all the messages it has worked with.
The information is held in two fields: context and origin context.
Message Context
QUEUE 3
D
C
QUEUE 2
A
QUEUE 1
B
Information about source of message
dentity section - user related
Origin section - program related
Part of Message Descriptor
Can be passed in reIated message
Instructor Guide
Instructor Notes:
Purpose To introduce the concept of message context.
Details There are two groups of fields in the message descriptor about the originator of a
message. They are supplied by an application, or generated by the queue manager,
depending on the option used on an MQPUT or MQPUT1 call.
Transition Statement Next we look at the context fields.
Instructor Guide
V2.0
Uempty
Figure 6-28. The Context Fields MQ157.0
Notes:
An application can request the queue manager to set the context fields of a message by
using the put message option MQPMO_DEFAULT_CONTEXT on an MQPUT or MQPUT1
call. This is the default action if no context option is specified.
The visual lists the context fields and provides some examples of what the queue manager
sets them to when it generates the information.
Identity context
User that originated the message.
UserIdentifier is 12 characters long. Longer user IDs are generally
not permitted. For Windows, the queue manager uses the first 12
characters of the logged-on user name.
On OS/2 Warp, the queue manager uses the string os2.
On OS/400, the queue manager uses the name of the user profile
associated with the application job.
The Context FieIds
Identity context
UserIdentifier
AccountingToken
DigitaI OpenVMS
Numeric group ID and user ID
(UIC) in ASCII characters
OS/2 Warp, DOS cIient,
Windows cIient, Windows
ASCII character '1'
OS/400
Job accounting code
UNIX
Numeric user ID in ASCII
characters
ApplIdentityData
BIank
Origin context
PutApplType
MQAT_AX, MQAT_CCS, and
so forth
PutApplName
PutDate
YYYYMMDD (GMT)
PutTime
HHMMSSTH (GMT)
ApplOriginData
BIank
Instructor Guide
Accounting token
The queue manager treats the information in this field as binary
information, not character information. When the queue manager
generates this information, it sets the first byte to the length of the
accounting information. The length of the first byte is in the range
zero through 30. The second and subsequent bytes are set to the
accounting information based on the environment.
On OS/2 Warp, PC DOS, Windows 3.1, 95, 98, the accounting
information is set to the ASCII character 1.
On Windows, the accounting information is set to a Windows NT
security identifier (SID) in a compressed format.
On Compaq OpenVMS Alpha, Compaq NonStop Kernel, and UNIX
systems, the accounting information is set to the numeric user
identifier, in ASCII characters.
The last byte is set to the accounting-token type, on of the following
values:
MQACTT_NT_SECURITY_ID
Windows security identifier
MQACTT_OS2_DEFAULT - OS/2
default accounting token
MQACTT_OS400_ACCOUNT_TOKEN
OS/400 accounting token
Application data relating to identity.
Origin context
Type of the application that put the message.
Name of the application that put the message.
On OS/2, PC DOS, and Windows systems, the queue manager
uses:
For a CICS application, the CICS translation name
For a non-CICS application, the rightmost 28 characters of the fully
qualified name of the executable
On Compaq OpenVMS Alpha and Compaq NonStop Kernel, the
rightmost 28 characters, if available otherwise blanks.
On UNIX systems, it uses the same as for CICS applications just
like Windows, but for non-CICS applications, the rightmost 14
characters.
Instructor Guide
V2.0
Uempty
On OS/400, the fully qualified job name is used.
Date when the message was put.
The format of the date, when it is generated by the queue
manager, is YYYYMMDD and the date itself is in GMT.
Time when the message was put.
The format of the time, when it is generated by the queue
manager, is HHMMSSTH and the time itself is in GMT.
Application data relating to the origin.
Instructor Guide
Instructor Notes:
Purpose To introduce the context fields and to explain what the queue manager sets in
these fields when it generates the information.
Details On AIX, HP-UX, OS/2, Compaq NonStop Kernel, Compaq OpenVMS Alpha,
OS/400, Solaris, Linus, Windows, plus WebSphere MQ clients connected to these systems
the accounting-token is set to an explicit value.
Transition Statement There is no need to have the queue manager set the context fields
if they are not going to be used.
Instructor Guide
V2.0
Uempty
Figure 6-29. No Context MQ157.0
Notes:
An application may elect to put a message with no context by specifying the put message
option MQPMO_NO_CONTEXT. In which case, the queue manager clears all the context
fields. Specifically, it sets the field PutApplType to MQAT_NO_CONTEXT so that the
receiving application can test for this value. Setting no context can be slightly faster
provided, of course, the information is not required.
The receiver of a message can test the PutApplType field to determine whether the
message has no context.
No Context
Requested by a put message option
MQPMO_NO_CONTEXT
Queue manager clears all the context fields, specifically
PutApplType is set to MQAT_NO_CONTEXT
To request default context or no context requires no more
authority than that required to put the message on the queue
Instructor Guide
Instructor Notes:
Purpose To explain how an application requests the queue manager to set no context in
a message.
Details To request default context or no context requires no more authority than that
required to put the message on the queue.
Transition Statement Next we look at how the context of a message can be preserved
when forwarding the message.
Instructor Guide
V2.0
Uempty
Figure 6-30. Passing Context MQ157.0
Notes:
Programs should generally pass the identity context information from message to
message around an application until the data reaches its final destination.
Passing context is not supported on Windows 3.1, 95, and 98.
Passing Context
D
QUEUE 2
A
QUEUE 1
B
Put messages on Queue 2 with same
identity context as message taken from
Queue 1
Open Queue 1 as "Save All Context"
Put messages with "Pass dentity
Context"
Or transfer "No Context"
Instructor Guide
Instructor Notes:
Purpose To describe how to preserve the context when forwarding a message.
Details These options allow an application to forward a message or send a reply using
the context information from the original message.
When a queue manager generates a report, it sets the identity context to be same as that
of the original message. When an application generates a reply or a report, it is generally a
good idea to follow the same convention.
In order to forward a message or send a reply with the same identity context, an application
needs to do the following.
Open the input queue with the option "save all context".
Open the output queue with the option "pass identity context" or "pass all context".
Get a message from the input queue.
Put the message, or the reply, on the output queue with the option pass identity
context or pass all context.
If the original message has no context, the application may forward it with the option "no
context".
An application needs authority to open a queue with the pass identity context or pass all
context option.
Additional Information In case you are asked, the actual open options referred to on the
visual are:
MQOO_SAVE_ALL_CONTEXT
MQOO_PASS_IDENTITY_CONTEXT
MQOO_PASS_ALL_CONTEXT
and the actual put message options are:
MQPMO_PASS_IDENTITY_CONTEXT
MQPMO_PASS_ALL_CONTEXT
Transition Statement Next we look at alternate user authority.
Instructor Guide
V2.0
Uempty
Figure 6-31. Alternate User Authority MQ157.0
Notes:
The alternate user authority option allows an application to open a queue, or any other
WebSphere MQ object, by providing the queue manager with a user identifier other than
the one it is currently running under. The queue manager uses this alternate user identifier
in order to check whether it is authorized to open the queue.
On Windows 3.1, 95, and 98 the alternate user authority option is accepted, but
ignored.
AIternate User Authority
D
QUEUE 2
A
QUEUE 1
B
Put message with A's authority
B needs appropriate authority
User D taken from Message Context
How it is requested
AlternateUserD field in Object Descriptor
Option on MQOPEN or MQPUT1
Instructor Guide
Instructor Notes:
Purpose To describe how a suitably authorized application may open a queue using the
authority of an alternate user identifier.
Details Typically, this option would be used by a server application which is doing work
on behalf of other applications. The server application would obtain the alternate user
identifier from the context of the message it is currently processing.
In order for an application to open a queue in this way, the following authorizations are
required.
The application requires authority to use the "alternate user authority" option.
The alternate user identifier requires the authority to open the queue.
Additional Information In case you are asked, the actual open option referred to on the
visual is MQOO_ALTERNATE_USER_AUTHORITY.
Transition Statement Next we look at the two remaining context options.
Instructor Guide
V2.0
Uempty
Figure 6-32. Setting Context MQ157.0
Notes:
The visual depicts the two remaining context options for use when opening a queue. An
application requires authority to use these options. The corresponding put message
options are for use when putting a message on a queue once it has been opened.
Setting Context
Two open options that require authority to use
MQOO_SET_DENTTY_CONTEXT
MQOO_SET_ALL_CONTEXT
Two corresponding put message options
MQPMO_SET_DENTTY_CONTEXT
MQPMO_SET_ALL_CONTEXT
Normally used by special programs only
Message channel agents
System utilities
Instructor Guide
Instructor Notes:
Purpose To describe the remaining context options.
Details As an example, consider a receiving MCA which receives data from the network,
reconstitutes the messages, and puts them on their respective destination queues. It order
to be able to preserve the context information of a message, the MCA needs to be able to
open the destination queue with the "set all context" option.
Transition Statement Next we look at channel exit programs which have a particular
relevance to security.
Instructor Guide
V2.0
Uempty
Figure 6-33. Channel Exit Programs MQ157.0
Notes:
The uses of channel exit programs are:
Auto-definition exit
can be used to modify the channel definition derived from the model
SYSTEM.AUTO.RECEIVER.
Security exit
is primarily used by the MCA at each end of a message channel to
authenticate its partner.
Send and receive exits
can be used for purposes such as data compression/decompression
and data encryption/decryption.
Message exit
can be used for any purpose which makes sense at the message level.
The following are some examples.
-Application data conversion
ChanneI Exit Programs
MQPUT
Transmission
queue
MQGET
Destination
queue
M
C
A
M
C
A
Security Security
Send Receive
Auto-definition
Message Message
Message-retry
Current WebSphere MQ Channel Exit Programs
Significant setup required for user exits
Not 'out the box' security
Instructor Guide
-Encryption/decryption
-Journaling
-Additional security checks such as validating an incoming user
identifier
-Substitution of one user identifier for another as a message enters a
new security domain
-Reference message handling
Message-retry exit
is called when an attempt to open a destination queue, or put a
message on a destination queue, has been unsuccessful. The exit can
be used to determine under what circumstances the MCA should
continue to retry, how many times it should retry, and how frequently.
Transport-retry exit
is called before a datagram is about to be sent. The exit allows your
application to suspend data being sent on a channel when
communication is possible. There are at least five different conditions
that a transport-retry exit can be used.
The auto-definition exit is only supported on WebSphere MQ for AIX, HP-UX, iSeries,
Solaris, and Windows, and MQSeries for Compaq Tru64 UNIX and OS/2 Warp V5.1.
The message-retry exit is supported on all MQSeries and WebSphere MQ platforms
except WebSphere MQ for z/OS.
The transport-retry exit applies to WebSphere MQ for AIX.
Full details on how to write channel exit programs can be found in WebSphere MQ
Intercommunication manual.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce the current WebSphere MQ channel exits.
Details
The visual depicts all the channel exit programs that may be called on a message channel.
We shall discuss channel exit programs on MQI channels on the next visual. A description
of each channel exit program follows.
Auto-definition exit
This exit can only be invoked at the end of a channel which has a channel
type of receiver. It is called when an incoming request is received to start a
channel but no channel definition exists. Under these circumstances, it can
be used to modify the channel definition derived from the model
SYSTEM.AUTO.RECEIVER.
The name of the exit is specified as an attribute of the queue manager
object.
Security exit
Security exits normally work in pairs, one at each end of a channel. They
are called immediately after the initial data exchange negotiation has
completed on channel startup, but before any messages start to flow. The
primary purpose of a security exit is to allow the MCA at each end of a
channel to authenticate its partner. In order to do this, the security exits
send security flows to each other. One possible outcome of the
conversation between the security exits is that the channel is closed and
message flow is not allowed to proceed.
The name of the security exit is specified as a parameter on the channel
definition at each end of a channel.
Send and receive exits
A send exit and a receive exit normally work in pairs. A send exit is called
just before an MCA issues a communications send to send data over a
communications link. A receive exit is called just after an MCA has issued
a communications receive to receive data from a communications link.
They are able to modify the contents of the data and can therefore be used
for purposes such as data compression/decompression and data
encryption/decryption.
The flows of data between two MCAs may contain message data, but there
may also be flows of control information. Send and receive exits are called
for both types of data. One consequence of this is that send and receive
exits may be called at both ends of a channel.
The names of the send and receive exits are specified as parameters on
the channel definition at each end of a channel. You can specify a list of
send and receive exits to be run in succession.
Instructor Guide
Message exit
Message exits at the sending and receiving ends of a channel normally
work in pairs. A message exit at the sending end is called just after an
MCA has got a message from the transmission queue. At the receiving
end, a message exit is called just before an MCA puts a message on its
destination queue.
The exit has access to both the message descriptor and the application
data and is able to modify their contents. It can therefore be used for any
purpose which makes sense at the message level. The following are some
examples.
Encryption/decryption
Journaling
Additional security checks such as validating an incoming user
identifier
Substitution of one user identifier for another as a message enters
a new security domain
Reference message handling (see below)
The name of the message exit is specified as a parameter on the channel
definition at each end of a channel. You can specify a list of message exits
to be run in succession.
Message-retry exit
A message-retry exit can only be invoked at the end of a channel which has
a channel type of receiver or requester. It is called when an attempt to
open a destination queue, or put a message on a destination queue, has
been unsuccessful. The exit can be used to determine under what
circumstances the MCA should continue to retry, how many times it should
retry, and how frequently.
The name of the exit is specified as a parameter on the channel definition
at the receiving end of a channel. If no message-retry exit is defined, the
message-retry count and message-retry interval, as specified in the
channel definition, are used instead.
Transport-retry exit
Applies to WebSphere MQ for AIX, V5.3, and is supported on UDP only.
You can write a C-language retry exit. It allows your application to suspend
data being sent on a channel when communication is not possible, for
example, when a mobile user is traveling through a tunnel or is temporarily
out of range of a transmitter. The exit is normally called before a datagram
is sent but is also called to provide other useful signals.
There are at least five different conditions in which this retry exit can be
called:
Instructor Guide
V2.0
Uempty
When the channel is first initialized.
When the channel is shut down.
Before each datagram is sent.
When the end of a batch of message occurs.
When an information datagram is received from the remote end of the
link.
You can configure the retry exit by editing the qm.ini file.
Additional Information You can use the visual to introduce reference messages. The
use of reference messages allows a large object, such as a file, to be transferred from one
system to another without the need to store the object on a queue on either system. This is
accomplished as follows.
1. An application puts a message to a remote queue. The message consists of a
reference message header, structure MQRMH, with no data following. The reference
message header contains information such as the name of the object and where it is
located on the source system, and the name by which the object will be known and
where it will be located on the destination system.
2. When the reference message is got from the transmission queue by the sending MCA,
a message exit is called. The message exit inspects the reference message header,
retrieves the object, and appends the object data to the reference message.
3. The sending MCA sends the reference message with the object data to the receiving
MCA.
4. Just before the receiving MCA puts the reference message on its destination queue,
another message exit is called. The message exit extracts the object data from the
reference message and creates the object on the destination system. The message
exit passes on the reference message without the object data, and the receiving MCA
puts it on its destination queue.
5. The reference message can now be received by an application which then knows that
the object has been created on this system.
Further information on references messages can be found in the WebSphere MQ
Application Programming Reference and the WebSphere MQ Application Programming
Guide.
Transition Statement Next we look at what channel exit programs can be used on MQI
channels.
Instructor Guide
Figure 6-34. Channel Exit Programs on MQI Channels MQ157.0
Notes:
No channel exit programs can be called on a client system if the MQSERVER
environment variable is used to define a simple client connection.
No channel exit programs can be called in a native DOS environment.
The auto-definition exit can be used to modify the channel definition derived from the
model SYSTEM.AUTO.SVRCONN.
The auto-definition exit is only supported on a Version 5 queue manager.
ChanneI Exit Programs on MQI ChanneIs
C
L
N
T
C
O
N
N
S
V
R
C
O
N
N
Security Security
Send Receive
Auto-definition
MQCONN(...)
MQOPEN(...)
MQPUT(...)
...
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain what exits are available for use on MQI channels.
Details
The main thing to recall is that an MQI channel is used to flow the input and output
parameters of an MQI call, not messages. The message and message-retry exits are not
therefore applicable to MQI channels. All the remaining exits we looked at on the last visual
are applicable.
The auto-definition exit can only be invoked at the server connection end of an MQI
channel. Like in the case of a message channel, it is called when a request is received to
start an MQI channel but no channel definition exists. It can be used to modify the channel
definition derived from the model SYSTEM.AUTO.SVRCONN.
Transition Statement Next we will look at Secure Sockets Layer and what it provides in
WebSphere MQ V5.3.
Instructor Guide
Figure 6-35. Secure Sockets Layer MQ157.0
Notes:
Secure Sockets Layer (SSL) is common across all the V5.3 platforms -z/OS, UNIX,
Windows, iSeries.
SSL is an industry-standard protocol for secure communications, involving encryption,
authentication, and integrity of data. SSL is supported in both client/server and qmgr/qmgr
channels (including clusters). There are many flexible capabilities built-in, including the
ability to select who are prepared to accept communications from based on their
fully-authenticated identity. This will remove, for many people, the need to set up channel
exits, where they were used for security purposes.
SSL, is widely accepted in the Internet community, has been subjected to significant testing
by the hacker community. To prevent eavesdropping, how do I stop someone from seeing
the information I send?; to prevent impersonation, how can I detect if someone has
intercepted my information and changed it?; and to prevent tampering, how can I be sure
who the information is from or who I am exchanging information with?
Protocol to allow transmission of secure data over an insecure
network
Combines these techniques
Symmetric / Secret Key encryption
Asymmetric / Public Key encryption
Digital Signature
Digital Certificates
Protection
Client/Server
Qmgr/QMgr channels
To combat Security Problems
Eavesdropping
Encryption techniques
Tampering
Digital Signature
mpersonation
Digital Certificates
Secure Sockets Layer
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To describe Secure Sockets Layer (SSL)
Details SSL is an industry-standard protocol that provides a data security layer between
application protocols and the communications layer usually, TCT/IP. The SSL protocol was
designed by Netscape Development Corporation, and is widely deployed, in both Internet
and intranet applications. SSL defines methods of data encryption, server authentication,
message integrity, and client identification for a TCP/IP connection. SSL uses public key
and symmetric techniques to provide the following security services:
Message privacy - SSL uses a combination public key and symmetric key encryption to
ensure message privacy. Before exchanging messages, an SSL server and SSL client
perform an electronic handshake during which they agree to use a session key and
encryption algorithm. All messages between the client and the server are then encrypted.
Encryption ensures that the messages remains private even if eavesdroppers intercept it.
Message integrity - SSL uses the combination of shared secret key and message hash
functions. This ensures that nothing changes the content of a message as it travels
between client and server.
Mutual authentication - During the initial SSL handshake, the server uses a public-key
certificate to convince the client of the server's identity. Optionally, the client may also
exchange a public-key certificate with the server to ensure the authenticity of the client.
Additional Information The keystore (where private and CA signing keys live) is
implemented differently on each platform. The key management tool used on UNIX is
iKeyMan. Windows can used the built in store which is the Internet Explorer, and Digital
Certificate Management tool is what the iSeries uses. With the release of WebSphere MQ
Version 5.3 one of the new manuals that contains information on Secure Sockets Layer
(SSL) is the WebSphere MQ Security manual (SC34-6079). This manual supports
distributed and the z/OS for your security requirements in a WebSphere MQ environment.
Transition Statement Next we will look at an overview of the SSL handshake.
Instructor Guide
Figure 6-36. SSL Handshake MQ157.0
Notes:
SSL Handshake
Hi
from
Jill
Jill
Jack
The Client Hello
Jill sends Jack some random text
Also sends what CipherSpecs and compression methods
she can use
Jill is the client
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To attempt to explain what is involved in the SSL handshake.
Details
1. The SSL client sends a client hello message that lists cryptographic information such as
SSL version and, in the client's order of preference, the Cipher Suites supported by the
client. The message also contains a random byte string that is used in subsequent
computations. The SSL protocol allows for the "client hello" to include the data
compression methods supported by the client, but SSL implementations do not usually
include this provisions.
Transition Statement Step 2
Instructor Guide
Notes:
SSL Handshake
Hi from
Jill
Jill
Jack
The Server Hello
Jack sends Jill some random text
Jack chooses the CipherSpec and compression
method to be used, from Jill's list
The Server Certificate
The Client Certificate Request
Hi from Jack
+ Jack's Cert
+ Cert Request
1ack's Digital
Certificate
&$ 6LJ
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details
2. The SSL server responds with a server hello message that contains the CipherSuite
chosen by the server from the list provided by the SSL client, the session ID and
another random byte string. The SSL server also sends its digital certificate. If the
server requires a digital certificate for the client authentication, the server sends a client
certificate request that includes a list of the types of certificates supported and the
Distinguished Names of acceptable Certification Authorities (CAs).
Instructor Guide
Notes:
SSL Handshake
Hi from
Jill
Jill
Jack
Verify Server Certificate
Check Validity Period
Decrypt using CA's Public Key - verifies that CA is trusted
Check Domain Name and/or Distinguished Name
Also receives Jack's Public Key
Hi from Jack
+ Jack's Cert
+ Cert Request
It's Jack !
CA
PubIic
J
PubIic
1ack's Digital
Certificate
&$ 6LJ
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details
3. The SSL client verifies the digital signature on the SSL server's digital certificate and
checks that the CipherSuite chosen by the server is acceptable.
Instructor Guide
Notes:
SSL Handshake
Hi from
Jill
Jill
Jack
Client Key Exchange
Jill sends Jack the Secret Key to use
This is encrypted with Jack's Public Key
Also sends her certificate
Hi from Jack
+ Jack's Cert
+ Cert Request
It's Jack !
Secret Key
+ Jill's Cert
J
PubIic
1ill's Digital
Certificate
&$ 6LJ
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details
4. The SSL client sends the random byte string that enables both the client and the server
to compute the secret key to be used for encrypting subsequent message data. The
random byte string itself is encrypted with the server's public key.
Instructor Guide
Notes:
SSL Handshake
Hi from
Jill
Jill
Jack
Verify Client Certificate
Decrypt using CA's public Key
Hi from Jack
+ Jack's Cert
+ Cert Request
It's Jack !
Secret Key
+ Jill's Cert
J
PubIic
It's JiII !
CA
PubIic
1ill's Digital
Certificate
&$ 6LJ
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details
5. If the SSL server sent a client certificate request, the SSL client sends a random byte
string encrypted with the client's private key, together with the client's digital certificate,
or a no digital certificate alert. This alert is only a warning, but with some
implementations the handshake fails if client authentication is mandatory.
Transition Statement Steps 6 through 9.
Instructor Guide
Notes:
SSL Handshake
Hi from
Jill
Jill
Jack Hi from Jack
+ Jack's Cert
+ Cert Request
It's Jack !
Secret Key
+ Jill's Cert
J
PubIic
It's JiII !
Private
messages using
Secret Key
Send nformation using agreed Secret Key
Randomly generated 1-time key
This is now a secure line
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details
6. The SSL server verifies the signature on the client certificate.
7. The SSL client sends the SSL server a finished message, which is encrypted with the
secret key, indicating that the client part of the handshake is complete.
8. The SSL server sends the SSL client a finished message, which is encrypted with the
secret key, indicating the server part of the handshake is complete.
9. For the duration of the SSL session, the SSL server and the SSL client can now
exchange messages that are symmetrically encrypted with the shared secret key.
Transition Statement Next lets look at the Queue manager attributes that are available.
Instructor Guide
Figure 6-42. QMGR Attributes for SSL MQ157.0
Notes:
QMGR Attributes for SSL
ALTER QMGR command
SSLKEYR
Sets the SSLKeyRepository
SSLCRLNL
Sets the SSLCRLNamelist
SSLCRYP
Sets the SSLCryptoHardware
SSLTASKS
Sets the SSLTasks
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To discuss the WebSphere MQ SSL attributes that are available for use on the
ALTER QMGR command.
Details All of these changes affect the queue manager definition. The SSLKEYR
(SSLKeyRepository), holds the name of the SSL key repository. SSLCRLNL
(SSLCRLNamelist), holds the name for the namelist of authentication information objects.
SSLCRYP (SSLCryptoHardware), holds the name of the parameter string required to
configure the cryptographic hardware present on the system. This parameter applies to
UNIX only. SSLTASKS (SSLTasks), holds the number of server subtasks to use for
processing SSL calls. If you use SSL channels you must provide two for these tasks. This
applies to z/OS.
Transition Statement Next look at the queue manager object AUTHINFO.
Instructor Guide
Figure 6-43. QMGR Authentication Object MQ157.0
Notes:
You can either alter, define, delete or display the authentication information objects. These
objects contain the definitions required to perform Certificate Revocation Lists (CRL)
checking using LDAP servers.
The AUTHINFO queue manager attribute is supported on UNIX, Windows, and OS/400.
On OS/400 these objects are defined by the Digital Certificate Manager.
QMGR Authentication Object
ALTER AUTHNFO
DEFNE AUTHNFO
DELETE AUTHNFO
DSPLAY AUTHNFO
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To discuss the authentication information object AUTHINFO.
Details You can either alter, define, delete or display the authentication information
objects. These objects contain the definitions required to perform Certificate Revocation
Lists (CRL) checking using LDAP servers.
The AUTHINFO queue manager attribute is supported on UNIX, Windows, and OS/400.
On OS/400 these objects are defined by the Digital Certificate Manager.
Additional Information This command is documented in the WebSphere MQ Script
(MQSC) Command Reference.
Transition Statement Next we will discuss WebSphere MQ SSL support for channels.
Instructor Guide
Figure 6-44. Channel Attributes for SSL MQ157.0
Notes:
SSLCIPH - Specifies the encryption strength and function (CipherSpec), for example
NULL_MD5 or RC4_MD5_US. The CipherSPec must match at both ends. of the channel.
SSLPEER - Specifies the distinguished name (unique identifier) of allowed partners.
SSLCAUTH - defines whether WebSphere MQ requires and validates a certificate from the
SSL client.
ChanneI Attributes for SSL
DEFNE or ALTER CHANNEL
SSLCPH
SSLPEER
SSLCAUTH
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To discuss the parameters available on the DEFINE CHANNEL command for
use with SSL.
Details SSLCIPH - Specifies the encryption strength and function (CipherSpec), for
example NULL_MD5 or RC4_MD5_US. The CipherSPec must match at both ends. of the
channel. SSLPEER - Specifies the distinguished name (unique identifier) of allowed
partners. SSLCAUTH - defines whether WebSphere MQ requires and validates a
certificate from the SSL client.
The sever authentication the client uses the server's public key to encrypt the data that
issued to compute the secret key. The server can generate the secret key only if it can
decrypt that data with the correct private key.
For client authentication, the server uses the public key in the client certificate to decrypt
the data the client sends during step 5 of the handshake. The exchange finished
messages that are encrypted with the secret key in steps 7 and 8 in the handshake
confirms that authentication is complete.
If any step of the authentication fails, the handshake fails and the session terminates.
Transition Statement Next we will look at the approach to security when running
WebSphere MQ client applications.
Instructor Guide
Figure 6-45. Access Control for an WebSphere MQ Client MQ157.0
Notes:
When an WebSphere MQ client application wishes to access a WebSphere MQ object on
the server queue manager (for example, connect to the queue manager, or open a queue),
access control is based on a user ID used by the server connection process. The reason
for this is that it is the server connection which actually issues the MQI calls. This user ID is
determined by the value of the MCAUserIdentifier field in the active channel definition at the
server end of the MQI channel instance. The active channel definition is defined by the
structure MQCD and is documented in WebSphere MQ Intercommunication manual.
MQ_USER_ID and MQ_PASSWORD are no longer supported with MQSeries V.5.1
clients on Unix an Windows NT/2000.
Access ControI for a WebSphere MQ CIient
Access control is based on a user D used by the server connection
process
Value of MCAUserdentifier in MQCD determines this user D
Security exits at both ends of the MQ channel
Client security exit can flow a user D and password
Server security exit can authenticate the user D and set
MCAUserdentifier
No security exit at the client end of the MQ channel
Values of
Logged_in USERD or
MQ_USER_D and MQ_PASSWORD flow to the server system
Server security exit can authenticate the user D and set
MCAUserdentifier
No security exit at either end of the MQ channel
MCAUserdentifier has the value of MCAUSER if it is nonblank
MCAUserdentifier has the value of flowed user D otherwise
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain how access control works for an WebSphere MQ client.
Details If the field MCAUserIdentifier is nonblank, it contains the user ID used by the
server connection for authorization to access WebSphere MQ resources. If it is blank, the
server connection uses its default user ID instead.
How then is the field MCAUserIdentifier set?
Initially, when an MQI channel instance is started, MCAUserIdentifier is set to the value of
the MCAUSER parameter in the server connection channel definition. Subsequently, its
value may be changed as follows.
If there is a channel security exit at both ends of the MQI channel
The security exit on the client system may pass a user ID to the security
exit on the server system along with any other information required to
authenticate it, for example, a password. Once it has authenticated the
user ID, the security exit on the server system can place the user ID in the
MCAUserIdentifier field, thus overwriting its initial setting.
If there is no security exit at the client end of the MQI channel
The values of the environment variables MQ_USER_ID and
MQ_PASSWORD on the client system flow to the server system and are
placed respectively in the RemoteUserIdentifier and RemotePassword
fields in the MQCD structure for the MQI channel instance. At the same
time, if the initial value of MCAUserIdentifier is blank because the value of
the MCAUSER is blank, MCAUserIdentifier is also set to the value of
MQ_USER_ID.
If there is a security exit at the server end of the MQI channel
The security exit can access the RemoteUserIdentifier and
RemotePassword fields, authenticate the user ID, and
place the user ID in the MCAUserIdentifier field as
previously.
If there is no security exit at the server end of the MQI channel
The field MCAUserIdentifier retains whatever value it has
already acquired. This is either the value of MCAUSER, if
it is nonblank, or the value of MQ_USER_ID.
This is not the complete picture. The case when the environment variable MQ_USER_ID is
not set has not been covered and, under certain circumstances, MCAUserIdentifier is set to
a user ID obtained from the underlying communications subsystem, SNA LU6.2 or TCP/IP.
Full details can be found in WebSphere MQ Clients and WebSphere MQ
Intercommunication manuals.
Transition Statement Next we look at Userids with remote queueing and clients.
Instructor Guide
Figure 6-46. Remote Queueing and Clients MQ157.0
Notes:
Remote Queuing and CIients
Channel Exits
A number of channel exits are available in the product and as
SupportPacs
Several vendors in this market too
MCAUSER
The default setting is wide open, especially for client attach
May want to set this to restrict who can access your queue
manager
MQ_ USER_ D environment variable
This was removed for WindowsNT and UNX in the 5.1 release
client environments
The logged-in username is now automatically used
But this is not authenticated at the server; you may still need
security exits
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose
Details
Transition Statement Next we look at supplied sample channel exit programs.
Instructor Guide
Figure 6-47. Supplied Channel Exit Programs MQ157.0
Notes:
SuppIied ChanneI Exit Programs
Version 5 queue managers only
Security, message, send, and receive exits
Windows 95/98 client supplies security, send, and receive exits
Exit programs supplied in source and object format
Uses DCE Security for:
Authentication of partner by token exchange
Data encryption/decryption
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce the sample channel exit programs
Details
Channel exit programs are supplied for the security, message, send, and receive exits. The
programs are supplied in both source and object format so that users may use them as the
basis for writing their own exit programs.
The exit programs use DCE Security. The security exit program provides function to allow
each end of a message channel or MQI channel to authenticate its partner. It does this by
the technique of token exchange. The message, send, and receive exit programs provide
the function to encrypt and decrypt messages. They do this by using the gss_seal() and
gss_unseal() API calls.
Full details of the supplied channel exit programs, and how to use them, can be found in
WebSphere MQ Intercommunication.
Transition Statement End of the topic. Next there is a practical exercise to do a simple
client connection and to demonstrate autodefinition.
Instructor Guide
Instructor Guide
V2.0
Uempty Checkpoint
Unit 6 Checkpoint
1. T/F All SupportPacs are AS-IS code.
2. T/F A client channel does not require a START CHANNEL
command.
3. On a Version 5.1 client, what additional method is available to
identify the server connection desired?
a. Use SET MQSERVER environment variable
b. Use the MQCONNX call
c. Use a client channel table
d. If a SVRCONN is defined, the client will find it.
Correct Answer: b
4. T/F A message exit can be used to control security when running
from an WebSphere MQ client.
Instructor Guide
Notes:
We looked at other aspects of distributed queuing and there was a practical exercise in
using more of its features.
We described the WebSphere MQ Family SupportPacs and how to obtain them.
WebSphere MQ clients were explained.
The WebSphere MQ approach to security was discussed including the Secure Sockets
Layer for V5.3.
There was a practical exercise to extend the WebSphere MQ network established in the
previous practical session.
- It may have included the configuration of an WebSphere MQ client.
- It may have resulted in the connection of multiple queue managers.
- Security may have been a necessary consideration.
Unit Summary
WebSphere MQ SupportPacs
Security
Exercise 6
Instructor Guide
V2.0
Uempty
Instructor Notes:
Transition Statement End of the unit.
Instructor Guide
Instructor Guide
Copyright IBM Corp. 1996, 2003 Unit 7. WebSphere MQ for Windows (optional) 7-1
V2.0
Uempty
Unit 7. WebSphere MQ for Windows (optional)
This unit describes focusing on those aspects of its administration
which are unique to the product.
Install
Perform simple customization and administration tasks
Enable an queue manager to exchange messages with another
queue manager
With the aid of the User's Guide, prepare installation diskettes to
allow a user to install and then start an application which uses it
Perform basic problem determination
Accountability:
Classroom discussions
Instructor Guide
Notes:
Although there are no exercises for the WebSphere MQ for Windows leaf node queue
managers, it is worthwhile to spend a few minutes reviewing them and understanding
where they fit in an WebSphere MQ solution.
Unit Objectives
ntroduce the WebSphere MQ for Windows (Leaf node) queue
managers
Provide an overview of available function
Detail limitations
Describe installation and administration
Explain channel implementation for leaf node queue managers
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details Note that the final exercise in this unit is not related to the actual topic. There is
no exercise for the WebSphere MQ for Windows queue manager. The exercise will allow
students to use the command server.
This final unit consists of a single topic which describes focusing on those aspects of its
administration which are unique to the product.
It should be noted that, if there is no interest in this topic, it can be considered optional.
However, don't forget the exercise at the end of the course (end of this unit). It does not use
The topic may be delivered either before the last practical exercise or after it. Delivering it
before the last practical exercise has the advantage that an interested student could install
and use as part of the exercise. Delivering it after the last practical exercise provides a
good opportunity to end the course on a high note, particularly if a demonstration is
provided.
The topic may be delivered just using the visuals. However, it is highly recommended that
is demonstrated as part of the topic. In which case, many of the visuals need not be shown
as the same information can be provided as part of the demonstration. The following is a
suggestion for what the demonstration might contain if Version 2.1 is used. It would need
to be modified if Version 2.0 is used instead.
1. Install the complete version of Version 2.1. Elect to start immediately. Point out the
WebSphere MQ icon on the Windows taskbar, and that the tick or check mark () on the
icon indicates that a connection is already active. This is because the installation
process will have run the supplied MQD file which will have created a standalone
connection and caused it to start when WebSphere MQ started.
2. Open the WebSphere MQ Properties dialogue box, select the Service page, then the
Verify page, and verify the installation in standalone mode. Point out that, because a
connection is already active, Verify just opens a queue, puts a message on it, gets the
message from it, and closes the queue.
3. Run the supplied samples AMQSPUTW.EXE and AMQSGETW.EXE against the queue
SYSTEM.SAMPLE.LOCAL in order to demonstrate that can be ready for use
immediately after installation. The queue is defined in the supplied WebSphere MQ
command file AMQSCOSW.TST which will have been run because the contents of the
MQD file caused it to be run. Display the contents of the MQD file and explain the
meaning of the more important keywords.
4. Select the Components page of WebSphere MQ Properties and create a queue
manager, a local queue, a local definition of a remote queue, a transmission queue, a
channel to send messages to a remote queue manager, and a channel to receive
messages from that queue manager. Create a channel group consisting of the channel
Instructor Guide
to send messages to the remote queue manager and the listener. Create a LAN
connection consisting of the queue manager and the channel group.
5. Assuming that you have already created and configured a remote queue manager which
is running on a system connected over a LAN to the system on which is running, select
the Connections page of WebSphere MQ Properties and start the connection you have
just created.
6. Using the supplied samples AMQSPUTW.EXE and AMQSGETW.EXE, demonstrate the
exchange of messages between the queue manager and the remote queue manager.
7. Finish the demonstration by showing and describing the other pages in WebSphere MQ
Properties and the shortcuts from the folder.
Install WebSphere MQ for Windows
Perform simple customization and administration tasks.
Enable an WebSphere MQ for Windows queue manager to exchange messages with
another queue manager.
With the aid of the WebSphere MQ for Windows User's Guide, prepare installation
diskettes to allow a user to install WebSphere MQ for Windows and then start an
application which uses it.
Perform basic problem determination.
Transition Statement We commence by positioning WebSphere MQ for Windows in
relation to the other Level 2 queue managers.
Instructor Guide
V2.0
Uempty 7.1 WebSphere MQ for Windows (optional)
This topic is about the administration of WebSphere MQ for Windows.
What students will do Students will listen to a presentation on and may see a
demonstration of it.
What students will learn Students will learn about the unique features of WebSphere
MQ for Windows in comparison with the other Level 2 queue managers.
How this will help students on their job This knowledge will help the students provide
administration support for WebSphere MQ for Windows.
Instructor Guide
Figure 7-2. Positioning MQ157.0
Notes:
Positioning
Small footprint or lightweight queue manager
Leaf node queue manager
Therefore:
Not intended as an intermediate queue manager
Does not support WebSphere MQ clients
Would typically run on a workstation not powerful enough to act
as a server
Minimal user contact with WebSphere MQ function
TCP/P support only
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To position WebSphere MQ for Windows in relation to the other Level 2 queue
managers.
Details WebSphere MQ for Windows is described as a small footprint or lightweight
queue manager. This means that it uses significantly fewer resources than other
WebSphere MQ queue managers. This is achieved by providing less function than is
available on other WebSphere MQ queue managers.
WebSphere MQ for Windows is also designed as a leaf node queue manager. This means
that it is intended for use by a single user on a workstation that is connected to only one
other system in an WebSphere MQ network.
As a consequence, WebSphere MQ for Windows has the following properties.
It is not intended for use as an intermediate queue manager; that is, one that receives
messages from one queue manager and sends them to another queue manager.
It does not support the connection of WebSphere MQ clients.
It is typically intended for use on a workstation which is not powerful enough to support a
server queue manager.
WebSphere MQ for Windows has been designed so that the users require very little contact
with WebSphere MQ function. For example, on both versions, it is possible to configure
WebSphere MQ so that a user can start Windows and then immediately begin to use
applications. On WebSphere MQ for Windows Version 2.1, it is also possible for a user to
install WebSphere MQ for Windows and, immediately after installation, begin to use
applications. On WebSphere MQ for Windows Version 2.0, one extra step is required after
installation before a user can start an application.
WebSphere MQ for Windows only supports TCP/IP as a communications protocol. Other
communications protocols, such as SNA LU6.2, NetBIOS, and IPX/SPX, are not
supported.
Transition Statement There are two current versions of WebSphere MQ for Windows.
Next we look at how each is positioned.
Instructor Guide
Figure 7-3. Versions MQ157.0
Notes:
The are two current versions of WebSphere MQ for Windows, Version 2.0 and Version
2.1. Version 2.0 is a 16-bit queue manager and Version 2.1 is a 32-bit queue manager.
The visual depicts the supported environments for each version.
WebSphere MQ for Windows Version 2.0 will run on Windows 95, but in 16-bit
compatibility mode only. It can support 32-bit applications but the MQI calls are passed
straight through to the 16-bit MQI, that is, thunking occurs.
You can install both WebSphere MQ for Windows Version 2.1 and WebSphere MQ for
Windows Version 5.0 on the same Windows NT system, but you are only recommended
to do this in a test environment. You cannot install WebSphere MQ for Windows Version
2.1 and a version of WebSphere MQ for Windows earlier than Version 5.0 on the same
Windows NT system.
Versions
Version 2.0
16-bit queue manager
Supported environments
Windows 3.1
Windows for Workgroups 3.11
Windows 95/98, in 16-bit compatibility mode
WN-OS/2 on OS/2 Warp V3.0 or later
Version 2.1
32-bit queue manager
Supported environments
Windows 95/98
Windows NT V4.0
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To introduce the two versions of WebSphere MQ for Windows and their
intended environments.
Transition Statement As a small footprint or lightweight queue manager, WebSphere
MQ for Windows does not provide many of the features available on other queue
managers. Next we see which features it does not provide.
Instructor Guide
Figure 7-4. Family Differences MQ157.0
Notes:
FamiIy Differences
WebSphere MQ for Windows does not support:
WebSphere MQ for Windows Version 2.1 supports:
. . . but not WebSphere MQ for Windows Version 2.0
Distribution Iists
InstaIIabIe services and components
Media recovery
Message-retry
MQSeries cIients
Triggering
Queue manager quiescing
Remote administration using MQSeries commands
Two phase commit protocoI as a resource manager
User written MCAs
Authority checking
Certain MQI function
ChanneI auto-definition
ChanneI heartbeats
ChanneI instances
Configuration fiIes
Context passing
ControI commands
Data conversion
Dead Ietter queues
Command server and PCF commands
Fast nonpersistent messages
Instrumentation events
Set signaI option on the MQGET caII
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To summarize those features of Level 2 queue managers which are not
supported by .
Details The first part of the visual summarizes those features of Level 2 queue
managers which are not supported by WebSphere MQ for Windows . Most of the features
listed should be self explanatory, but a few may require clarification.
Authority checking
WebSphere MQ for Windows provides no function in support of access
control to its own resources.
Certain MQI function
Examples of function not supported are as follows.
The MQBEGIN call
The MQCONNX call
Message groups
Message segmentation
The options MQOO_ALTERNATE_USER_AUTHORITY and
MQPMO_ALTERNATE_USER_AUTHORITY (these options may be
used in an application but they are ignored by the queue manager)
A full list of MQI function not supported, or ignored, can be found in the
WebSphere MQ for Windows User's Guide.
Context passing
WebSphere MQ for Windows does not support the options
MQOO_SAVE_ALL_CONTEXT, MQOO_PASS__CONTEXT, and
MQPMO_PASS__CONTEXT. The other context options are supported
however.
Data conversion
WebSphere MQ for Windows supports neither the MQGMO_CONVERT
option, nor the CONVERT parameter on the DEFINE CHANNEL
command, nor data conversion exits. When exchanging messages with
another queue manager which is not WebSphere MQ for Windows, the
other queue manager must perform the data conversion.
An WebSphere MQ client application cannot connect to a WebSphere MQ
for Windows queue manager.
Triggering
No form of triggering is available on WebSphere MQ for Windows. The
implications of this are:
The attributes of a queue associated with triggering are not supported.
The process object is not supported.
There is no supplied trigger monitor.
Instructor Guide
Queue manager quiescing
If an WebSphere MQ for Windows queue manager has received a request
to stop, it does not wait for any applications to disconnect before stopping.
If an application issues an MQI call with the "fail if quiescing" option, the
option is ignored by the queue manager. The user should ensure that all
his/her applications have finished before stopping a queue manager.
Remote administration using WebSphere MQ commands
You cannot issue WebSphere MQ commands on an WebSphere MQ for
Windows queue manager to run on another queue manager. Neither can
you issue WebSphere MQ commands on another queue manager to run
on an WebSphere MQ for Windows queue manager. Although
WebSphere MQ for Windows Version 2.1 does support PCF commands, it
does not support the Escape PCF command.
Two phase commit protocol as a resource manager
Changes to the resources of a WebSphere MQ for Windows queue
manager cannot be coordinated by an external syncpoint coordinator using
a two phase commit protocol. WebSphere MQ for Windows does however
support the MQCMIT and MQBACK calls to commit and back out changes
to its own resources only.
User written MCAs
On all other Level 2 queue managers, it is possible to replace the supplied
MCAs with user written ones. This is not possible on WebSphere MQ for
Windows.
The second part of the visual lists those features which are supported by WebSphere MQ
for Windows Version 2.1 but not by WebSphere MQ for Windows Version 2.0. The
WebSphere MQ for Windows Version 2.1 User's Guide contains a list of the supported PCF
commands and their parameters. It also contains a list of the instrumentation events
generated by WebSphere MQ for Windows Version 2.1.
Transition Statement WebSphere MQ for Windows has two WebSphere MQ
components which are not supported by any other queue manager. Next we examine one
of them, the channel group.
Instructor Guide
V2.0
Uempty
Figure 7-5. Channel Group MQ157.0
Notes:
A channel group is a named collection of channels which is owned by a queue manager.
When you start a channel group, all the channels in the group are started at that time.
Similarly, when you stop a channel group, all channels in the group are stopped at that
time. Thus, the single action of starting a channel group is all that a user is required to
perform in order to start all the channels required by his/her applications.
Only a channel which is implemented by a caller MCA at the Windows end can belong to
a channel group. This means that a channel whose type is receiver at the Windows end
cannot belong to a channel group. This is because such a channel is implemented by a
responder MCA at the Windows end.
A channel group may contain the WebSphere MQ listener. This means that the listener
is started whenever the group is started and stopped whenever the group is stopped.
The listener can start any number of responder MCAs, that is, any number of channels
of type receiver at the Windows end.
ChanneI Group
A named collection of channels
When you start a channel group, all channels in the group are
started at that time
ncludes only channels for which a caller MCA needs to be started
Can include the WebSphere MQ listener
A queue manager can own many channel groups, but
only one channel group can be active at a time
A channel may belong to more than one channel group
Instructor Guide
Typically, however, a channel group might contain just two channels for message transfer
in each direction with channel types sender and requester at the Windows end. A
listener would only be required if there is a possibility that a remote queue manager may
need to start a channel to the queue manager.
A queue manager may own many channel groups, but only one channel group can be
active at a time.
A channel may belong to more than one channel group and so may the listener.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the concept of a channel group.
Transition Statement The other WebSphere MQ component unique to WebSphere MQ
for Windows is the connection. Next we examine this concept.
Instructor Guide
Figure 7-6. Connection MQ157.0
Notes:
Only WebSphere MQ for Windows Version 2.1 supports the concept of a connection. It
is not supported on WebSphere MQ for Windows Version 2.0.
A connection is a named component that was introduced in order to hide the
complexities of queue managers, channel groups, and phonebook entries from
application users. (Phonebook entries are discussed on a later visual.)
There are three types of connection.
A stand-alone connection is for using WebSphere MQ for Windows when not
connected to another queue manager. It comprises one queue manager only.
A LAN connection is for using WebSphere MQ for Windows when connected to
another queue manager over a local area network. It comprises one queue manager
and one channel group.
A dial-up connection is for using WebSphere MQ for Windows when connected to
another queue manager using a dial-up telephone link. It comprises one queue
Connection
Supported by Version 2.1 only
A named component to hide the complexities of queue
managers, channel groups, and phonebook entries
Three types
Stand-alone connection -a queue manager
LAN connection -a queue manager + a
channeI group
Dial-up connection -a queue manager + a
channeI group +
a phonebook entry
When you start a connection, all components belonging to the
connection are started at that time
A queue manager, a channel group, or a phonebook entry can
belong to more than one connection, but only one connection can
be active at a time
Instructor Guide
V2.0
Uempty
manager, one channel group, and one phonebook entry which Windows uses to dial
the server workstation.
When a connection is started, all components belonging to the connection are started at
that time. Similarly, when a connection is stopped, all components belonging to the
connection are stopped at that time.
A queue manager, a channel group, or a phonebook entry can belong to more than one
connection, but only one connection can be active at a time.
Instructor Guide
Instructor Notes:
Purpose To explain the concept of a connection.
Details It is worth stressing the importance of the connection. A user need only be
concerned with deciding which connection to use, and with starting and stopping a
connection. A user need not be concerned with the concepts of a queue manager, a
channel group, or a phonebook entry which are effectively hidden from the user.
One scenario might be as follows. A sales rep has WebSphere MQ for Windows
configured on his/her ThinkPad with three connections.
A stand-alone connection for use when the sales rep is travelling, or at a customer site
without access to a telephone.
A LAN connection for use when the sales rep is back in the office and can connect
his/her ThinkPad to the local area network.
A dial-up connection for use when the sales rep is at a customer site with access to a
telephone, or in his/her home, or in a hotel room.
Transition Statement Next we examine the dial-up support provided by WebSphere MQ
for Windows.
Instructor Guide
V2.0
Uempty
Figure 7-7. Dial-up Support MQ157.0
Notes:
The dial-up support provided by WebSphere MQ for Windows Version 2.0 is different
from that provided by WebSphere MQ for Windows Version 2.1.
On WebSphere MQ for Windows Version 2.0, two batch files must be created, one
containing the commands to start the dial-up device (a modem, for example) and the
other containing the commands to stop it. Two sample batch files, STRTLINK.BAT and
STOPLINK.BAT, are supplied in the \MQW\SAMPLES directory. These contain
comments which provide guidance on how to create the batch files for your dial-up
device.
When the batch files have been created, you then need to create a component called a
transport link. A transport link is owned by a queue manager and effectively declares
the names of the two batch files to the queue manager.
In order to exchange messages with another queue manager over a dial-up telephone
link, one queue manager, one channel group, and one transport link must all be active.
DiaI-up Support
Version 2.0
Need to write two batch files:
To start the dial-up device
To stop the dial-up device
Sample batch files are provided with comments
Need to create a transport link declaring the names of the two
batch files
Version 2.1
Uses the built in dial-up support provided by Windows
Need to create:
A dial-up networking connection in Windows (= phonebook entry in
WebSphere MQ)
An WebSphere MQ dial-up connection referencing a phonebook entry
Instructor Guide
On WebSphere MQ for Windows Version 2.1, a dial-up connection uses the built in
dial-up networking support provided by Windows 95 and Windows NT.
Within Windows, you must first create one or more dial-up networking connections, each
of which relates a name to a telephone number. WebSphere MQ for Windows refers to
these as phonebook entries. In order to create an WebSphere MQ for Windows dial-up
connection therefore, you just need to specify the name of the queue manager, the
name of the channel group, and the name of the required phonebook entry.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain what dial-up support is provided by WebSphere MQ for Windows.
Transition Statement Next we look at how WebSphere MQ for Windows is installed.
Instructor Guide
Notes:
The installation of WebSphere MQ for Windows uses the standard function provided by
the respective Windows platform.
- On Windows 95 and Windows NT, open the Control Panel, select Add/Remove
Program, and then Install.
- On the remaining Windows environments, select Run... from the File menu in
Program Manager and then execute A:\INSTALL.
During the installation of WebSphere MQ for Windows Version 2.0 only, you are asked
which components of the product you wish to install. There are three components.
- Base component
- Online information
- Toolkit and samples
The base component always needs to be installed, but the other two components may
be installed later.
InstaIIation
Standard procedure
Windows 95/98 and Windows NT
Select nstall from Add/Remove Programs in Control Panel
Other environments
Select Run... from File menu and execute A:\NSTALL
Version 2.0 only - select which components to install
Base
Online information
Toolkit and samples
Version 2.1 only - two types of installation
Compact
Complete
Automatic installation possible
Automated installation verification available
Instructor Guide
V2.0
Uempty
During the installation of WebSphere MQ for Windows Version 2.1 only, you are asked
whether you wish to install the compact or the complete version of the product.
Compact
This version is intended for users. Select this version if you only wish to
run WebSphere MQ applications.
Complete
This version contains all the product function. Select this version if you
are an administrator or an application developer.
WebSphere MQ for Windows can be installed automatically. This can be done in one of
two ways.
- An attended installation from a LAN file server and using a response file.
- An unattended installation using a software distribution manager such as IBM's
NetView Distribution Manager or Microsoft's Systems Management Server (SMS).
Following an installation, you can use the automated installation verification procedure
supplied with WebSphere MQ for Windows.
On WebSphere MQ for Windows Version 2.0, the procedure creates a queue manager,
starts the queue manager, connects to the queue manager, opens a queue, puts
messages on the queue, gets the messages from the queue, closes the queue,
disconnects from the queue manager, stops the queue manager, and finally deletes the
queue manager.
On WebSphere MQ for Windows Version 2.1, you may run the installation verification
procedure in two modes.
Stand-alone mode
In this mode, if there is no active connection, the procedure creates a
stand-alone connection, starts the connection, opens the default queue,
puts a message on the queue, gets the message from the queue, closes
the queue, stops the connection, and finally deletes the connection. If
there is an active connection, the procedure uses that connection to
open the default queue, put a message on the queue, get the message
from the queue, and finally close the queue.
LAN mode
In this mode, the procedure uses a LAN connection to test whether a
message can be sent to a remote queue manager and be received from
that queue manager. In order to do this, the remote queue manager has
to be configured according the instructions provided in the WebSphere
MQ for Windows Version 2.1 User's Guide.
Instructor Guide
Instructor Notes:
Purpose To summarize how WebSphere MQ for Windows is installed.
Details More detailed lists of what the compact and the complete versions contain can
be found in the WebSphere MQ for Windows Version 2.1 User's Guide.
Transition Statement The administration interfaces provided by the two versions of
WebSphere MQ for Windows are different. First, we look at the administration interfaces
provided by WebSphere MQ for Windows Version 2.0.
Instructor Guide
V2.0
Uempty
Figure 7-9. Administration on Version 2.0 MQ157.0
Notes:
The installation of WebSphere MQ for Windows Version 2.0 creates an WebSphere MQ
for Windows program group which contains icons providing access to administration
utilities, sample programs, and online information.
The utilities are as follows:
Create Components
This utility allows you to create queue managers, queues, channels,
channel groups, and transport links. When you create a queue
manager, the file containing the WebSphere MQ commands to create
the system and default objects, AMQSCOMW.TST, is run automatically.
However, you can also specify, as part of the definition, that other files
containing WebSphere MQ commands are to be run as well.
Delete Components
This utility provides the function to delete queue managers, queues,
channels, channel groups, and transport links.
Administration on Version 2.0
InstaIIation creates an WebSphere MQ for Windows program
group providing access to:
Command Reference
User's Guide
Quick Tour
OnIine information
Putting messages
Getting messages
Browsing messages
SampIe programs
Create components
DeIete components
Standard controIs
Advanced controIs
MQSC commands
Create and Go
InstaIIation
Verify InstaII
Service Information
Service Trace
UtiIities
Instructor Guide
Standard Controls
This utility allows you to start a queue manager, a channel group, and a
transport link, and to stop any of these. Although you may create more
than one queue manager on a system, only one queue manager can be
active at a time.
The utility also allows you to designate one queue manager, one
channel group, and one transport link to be started automatically when
Standard Controls starts. Thus, by adding the Standard Controls icon to
the Windows StartUp group, you can cause a queue manager, a
channel group, and a transport link to be started automatically when
Windows is started, and so the workstation is immediately ready to run
WebSphere MQ applications.
The utility also allows you to view the status of a queue manager, a
queue, a channel, a channel group, and a transport link, and to view the
attributes of any of these components.
When you exit from Standard Controls, any active queue manager,
channel group, and transport link are stopped.
Advanced Controls
This utility provides the same function as Standard Controls but, in
addition, allows you to change the definitions of WebSphere MQ
components, such as altering the value of an attribute of a queue or
adding a channel to a channel group.
MQSC Commands
This utility allows you to enter WebSphere MQ commands interactively
or to run a file containing WebSphere MQ commands.
Create and Go
This utility reads the contents of the initialization, or INI, file,
CREATEMQ.INI, and uses the definitions it contains to create all the
WebSphere MQ components a user requires on his/her workstation
prior to running applications. We shall look at the initialization file in a
little more detail later.
Installation
You use this utility to change your installation. It allows you to add any
components of WebSphere MQ for Windows which you did not install
initially, remove any components which are no longer required, and
apply maintenance upgrades.
Verify Install
This is the utility which invokes the automated installation verification
procedure.
Service Information
This utility displays certain information which may be useful in solving
Instructor Guide
V2.0
Uempty
problems. The information includes the release level of each of the
WebSphere MQ for Windows files so that you can determine whether
any maintenance fixes have been applied.
Service Trace
This utility is used to produce a trace of the operation of WebSphere MQ
for Windows. It is designed for use only under the direction and
guidance of IBM Service personnel.
There are sample programs to put messages on a queue, get messages from a queue,
and browse messages on a queue.
The online information consists of a version of the WebSphere MQ Command Reference
applicable only to WebSphere MQ for Windows Version 2.0, an online version of the
WebSphere MQ for Windows Version 2.0 User's Guide, and the Quick Tour. Access to
the READ.ME file is also provided.
Instructor Guide
Instructor Notes:
Purpose To explain how administration function is accessed on WebSphere MQ for
Windows Version 2.0.
Details Earlier in the course, it was stated that WebSphere MQ for Windows holds all its
data in memory but persistent information is written to a persistence file as well. There is a
persistence file for each queue manager and it is created when the queue manager is
created. Its name is MQPERS.MQI and it is located in the queue manager directory. Other
than ensuring that there is enough disk space to hold the file, there are no further
administration tasks associated with logging and recovery. This applies to both
WebSphere MQ for Windows Version 2.0 and WebSphere MQ for Windows Version 2.1.
Transition Statement Next we look at the administration interfaces provided by
Instructor Guide
V2.0
Uempty
Figure 7-10. Administration on Version 2.1 MQ157.0
Notes:
WebSphere MQ for Windows Version 2.1 starts every time Windows starts and can only
be stopped by stopping Windows. The WebSphere MQ icon on the Windows taskbar
indicates that WebSphere MQ is running. You may choose to hide the WebSphere MQ
icon if you wish.
The administration utilities of WebSphere MQ for Windows Version 2.0 are integrated
into a single WebSphere MQ Properties dialogue box on WebSphere MQ for Windows
Version 2.1. WebSphere MQ Properties can be opened in any one of the four ways
depicted on the visual. If you choose to hide the WebSphere MQ icon however, only the
last two ways are available.
If you install the complete version of WebSphere MQ for Windows Version 2.1, the
WebSphere MQ Properties dialogue box has the following pages.
Connections
This page is used to start or stop a connection. Although you may
create more than one connection on a system, only one connection can
be active at a time.
WebSphere MQ runs whenever Windows is running
WebSphere MQ icon on the Windows taskbar
WebSphere MQ Properties dialog box can be opened:
By double clicking on the WebSphere MQ icon
By selecting Open WebSphere MQ Properties from the
WebSphere MQ icon menu
From the Windows Control Panel
By selecting the shortcut from the WebSphere MQ for Windows
folder
. . . and provides access to the following pages
Shortcuts from the WebSphere MQ for Windows folder to:
Connections
Components
Options
MQSC
Command Server
Service
Command Reference
MQSeries Properties
Quick Tour
Registration
Service Trace
User's Guide
Administration on Version 2.1
Instructor Guide
Components
This page allows you to create, alter, and delete connections, queue
managers, queues, channels, and channel groups. The status of
WebSphere MQ components may also be viewed.
Like on WebSphere MQ for Windows Version 2.0, when you create a
queue manager, the file containing the WebSphere MQ commands to
create the system and default objects, AMQSCOMW.TST, is run
automatically.
One connection may be designated to start automatically when
WebSphere MQ starts. And because WebSphere MQ starts when
Windows starts, this is the mechanism by which a user can start
Windows and immediately commence running WebSphere MQ
applications.
Options This page allows you to select options which control the operation of
WebSphere MQ for Windows. There is an option to hide or make visible
the WebSphere MQ icon on the Windows taskbar. There is also an
option to request that the Connections page of WebSphere MQ
Properties is displayed whenever WebSphere MQ starts so that the user
can select which connection to start.
MQSC This page allows you to enter WebSphere MQ commands interactively
or to run a file containing WebSphere MQ commands.
Command Server
This page allows you to start and stop the command server.
Service This page has various sub-pages providing access to the following.
- The automated installation verification procedure in either
standalone or LAN mode.
- Similar information as that provided by the Service Information
utility on WebSphere MQ for Windows Version 2.0.
- A readable display of the contents of the channel log,
CHANNEL.LOG, which contains binary information. The
equivalent log on WebSphere MQ for Windows Version 2.0 is
AMQERR01.LOG but no function is supplied to convert it into a
readable format. It is for use by IBM Service personnel only.
If you install the compact version of WebSphere MQ for Windows Version 2.1, the
content of the WebSphere MQ Properties dialogue box is different. It only provides
access to function which a user might require.
Shortcuts from the WebSphere MQ for Windows folder provide access to the following.
- An online version of the WebSphere MQ Command Reference applicable only to
- The WebSphere MQ Properties dialogue box.
Instructor Guide
V2.0
Uempty
- The Quick Tour.
- The Registration dialogue.
- The Service Trace utility.
- An online version of the WebSphere MQ for Windows Version 2.1 User's Guide.
The sample programs for putting messages on a queue, getting messages from a
queue, and browsing messages on a queue are found and started using the Windows
Explorer. The names of the executables are AMQSPUTW.EXE, AMQSGETW.EXE, and
AMQSBCGW.EXE respectively.
Instructor Guide
Instructor Notes:
Purpose To explain how administration function is accessed on WebSphere MQ for
Transition Statement We have seen that WebSphere MQ commands may be used on
WebSphere MQ for Windows. Next we look at the subset of WebSphere MQ commands
that are supported.
Instructor Guide
V2.0
Uempty
Figure 7-11. Supported WebSphere MQ Commands MQ157.0
Notes:
WebSphere MQ for Windows supports all the DEFINE, ALTER, and DELETE
commands associated with the following WebSphere MQ objects.
Local queue (QLOCAL)
Model queue (QMODEL)
Alias queue (QALIAS)
Local definition of a remote queue (QREMOTE)
Queue manager (QMGR)
Channel (CHANNEL)
WebSphere MQ for Windows Version 2.0 does not support any DISPLAY commands
but Version 2.1 supports the following three.
DISPLAY CHANNEL
DISPLAY QMGR
DISPLAY QUEUE
Supported MQSeries Commands
All relevant DEFNE, ALTER, and DELETE commands
The following DSPLAY commands on Version 2.1 only
DSPLAY CHANNEL
DSPLAY QMGR
DSPLAY QUEUE
The following operational commands
CLEAR QLOCAL
RESET CHANNEL
RESOLVE CHANNEL
START CHANNEL
STOP CHANNEL
Instructor Guide
Of the WebSphere MQ commands for operating WebSphere MQ, only the following are
supported.
CLEAR QUEUE
RESET CHANNEL
RESOLVE CHANNEL
START CHANNEL
STOP CHANNEL
Of the WebSphere MQ commands that are supported by WebSphere MQ for Windows,
certain of their parameters are not supported. In addition, there are some minor
differences in the syntax rules for constructing WebSphere MQ commands on
WebSphere MQ for Windows compared to those which apply on other Level 2 queue
managers. Full details of all these can be found in the online versions of the WebSphere
MQ Command Reference.
There are no WebSphere MQ commands associated with components unique to
WebSphere MQ for Windows, namely, a connection, a channel group, and a transport
link.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To summarize which WebSphere MQ commands are supported by
Transition Statement Earlier we encountered the concept of an initialization, or INI, file
on WebSphere MQ for Windows Version 2.0 in relation to the Create and Go utility. We
now take a closer look at this file.
Instructor Guide
Figure 7-12. Initialization (INI) File on Version 2.0 MQ157.0
Notes:
The initialization, or INI, file must be named CREATEMQ.INI and be located in the
\MQW directory. A sample INI file with this name is supplied with WebSphere MQ for
Windows Version 2.0 and is placed in the \MQW directory by the installation process. It
can be replaced by an INI file written by an administrator.
The INI file contains definitions of WebSphere MQ components which are read by the
Create and Go utility. The utility uses the definitions to create the components.
The INI file can therefore be used to create all the WebSphere MQ components that a
user requires in order to run applications on his/her workstation. It may also cause
Standard Controls or Advanced Controls to be started automatically and/or cause either
of these to be added to the Windows StartUp group. The former option enables
WebSphere MQ applications to be run immediately after the Create and Go utility has
completed. The latter option enables WebSphere MQ applications to be run
immediately after starting Windows.
An administrator may replace the default INI file on the installation diskettes which
he/she gives to a user. All the user then has to do is install WebSphere MQ for
InitiaIization (INI) FiIe on Version 2.0
CREATEMQ.N in the \MQW directory
Contains definitions which are read and executed by the
Create and Go utility
The definitions can be used to:
Create all the WebSphere MQ components required by a user on
a workstation
Start Standard Controls or Advanced controls automatically or
add one of these to the Windows StartUp group
The default N file on the installation diskettes can be replaced
Instructor Guide
V2.0
Uempty
Windows, optionally verify the installation, run the Create and Go utility, and then start
an application.
Instructor Guide
Instructor Notes:
Purpose To explain the concept of an initialization, or INI, file on WebSphere MQ for
Transition Statement Next we look at how the equivalent function is provided on
Instructor Guide
V2.0
Uempty
Figure 7-13. MQSeries Definition (MQD) File on Version 2.1 MQ157.0
Notes:
WebSphere MQ for Windows Version 2.1 uses an WebSphere MQ definition, or MQD,
file to provide the function equivalent to that provided by the INI file on Version 2.0.
The MQD file must be named CREATEMQ.MQD and be located in the
\Program Files\MQSeries for Windows directory. Alternatively, the environment variable
MQW_MQDPATH may specify the name and location of the file.
Like an INI file, an MQD file can contain the definitions of all the WebSphere MQ
components required by a user to run applications on his/her workstation. In addition,
an MQD file can designate one connection to be started automatically whenever
WebSphere MQ starts.
There is no Create and Go utility on WebSphere MQ for Windows Version 2.1. Instead,
the MQD file is run under the following circumstances.
- The MQD file is run automatically as part of the installation process.
MQSeries Definition (MQD) FiIe on Version 2.1
CREATEMQ.MQD in the \Program Files\MQSeries for Windows
directory
When it is run, it can:
Create all the WebSphere MQ components required by a user on
a workstation
Designate one connection to be started automatically whenever
WebSphere MQ starts
t is run:
Automatically as part of the installation process
Subsequently, whenever WebSphere MQ starts
Checks the date, time, and size of the MQD file, and prompts
the user
By selecting Run MQD file now from the WebSphere MQ icon
menu
Main differences compared to an N file on Version 2.0
No user action required to run an MQD file
More keywords
Instructor Guide
An administrator can provide an MQD file, tailored to a user's requirements, on the
installation diskettes. All the user then has to do is install WebSphere MQ for
Windows, optionally verify the installation, and then start an application.
- Subsequently, the MQD file may be run whenever WebSphere MQ starts.
When WebSphere MQ starts, it checks the date, time, and size of the MQD file. If any
of these are different from those of the MQD file that was last run, the user is
prompted to choose whether to process the new file.
- At any time, a user can force the MQD file to be run by selecting Run MQD file now
from the WebSphere MQ icon menu.
The main differences between an INI file and an MQD file are as follows.
- There are more choices for when the MQD file is run. In particular, it is run
automatically as part of the installation process and so can be hidden from the user.
- The syntax of the language used to write an MQD file is similar to that used to write
an INI file, but there are more keywords available for an MQD file.
Instructor Guide
V2.0
Uempty
Instructor Notes:
Purpose To explain the concept of an WebSphere MQ definition, or MQD, file on
Transition Statement Next we look at an example of an MQD file.
Instructor Guide
Figure 7-14. Example of an MQD File MQ157.0
Notes:
An MQD file comprises one or more sections, each beginning with a section name. A
section may either define an WebSphere MQ component or it may be a special section.
A section defining an WebSphere MQ component must commence with a name of the
form [Component_n]. In the example on the visual, there are three sections, each
defining an WebSphere MQ component, and no special sections.
The section with name [Component_1] defines a queue manager whose name is
MARS. When the MQD file is run and the queue manager is created, the file containing
the WebSphere MQ commands to create the system and default objects,
AMQSCOMW.TST, is run automatically. However, the use of the keyword
LoadUserMQSC_1 causes the WebSphere MQ commands in the file MARS.TST to be
run as well. This file contains the WebSphere MQ commands to create all the
WebSphere MQ objects required to run applications which connect to the queue
manager. In particular, it defines the two channels, MARS.TO.VENUS and
VENUS.TO.MARS, which are referenced in the next section.
ExampIe of an MQD FiIe
[Component_1]
ComponentType=QueueManager
Name=MARS
Description=Queue manager to use on MARS workstation
LoadUserMQSC_1=\Program Files\MQSeries for Windows\Samples\mars.tst
Replace=yes
[Component_2]
ComponentType=ChannelGroup
Name=VENUS_Group
Description=Channel group to communicate with VENUS
QueueManagerName=MARS
Channel_1=MARS.TO.VENUS
Channel_2=VENUS.TO.MARS
Replace=yes
[Component_3]
ComponentType=Connection
Name=VENUS_Connection
Description=Connection to communicate with VENUS
QueueManagerName=MARS
HasChannelGroup=yes
ChannelGroupName=VENUS_Group
Replace=yes
AutoStart=yes
Instructor Guide
V2.0
Uempty
The section with name [Component_2] defines a channel group whose name is
VENUS_Group. This channel group belongs to the queue manager MARS and consists
of two channels, MARS.TO.VENUS and VENUS.TO.MARS.
The section with name [Component_3] defines a connection whose name is
VENUS_Connection. Specifying HasChannelGroup=yes without
HasPhonebookEntry=yes indicates that the section is defining a LAN connection.
The connection consists of the queue manager MARS and the channel group
VENUS_Group. Specifying AutoStart=yes indicates that the connection is to be
started automatically when WebSphere MQ starts.
Full details on how to write an MQD file can be found in the WebSphere MQ for
Windows Version 2.1 User's Guide.
Similarly, full details on how to write an INI file can be found in the WebSphere MQ for
Windows Version 2.0 User's Guide.
Instructor Guide
Instructor Notes:
Purpose To show an simple example of an MQD file and to explain some of its more
important features.
Transition Statement End of the topic. There now follows the final exercise and
checkpoints followed by a summary of this unit.
Instructor Guide
V2.0
Uempty Checkpoint
Unit 7 Checkpoint
1. WebSphere MQ for Windows 2.0 and 2.1 have some differences
relating to supported functions. Which of the following is only
supported with 2.1?
a. Command server
b. Dead letter queue
c. Requester channels
d. Triggering
Correct Answer: a
Neither supports dead letter queues or triggering. Both support
requester channels.
2. WebSphere MQ for Windows V2.1 supports which of the following:
a. Windows 3.1
b. Windows NT
c. Windows for Workgroups 3.11
d. WIN-OS/2
Correct Answer: b
Only 32-bit implementations are supported on 2.1.
Instructor Guide
Notes:
We saw first of all how WebSphere MQ for Windows is positioned in relation to the other
members of the WebSphere MQ family. Note particularly the differences between running
WebSphere MQ for Windows on a Windows system and running an WebSphere MQ client
or a full server queue manager on the same system.
We also saw that there are some differences in function between WebSphere MQ for
Windows and the other Level 2 queue managers. But WebSphere MQ for Windows has
some unique features as well.
The administration function on WebSphere MQ for Windows is provided by a graphical user
interface, or GUI. This is well integrated into the Windows environment.
Minimal contact with WebSphere MQ function is required by the user. This is an important
design feature of WebSphere MQ for Windows. WebSphere MQ for Windows Version 2.1
is better that WebSphere MQ for Windows Version 2.0 in this respect. One of the principal
ways in which this was achieved was by introducing the concept of a connection.
Positioning
Some differences compared to other WebSphere MQ queue
managers . . .
. . . and some unique features
GU for administration, well integrated into the Windows
environment
Minimal user contact with WebSphere MQ function
Final checkpoint test
Unit Summary
Instructor Guide
V2.0
Uempty
Instructor Notes:
Details As this ends course - be sure to thank students.
Transition Statement End of the unit and the course.
Instructor Guide
Instructor Guide
Copyright IBM Corp. 1996, 2003 Appendix A. Checkpoint Solutions A-1
V2.0
Uempty
Appendix A. Checkpoint Solutions
Unit 1
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.
Correct Answer: d
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.
Correct Answer: b
Unit 2
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
Correct Answer: b
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.
Correct Answer: a
4. T/F Altering queue attributes can be done while the queue
manager is running and the changes take effect immediately.
Instructor Guide
A-2 WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
Unit 3
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.
Correct Answer: a
3. When an application issues an MQPUT of a message and explicitly
sets 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.
Correct Answer: c
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
Correct Answer: b, d
Unit 4
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
Instructor Guide
V2.0
Uempty
c. circular
d. checkpointing
Correct Answer: b, c
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
Correct Answer: c
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
Correct Answer: c
Unit 5
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 SENDER 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.
Correct Answer: b
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.
Instructor Guide
c. Because the channel is active, this command will no be
executed.
d. The channel will fail and any in-transmit messages will be lost.
Correct Answer: a
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.
Unit 6
1. T/F All SupportPacs are AS-IS code.
2. T/F A client channel does not require a START CHANNEL
command.
3. On a Version 5.1 client, what additional method is available to
identify the server connection desired?
a. Use SET MQSERVER environment variable
b. Use the MQCONNX call
c. Use a client channel table
d. If a SVRCONN is defined, the client will find it.
Correct Answer: b
4. T/F A message exit can be used to control security when running
from an WebSphere MQ client.
Unit 7
1. WebSphere MQ for Windows 2.0 and 2.1 have some differences
relating to supported functions. Which of the following is only
supported with 2.1?
a. Command server
b. Dead letter queue
c. Requester channels
d. Triggering
Correct Answer: a
Neither supports dead letter queues or triggering. Both support
requester channels.
2. WebSphere MQ for Windows V2.1 supports which of the following:
Instructor Guide
V2.0
Uempty
a. Windows 3.1
b. Windows NT
c. Windows for Workgroups 3.11
d. WIN-OS/2
Correct Answer: b
Only 32-bit implementations are supported on 2.1.
Instructor Guide
Instructor Guide
Copyright IBM Corp. 1996, 2003 Appendix B. Selected WebSphere MQ Constants B-1
V2.0
Uempty
Appendix B. Selected WebSphere MQ Constants
This appendix specifies the values of selected WebSphere MQ constants. For other
WebSphere MQ constants, refer to the MQSeries Application Programming Reference, the
MQSeries Programming Interface Reference Summary, MQSeries Intercommunication,
and MQSeries Programmable System Management.
The constants are grouped according to the parameter or field to which they relate. All of
the names of the constants in a group begin with a common prefix of the form "MQxxxx_.
where xxxx represents a string of 0 through 4 characters that indicates the nature of the
values defined in that group. The constants are ordered alphabetically by the prefix.
Notes:
1. For constants with numeric values, the values are shown in both decimal and
hexadecimal forms.
2. Hexadecimal values are represented using the notation X'hhhhhhhh', where each "h
"denotes a single hexadecimal digit.
MQFB_ (Feedback)
MQCC_ (Completion code)
MQCC_UNKNOWN -1 X FFFFFFFF
MQCC_OK 0 X00000000
MQCC_WARNING 1 X 00000001
MQCC_FAILED 2 X 00000002
MQFB_NONE 0 X00000000
MQFB_SYSTEM_FIRST 1 X00000001
MQFB_QUIT 256 X00000100
MQFB_EXPIRATION 258 X00000102
MQFB_COA 259 X00000103
MQFB_COD 260 X00000104
MQFB_CHANNEL_COMPLETED 262 X00000106
MQFB_CHANNEL_FAIL_RETRY 263 X00000107
Instructor Guide
B-2 WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
MQFB_CHANNEL_FAIL 264 X00000108
MQFB_APPL_CANNOT_BE_STARTED 265 X00000109
MQFB_TM_ERROR 266 X0000010A
MQFB_APPL_TYPE_ERROR 267 X0000010B
MQFB_STOPPED_BY_MSG_EXIT 268 X0000010C
MQFB_XMIT_Q_MSG_ERROR 271 X0000010F
MQFB_PAN 275 X00000113
MQFB_NAN 276 X00000114
MQFB_STOPPED_BY_CHAD_EXIT 277 X00000115
MQFB_NOT_A_REPOSITORY_MSG 280 X00000118
MQFB_DATA_LENGTH_ZERO 291 X00000123
MQFB_DATA_LENGTH_NEGATIVE 292 X00000124
MQFB_DATA_LENGTH_TOO_BIG 293 X00000125
MQFB_BUFFER_OVERFLOW 294 X00000126
MQFB_LENGTH_OFF_BY_ONE 295 X00000127
MQFB_IIH_ERROR 296 X00000128
MQFB_NOT_AUTHORIZED_FOR_IMS 298 X0000012A
MQFB_IMS_ERROR 300 X0000012C
MQFB_IMS_FIRST 301 X0000012D
MQFB_IMS_LAST 399 X0000018F
MQFB_CICS_INTERNAL_ERROR 401 X00000191
MQFB_CICS_NOT_AUTHORIZED 402 X00000192
MQFB_CICS_BRIDGE_FAILURE 403 X00000193
MQFB_CICS_CORREL_ID_ERROR 404 X00000194
MQFB_CICS_CCSID_ERROR 405 X00000195
MQFB_CICS_ENCODING_ERROR 406 X00000196
MQFB_CICS_CIH_ERROR 407 X00000197
Instructor Guide
V2.0
Uempty
MQRC_ (Reason code)
MQFB_CICS_UOW_ERROR 408 X00000198
MQFB_CICS_COMMAREA_ERROR 409 X00000199
MQFB_CICS_APPL_NOT_STARTED 410 X0000019A
MQFB_CICS_APPL_ABENDED 411 X0000019B
MQFB_CICS_DLQ_ERROR 412 X0000019C
MQFB_CICS_UOW_BACKED_OUT 413 X0000019D
MQFB_SYSTEM_LAST 65535 X0000FFFF
MQFB_APPL_FIRST 65536 X00010000
MQFB_APPL_LAST 999999999 X3B9AC9FF
MQRC_NONE 0 X00000000
MQRC_APPL_FIRST 900 X00000384
MQRC_APPL_LAST 999 X000003E7
MQRC_ALIAS_BASE_Q_TYPE_ERROR 2001 X000007D1
MQRC_ALREADY_CONNECTED 2002 X000007D2
MQRC_BACKED_OUT 2003 X000007D3
MQRC_BUFFER_ERROR 2004 X000007D4
MQRC_BUFFER_LENGTH_ERROR 2005 X000007D5
MQRC_CHAR_ATTR_LENGTH_ERROR 2006 X000007D6
MQRC_CHAR_ATTRS_ERROR 2007 X000007D7
MQRC_CHAR_ATTRS_TOO_SHORT 2008 X000007D8
MQRC_CONNECTION_BROKEN 2009 X000007D9
MQRC_DATA_LENGTH_ERROR 2010 X000007DA
MQRC_DYNAMIC_Q_NAME_ERROR 2011 X000007DB
MQRC_ENVIRONMENT_ERROR 2012 X000007DC
MQRC_EXPIRY_ERROR 2013 X000007DD
Instructor Guide
MQRC_FEEDBACK_ERROR 2014 X000007DE
MQRC_GET_INHIBITED 2016 X000007E0
MQRC_HANDLE_NOT_AVAILABLE 2017 X000007E1
MQRC_HCONN_ERROR 2018 X000007E2
MQRC_HOBJ_ERROR 2019 X000007E3
MQRC_INHIBIT_VALUE_ERROR 2020 X000007E4
MQRC_INT_ATTR_COUNT_ERROR 2021 X000007E5
MQRC_INT_ATTR_COUNT_TOO_SMALL 2022 X000007E6
MQRC_INT_ATTRS_ARRAY_ERROR 2023 X000007E7
MQRC_SYNCPOINT_LIMIT_REACHED 2024 X000007E8
MQRC_MAX_CONNS_LIMIT_REACHED 2025 X000007E9
MQRC_MD_ERROR 2026 X000007EA
MQRC_MISSING_REPLY_TO_Q 2027 X000007EB
MQRC_MSG_TYPE_ERROR 2029 X000007ED
MQRC_MSG_TOO_BIG_FOR_Q 2030 X000007EE
MQRC_MSG_TOO_BIG_FOR_Q_MGR 2031 X000007EF
MQRC_NO_MSG_AVAILABLE 2033 X000007F1
MQRC_NO_MSG_UNDER_CURSOR 2034 X000007F2
MQRC_NOT_AUTHORIZED 2035 X000007F3
MQRC_NOT_OPEN_FOR_BROWSE 2036 X000007F4
MQRC_NOT_OPEN_FOR_INPUT 2037 X000007F5
MQRC_NOT_OPEN_FOR_INQUIRE 2038 X000007F6
MQRC_NOT_OPEN_FOR_OUTPUT 2039 X000007F7
MQRC_NOT_OPEN_FOR_SET 2040 X000007F8
MQRC_OBJECT_CHANGED 2041 X000007F9
MQRC_OBJECT_IN_USE 2042 X000007FA
MQRC_OBJECT_TYPE_ERROR 2043 X000007FB
Instructor Guide
V2.0
Uempty
MQRC_OD_ERROR 2044 X000007FC
MQRC_OPTION_NOT_VALID_FOR_TYPE 2045 X000007FD
MQRC_OPTIONS_ERROR 2046 X000007FE
MQRC_PERSISTENCE_ERROR 2047 X000007FF
MQRC_PERSISTENT_NOT_ALLOWED 2048 X00000800
MQRC_PRIORITY_EXCEEDS_MAXIMUM 2049 X00000801
MQRC_PRIORITY_ERROR 2050 X00000802
MQRC_PUT_INHIBITED 2051 X00000803
MQRC_Q_DELETED 2052 X00000804
MQRC_Q_FULL 2053 X00000805
MQRC_Q_NOT_EMPTY 2055 X00000807
MQRC_Q_SPACE_NOT_AVAILABLE 2056 X00000808
MQRC_Q_TYPE_ERROR 2057 X00000809
MQRC_Q_MGR_NAME_ERROR 2058 X0000080A
MQRC_Q_MGR_NOT_AVAILABLE 2059 X0000080B
MQRC_REPORT_OPTIONS_ERROR 2061 X0000080D
MQRC_SECOND_MARK_NOT_ALLOWED 2062 X0000080E
MQRC_SECURITY_ERROR 2063 X0000080F
MQRC_SELECTOR_COUNT_ERROR 2065 X00000811
MQRC_SELECTOR_LIMIT_EXCEEDED 2066 X00000812
MQRC_SELECTOR_ERROR 2067 X00000813
MQRC_SELECTOR_NOT_FOR_TYPE 2068 X00000814
MQRC_SIGNAL_OUTSTANDING 2069 X00000815
MQRC_SIGNAL_REQUEST_ACCEPTED 2070 X00000816
MQRC_STORAGE_NOT_AVAILABLE 2071 X00000817
MQRC_SYNCPOINT_NOT_AVAILABLE 2072 X00000818
MQRC_TRIGGER_CONTROL_ERROR 2075 X0000081B
Instructor Guide
MQRC_TRIGGER_DEPTH_ERROR 2076 X0000081C
MQRC_TRIGGER_MSG_PRIORITY_ERR 2077 X0000081D
MQRC_TRIGGER_TYPE_ERROR 2078 X0000081E
MQRC_TRUNCATED_MSG_ACCEPTED 2079 X0000081F
MQRC_TRUNCATED_MSG_FAILED 2080 X00000820
MQRC_UNKNOWN_ALIAS_BASE_Q 2082 X00000822
MQRC_UNKNOWN_OBJECT_NAME 2085 X00000825
MQRC_UNKNOWN_OBJECT_Q_MGR 2086 X00000826
MQRC_UNKNOWN_REMOTE_Q_MGR 2087 X00000827
MQRC_WAIT_INTERVAL_ERROR 2090 X0000082A
MQRC_XMIT_Q_TYPE_ERROR 2091 X0000082B
MQRC_XMIT_Q_USAGE_ERROR 2092 X0000082C
MQRC_NOT_OPEN_FOR_PASS_ALL 2093 X0000082D
MQRC_NOT_OPEN_FOR_PASS_IDENT 2094 X0000082E
MQRC_NOT_OPEN_FOR_SET_ALL 2095 X0000082F
MQRC_NOT_OPEN_FOR_SET_IDENT 2096 X00000830
MQRC_CONTEXT_HANDLE_ERROR 2097 X00000831
MQRC_CONTEXT_NOT_AVAILABLE 2098 X00000832
MQRC_SIGNAL1_ERROR 2099 X00000833
MQRC_OBJECT_ALREADY_EXISTS 2100 X00000834
MQRC_OBJECT_DAMAGED 2101 X00000835
MQRC_RESOURCE_PROBLEM 2102 X00000836
MQRC_ANOTHER_Q_MGR_CONNECTED 2103 X00000837
MQRC_UNKNOWN_REPORT_OPTION 2104 X00000838
MQRC_STORAGE_CLASS_ERROR 2105 X00000839
MQRC_COD_NOT_VALID_FOR_XCF_Q 2106 X0000083A
MQRC_XWAIT_CANCELED 2107 X0000083B
Instructor Guide
V2.0
Uempty
MQRC_XWAIT_ERROR 2108 X0000083C
MQRC_SUPPRESSED_BY_EXIT 2109 X0000083D
MQRC_FORMAT_ERROR 2110 X0000083E
MQRC_SOURCE_CCSID_ERROR 2111 X0000083F
MQRC_SOURCE_INTEGER_ENC_ERROR 2112 X00000840
MQRC_SOURCE_DECIMAL_ENC_ERROR 2113 X00000841
MQRC_SOURCE_FLOAT_ENC_ERROR 2114 X00000842
MQRC_TARGET_CCSID_ERROR 2115 X00000843
MQRC_TARGET_INTEGER_ENC_ERROR 2116 X00000844
MQRC_TARGET_DECIMAL_ENC_ERROR 2117 X00000845
MQRC_TARGET_FLOAT_ENC_ERROR 2118 X00000846
MQRC_NOT_CONVERTED 2119 X00000847
MQRC_CONVERTED_MSG_TOO_BIG 2120 X00000848
MQRC_TRUNCATED 2120 X00000848
MQRC_NO_EXTERNAL_PARTICIPANTS 2121 X00000849
MQRC_PARTICIPANT_NOT_AVAILABLE 2122 X0000084A
MQRC_OUTCOME_MIXED 2123 X0000084B
MQRC_OUTCOME_PENDING 2124 X0000084C
MQRC_BRIDGE_STARTED 2125 X0000084D
MQRC_BRIDGE_STOPPED 2126 X0000084E
MQRC_ADAPTER_STORAGE_SHORTAGE 2127 X0000084F
MQRC_UOW_IN_PROGRESS 2128 X00000850
MQRC_ADAPTER_CONN_LOAD_ERROR 2129 X00000851
MQRC_ADAPTER_SERV_LOAD_ERROR 2130 X00000852
MQRC_ADAPTER_DEFS_ERROR 2131 X00000853
MQRC_ADAPTER_DEFS_LOAD_ERROR 2132 X00000854
MQRC_ADAPTER_CONV_LOAD_ERROR 2133 X00000855
Instructor Guide
MQRC_BO_ERROR 2134 X00000856
MQRC_DH_ERROR 2135 X00000857
MQRC_MULTIPLE_REASONS 2136 X00000858
MQRC_OPEN_FAILED 2137 X00000859
MQRC_ADAPTER_DISC_LOAD_ERROR 2138 X0000085A
MQRC_CNO_ERROR 2139 X0000085B
MQRC_CICS_WAIT_FAILED 2140 X0000085C
MQRC_DLH_ERROR 2141 X0000085D
MQRC_HEADER_ERROR 2142 X0000085E
MQRC_SOURCE_LENGTH_ERROR 2143 X0000085F
MQRC_TARGET_LENGTH_ERROR 2144 X00000860
MQRC_SOURCE_BUFFER_ERROR 2145 X00000861
MQRC_TARGET_BUFFER_ERROR 2146 X00000862
MQRC_IIH_ERROR 2148 X00000864
MQRC_PCF_ERROR 2149 X00000865
MQRC_DBCS_ERROR 2150 X00000866
MQRC_OBJECT_NAME_ERROR 2152 X00000868
MQRC_OBJECT_Q_MGR_NAME_ERROR 2153 X00000869
MQRC_RECS_PRESENT_ERROR 2154 X0000086A
MQRC_OBJECT_RECORDS_ERROR 2155 X0000086B
MQRC_RESPONSE_RECORDS_ERROR 2156 X0000086C
MQRC_ASID_MISMATCH 2157 X0000086D
MQRC_PMO_RECORD_FLAGS_ERROR 2158 X0000086E
MQRC_PUT_MSG_RECORDS_ERROR 2159 X0000086F
MQRC_CONN_ID_IN_USE 2160 X00000870
MQRC_Q_MGR_QUIESCING 2161 X00000871
MQRC_Q_MGR_STOPPING 2162 X00000872
Instructor Guide
V2.0
Uempty
MQRC_DUPLICATE_RECOV_COORD 2163 X00000873
MQRC_PMO_ERROR 2173 X0000087D
MQRC_API_EXIT_LOAD_ERROR 2183 X00000887
MQRC_REMOTE_Q_NAME_ERROR 2184 X00000888
MQRC_INCONSISTENT_PERSISTENCE 2185 X00000889
MQRC_GMO_ERROR 2186 X0000088A
MQRC_STOPPED_BY_CLUSTER_EXIT 2188 X0000088C
MQRC_CLUSTER_RESOLUTION_ERROR 2189 X0000088D
MQRC_CONVERTED_STRING_TOO_BIG 2190 X0000088E
MQRC_TMC_ERROR 2191 X0000089f
MQRC_PAGESET_FULL 2192 X00000890
MQRC_PAGESET_ERROR 2193 X00000891
MQRC_NAME_NOT_VALID_FOR_TYPE 2194 X00000892
MQRC_UNEXPECTED_ERROR 2195 X00000893
MQRC_UNKNOWN_XMIT_Q 2196 X00000894
MQRC_UNKNOWN_DEF_XMIT_Q 2197 X00000895
MQRC_DEF_XMIT_Q_TYPE_ERROR 2198 X00000896
MQRC_DEF_XMIT_Q_USAGE_ERROR 2199 X00000897
MQRC_NAME_IN_USE 2201 X00000899
MQRC_CONNECTION_QUIESCING 2202 X0000089A
MQRC_CONNECTION_STOPPING 2203 X0000089B
MQRC_ADAPTER_NOT_AVAILABLE 2204 X0000089C
MQRC_MSG_ID_ERROR 2206 X0000089E
MQRC_CORREL_ID_ERROR 2207 X0000089F
MQRC_FILE_SYSTEM_ERROR 2208 X000008A0
MQRC_NO_MSG_LOCKED 2209 X000008A1
MQRC_FILE_NOT_AUDITED 2216 X000008A8
Instructor Guide
MQRC_CONNECTION_NOT_AUTHORIZED 2217 X000008A9
MQRC_MSG_TOO_BIG_FOR_CHANNEL 2218 X000008AA
MQRC_CALL_IN_PROGRESS 2219 X000008AB
MQRC_RMH_ERROR 2220 X000008AC
MQRC_Q_MGR_ACTIVE 2222 X000008AE
MQRC_Q_MGR_NOT_ACTIVE 2223 X000008AF
MQRC_Q_DEPTH_HIGH 2224 X000008B0
MQRC_Q_DEPTH_LOW 2225 X000008B1
MQRC_Q_SERVICE_INTERVAL_HIGH 2226 X000008B2
MQRC_Q_SERVICE_INTERVAL_OK 2227 X000008B3
MQRC_UNIT_OF_WORK_NOT_STARTED 2232 X000008B8
MQRC_CHANNEL_AUTO_DEF_OK 2233 X000008B9
MQRC_CHANNEL_AUTO_DEF_ERROR 2234 X000008BA
MQRC_CFH_ERROR 2235 X000008BB
MQRC_CFIL_ERROR 2236 X000008BC
MQRC_CFIN_ERROR 2237 X000008BD
MQRC_CFSL_ERROR 2238 X000008BE
MQRC_CFST_ERROR 2239 X000008BF
MQRC_INCOMPLETE_GROUP 2241 X000008C1
MQRC_INCOMPLETE_MSG 2242 X000008C2
MQRC_INCONSISTENT_CCSIDS 2243 X000008C3
MQRC_INCONSISTENT_ENCODINGS 2244 X000008C4
MQRC_INCONSISTENT_UOW 2245 X000008C5
MQRC_INVALID_MSG_UNDER_CURSOR 2246 X000008C6
MQRC_MATCH_OPTIONS_ERROR 2247 X000008C7
MQRC_MDE_ERROR 2248 X000008C8
MQRC_MSG_FLAGS_ERROR 2249 X000008C9
Instructor Guide
V2.0
Uempty
MQRC_MSG_SEQ_NUMBER_ERROR 2250 X000008CA
MQRC_OFFSET_ERROR 2251 X000008CB
MQRC_ORIGINAL_LENGTH_ERROR 2252 X000008CC
MQRC_SEGMENT_LENGTH_ZERO 2253 X000008CD
MQRC_UOW_NOT_AVAILABLE 2255 X000008CF
MQRC_WRONG_GMO_VERSION 2256 X000008D0
MQRC_WRONG_MD_VERSION 2257 X000008D1
MQRC_GROUP_ID_ERROR 2258 X000008D2
MQRC_INCONSISTENT_BROWSE 2259 X000008D3
MQRC_XQH_ERROR 2260 X000008D4
MQRC_SRC_ENV_ERROR 2261 X000008D5
MQRC_SRC_NAME_ERROR 2262 X000008D6
MQRC_DEST_ENV_ERROR 2263 X000008D7
MQRC_DEST_NAME_ERROR 2264 X000008D8
MQRC_TM_ERROR 2265 X000008D9
MQRC_CLUSTER_EXIT_ERROR 2266 X000008DA
MQRC_CLUSTER_EXIT_LOAD_ERROR 2267 X000008DB
MQRC_CLUSTER_PUT_INHIBITED 2268 X000008DC
MQRC_NO_DESTINATIONS_AVAILABLE 2270 X000008DE
MQRC_CONNECTION_ERROR 2273 X000008E1
MQRC_OPTION_ENVIRONMENT_ERROR 2274 X000008E2
MQRC_CD_ERROR 2275 X000008E5
MQRC_CLIENT_CONN_ERROR 2278 X000008E6
MQRC_CHANNEL_STOPPED_BY_USER 2279 X000008E7
MQRC_HCONFIG_ERROR 2280 X000008E8
MQRC_FUNCTION_ERROR 2281 X000008E9
MQRC_CHANNEL_STARTED 2282 X000008EA
Instructor Guide
MQRC_CHANNEL_STOPPED 2283 X000008EB
MQRC_CHANNEL_CONV_ERROR 2284 X000008EC
MQRC_SERVICE_NOT_AVAILABLE 2285 X000008ED
MQRC_INITIALIZATION_FAILED 2286 X000008EE
MQRC_TERMINATION_FAILED 2287 X000008EF
MQRC_UNKNOWN_Q_NAME 2288 X000008F0
MQRC_SERVICE_ERROR 2289 X000008F1
MQRC_Q_ALREADY_EXISTS 2290 X000008F2
MQRC_USER_ID_NOT_AVAILABLE 2291 X000008F3
MQRC_UNKNOWN_ENTITY 2292 X000008F4
MQRC_UNKNOWN_AUTH_ENTITY 2293 X000008F5
MQRC_UNKNOWN_REF_OBJECT 2294 X000008F6
MQRC_CHANNEL_ACTIVATED 2295 X000008F7
MQRC_CHANNEL_NOT_ACTIVATED 2296 X000008F8
MQRC_UOW_CANCELED 2297 X000008F9
MQRC_SELECTOR_TYPE_ERROR 2299 X000008FB
MQRC_COMMAND_TYPE_ERROR 2300 X000008FC
MQRC_MULTIPLE_INSTANCE_ERROR 2301 X000008FD
MQRC_SYSTEM_ITEM_NOT_ALTERABLE 2302 X000008FE
MQRC_BAG_CONVERSION_ERROR 2303 X000008FF
MQRC_SELECTOR_OUT_OF_RANGE 2304 X00000900
MQRC_SELECTOR_NOT_UNIQUE 2305 X00000901
MQRC_INDEX_NOT_PRESENT 2306 X00000902
MQRC_STRING_ERROR 2307 X00000903
MQRC_ENCODING_NOT_SUPPORTED 2308 X00000904
MQRC_SELECTOR_NOT_PRESENT 2309 X00000905
MQRC_OUT_SELECTOR_ERROR 2310 X00000906
Instructor Guide
V2.0
Uempty
MQRC_STRING_TRUNCATED 2311 X00000907
MQRC_SELECTOR_WRONG_TYPE 2312 X00000908
MQRC_INCONSISTENT_ITEM_TYPE 2313 X00000909
MQRC_INDEX_ERROR 2314 X0000090A
MQRC_SYSTEM_BAG_NOT_ALTERABLE 2315 X0000090B
MQRC_ITEM_COUNT_ERROR 2316 X0000090C
MQRC_FORMAT_NOT_SUPPORTED 2317 X0000090D
MQRC_SELECTOR_NOT_SUPPORTED 2318 X0000090E
MQRC_ITEM_VALUE_ERROR 2319 X0000090F
MQRC_HBAG_ERROR 2320 X00000910
MQRC_PARAMETER_MISSING 2321 X00000911
MQRC_CMD_SERVER_NOT_AVAILABLE 2322 X00000912
MQRC_STRING_LENGTH_ERROR 2323 X00000913
MQRC_INQUIRY_COMMAND_ERROR 2324 X00000914
MQRC_NESTED_BAG_NOT_SUPPORTED 2325 X00000915
MQRC_BAG_WRONG_TYPE 2326 X00000916
MQRC_ITEM_TYPE_ERROR 2327 X00000917
MQRC_SYSTEM_BAG_NOT_DELETABLE 2328 X00000918
MQRC_SYSTEM_ITEM_NOT_DELETABLE 2329 X00000919
MQRC_CODED_CHAR_SET_ID_ERROR 2330 X0000091A
MQRC_MSG_TOKEN_ERROR 2331 X0000091B
MQRC_MISSING_WIH 2332 X0000091C
MQRC_WIH_ERROR 2333 X0000091D
Instructor Guide
Instructor Guide
Copyright IBM Corp. 1996, 2003 Appendix C. Bibliography C-1
V2.0
Uempty
Appendix C. Bibliography
WebSphere MQ cross-platform publications
WebSphere MQ Bibliography and Glossary
The WebSphere MQ Bibliography and Glossary book, SC34-6113, this book provides
WebSphere MQ cross-platform publications that are available. We show the title and order
number, followed by a brief description of the content of the publication and the intended
audience, to help you decide whether you need that publication. We also define the
members of the WebSphere MQ and MQSeries family to which the publication applies.
An Introduction to Messaging and Queuing
MQSeries: An Introduction to Messaging and Queuing, GC33-0805, describes briefly what
MQSeries is, how it works, and how it can solve some classic interoperability problems.
This book is intended for a more technical audience than the MQSeries Brochure.
MQSeries Planning Guide
The MQSeries Planning Guide, GC33-1349, describes some key MQSeries concepts,
identifies items that need to be considered before MQSeries is installed, including storage
requirements, backup and recovery, security, and migration from earlier releases, and
specifies hardware and software requirements for every MQSeries platform.
MQSeries Release Guide V5.2
The MQSeries Release Guide V5.2, GC34-5761, introduces all the new functions in V5.2.
These are additions to the cross-product books and should be used in conjunction with
them.
This book is for users of any of the following products:
AIX
HP-UX
iSeries
Linux
Sun Solaris
Windows
WebSphere MQ Intercommunication
The WebSphere MQ Intercommunication book, SC34-6059, defines the concepts of
distributed queuing and explains how to set up a distributed queuing network in a variety of
MQSeries environments. In particular, it demonstrates how to (1) configure
communications to and from a representative sample of MQSeries products, (2) create
required MQSeries objects, and (3) create and configure MQSeries channels. and (4)
establish MQSeries client/server connections. The use of channel exits is also described.
Instructor Guide
C-2 WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
WebSphere MQ Clients
The WebSphere MQ Clients book, GC34-6058, describes how to install, configure, use,
and manage MQSeries client systems
WebSphere MQ System Administration Guide
The WebSphere MQ System Administration Guide book, SC34-6068, supports day-to-day
management of local and remote MQSeries objects. It includes topics such as security,
recovery and restart, transactional support, problem determination, the dead-letter queue
handler, and the MQSeries links for Lotus Notes. It also includes the syntax of the
MQSeries control commands.
The book applies to the following WebSphere MQ products only:
WebSphere MQ for AIX V5.3
WebSphere MQ for HP-UX V5.3
WebSphere MQ for Linux for Intel and Linus for zSeries V5.3
WebSphere MQ for Sun Solaris V5.3
WebSphere MQ for Windows V5.3
WebSphere MQ Script (MQSC) Command Reference
The WebSphere MQ Script (MQSC) Command Reference, SC34-6055, contains the
syntax of the MQSC commands, which are used by MQSeries system operators and
administrators to manage MQSeries objects.
This book applies to the following MQSC commands for these WebSphere MQ products
only:
Compaq NSK
Compaq Open VMS
iSeries
OS/2 Warp
Unix Operating System
Windows
z/OS
WebSphere MQ Programmable Command Formats and Administration Interface
The WebSphere MQ Programmable Command Formats and Administration Interface book,
SC34-6060, provides both reference and guidance information for writing programs using
Programmable Command Formats (PCFs), and the administrative interface (MQAI) for
WebSphere MQ. Advanced topics include, indexing, data conversion, and the message
descriptor. The new SSL parameters are introduced.
WebSphere MQ Messages
The WebSphere MQ Messages, GC34-6057, which describes "AMQ" messages issued by
WebSphere MQ, applies to these WebSphere MQ products only:
Instructor Guide
V2.0
Uempty
WebSphere MQ for Linux for Intel V5.3
WebSphere MQ for Linux for zSeries V5.3
WebSphere MQ Application Programming Guide
The WebSphere MQ Application Programming Guide, SC34-6064, provides guidance
information for users of the message queue interface (MQI). It describes how to design,
write, and build an MQSeries application. It also includes full descriptions of the sample
programs supplied with MQSeries.
This book applies to the following WebSphere MQ V5.3 products:
WebSphere MQ for AIX
WebSphere MQ for HP-UX
WebSphere MQ for Linux for Intel and zSeries
WebSphere MQ for Solaris
Some information applies to these products:
MQSeries for AT&T GIS UNIX, V2.2
MQSeries for Compaq NonStop Kernel, V5.1
MQSeries for Compaq Open VMS Alpha, V5.1
MQSeries for Compaq Tru64 UNIX, V5.1
MQSeries for OS/2 Warp, V5.1
MQSeries for SINIX and DC/OSx, V2.2
MQSeries for Sun Solaris, Intel Platform Edition, V5.1
MQSeries for VSE/ESA, V2.1.1
WebSphere MQ Application Programming Reference
The WebSphere MQ Application Programming Reference, SC34-6062 provides
comprehensive reference information for users of the MQI. It includes: data-type
descriptions; MQI call syntax; attributes of MQSeries objects; return codes; constants; and
code-page conversion tables.
This book applies to the following WebSphere MQ products:
WebSphere MQ for AIX, V5.3
WebSphere MQ for iSeries, V5.3
WebSphere MQ for Linux for zSeries, V5.3
WebSphere MQ for Solaris, V5.3 (SPARC and Intel Platform Editions)
WebSphere MQ for Windows, V5.3
WebSphere MQ for z/OS, V5.3
MQSeries for AT&T GIS (NCR) UNIX V2.2.1 1
Instructor Guide
MQSeries for Compaq NonStop Kernel V5.1
MQSeries for Compaq OpenVMS Alpha V5.1
MQSeries for OS/2 Warp V5.1
MQSeries for SINIX and DC/OSx V2.2.1
WebSphere MQ Using C++
The WebSphere MQ Using C++, SC34-6067, provides both guidance and reference
information for users of the WebSphere MQ C ++ programming-language binding to the
MQI.
This book applies to the following WebSphere MQ products only:
WebSphere MQ for Linux for Intel and zSeries, V5.3
WebSphere MQ for Solaris, V5.3
Websphere MQ Using Java
The Websphere MQ Using Java, SC34-6066, applies to IBM WebSphere MQ classes
for Java Version 5.3 and WebSphere MQ classes for Java Message Service Version 5.3.
Also included are the integration with WebSphere MQ product, JMS Postcard, and Secure
Socket Layer (SSL) support.
WebSphere MQ Application Messaging Interface
The WebSphere MQ Application Messaging Interface, SC34-6065, applies to IBM
WebSphere MQ Application Messaging Interface Version 1.2.2. This book provides you
with information on the use the Application Messaging Interface to send and receive
WebSphere MQ messages, including publish/subscribe and point-to-point applications.
The interfaces discussed are, C, C++, COBOL, and JAVA.
WebSphere MQ Queue Managers Clusters
The WebSphere MQ Queue Managers Clusters, SC34-6061, book describes how to create
and use clusters of WebSphere MQ queue managers. It explains the concepts and
terminology of clustering and shows how you can benefit by taking advantage of clustering.
It details changes to the message queue interface (MQI), and summarizes the syntax of
new and changed WebSphere MQ commands. It shows a number of examples of tasks you
can perform to set up and maintain clusters of queue managers.
This book applies to the following WebSphere MQ V5.3 products:
WebSphere MQ for Linux for Intel
Instructor Guide
V2.0
Uempty
WebSphere MQ for Linux for zSeries
WebSphere MQ for Solaris
Unless otherwise stated, the information also applies to these products:
MQSeries for OS/2 Warp, V5.1
MQSeries for Compaq Tru64 UNIX, V5.1
WebSphere MQ Security
The WebSphere MQ Security book, SC34-6079, describes the factors you need to
consider when planning to meet your security requirements in a WebSphere MQ
environment. It provides the background information for you to evaluate the security
provisions offered by WebSphere MQ and related products. This book also describes the
Secure Sockets Layer (SSL) support in WebSphere MQ.
This book applies to the following IBM WebSphere MQ products:
WebSphere MQ for Linux for zSeries, V5.3
WebSphere MQ for Solaris, V5.3
MQSeries Event Monitoring
MQSeries Event Monitoring, SC34-5760.
MQSeries Application Messaging Interface
MQSeries Application Messaging Interface, SC34-5604.
WebSphere MQ and MQSeries platform-specific publication
WebSphere MQ for AIX V5.3 Quick Beginnings, GC34-6076
WebSphere MQ for HP-UX V5.2 Quick Beginnings, GC34-6077
WebSphere MQ for iSeries V5.3 Quick Beginnings, GC34-6072
WebSphere MQ for iSeries V5.3 System Administration Guide, SC34-6070
Instructor Guide
WebSphere MQ for iSeries V5.3 Application Programming Reference (ILE RPG),
SC34-6071
WebSphere MQ for Linux
WebSphere MQ for Linux V5.3 Quick Beginnings, GC34-6078
WebSphere MQ for Sun Solaris
WebSphere MQ Solaris V5.3 Quick Beginnings, GC34-6075
WebSphere MQ for Windows V5.3 Quick Beginnings, GC34-6073
WebSphere MQ for Windows, Using the Component Object Model Interface,
SC34-6134
WebSphere MQ for z/OS V5.3 Program Directory, GI10-2548
WebSphere MQ for z/OS Concepts and Planning Guide V5.3, GC34-6051
WebSphere MQ for z/OS System Setup Guide V5.3, SC34-6052
WebSphere MQ for z/OS System Administration Guide V5.3, SC34-6053
WebSphere MQ for z/OS Problem Determination Guide V5.3, GC34-6054
WebSphere MQ for z/OS Messages and Codes V5.3, GC34-6056
MQSeries for AT&T GIS UNIX
MQSeries for AT&T GIS UNIX Version 2.2 System Management Guide, SC33-1642
MQSeries for Compaq NSK
MQSeries for Compaq NSK V5.1 Quick Beginnings, GC34-5887
MQSeries for Compaq NSK V5.1 System Administration Guide, SC34-5886
MQSeries for Compaq OpenVMS V5.1 Quick Beginnings, GC34-5885
MQSeries for Compaq OpenVMS V5.1 System Administration Guide, SC34-5884
MQSeries for Compaq Tru64 UNIX
MQSeries for Compaq Tru64 UNIX, V5.1 Quick Beginnings, GC34-5684
MQSeries for Digital OpenVMS
MQSeries for Digital OpenVMS Version 2.2 System Management Guide, GC33-1791
MQSeries for OS/2 Warp V5.1 Quick Beginnings, GC33-1868
MQSeries link for R/3
MQSeries link for R/3 Version 1.2 Users Guide, GC33-1934
Instructor Guide
V2.0
Uempty
MQSeries for SINIX and DC/OSx
MQSeries for SINIX and DC/OSx Version 2.2 System Management Guide, GC33-1768
MQSeries for Tandem NonStop Kernel Version 2.2.0.1 System Management Guide,
GC33-1893
MQSeries for VSE/ESA
MQSeries for VSE/ESA Version 2 Release 1.1 System Management Guide,
GC34-5364
MQSeries LotusScript Extension., SC34-5404
MQSeries Level 1 product publications
MQSeries: Concepts and Architecture, GC33-1141
MQSeries Version 1 Products for UNIX Operating Systems Messages and Codes,
SC33-1754
MQSeries for UnixWare Version 1.4.1 Users Guide, SC33-1379
Softcopy books
Most of the MQSeries books are supplied in both hardcopy and softcopy formats.
BookManager format
The MQSeries library is supplied in IBM BookManager format on a variety of online library
collection kits, including the Transaction Processing and Data collection kit, SK2T-0730.
You can view the softcopy books in IBM BookManager format using the following IBM
licensed programs:
BookManager READ/2
BookManager READ/6000
BookManager READ/DOS
BookManager READ/MVS
BookManager READ/VM
HTML format
The WebSphere MQ documentation is provided in HTML format with these WebSphere
MQ products:
WebSphere MQ for iSeries V5.3
WebSphere MQ for Linux V5.3
WebSphere MQ for z/OS V5.3
Instructor Guide
MQSeries link for R/3 V1.2
The WebSphere MQ books are also available from the WebSphere MQ product family
home page at http://www.software.ibm.com/ts/mqseries/support
Portable Document Format (PDF)
PDF files can be viewed and printed using the Adobe Acrobat Reader.
If you need to obtain the Adobe Acrobat Reader, or would like up-to-date information about
the platforms on which the Acrobat Reader is supported, visit the Adobe Systems Inc. Web
site at:
http://www.adobe.com/
PDF versions of relevant WebSphere MQ books are supplied with these WebSphere MQ
products:
WebSphere MQ for iSeries V5.3
WebSphere MQ for Linux V5.3
WebSphere MQ for z/OS V5.3
MQSeries link for R/3 V1.2
PDF versions of all current WebSphere MQ books are also available from the WebSphere
MQ product family Web site at:
http://www.software.ibm.com/ts/mqseries/support
PostScript format
The WebSphere MQ library is provided in PostScript (.PS) format with many WebSphere
MQ Version 2 products. Books in PostScript format can be printed or on a PostScript printer
or viewed with a suitable viewer.
MQSeries information available on the Internet
WebSphere MQ URL
The URL of the WebSphere MQ product family home page is:
http://www.software.ibm.com/ts/mqseries/support
Instructor Guide
Copyright IBM Corp. 1996, 2003 Appendix D. Glossary of terms and abbreviations D-1
V2.0
Uempty
Appendix D. Glossary of terms and abbreviations
This glossary defines WebSphere MQ terms and abbreviations used in this book. If you do
not find the term you are looking for, refer to the Index or the IBM Dictionary of Computing,
New York: McGraw-Hill, 1994.
This glossary includes terms and definitions from the American National Dictionary for
Information Systems, ANSI X3.172-1990, copyright 1990 by the American National
Standards Institute (ANSI). Copies may be purchased from the American National
Standards Institute, 11 West 42 Street, New York, New York 10036. Definitions are
identified by the symbol (A) after the definition.
The ANSI/EIA Standard 440-A: Fiber Optic Terminology. Copies may be purchased
from the Electronic Industries Association, 2001 Pennsylvania Avenue, N.W.,
Washington DC 20006. Definitions are identified by the symbol (E) after the definition.
The Information Technology Vocabulary, developed by Subcommittee 1, Joint Technical
Committee 1, of the International Organization for Standardization and the International
Electrotechnical Commission (ISO/IEC JTC1/SC1). Definitions of published parts of this
vocabulary are identified by the symbol (I) after the definition; definitions from draft
international standards, committee drafts, and working papers being developed by
ISO/IEC JTC1/SC1 are identified by the symbol (T) after the definition, indicating that
final agreement has not yet been reached among the participating National Bodies of
SC1.
A
abend reason code. A 4-byte hexadecimal code that uniquely identifies a problem with
WebSphere MQ for z/OS. A complete list of WebSphere MQ for z/OS abend reason codes
and their explanations is contained in the WebSphere MQ for z/OS Messages and Codes
manual.
abstract class. A class that can only be instantiated as a derivation.
active log. See recovery log.
adapter. An interface between WebSphere MQ for z/OS and TSO, IMS, CICS, or batch
address spaces. An adapter is an attachment facility that enables applications to access
WebSphere MQ services.
address space. The area of virtual storage available for a particular job.
address space identifier (ASID). A unique, system-assigned identifier for an address
space.
Instructor Guide
D-2 WebSphere MQ System Administration I Copyright IBM Corp. 1996, 2003
administration bag. In the MQAI, a type of data bag that is created for administering
WebSphere MQ by implying that it can change the order of data items, create lists, and
check selectors within a message.
administrator commands. WebSphere MQ commands used to manage WebSphere MQ
objects, such as queues, processes, and namelist.
Advanced Program-to-Program Communication (APPC). The general facility
characterizing the LU 6.2 architecture and its various implementations in products.
affinity. An association between objects that have some relationship or dependency upon
each other.
alert. A message sent to a management services focal point in a network to identify a
problem or an impending problem.
alert monitor. In WebSphere MQ for z/OS, a component of the CICS adapter that
handles unscheduled events occurring as a result of connection requests to WebSphere
MQ for z/OS.
alias queue object. An WebSphere MQ object, the name of which is an alias for a base
queue defined to the local queue manager. When an applicator or a queue manager uses
an alias queue, the alias name is resolved and the requested operation is performed on the
associated base queue.
allied address space. See ally.
ally. An OS/390 address space that is connected to WebSphere MQ for z/OS.
alternate user security. A security feature in which the authority of one user ID can be
used by another user ID; for example, to open an WebSphere MQ object.
APAR. Authorized program analysis report.
APC. Advanced Program Communication.
APPC. Advanced Program-to-Program Communication.
application-defined format. In message queuing, application data in a message, which
has a meaning defined by the user application. Contrast with built-in format.
application environment. The software facilities that are accessible by an application
program. On the z/OS platform, CICS and IMS are examples of application environments.
application log. In Windows NT, a log that records significant application events.
application queue. A queue used by an application.
archive log. See recovery log.
ARM. Automatic Restart Management
ASID. Address space identifier.
asynchronous messaging. A method of communication between programs in which
programs place messages on message queues. With asynchronous messaging, the
Instructor Guide
V2.0
Uempty
sending program proceeds with its own processing without waiting for a reply to its
message. Contrast with synchronous messaging.
attribute. One of a set of properties that defines the characteristics of an WebSphere MQ
object.
attribute. A property of an object or class, which can be distinguished distinctly from any
other properties. Attributes often describe state information.
authorization checks. Security checks that are performed when a user tries to issue
administration commands against an object, for example to open a queue or connect to a
queue manager.
authorization file. In WebSphere MQ on UNIX systems, a file that provides security
definitions for an object, a class of objects, or all classes of objects.
authorization service. In WebSphere MQ on UNIX systems, MQSeries for OS/2 Warp,
and WebSphere MQ for Windows, a service that provides authority checking of commands
and MQI calls for the user identifier associated with the command or call.
authorized program analysis report (APAR). A report of a problem caused by a
suspected defect in a current, unaltered release of a program.
Automatic Restart Management (ARM). An recovery function that can improve the
availability of specific batch jobs or started tasks, and therefore result in faster resumption
of productive work.
B
backout. An operation that reverses all the changes made during the current unit of
recovery or unit of work. After the operation is complete, a new unit of recovery or unit of
work begins. Contrast with commit.
bag. See data bag.
basic mapping support (BMS). An interface between CICS and application programs that
formats input and output display data and routes multiple-page output messages without
regard for control characters used by various terminals.
behavior. The functionality embodied within a method.
BMS. Basic mapping support.
bootstrap data set (BSDS). A VSAM data set that contains:
An inventory of all active and archived log data sets known to WebSphere MQ for z/OS
A wrap-around inventory of all recent WebSphere MQ for z/OS activity
The BSDS is required if the WebSphere MQ for z/OS subsystem has to be restarted.
browse. In message queuing, to use the MQGET call to copy a message without
removing it from the queue. See also get.
Instructor Guide
browse cursor. In message queuing, an indicator used when browsing a queue to identify
the message that is next in sequence.
BSDS. Bootstrap data set.
buffer pool. An area of main storage used for WebSphere MQ for z/OS queues,
messages, and object definitions. See also page set.
built-in format. In message queuing, application data in a message, which has a meaning
defined by the queue manager. Synonymous with in-built format. Contrast with
application-defined format.
C
call back. In WebSphere MQ, a requester message channel initiates a transfer from a
sender channel by first calling the sender, then closing down and awaiting a call back.
CCF. Channel control function.
CCSID. Coded character set identifier.
CDF. Channel definition file.
channel. See message channel.
channel control function (CCF). In WebSphere MQ, a program to move messages from
a transmission queue to a communication link, and from a communication like to a local
queue, together with an operator panel interface to allow the setup and control of channels.
channel definition file (CDF). In WebSphere MQ, a file containing communication
channel definitions that associate transmission queues with communication links.
channel event. An event indicating that a channel instance has become available or
unavailable. Channel events are generated on the queue managers at both ends of the
channel.
channel exit program. A user-written program that can be entered from one of a defined
number of places during channel operation.
channel initiator. A component of WebSphere MQ distributed queuing, which monitors the
initiation queue to see when triggering criteria have been met and then starts the sender
channel.
channel listener. A component of WebSphere MQ distributed queuing, which monitors the
network for a startup request and then starts the receiving channel.
checkpoint. (1) A time when significant information is written on the log. Contrast with
syncpoint. (2) In WebSphere MQ on UNIX systems, the point in time when a data record
described in the log is the same as the data record in the queue. Checkpoints are
generated automatically and are used during the system restart process.
CI. Control interval.
CICS transaction. In CICS, a unit of application processing, usually comprising one or
more units of work.
Instructor Guide
V2.0
Uempty
circular logging. In WebSphere MQ on UNIX systems, MQSeries for OS/2 Warp, and
WebSphere MQ for Windows, the process of keeping all restart data in a ring of log files.
Logging fills the first file in the ring and then moves on to the next, until all the files are full.
At this point, logging goes back to the first file in the ring and starts again, if the space has
been freed or is no longer needed. Circular logging is used during restart recovery, using
the log to roll back transactions that were in progress when the system stopped. Contrast
with linear logging.
CL. Control Language.
class. An abstract model of behavior; a collection of methods. A class typically provides
some unique behavior, in addition to other, common, behavior. The distinction between
unique and common behavior is effected using either inheritance, or multiple interfaces.
class hierarchy. Classes related by inheritance.
class library. A bundled collection of classes, usually related.
client. A run-time component that provides access to queuing services on a server for
local user applications. The queues used by the applications reside on the server. See also
WebSphere MQ client.
client application. An application, running on a workstation and linked to a client, that
gives the application access to queuing services on a server.
client connection channel type. The type of MQI channel definition associated with an
WebSphere MQ client. See also server connection channel type.
CLUSRCVR. Cluster-receiver channel definition.
CLUSSDR. Cluster-sender channel definition.
cluster. A network of queue managers that are logically associated in some way.
cluster queue. A queue that is hosted by a cluster queue manager and made available to
other queue managers in the cluster.
cluster queue manager. A queue manager that is a member of a cluster. A queue
manager may be a member of more than one cluster.
cluster-receiver channel (CLUSRCVR). A channel on which a cluster queue manager
can receive messages from other queue managers in the cluster and cluster information
from the repository queue managers.
cluster-sender channel (CLUSSDR). A channel on which a cluster queue manager can
send messages to other queue managers in the cluster and cluster information to the
repository queue managers.
cluster transmission queue. A transmission queue that transmits all messages from a
queue manager to any other queue manager that is in the same cluster. The queue is
called SYSTEM.CLUSTER.TRANSMIT.QUEUE.
coded character set identifier (CCSID). The name of a coded set of characters and their
code point assignments.
Instructor Guide
command. In WebSphere MQ, an administration instruction that can be carried out by the
queue manager.
command bag. In the MQAI, a type of bag that is created for administering WebSphere
MQ objects, but cannot change the order of data items nor create lists within a message.
command prefix (CPF). In WebSphere MQ for z/OS, a character string that identifies the
queue manager to which WebSphere MQ for z/OS commands are directed, and from which
WebSphere MQ for z/OS operator messages are received.
command processor. The WebSphere MQ component that processes commands.
command server. The WebSphere MQ component that reads commands from the
system-command input queue, verifies them, and passes valid commands to the command
processor.
commit. An operation that applies all the changes made during the current unit of recovery
or unit of work. After the operation is complete, a new unit of recovery or unit of work
begins. Contrast with backout.
Common Run-Time Environment (CRE). A set of services that enable system and
application programmers to write mixed-language programs. These shared, run-time
services can be used by C, COBOL85, FORTRAN, Pascal, and TAL programs.
completion code. A return code indicating how an MQI call has ended.
configuration file. In WebSphere MQ on UNIX systems, MQSeries for OS/2 Warp, and
WebSphere MQ for Windows, a file that contains configuration information related to, for
example, logs, communications or installable services. Synonymous with .ini file. See also
stanza.
connect. To provide a queue manager connection handle, which an application uses on
subsequent MQI calls. The connection is made either by the MQCONN call, or
automatically by the MQOPEN call.
connection handle. The identifier or token by which a program accesses the queue
manager to which it is connected.
constructor. A special method used to initialize an object.
context. Information about the origin of a message.
context security. In WebSphere MQ, a method of allowing security to be handled such
that messages are obliged to carry details of their origins in the message descriptor.
control command. In WebSphere MQ on UNIX systems, MQSeries for OS/2 Warp, and
WebSphere MQ for Windows, a command that can be entered interactively from the
operating system command line. Such a command requires only that the WebSphere MQ
product be installed; it does not require a special utility or program to run it.
control interval (CI). A fixed-length area of direct access storage in which VSAM stores
records and creates distributed free spaces. The control interval is the unit of information
that VSAM transmits to or from direct access storage.
Instructor Guide
V2.0
Uempty
Control Language (CL). In WebSphere MQ for iSeries, UNIX, Windows NT, and
MQSeries for OS/2 Warp, a language that can be used to issue commands, either at the
command line or by writing a CL program.
controlled shutdown. See quiesced shutdown.
CPF. Command prefix.
CRE. Common Run-Time Environment.
Cross Systems Coupling Facility (XCF). Provides the coupling services that allow
authorized programs in a multisystem environment to communicate with programs on the
same or different systems.
D
DAE. Dump analysis and elimination.
daemon. In UNIX systems, a program that runs unattended to perform a standard service.
Some daemons are triggered automatically to perform their tasks; others operate
periodically.
data bag. In the MQAI, a bag that allows you to handle properties (or parameters) of
objects.
data item. In the MQAI, an item contained within a data bag. This can be an integer item or
a character-string item, and a user item or a system item.
data conversion interface (DCI). The WebSphere MQ interface to which customer-or
vendor-written programs that convert application data between different machine
encodings and CCSIDs must conform. A part of the WebSphere MQ Framework.
datagram. The simplest message that WebSphere MQ Supports. This type of message
does not require a reply.
DCE. Distributed Computing Environment.
DCE principal. A user ID that uses the distributed computing environment.
DCI. Data conversion interface.
data-conversion service. A service that converts application data to the character set and
encoding that are required by applications on other platforms.
dead-letter queue (DLQ). A queue to which a queue manager or application sends
messages that it cannot deliver to their correct destination.
dead-letter queue handler. A WebSphere MQ-supplied utility that monitors a dead-letter
queue (DLQ) and processes messages on the queue in accordance with a user-written
rules table.
default object. A definition of an object (for example, a queue) with all attributes defined. If
a user defines an object but does not specify all possible attributes for that object, the
queue manager uses default attributes in place of any that were not specified.
Instructor Guide
deferred connection. A pending event that is activated when a CICS subsystem tries to
connect to WebSphere MQ for z/OS before WebSphere MQ for z/OS has been started.
dequeue. To remove a message from a queue. Contrast with enqueue.
derivation. The refinement or extension of one class from another.
desktop clients. A group of WebSphere MQ clients that run on the smaller platforms such
as DOS and Windows 3.1. Desktop clients are supplied with most of the WebSphere MQ
products; the members of the group may be different for the different products.
distributed application. In message queuing, a set of application programs that can each
be connected to a different queue manager, but that collectively constitute a single
application.
Distributed Computing Environment (DCE). Middleware that provides some basic
services, making the development of distributed applications easier. DCE is defined by the
Open Software Foundation (OSF).
distributed queue management (DQM). In message queuing, the setup and control of
message channels to queue managers on other systems.
distribution list. A list of queues to which a message can be put using a single MQPUT or
MQPUT1 statement.
DLQ. Dead-letter queue.
DQM. Distributed queue management.
dual logging. A method of recording WebSphere MQ for z/OS activity, where each change
is recorded on two data sets, that if a restart is necessary and one data set is unreadable,
the other can be used. Contrast with single logging.
dual mode. See dual logging.
dump analysis and elimination (DAE). An service that enables an installation to
suppress SVC dumps and ABEND SYSUDUMP dumps that are not needed because they
duplicate previously written dumps.
dynamic queue. A local queue created when a program opens a model queue object. See
also permanent dynamic queue and temporary dynamic queue.
E
encapsulation. The restriction whereby class behavior may only be observed using the
methods of that class.
enqueue. To put a message on a queue. Contrast with dequeue.
environment. See application environment.
environment variable. One of a series of variables that control the way your operating
system runs and what external devices it will recognize. You can define these variables in
your system profile or override them temporarily with command-line commands.
Instructor Guide
V2.0
Uempty
ESM. External security manager.
ESTAE. Extended specify task abnormal exit.
event. See channel event, instrumentation event, performance event, and queue manager
event.
event data. In an event message, the part of the message data that contains information
about the event (such as the queue manager name, and the application that gave rise to
the event). See also event header.
event header. In an event message, the part of the message data that identifies the event
type of the reason code for the event.
event log. See application log.
event message. Contains information (such as the category of event, the name of the
application that caused the event, and queue manager statistics) relating to the origin of an
instrumentation event in a network of WebSphere MQ system.
event queue. The queue onto which the queue manager puts an event message after it
detects an event. Each category of event (queue manager, performance, or channel event)
has its own event queue.
Event Viewer. A tool provided by Windows NT to examine and manage log files.
exclusive method. A method that is not intended to exhibit polymorphism; one with
specific effect.
extended specify task abnormal exit (ESTAE). A z/OS macro that provides recovery
capability and gives control to the specified exit routine for processing, diagnosing an
abend, or specifying a retry address.
external security manager (ESM). A security product that is invoked by the z/OS system
Authorization Facility. RACF is an example of an ESM.
F
FAP. Formats and Protocols.
FFST. First Failure Support Technology.
FIFO. First-in-first-out.
First Failure Support Technology (FFST). Used by WebSphere MQ for iSeries, UNIX,
Windows, and MQSeries for OS/2 Warp to detect and report software problems.
first-in-first-out (FIFO). A queuing technique in which the next item to be retrieved is the
item that has been in the queue for the longest time. (A)
forced shutdown. A type of shutdown of the CICS adapter where the adapter immediately
disconnects from WebSphere MQ for z/OS, regardless of the state of any currently active
tasks. Contrast with quiesced shutdown.
Instructor Guide
format. In message queuing, a term used to identify the nature of application data in a
message. See also built-in format and application-defined format.
Formats and Protocols (FAP). The WebSphere MQ FAPs define how queue managers
communicate with one another, and also how WebSphere MQ clients communicate with
server queue managers.
Framework. In WebSphere MQ, a collection of programming interfaces that allow
customers or vendors to write programs that extend or replace certain functions provided in
WebSphere MQ products. The interfaces are:
WebSphere MQ data conversion interface (DCI)
WebSphere MQ message channel interface (MCI)
WebSphere MQ name service interface (NSI)
WebSphere MQ security enabling interface (SEI)
WebSphere MQ trigger monitor interface (TMI)
friend class. A class that is regarded as being derived from another, while this is not the
case, for the purpose of accessing protected methods and instance data.
FRR. Functional recovery routine.
full repository. A complete set of information about every queue manager in a cluster. This
set of information is called the repository or sometimes the full repository and is held
usually by two of the queue managers in the cluster. Contrast with partial repository.
function. A classic function call such as is supported by the C programming language.
functional recovery routine (FRR). A z/OS recovery/termination manager facility that
enables a recovery routine to gain control in the event of a program interrupt.
G
GCPC. Generalized command preprocessor.
generalized command preprocessor (GCPC). An WebSphere MQ for z/OS component
that processes WebSphere MQ commands and runs them.
Generalized Trace Facility (GTF). A z/OS service program that records significant
system events, such as supervisor calls and start I/O operations, for the purpose of
problem determination.
get. In message queuing, to use the MQGET call to remove a message from a queue.
See also browse.
global trace. An WebSphere MQ for z/OS trace option where the trace data comes from
the entire WebSphere MQ for z/OS subsystem
GTF. Generalized Trace Facility.
Instructor Guide
V2.0
Uempty
H
handle. See connection handle and object handle.
hardened message. A message that is written to auxiliary (disk) storage so that the
message will not be lost in the event of a system failure.
See also persistent message.
heartbeat flow. A pulse that is passed from a sending MCA to a receiving MCA when there
are no messages to send. The pulse unblocks the receiving MCA, which otherwise, would
remain in a wait state until a message arrived or the disconnect interval expired.
heartbeat interval. The time, in seconds, that is to elapse between heartbeat flows.
I
ICE. Intersystem Communications Environment is a family of Tandem-based software
products that enables you to access a variety of applications on Tandem computers.
IFCID. A trace event number.
immediate shutdown. In WebSphere MQ, a shutdown of a queue manager that does not
wait for applications to disconnect. Current MQI calls are allowed to complete, but new MQI
calls fail after an immediate shutdown has been requested. Contrast with quiesced
shutdown and preemptive shutdown.
in-built format. See built-in format.
index. In the MQAI, a means of referencing data items.
in-doubt unit of recovery. In WebSphere MQ, the status of a unity of recovery for which a
syncpoint has been requested but not yet confirmed.
inheritance. The ability of a class to include the behavior of another through refinement
and extension; only refined and extended methods are defined in the derived class, thereby
preserving encapsulation.
.ini file. See configuration file.
initialization file. In MQSeries for AS/400, a file that contains two parameters; the TCP/IP
listener port number and the maximum number of channels that can be current at a time.
The file is called QMINI.
initialization input data sets. Data sets used by WebSphere MQ for z/OS when it starts
up.
initiation queue. A local queue on which the queue manager puts trigger messages.
input/output parameter. A parameter of an MQI call in which you supply information when
you make the call, and in which the queue manager changes the information when the call
completes or fails.
input parameter. A parameter of an MQI call in which you supply information when you
make the call.
Instructor Guide
insertion order. In the MQAI, the order that data items are placed into a data bag.
installable services. In WebSphere MQ on UNIX systems, MQSeries for OS/2 Warp, and
WebSphere MQ for Windows, additional functionality provides as independent
components. The installation of each component is optional: in-house or third-party
components can be used instead. See also authorization service, name service, and user
Jennifer service.
instance. An object.
instance data. State information associated with an object.
instrumentation event. A facility that can be used to monitor the operation of queue
managers in a network of WebSphere MQ systems. WebSphere MQ provides
instrumentation events for monitoring queue manager resource definitions, performance
conditions, and channel conditions. Instrumentation events can be used by a user-written
reporting mechanism in an administration application that displays the events to a system
operator. They also allow applications acting as agents for other administration networks to
monitor reports and create the appropriate alerts.
Interactive Problem Control System (IPCS). A component of z/OS that permits online
problem management, interactive problem diagnosis, online debugging for disk-resident
abend dumps, problem tracking, and problem reporting.
Interactive System Productivity Facility (ISPF). An IBM licensed program that serves as
a full-screen editor and dialog manager. It is used for writing application programs, and
provides a means of generating standard screen panels and interactive dialogues between
the application programmer and terminal user.
interface. An abstract model of behavior; a collection of functions or methods.
Internet Protocol (IP). A protocol used to route data from its source to its destination in an
Internet environment. This is the base layer, on which other protocol layers, such as TCP
and UDP are built.
Intersystem communication. In CICS, communication between separate systems by
means of SNA networking facilities or by means of the application-to-application facilities of
an SNA access method.
IP. Internet Protocol.
IPCS. Interactive Problem Control System.
ISC. Intersystem communication.
ISPF. Interactive System Productivity Facility.
L
linear logging. In WebSphere MQ on UNIX systems, MQSeries for OS2 Warp, and
WebSphere MQ for Windows, the process of keeping restart data in a sequence of files.
New files are added to the sequence as necessary. The space in which the data is written
is not reused until the queue manager is restarted. Contrast with circular logging.
Instructor Guide
V2.0
Uempty
listener. In WebSphere MQ distributed queuing, a program that monitors for incoming
network connections.
local definition. A WebSphere MQ object belonging to a local queue manager.
local definition of a remote queue. A WebSphere MQ object belonging to a local queue
manager. This object defines the attributes of a queue that is owned by another queue
manager. In addition, it is used for queue-manager aliasing and reply-to-queue aliasing.
locale. On UNIX systems, a subset of a user's environment that defines conventions for a
specific culture (such as time, numeric, or monetary formatting and character classification,
collation, or conversion). The queue manager CCSID is derived from the locale of the user
ID that created the queue manager.
local queue. A queue that belongs to the local queue manager. A local queue can contain
a list of messages waiting to be processed. Contrast with remote queue.
local queue manager. The queue manager to which a program is connected and that
provides message queuing services to the program. Queue managers to which a program
is not connected are called remote queue managers, even if they are running on the same
system as the program.
log. In WebSphere MQ, a file recording the work done by queue managers while they
receive, transmit, and deliver messages, to enable them to recover in the event of failure.
log control file. In WebSphere MQ on UNIX systems, MQSeries for OS/2 Warp, and
WebSphere MQ for Windows, the file containing information needed to monitor the use of
log files (for example, their size and location, and the name of the next available file).
log file. In WebSphere MQ on UNIX systems, MQSeries for OS/2 Warp, and WebSphere
MQ for Windows, a file in which all significant changes to the data controlled by a queue
manager are recorded. If the primary log files become full, WebSphere MQ allocates
secondary log files.
logical unit of work (LUW). See unit of work.
luname. The name of the logical unit on your workstation, that is the name of the software
that interfaces between your applications and the network.
LUWID. Logical unit of work identifier.
LU 6.2. A type of logical unit (LU) that supports general communication between programs
in a distributed processing environment.
M
machine check interrupt. An interruption that occurs as a result of an equipment
malfunction or error. A machine check interrupt can be either hardware recoverable,
software recoverable, or nonrecoverable.
marshalling. The serialization of data.
MCA. Message channel agent.
Instructor Guide
MCI. Message channel interface.
media image. In WebSphere MQ on UNIX systems, MQSeries for OS/2 Warp, and
WebSphere MQ for Windows, the sequence of log records that contain an image of an
object. The object can be re-created from this image.
message. In message queuing applications, a communication sent between programs.
See also persistent message and nonpersistent message.
message. In system programming, information intended for the terminal operator or
system administrator.
message channel. In distributed message queuing, a mechanism for moving messages
from one queue manager to another. A message channel comprises two message channel
agents (a sender at one end and a receiver at the other end) and a communication link.
Contrast with MQI channel.
message channel agent (MCA). A program that transmits prepared messages from a
transmission queue to a communication link, or from a communication link to a destination
queue. See also message queue interface.
message channel interface (MCI). The WebSphere MQ interface to which customer- or
vendor-written programs that transmit messages between an WebSphere MQ queue
manager and another messaging system must conform. A part of the WebSphere MQ
Framework.
message descriptor. Control information describing the message format and presentation
that is carried as part of an WebSphere MQ message. The format of the message
descriptor is defined by the MQMD structure.
message flow control. A distributed queue management task that involves setting up and
maintaining message routes between queue managers.
message format service (MFS). In IMS, and editing facility that allows application
programs to deal with simple logical messages, instead of device-dependent data, thus
simplifying the application development process. See message input descriptor and
message output descriptor.
message group. A group of logical messages. Logical grouping of messages allows
applications to group messages that are similar and to ensure the sequence of the
messages.
message input descriptor (MID). In IMS, the MFS control block that describes the format
of the data presented to the application program. Contrast with message output descriptor.
message output descriptor (MOD). In IMS, the MFS control block that describes the
format of the output data produced by the application program. Contrast with message
input descriptor.
message priority. In WebSphere MQ, an attribute of a message that can affect the order in
which messages on a queue are retrieved, and whether a trigger event is generated.
Instructor Guide
V2.0
Uempty
message queue. Synonym for queue.
message queue interface (MQI). The programming interface provided by the WebSphere
MQ queue managers. This programming interface allows application programs to access
message queuing services.
message queue management. The Message Queue Management (MQM) facility in
MQSeries for Tandem NSK V2.2 uses PCF command formats and control commands.
MQM runs as a PATHWAY SCOBOL requester under the Terminal Control Process (TCP)
and uses an MQM SERVERCLASS server, which invokes the C language API to perform
PCF commands. There is a separate instance of MQM for each queue manager configured
on a system, since each queue manager is controlled under its own PATHWAY
configuration. Consequently, an MQM is limited to the management of the queue manager
to which it belongs.
message queuing. A programming technique in which each program within an application
communicates with the other programs by putting messages on queues.
message-retry. An option available to an MCA that is unable to deliver a message. The
MCA can wait for a predefined amount of time and then try to send the message again.
message segment. One of a number of segments of a message that is too large either for
the application or for the queue manager to handle.
message sequence numbering. A programming technique in which messages are given
unique numbers during transmission over a communication link. This enables the receiving
process to check whether all messages are received, to place them in a queue in the
original order, and to discard duplicate messages.
messaging. See synchronous messaging and asynchronous messaging.
method. A means of invoking a particular behavior in an object or class.
MFS. Message format service.
model queue object. A set of queue attributes that act as a template when a program
creates a dynamic queue.
MQAI. MQSeries Administration Interface.
MQI. Message queue interface.
MQI channel. Connects an WebSphere MQ client to a queue manager on a server system,
and transfers only MQI calls and responses in a bidirectional manner. Contrast with
message channel.
MQSC. MQSeries commands.
WebSphere MQ. A family of IBM licensed programs that provides message queuing
services.
MQSeries Administration Interface (MQAI). A programming interface to WebSphere MQ.
Instructor Guide
WebSphere MQ client. Part of an WebSphere MQ product that can be installed on a
system without installing the full queue manager. The WebSphere MQ client accepts MQI
calls from applications and communicates with a queue manager on a server system.
WebSphere MQ commands (MQSC). Human-readable commands, uniform across all
platforms, that are used to manipulate WebSphere MQ objects. Contrast with
programmable command format (PCF).
Contrast with programmable command format (PCF).
WebSphere MQ server. An WebSphere MQ server is a queue manager that provides
queuing services to one or more clients. All the WebSphere MQ objects, for example
queues, exist only on the queue manager system, that is, on the MQI server machine. A
server can support normal local MQI applications as well.
multi-hop. To pass through one or more intermediate queue managers when there is no
direct communication link between a source queue manager and the target queue
manager.
N
namelist. An WebSphere MQ object that contains a list of names, for example, queue
names.
name service. In WebSphere MQ on UNIX systems, MQSeries for OS/2 Warp, and
WebSphere MQ for Windows, the facility that determines which queue manager owns a
specified queue.
name service interface (NSI). The WebSphere MQ interface to which customer- or
vendor-written programs that resolve queue-name ownership must conform. A part of the
WebSphere MQ Framework.
name transformation. In WebSphere MQ on UNIX systems, WebSphere MQ for OS/2
Warp, and WebSphere MQ for Windows, an internal process that changes a queue
manager name so that it is unique and valid for the system being used. Externally, the
queue manager name remains unchanged.
nested bag. In the MQAI, a system bag that is inserted into another data bag
nesting. In the MQAI, a means of grouping information returned from WebSphere MQ.
NetBIOS. Network Basic Input/Output System. An operating system interface for
application programs used on IBM personal computers that are attached to the IBM
Token-Ring Network.
New Technology File System (NTFS). A Windows NT recoverable file system that
provides security for files.
nonpersistent message. A message that does not survive a restart of the queue
manager. Contrast with persistent message.
NSI. Name service interface.
NTFS. New Technology File System.
Instructor Guide
V2.0
Uempty
null character. The character that is represented byX00.
O
OAM. Object authority manager.
object. In WebSphere MQ, an object is a queue manager, a queue, a process definition, a
channel, a namelist, or a storage class (z/OS only).
object. In C an object is an instance of a class.
object authority manager (OAM). In WebSphere MQ on UNIX systems and WebSphere
MQ for Windows, the default authorization service for command and object management.
The OAM can be replaced by, or run in combination with, a customer-supplied security
service.
object descriptor. A data structure that identifies a particular WebSphere MQ object.
Included in the descriptor are the name of the object and the object type.
object handle. The identifier or token by which a program accesses the WebSphere MQ
object with which it is working.
off-loading. In WebSphere MQ for z/OS, an automatic process whereby a queue
manager's active log is transferred to its archive log.
Open Transaction Manager Access (OTMA). A transaction-based, connectionless
client/server protocol. It functions as an interface for host-based communications servers
accessing IMS TM applications through the Cross Systems Coupling Facility (XCF). OTMA
is implemented in an sysplex environment. Therefore, the domain of OTMA is restricted to
the domain of XCF.
OTMA. Open Transaction Manager Access.
output log-buffer. In WebSphere MQ for z/OS, a buffer that holds recovery log records
before they are written to the archive log.
output parameter. A parameter of an MQI call in which the queue manager returns
information when the call completes or fails.
overloading. The existence of more than one flavor of method with the same name or
operator, but with different signatures, within a class; while the name or operator remains
the same, the method parameters differ, each signature requiring a separate
implementation. Such methods usually exhibit the same behavior, despite differences in
signature.
P
page set. A VSAM data set used when WebSphere MQ for z/OS moves data (for example,
queues and messages) from buffers in main storage to permanent backing storage
(DASD).
parent class. A class from which another is derived.
Instructor Guide
partial repository. A partial set of information about queue managers in a cluster. A partial
repository is maintained by all cluster queue managers that do not host a full repository.
PCF. Programmable command format.
PCF command. See programmable command format.
pending event. An unscheduled event that occurs as a result of a connect request from a
CICS adapter.
percolation. In error recovery, the passing along a preestablished path of control from a
recovery routine to a higher-level recovery routine.
performance event. A category of event indicating that a limit condition has occurred.
performance trace. An WebSphere MQ trace option where the trace data is to be used for
performance analysis and tuning.
permanent dynamic queue. A dynamic queue that is deleted when it is closed only if
deletion is explicitly requested. Permanent dynamic queues are recovered if the queue
manager fails, so they can contain persistent messages. Contrast with temporary dynamic
queue.
persistent message. A message that survives a restart of the queue manager. Contrast
with nonpersistent message.
ping. In distributed queuing, a diagnostic aid that uses the exchange of a test message to
confirm that a message channel or a TCP/IP connection is functioning.
platform. In WebSphere MQ, the operating system under which a queue manager is
running.
point of recovery. In WebSphere MQ for z/OS, the term used to describe a set of backup
copies of WebSphere MQ for z/OS page sets and the corresponding log data sets required
to recover these page sets. These backup copies provide a potential restart point in the
event of page set loss (for example, page set I/O error).
polymorphism. The characteristic whereby a method can be applied to a variety of
classes, with consequent various effects: for example, an open method could be applied
equally to book and door class objects.
preemptive shutdown. In WebSphere MQ, a shutdown of a queue manager that does not
wait for connected applications to disconnect, nor for current MQI calls to complete.
Contrast with immediate shutdown and quiesced shutdown.
principal. In WebSphere MQ on UNIX systems, MQSeries for OS/2 Warp, and WebSphere
MQ for Windows, a term used for a user identifier. Used by the object authority manager for
checking authorizations to system resources.
private methods and instance data. Methods and instance data that are only accessible
to the implementation of the same class.
Instructor Guide
V2.0
Uempty
process definition object. A WebSphere MQ object that contains the definition of an
WebSphere MQ application. For example, a queue manager uses the definition when it
works with trigger messages.
programmable command format (PCF). A type of WebSphere MQ message used by:
User administration applications, to put PCF commands onto the system command input
queue of a specified queue manager
User administration applications, to get the results of a PCF command from a specified
queue manager
A queue manager, as a notification that an event has occurred
Contrast with MQSC.
program temporary fix (PTF). A solution or by-pass of a problem diagnosed by IBM field
engineering as the result of a defect in a current, unaltered release of a program.
protected methods and instance data. Methods and instance data that are only
accessible to the implementations of the same or derived classes, or from friend classes.
PTF. Program temporary fix.
public methods and instance data. Methods and instance data that are accessible to all
classes.
Q
queue. An WebSphere MQ object. Message queuing applications can put messages on,
and get messages from, a queue. A queue is owned and maintained by a queue manager.
Local queues can contain a list of messages waiting to be processed. Queues of other
types cannot contain messages they point to other queues, or can be used as models for
dynamic queues.
queue manager. (1) A system program that provides queuing services to applications. It
provides an application programming interface so that programs can access messages on
the queues that the queue manager owns. See also local queue manager and remote
queue manager. (2) An WebSphere MQ object that defines the attributes of a particular
queue manager.
queue manager event. An event that indicates:
An error condition has occurred in relation to the resources used by a queue manager.
For example, a queue is unavailable.
A significant change has occurred in the queue manager. For example, a queue
manager has stopped or started.
queuing. See message queuing.
quiesced shutdown. (1) In WebSphere MQ, a shutdown of a queue manager that allows
all connected applications to disconnect. Contrast with immediate shutdown and
preemptive shutdown. (2) A type of shutdown of the CICS adapter where the adapter
Instructor Guide
disconnects from WebSphere MQ, but only after all the currently active tasks have been
completed. Contrast with forced shutdown.
quiescing. In WebSphere MQ, the state of a queue manager prior to it being stopped. In
this state, programs are allowed to finish processing, but no new programs are allowed to
start.
R
RBA. Relative byte address.
reason code. A return code that describes the reason for the failure or partial success of
an MQI call.
receiver channel. In message queuing, a channel that responds to a sender channel,
takes messages from a communication link, and puts them on a local queue.
recovery log. In WebSphere MQ for z/OS, data sets containing information needed to
recover messages, queues, and the WebSphere MQ subsystem. WebSphere MQ for z/OS
writes each record to a data set called the active log. When the active log is full, its contents
are off loaded to a DASD or tape data set called the archive log. Synonymous with log.
recovery termination manager (RTM). A program that handles all normal and abnormal
termination of tasks by passing control to a recovery routine associated with the
terminating function.
reference message. A message that refers to a piece of data that is to be transmitted. The
reference message is handled by message exit programs, which attach and detach the
data from the message so allowing the data to be transmitted without having to be stored
on any queues.
Registry. In Windows NT, a secure database that provides a single source for system and
application configuration data.
Registry Editor. In Windows NT, the program item that allows the user to edit the Registry.
Registry Hive. In Windows NT, the structure of the data stored in the Registry.
relative byte address (RBA). The displacement in bytes of a stored record or control
interval from the beginning of the storage space allocated to the data set to which it
belongs.
remote queue. A queue belonging to a remote queue manager. Programs can put
messages on remote queues, but they cannot get messages from remote queues. Contrast
with local queue.
remote queue manager. To a program, a queue manager that is not the one to which the
program is connected.
remote queue object. See local definition of a remote queue.
remote queuing. In message queuing, the provision of services to enable applications to
put messages on queues belonging to other queue managers.
Instructor Guide
V2.0
Uempty
reply message. A type of message used for replies to request messages.
Contrast with request message and report message.
reply-to queue. The name of a queue to which the program that issued an MQPUT call
wants a reply message or report message sent.
report message. A type of message that gives information about another message. A
report message can indicate that a message has been delivered, has arrived at its
destination, has expired, or could not be processed for some reason.
Contrast with reply message and request message.
repository. A collection of information about the queue managers that are members of a
cluster. This information includes queue manager names, their locations, their channels,
what queues they host, and so on.
See also full repository and partial repository.
repository queue manager. A queue manager that hosts the full repository of information
about a cluster.
requester channel. In message queuing, a channel that may be started remotely by a
sender channel. The requester channel accepts messages from the sender channel over a
communication link and puts the messages on the local queue designated in the message.
See also server channel.
request message. A type of message used to request a reply from another program.
Contrast with reply message and report message.
RESLEVEL. In WebSphere MQ for z/OS, an option that controls the number of CICS user
IDs checked for API-resource security in WebSphere MQ for z/OS.
resolution path. The set of queues that are opened when an application specifies an alias
or a remote queue on input to an MQOPEN call.
resource. Any facility of the computing system or operating system required by a job or
task. In WebSphere MQ for z/OS, examples of resources are buffer pools, page sets, log
data sets, queues, and messages.
resource manager. An application, program, or transaction that manages and controls
access to shared resources such as memory buffers and data sets. WebSphere MQ, CICS,
and IMS are resource managers.
Resource Recovery Services (RRS). An z/OS facility that provides 2-phase syncpoint
support across participating resource managers.
responder. In distributed queuing, a program that replies to network connection requests
from another system.
resynch. In WebSphere MQ, an option to direct a channel to start up and resolve any
in-doubt status messages, but without restarting message transfer.
return codes. The collective name for completion codes and reason codes.
Instructor Guide
return-to-sender. An option available to an MCA that is unable to deliver a message. The
MCA can send the message back to the originator.
rollback. Synonym for back out.
RRS. Resource Recovery Services.
RTM. Recovery termination manager.
rules table. A control file containing one or more rules that the dead-letter queue handler
applies to messages on the DLQ.
S
SAF. System Authorization Facility.
Scalable Parallel 2 (SP2). IBM's parallel UNIX system effectively parallel AIX systems
on a high-speed network.
SDWA. System diagnostic work area.
security enabling interface (SEI). The WebSphere MQ interface to which customer- or
vendor-written programs that check authorization, supply a user identifier, or perform
authentication must conform. A part of the WebSphere MQ Framework.
SEI. Security enabling interface.
selector. Used to identify a data item. In the MQAI there are two types of selector: a user
selector and a system selector.
sender channel. In message queuing, a channel that initiates transfers, removes
messages from a transmission queue, and moves them over a communication link to a
receiver or requester channel.
sequential delivery. In WebSphere MQ, a method of transmitting messages with a
sequence number so that the receiving channel can reestablish the message sequence
when storing the messages. This is required where messages must be delivered only once,
and in the correct order.
sequential number wrap value. In WebSphere MQ, a method of ensuring that both ends
of a communication link reset their current message sequence numbers at the same time.
Transmitting messages with a sequence number ensures that the receiving channel can
reestablish the message sequence when storing the messages.
serialization. The writing of data in sequential fashion to a communications medium from
program memory.
server. (1) In WebSphere MQ, a queue manager that provides queue services to client
applications running on a remote workstation. (2) The program that responds to requests
for information in the particular two-program, information-flow model of client/server. See
also client.
Instructor Guide
V2.0
Uempty
server channel. In message queuing, a channel that responds to a requester channel,
removes messages from a transmission queue, and moves them over a communication
link to the requester channel.
server connection channel type. The type of MQI channel definition associated with the
server that runs a queue manager. See also client connection channel type.
service interval. A time interval, against which the elapsed time between a put or a get
and a subsequent get is compared by the queue manager in deciding whether the
conditions for a service interval event have been met. The service interval for a queue is
specified by a queue attribute.
service interval event. An event related to the service interval.
session ID. In WebSphere MQ for z/OS, the CICS-unique identifier that defines the
communication link to be used by a message channel agent when moving messages from
a transmission queue to a link.
shutdown. See immediate shutdown, preemptive shutdown, and quiesced shutdown.
signaling. In WebSphere MQ for z/OS and WebSphere MQ for Windows 2.1, a feature that
allows the operating system to notify a program when an expected message arrives on a
queue.
signature. A distinct combination of method name or operator, and parameters.
single logging. A method of recording WebSphere MQ for z/OS activity where each
change is recorded on one data set only. Contrast with dual logging.
single-phase backout. A method in which an action in progress must not be allowed to
finish, and all changes that are part of that action must be undone.
single-phase commit. A method in which a program can commit updates to a queue
without coordinating those updates with updates the program has made to resources
controlled by another resource manager. Contrast with two-phase commit.
SIT. System initialization table.
SNA. Systems Network Architecture.
source queue manager. See local queue manager.
SPX. Sequenced Packet Exchange transmission protocol.
SP2. Scalable Parallel 2
stanza. A group of lines in a configuration file that assigns a value to a parameter modifying
the behavior of a queue manager, client, or channel. In WebSphere MQ on UNIX systems,
MQSeries for OS/2, and WebSphere MQ for Windows, a configuration (.ini) file may contain
a number of stanzas.
star-connected communications network. A network in which all nodes are connected
to a central node.
Instructor Guide
storage class. In WebSphere MQ for z/OS, a storage class defines the page set that is to
hold the messages for a particular queue. The storage class is specified when the queue is
defined.
store and forward. The temporary storing of packets, messages, or frames in a data
network before they are retransmitted toward their destination.
streaming. The marshalling of class information and object instance data.
subsystem. In z/OS, a group of modules that provides function that is dependent on z/OS.
For example, WebSphere MQ for z/OS is an z/OS subsystem.
supervisor call (SVC). An instruction that interrupts a running program and passes
control to the supervisor so that it can perform the specific service indicated by the
instruction.
SVC. Supervisor call.
switch profile. In WebSphere MQ for z/OS, a RACF profile used when WebSphere MQ
starts up or when a refresh security command is issued. Each switch profile that
WebSphere MQ detects turns off checking for the specified resource.
symptom string. Diagnostic information displayed in a structured format designed for
searching the IBM software support database.
synchronous messaging. A method of communication between programs in which
programs place messages on message queues. With synchronous messaging, the
sending program waits for a reply to its message before resuming its own processing.
Contrast with asynchronous messaging.
syncpoint. An intermediate or end point during processing of a transaction at which the
transaction's protected resources are consistent. At a syncpoint, changes to the resources
can safely be committed, or they can be backed out to the previous syncpoint.
sysplex. A multiple -system environment that allows multiple-console support (MCS)
consoles to receive console messages and send operator commands across systems.
System Authorization Facility (SAF). An z/OS facility through which WebSphere MQ for
z/OS communicates with an external security manager such as RACF.
system bag. A type of data bag that is created by the MQAI.
system.command.input queue. A local queue on which application programs can put
WebSphere MQ commands. The commands are retrieved from the queue by the command
server, which validates them and passes them to the command processor to be run.
system control commands. Commands used to manipulate platform-specific entities
such as buffer pools, storage classes, and page sets.
system diagnostic work area (SDWA). Data recorded in a SYS1.LOGREC entry, which
describes a program or hardware error.
system initialization table (SIT). A table containing parameters used by CICS on start up.
system item. A type of data item that is created by the MQAI.
Instructor Guide
V2.0
Uempty
system selector. In the MQAI, used to identify a system item. A system selector is
included in the data bag when it is created.
Systems Network Architecture (SNA). The description of the logical structure, formats,
protocols, and operational sequences for transmitting information units through, and
controlling the configuration and operation of, networks.
SYS1.LOGREC. A service aid containing information about program and hardware errors.
T
TACL. Tandem Advanced Command Language.
target library high-level qualifier (thlqual). High-level qualifier for z/OS target data set
names.
target queue manager. See remote queue manager.
task control block (TCB). An z/OS control block used to communicate information about
tasks within an address space that are connected to an z/OS subsystem such as
WebSphere MQ for z/OS or CICS.
task switching. The overlapping of I/O operations and processing between several tasks.
In WebSphere MQ for z/OS, the task switcher optimizes performance by allowing some
MQI calls to be executed under subtasks rather than under the main CICS TCB.
TCB. Task control block.
TCP. Transmission Control Protocol.
TCP/IP. Transmission Control Protocol/Internet Protocol.
temporary dynamic queue. A dynamic queue that is deleted when it is closed. Temporary
dynamic queues are not recovered if the queue manager fails, so they can contain
nonpersistent messages only. Contrast with permanent dynamic queue.
termination notification. A pending event that is activated when a CICS subsystem
successfully connects to WebSphere MQ for z/OS.
this. The reserved word that represents a pointer to the current object.
thlqual. Target library high-level qualifier.
thread. In WebSphere MQ, the lowest level of parallel execution available on an operating
system platform.
time-independent messaging. See asynchronous messaging.
TMF. Transaction Management Facility.
TMI. Trigger monitor interface.
TM/MP. NonStop Transaction Manager/MP.
trace. In WebSphere MQ, a facility for recording WebSphere MQ activity. The destinations
for trace entries can include GTF and the system management facility (SMF). See also
global trace and performance trace.
Instructor Guide
tranid. See transaction identifier.
transaction. See unit of work and CICS transaction.
transaction identifier. In CICS, a name that is specified when the transaction is defined,
and that is used to invoke the transaction.
transaction manager. A software unit that coordinates the activities of resource managers
by managing global transactions and coordinating the decision to commit them or roll them
back. is a transaction manager.
Transmission Control Protocol (TCP). Part of the TCP/IP protocol suite. A host-to-host
protocol between hosts in packet-switched communications networks. TCP provides
connection-oriented data stream delivery. Delivery is reliable and orderly.
Transmission Control Protocol/Internet Protocol (TCP/IP). A suite of communication
protocols that support peer-to-peer connectivity functions for both local and wide area
networks.
transmission program. See message channel agent.
transmission queue. A local queue on which prepared messages destined for a remote
queue manager are temporarily stored.
trigger event. An event (such as a message arriving on a queue) that causes a queue
manager to create a trigger message on an initiation queue.
triggering. In WebSphere MQ, a facility allowing a queue manager to start an application
automatically when predetermined conditions on a queue are satisfied.
trigger message. A message containing information about the program that a trigger
monitor is to start.
trigger monitor. A continuously-running application serving one or more initiation queues.
When a trigger message arrives on an initiation queue, the trigger monitor retrieves the
message. It uses the information in the trigger message to start a process that serves the
queue on which a trigger event occurred.
trigger monitor interface (TMI). The WebSphere MQ interface to which customer- or
vendor-written trigger monitor programs must conform. A part of the WebSphere MQ
Framework.
two-phase commit. A protocol for the coordination of changes to recoverable resources
when more than one resource manager is used by a single transaction. Contrast with
single-phase commit.
type. A fundamental data type of computer architecture, including for example character
string and integer.
U
User Datagram Protocol.
UIS. User identifier service.
Instructor Guide
V2.0
Uempty
undelivered-message queue. See dead-letter queue.
undo/redo record. A log record used in recovery. The redo part of the record describes a
change to be made to an WebSphere MQ object. The undo part describes how to back out
the change if the work is not committed.
unit of recovery. A recoverable sequence of operations within a single resource manager.
Contrast with unit of work.
unit of work. A recoverable sequence of operations performed by an application between
two points of consistency. A unit of work begins when a transaction starts or after a
user-requested syncpoint. It ends either at a user-requested syncpoint or at the end of a
transaction.
Contrast with unit of recovery.
user bag. In the MQAI, a type of data bag that is created by the user.
User Datagram Protocol (). Part of the TCP/IP protocol suite. A packet-level protocol built
directly on the Internet Protocol layer. UDP is a connectionless and less reliable alternative
to TCP. It is used for application-to-application programs between TCP/IP host systems.
user identifier service (UIS). In MQSeries for OS/2 Warp, the facility that allows MQI
applications to associate a user ID, other than the default user ID, with WebSphere MQ
messages.
user item. In the MQAI, a type of data item that is created by the user.
user selector. In the MQAI, used to identify a user item. For the administration of objects,
valid user selectors are already defined.
utility. In WebSphere MQ, a supplied set of programs that provide the system operator or
system administrator with facilities in addition to those provided by the WebSphere MQ
commands. Some utilities invoke more than one function.
V
value. Value of a data item. This can be an integer, a string, or a handle of another bag.
virtual method. A method that exhibits polymorphism.
X
X/Open XA. The X/Open Distributed Transaction Processing XA interface. A proposed
standard for distributed transaction communication. The standard specifies a bidirectional
interface between resource managers that provide access to shared resources within
transactions, and between a transaction service that monitors and resolves transactions.
XCF. Cross Systems Coupling Facility.
Instructor Guide
V1.2.2
backpg

MQ15 - WebSphere MQ System Administration I

Uploaded by

Copyright:

Available Formats

MQ15 - WebSphere MQ System Administration I

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

MQ15 - WebSphere MQ System Administration I

Uploaded by

Copyright:

Available Formats

What is the purpose of the document?

What topics are covered in the document?

WebSphere MQ

System Administration I for

You might also like