MQ15 - WebSphere MQ System Administration I

V1.2.2.2

cover

WebSphere MQ System Administration I for Distributed Platforms (Course Code MQ15)

Instructor Guide ERC 7.0

IBM Certified Course Material

Instructor Guide

Trademarks IBM® is a registered trademark of International Business Machines Corporation. The following are trademarks of International Business Machines Corporation in the United States, or other countries, or both: AIX CICS FFST IMS Lotus Notes NetView OS/390 RACF ThinkPad WebSphere zSeries

AS/400 DYNIX/ptx First Failure Support Technology iSeries MQSeries Notes OS/400 SP2 TXSeries WIN-OS/2

BookManager Everyplace IBM Lotus MVS/ESA OS/2 QMF SupportPac VSE/ESA z/OS

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.

February 2003 Edition 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 customer’s ability to evaluate and integrate them into the customer’s 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.

V1.2.2.2 Instructor Guide

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 © Copyright IBM Corp. 1996, 2003 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

Contents

iii

Instructor Guide

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 iv

WebSphere MQ System Administration I

© Copyright IBM Corp. 1996, 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.


TOC

WebSphere MQ Publish/Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing WebSphere MQ Publish/Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Broker Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unit Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-70 3-73 3-75 3-78 3-81 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 © Copyright IBM Corp. 1996, 2003 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

Contents

v

Instructor Guide

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 vi





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

© Copyright IBM Corp. 1996, 2003 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

Contents

vii

Instructor Guide

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

viii





TMK

Trademarks The reader should recognize that the following terms, which appear in the content of this training document, are official trademarks of IBM or other companies: IBM® is a registered trademark of International Business Machines Corporation. The following are trademarks of International Business Machines Corporation in the United States, or other countries, or both: AIX® CICS® FFST

AS/400® DYNIX/ptx® First Failure Support Technology iSeries MQSeries® Notes® OS/400® SP2® TXSeries® WIN-OS/2®

IMS Lotus Notes® NetView® OS/390® RACF® ThinkPad® WebSphere® zSeries

BookManager® Everyplace IBM® Lotus® MVS/ESA OS/2® QMF SupportPac VSE/ESA z/OS

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.


Trademarks

xi

Instructor Guide

xii





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 Course Overview


xiii

Instructor Guide

xiv





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 WebSphere MQ for Windows

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.


Course Description

xv

Instructor Guide

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

xvi





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


Agenda

xvii

Instructor Guide

xviii WebSphere MQ System Administration I



V2.0 Instructor Guide

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

Unit 1. A Review of WebSphere MQ


1-1

Instructor Guide

8QLW2EMHFWLYHV $IWHUFRPSOHWLQJWKLVXQLW\RXVKRXOGEHDEOHWR 5HYLHZ:HE6SKHUH04FRQFHSWV (QVXUHVWXGHQWVKDYHQHFHVVDU\SUHUHTXLVLWHNQRZOHGJH (VWDEOLVKJRDOVRIFRXUVH

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.

1-2





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.




1-3

Instructor Guide

1-4





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.




1-5

Instructor Guide

:HE6SKHUH04&RPPHUFLDO0HVVDJLQJ &RPPRQDSSOLFDWLRQSURJUDPPLQJLQWHUIDFH $VVXUHGPHVVDJHGHOLYHU\ 7LPHLQGHSHQGHQWSURFHVVLQJ $SSOLFDWLRQSDUDOOHOLVP )DVWHUDSSOLFDWLRQGHYHORSPHQW

B eue Qu

A

eue Qu

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 1-6





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.




1-7

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.

1-8





Uempty

)XUWKHU,QIRUPDWLRQ :HE6SKHUH04SXEOLFDWLRQV 0DQ\DUHFURVVSODWIRUP )RULQIRUPDWLRQWKDWLVFRPPRQ )RUSODQQLQJDQGLPSOHPHQWLQJDQ:HE6SKHUH04QHWZRUN 6RPHDUHSODWIRUPVSHFLILF KWWSZZZLEPFRPVRIWZDUHWVPTVHULHV /DWHVWQHZV 5HIHUHQFHV %HWDFRGH 6XSSRUW3DFV

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/




1-9

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. Additional Information — None. Transition Statement — Next we consider two basic questions. What is a message, and what is a queue?

1-10 WebSphere MQ System Administration I




Uempty

0HVVDJHDQG4XHXH $PHVVDJHLV $XQLWRILQIRUPDWLRQ $UHTXHVWIRUDVHUYLFH $UHSO\ $UHSRUW $QDQQRXQFHPHQW $TXHXHLV $VDIHSODFHWRVWRUHPHVVDJHV /LQHGXSIRUVHUYLFLQJ 6WDJHGIRUGHOLYHU\

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.




1-11

Instructor Guide

Instructor Notes: Purpose — To clarify what is meant by a message and a queue. Details — Additional Information — None. Transition Statement — Next we see that a wide range of applications can be built on these simple concepts.





Uempty

$SSOLFDWLRQV(QDEOHGE\:HE6SKHUH04 3URJUDPWRSURJUDPFRPPXQLFDWLRQIRU 0HVVDJHGULYHQSURFHVVLQJ &OLHQWVHUYHULPSOHPHQWDWLRQ 'LVWULEXWHGSURFHVVLQJ &RPSRQHQWVRIDQDSSOLFDWLRQFDQUXQLQGHSHQGHQWO\RQGLIIHUHQW V\VWHPVDQGHQYLURQPHQWV $SSOLFDWLRQVZLWKVHYHUDOSURFHVVLQJVWHSV 6RPHIDVW 6RPHVORZ 6RPHQRWLPPHGLDWHO\DYDLODEOH 1RORVVRUGXSOLFDWLRQRILQIRUPDWLRQ

Figure 1-5. Applications Enabled by WebSphere MQ

MQ157.0

Notes:




1-13

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. Additional Information — None. Transition Statement — Next we introduce the concept of a queue manager, and the application programming interface it provides to an application.





Uempty

4XHXH0DQDJHU

3URJUDP

3URJUDP

3URJUDP

04,

$0,

-06

4XHXH 0DQDJHU

4 4 4

$TXHXHPDQDJHURZQVDQGPDQDJHVTXHXHV )DPLO\RIDSSOLFDWLRQSURJUDPPLQJLQWHUIDFHV 7KH0HVVDJH4XHXH,QWHUIDFH04, 7KH$SSOLFDWLRQ0HVVDJLQJ,QWHUIDFH$0, 7KH-DYD0HVVDJH6HUYLFH-06 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.




1-15

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.





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. Additional Information — None. Transition Statement — Next we look a little more closely at the calls provided by the MQI.




1-17

Instructor Guide

04,&DOOV
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 1-18 WebSphere MQ System Administration I




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.




1-19

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.





Uempty

0HVVDJH'HVFULSWRU 4

3URJUDP$

3URJUDP%

4

(DFKPHVVDJHKDVDPHVVDJHGHVFULSWRU $SSOLFDWLRQGHWHUPLQHVPHVVDJHFRQWHQW 0HVVDJH GHVFULSWRU

$SSOLFDWLRQ GDWD 0HVVDJH

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.




1-21

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. Additional Information — None. Transition Statement — The basic conversational model is a synchronous one. Next, we shall look at an asynchronous version.





Uempty

$V\QFKURQRXV0RGHO

3URJUDP$

3URJUDP;

4

3URJUDP%

4

6HSDUDWHSURFHVVIRUUHSOLHV 1RQHHGIRUFRPPXQLFDWLQJSURJUDPVWREH DFWLYHDWWKHVDPHWLPH 7LPHLQGHSHQGHQFH

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.




1-23

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. Additional Information — None. Transition Statement — Next we look at how triggering enhances the implementation of time-independent processing.





Uempty

7ULJJHULQJ 4XHXH0DQDJHU 3URJUDP%

$SSOLFDWLRQ 4XHXH

04*(7$4

3URJUDP$

04387$4

3URFHVV 2EMHFW

7ULJJHU0RQLWRU

04*(7,4

,QLWLDWLRQ 4XHXH

7ULJJHULQJDOORZV ,QVWDQWLDWLRQDVUHTXLUHG &RQVHUYDWLRQRIV\VWHPUHVRXUFHV $XWRPDWLRQRIIORZ 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.




1-25

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. Additional Information — None. Transition Statement — Next we look at how WebSphere MQ allows parallel processing within an application.





Uempty

3DUDOOHO3URFHVVHV 04387$''54

$''5

04387

$''54

04387%$/4 04387&24

%$/4

04*(75HSO\WR TXHXH

&24

%$/

&2

04387

5HSO\WRTXHXH

04387

5HTXHVWVQRWVHULDOL]HG

3RVVLEO\VHOHFWLYH04*(7"

6KRUWHUHODSVHGWLPH

,QFRPSOHWHVHWRIUHSOLHV"

&RQVROLGDWHUHSOLHV

'LIIHUHQWSURFHVVWRKDQGOHUHSOLHV"

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.




1-27

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. Additional Information — None. Transition Statement — Next we look at how WebSphere MQ can be used to implement client/server applications.





Uempty

&OLHQW6HUYHU ,QVXUDQFH GDWD ,QVXUDQFH TXRWDWLRQV ,QVXUDQFH DJHQW Server

4XHXH VHUYLFH 0HVVDJH UHTXHVW

,QVXUDQFH DJHQW ,QVXUDQFH DJHQW

5HSO\WRTXHXHQDPHLQPHVVDJH GHVFULSWRU &OLHQWV

0XOWLSOHLQVWDQFHVRIVHUYHU SRVVLEOH

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.




1-29

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. Additional Information — None. Transition Statement — Next we look at the benefit of assured message delivery.





Uempty

$VVXUHG'HOLYHU\

3URJUDP$

4 4W

40

3URJUDP%

4W 4

40

7UDQVPLVVLRQTXHXHVWRUHVPHVVDJHILUVW $SSOLFDWLRQQRWVWRSSHGLIOLQNLVLQDFWLYH

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.




1-31

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. Additional Information — None. Transition Statement — Next we look at how the WebSphere MQ approach to program to program communication can be viewed as connectionless.





Uempty

&RQQHFWLRQOHVV&RPPXQLFDWLRQV

3URJUDP$ 3URJUDP%

3URJUDP&

3URJUDP'

4 4

4W 40

0HVVDJH GHVFULSWRU

40 7UDQVPLVVLRQTXHXHKHDGHU

'HVWLQDWLRQ TXHXHQDPH

'HVWLQDWLRQ 2ULJLQDO TXHXHPDQDJHU PHVVDJH QDPH GHVFULSWRU

$SSOLFDWLRQ GDWD

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.




1-33

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. Additional Information — None.





Uempty

Transition Statement — Next we look at how this means that applications are decoupled from the network.




1-35

Instructor Guide

4XHXH0DQDJHU1HWZRUN 6\VWHP 3URJUDP$

043874

6\VWHP

3URJUDP%

043874

04*(74

3URJUDP&

04,

04*(74

4XHXH PDQDJHU

4XHXH PDQDJHU

4 4

1HWZRUN

$SSOLFDWLRQVVKLHOGHGIURPWKHQHWZRUN 04387FDOOVLGHQWLFDO 1RUHPRWH04*(7FDOO 8QGHOLYHUDEOHPHVVDJHV"

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.





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. Additional Information — None. Transition Statement — Next we look in a little more detail at how messages are transmitted from one queue manager to another.




1-37

Instructor Guide

'LVWULEXWHG4XHXH0DQDJHPHQW

&KDQQHO FRQWURO IXQFWLRQ

6HQGHU

5HFHLYHU

0 & $

0 & $

61$/87&3,3HWF

&KDQQHO FRQWURO IXQFWLRQ

0HVVDJHFKDQQHO

7UDQVPLVVLRQ TXHXH

'HVWLQDWLRQ TXHXHV

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.





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.




1-39

Instructor Guide

Instructor Notes: Purpose — To identify some of the main components of distributed queue management (DQM). Details — Nothing in addition to the student notes. Additional Information — None. Transition Statement — Next we look at how a complex business transaction can be implemented using the simple messaging and queuing model.





Uempty

0HVVDJH'ULYHQ3URFHVVLQJ &UHGLW +LVWRU\ 4

4

$FFRXQW %DODQFH

4 &XVWRPHU ,QIRUPDWLRQ

4 4

/RDQ 5HTXHVW

%DQN )XQGV $YDLODELOLW\

4

&UHGLW &DUG 6WDWXV

5LVN $QDO\VLV

4

/RDQ 5HVSRQVH

/RDQ7HUPV 6HFXULW\ ,QGHPQLW\

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.




1-41

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. Additional Information — None. Transition Statement — Next, we investigate the role of syncpoint control in this type of design.





Uempty

6HSDUDWH3URFHVVHVDV8QLWVRI:RUN

04*(7ORDQUHTXHVW 9DOLGDWHILHOGV 8SGDWHUHTXHVWILOH )RUPDWWZRUHTXHVWV 04387FUHGLWKLVWRU\UHTXHVW 04387EDQNIXQGV DYDLODELOLW\UHTXHVW

04*(7FXVWRPHULQIRUPDWLRQ UHTXHVW

&RPPLW

8SGDWHGDWDEDVH 04387DFFRXQWEDODQFH UHTXHVW 04387FUHGLWVWDWXVUHTXHVW &RPPLW

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.




1-43

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. Additional Information — None. Transition Statement — Next we look in little more detail at how a business transaction can be implemented as multiple asynchronous units of work.





Uempty

0XOWLSOH$V\QFKURQRXV8QLWVRI:RUN

'%

6\QFKURQRXV PRGHO

:ULWH 6HQG

5HFHLYH :ULWH SKDVH FRPPLW

6\QFSRLQW

'%

6\QFSRLQW

8QLWRIZRUN

'%

$V\QFKURQRXV PRGHO

:ULWH

3XW 8QLWRIZRUN 6\QFSRLQW

T

4 8QLWRIZRUN

*HW :ULWH 6\QFSRLQW

'%

8QLWRIZRUN

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.




1-45

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. Additional Information — None. Transition Statement — Next we look at a property of a message called its persistence.





Uempty

0HVVDJH3HUVLVWHQFH $SSOLFDWLRQ 3URJUDP 3HUVLVWHQWPHVVDJH

4XHXH 0DQDJHU 4XHXH

Log 04387

&&5&

4XHXH 1RQSHUVLVWHQWPHVVDJH

04387

&&5&

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.




1-47

Instructor Guide

Instructor Notes: Purpose — To introduce the concept of message persistence and the requirement for a log. Details — Nothing in addition to the student notes. Additional Information — None. Transition Statement — End of the topic. Next we look briefly at the family of WebSphere MQ queue managers and the platforms they support.





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.

Instructor Topic Introduction What students will do — Students will listen to a presentation on the WebSphere MQ products and platforms. How students will do it — No student activities are planned for this topic. 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. How this will help students on their job — This knowledge will help the students to understand the range of WebSphere MQ implementations and the opportunities they present for applications.




1-49

Instructor Guide

:HE6SKHUH044XHXH0DQDJHUV :HE6SKHUH04IRU /LQXVIRU,QWHO9 /LQXVIRU]6HULHV9 1&581,;9 26:DUS9 ]269 6,1,;DQG'&26[9 6RODULV9 7DQGHP16.9 96((6$9 :LQGRZV9

/HYHO

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 1-50 WebSphere MQ System Administration I




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




1-51

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.





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.




1-53

Instructor Guide

:HE6SKHUH04)UDPHZRUN $SSOLFDWLRQ 04, 'DWD FRQYHUVLRQ LQWHUIDFH

70,

'&,

0HVVDJLQJ 2EMHFW DXWKRULW\ PDQDJHU

'&( QDPH VHUYLFH

6HFXULW\ HQDEOLQJ LQWHUIDFH

6(,

7ULJJHU PRQLWRU LQWHUIDFH 2WKHU

DQG

61$

TXHXLQJ

7&3,3

NHUQHO 1DPH VHUYLFH LQWHUIDFH

16,

0&,

0HVVDJH FKDQQHO LQWHUIDFH

RWKHU:HE6SKHUH046\VWHPV

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





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. Additional Information — None. Transition Statement — Next we review the concept of an WebSphere MQ client.




1-55

Instructor Guide

:HE6SKHUH04&OLHQW

&OLHQWV\VWHP

6HUYHUV\VWHP

:HE6SKHUH 04 DSSOLFDWLRQ

:HE6SKHUH 04TXHXH PDQDJHU

&OLHQW FRQQHFWLRQ

6HUYHU FRQQHFWLRQ

&RPPXQLFDWLRQV VWDFN


$VVXUHGGHOLYHU\ 4XHXHVWRUDJH 'DWDFRQYHUVLRQ $GPLQLVWUDWLRQ 5HFRYHU\ 6\QFSRLQW FRQWURO

04,FKDQQHO

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. 1-56 WebSphere MQ System Administration I




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.




1-57

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. Additional Information — None. Transition Statement — Finally, we look at the range of application platforms supported by WebSphere MQ.





Uempty

:HE6SKHUH043ODWIRUPV $,; &RPSDT2SHQ906$;3 &RPSDT2SHQ9069$; &RPSDT7UX81,; +38;LQFOXGLQJ6WUDWXV&RQWLQXXP /LQX[ 1&581,; 26:DUS 6,1,;DQG'&26[ 6RODULV :LQGRZV

L6HULHV 1RWDVDQ ]26 :HE6SKHUH %DWFK 04 &,&6 FOLHQW ,06 762 7DQGHP1RQ6WRS.HUQHO 96((6$

2QO\DVDQ '26 :HE6SKHUH -DYD 04 6XQ26 FOLHQW 73) 90(6$ 2WKHUVVHHVWXGHQWQRWHV

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.




1-59

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).





Uempty

Instructor Notes: Purpose — To review the range of platforms supported by WebSphere MQ. Details — Nothing in addition to the student notes. Additional Information — None. Transition Statement — End of the topic. Let us review what we have done so far.




1-61

Instructor Guide





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. b. c. d.

A report of delivery will always be sent back. Unless the entire system goes down, no messages are lost. Messages may be duplicated but never lost. 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




1-63

Instructor Guide

8QLW6XPPDU\ &RPPHUFLDO0HVVDJLQJ %HQHILWVIRUDOOSODWIRUPV &RPPRQDSSOLFDWLRQSURJUDPPLQJLQWHUIDFH $VVXUHGPHVVDJHGHOLYHU\ 7LPHLQGHSHQGHQWSURFHVVLQJ $SSOLFDWLRQSDUDOOHOLVP )DVWHUDSSOLFDWLRQGHYHORSPHQW /HYHOHQKDQFHPHQWV 66/ $GGLWLRQDOIXQFWLRQ ,QVWUXPHQWDWLRQHYHQWV 6LQJOHSRLQWRIFRQWURO :HE6SKHUH04)UDPHZRUN :HE6SKHUH04FOLHQWV

Figure 1-25. Unit Summary

MQ157.0

Notes:





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. Additional Information — None. Transition Statement — End of the unit. Next we shall look at how to install WebSphere MQ and configure a queue manager.




1-65

Instructor Guide





Uempty

Unit 2. Installation and Configuration What This Unit is About The first unit reviewed the role of WebSphere MQ in commercial messaging and some of the facilities and functions that WebSphere MQ provides. WebSphere MQ supports a wide range of platforms and the major benefits of WebSphere MQ apply to all these platforms. However, the Level 2 queue managers provide some enhancements which, in turn, deliver additional benefits. It is these queue managers which now become the focus for the remainder of this course. The only Level 2 queue manager which is excluded is WebSphere MQ for z/OS which has its own course, MQ20, WebSphere MQ for z/OS System Administration. This unit commences by looking at what you need to consider, and what decisions you need to make, when planning to implement WebSphere MQ. The unit then describes how to create a basic configuration for a queue manager and provides a practical exercise in doing this.

What You Should Be Able to Do After completing this unit, you should be able to: • Install WebSphere MQ with reference to the relevant documentation • Create and configure a queue manager • Test a queue manager configuration • Start and stop a queue manager and perform other simple administration tasks

How You Will Check Your Progress Accountability: • Checkpoint questions • Machine exercises

References SC34-6055 © Copyright IBM Corp. 1996, 2003

WebSphere MQ Script (MQSC) Command Reference Unit 2. Installation and Configuration


2-1

Instructor Guide

SC34-6068

WebSphere MQ WebSphere MQ System Administration Guide

If using iSeries, use the following manual; SC34-6070

2-2

WebSphere MQ for iSeries V5.3 System Administration Guide





Uempty

8QLW2EMHFWLYHV $IWHUFRPSOHWLQJWKLVXQLW\RXVKRXOGEHDEOHWR /LVWYDULRXVDGPLQLVWUDWLRQLQWHUIDFHV ([SODLQZKLFKLQWHUIDFHVDUHDYDLODEOHRQYDULRXVSODWIRUPVDQG KRZWRXVHWKHP 'HVFULEHQDPLQJUXOHVDQGUHFRPPHQGHGFRQYHQWLRQV 4XHXH0DQDJHUV 4XHXHV &UHDWHDQGVWDUWTXHXHPDQDJHUV &UHDWHTXHXHV 8VHVDPSOHSURJUDPVWRWHVWQHZREMHFWV


MQ157.0

Notes:


Unit 2. Installation and Configuration


2-3

Instructor Guide

2-4





Uempty

Instructor Notes: Purpose — To highlight the unit objectives. 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. After completing this unit, the student should be able to: • Install WebSphere MQ with reference to the relevant documentation. • Create and configure a queue manager. • Test a queue manager configuration. • Start and stop a queue manager and perform other simple administration tasks. Transition Statement — First, some hints on the planning an WebSphere MQ implementation.




2-5

Instructor Guide

2-6





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.

Instructor Topic Introduction 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.




2-7

Instructor Guide

1DPLQJ:HE6SKHUH042EMHFWV $OORZDEOHFKDUDFWHUVHW $=D] B 0D[LPXPRIFKDUDFWHUVIRUWKHQDPHVRI 4XHXHV 3URFHVVHV 4XHXHPDQDJHUV 0D[LPXPRIFKDUDFWHUVIRUWKHQDPHVRI &KDQQHOV 1RLPSOLHGVWUXFWXUHLQDQDPH 1RWH1DPHVLQ:HE6SKHUH04DUHFDVHVHQVLWLYH

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.

2-8





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. Additional Information — None. Transition Statement — After installation, the first WebSphere MQ object to be created is a queue manager.




2-9

Instructor Guide

4XHXH0DQDJHU *HQHUDOO\RQHSHUV\VWHP 0D\FUHDWHDGGLWLRQDORQHVWKDWLVIRUDWHVWHQYLURQPHQW 1DPH 8VXDOO\VKRUW )RUH[DPSOHVDPHDVWKH7&3,3KRVWQDPHWKH:LQGRZV V\VWHPQDPHRUDQ61$/8DOLDV 6KRXOGEHXQLTXHZLWKLQDQHWZRUN

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.





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.




2-11

Instructor Guide

4XHXHV $ORFDOTXHXHVWRUHVPHVVDJHV 2WKHUTXHXHW\SHV $OLDVTXHXH /RFDOGHILQLWLRQRIDUHPRWHTXHXH 0RGHOTXHXHDQGG\QDPLFTXHXH 4XHXHW\SHLVWUDQVSDUHQWWRWKHDSSOLFDWLRQ 0RGHODQGG\QDPLFTXHXHVDUHWKHH[FHSWLRQ 8VHIXOQDPLQJFRQYHQWLRQV 7KHQDPHRIDTXHXHVKRXOGGHVFULEHLWVIXQFWLRQQRWLWVW\SH RUORFDWLRQ $FRPPRQSUHIL[IRUWKHQDPHVRIUHODWHGTXHXHVVLPSOLILHV DGPLQLVWUDWLRQ

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.





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. Additional Information — None. Transition Statement — Next we look at some special local queues that are used by WebSphere MQ.




2-13

Instructor Guide

6SHFLDO/RFDO4XHXHV 'HDGOHWWHUTXHXH 2QHSHUTXHXHPDQDJHU 'HVLJQDWHGTXHXHIRUPHVVDJHVWKDWFDQQRWEHGHOLYHUHG $OZD\VVHWXSDGHDGOHWWHUTXHXH ,QLWLDWLRQTXHXHV 8VHGIRUWULJJHULQJ 7UDQVPLVVLRQTXHXHV &RPPDQGTXHXH (YHQWTXHXHV 'HIDXOWTXHXHV

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. 2-14 WebSphere MQ System Administration I




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.




2-15

Instructor Guide

Instructor Notes: Purpose — To introduce some special local queues that are used by WebSphere MQ. Details — Additional Information — None. Transition Statement — Next we look at message channels.





Uempty

0HVVDJH&KDQQHO

0 & $

61$/87&3,3DQG VRIRUWK

0 & $

04*(7

04387

W4

4

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.




2-17

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.





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. Details — Nothing in addition to the student notes. Additional Information — None. Transition Statement — Next we look at the various administration interfaces provided by WebSphere MQ.




2-19

Instructor Guide

$GPLQLVWUDWLRQ,QWHUIDFHV :HE6SKHUH04FRPPDQGV046& (QWHUHGE\PHDQVRIDVXSSOLHGLQWHUIDFH 3URJUDPPDEOH&RPPDQG)RUPDW3&) FRPPDQGV 3XWRQWKHFRPPDQGTXHXHE\DQDSSOLFDWLRQDQGJRWE\WKHFRPPDQGVHUYHU (VFDSH3&)WRHQFDSVXODWHDQ:HE6SKHUH04FRPPDQG 046HULHVFRQWUROFRPPDQGV (QWHUHGDWDFRPPDQGSURPSW $GPLQLVWUDWLRQDSSOLFDWLRQ 3DQHODSSOLFDWLRQRQ:HE6SKHUH04IRU7DQGHP1RQ6WRS.HUQHO *8,RQ:HE6KSHUH04IRU:LQGRZV $GPLQLVWUDWLRQ,QWHUIDFHVRQ:LQGRZV 26&/FRPPDQGV ,1,ILOHDQG04'ILOHRQ:HE6SKHUH04IRU:LQGRZV (YHQWPHVVDJHV 3XWRQDQHYHQWTXHXHE\WKHTXHXHPDQDJHUDQGJRWWHQE\DQDSSOLFDWLRQ

Figure 2-7. Administration Interfaces

MQ157.0

Notes:





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.




2-21

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 don’t 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.





• The WebSphere MQ CL commands are described in the WebSphere MQ for iSeries V5.3 System Administration Guide.

Uempty

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. Additional Information — None. Transition Statement — With the introduction of WebSphere MQ for Windows V5.1, there are several new available interfaces.




2-23

Instructor Guide

:HE6SKHUH04:LQGRZV $GPLQLVWUDWLRQ,QWHUIDFHV $GGLWLRQDOWRSUHYLRXVO\OLVWHG :HE6SKHUH04([SORUHU :HE6SKHUH046HUYLFHVVQDSLQXQGHU0LFURVRIW0DQDJHPHQW &RQVROH00& :HE6SKHUH04:HE$GPLQLVWUDWLRQ

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 2-24 WebSphere MQ System Administration I




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. © Copyright IBM Corp. 1996, 2003



2-25

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.





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 Additional Information — None. Transition Statement — End of the topic. Now we are ready to create and configure a queue manager.




2-27

Instructor Guide





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.

Instructor Topic Introduction 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.




2-29

Instructor Guide

,QVWDOODWLRQ *HQHUDOO\ OLNHLQVWDOOLQJRWKHUVRIWZDUHRQWKHVDPHSODWIRUP 046HULHVIRU $,; 60,7 $OVRDQHDV\LQVWDOODWLRQ 1&581,; V\VDGPRUSNJDGG &RPSDT2SHQ906 906,167$/ +38; VZLQVWDOO 26:DUS ,167$// &,'HQDEOHG 26 *2/,&3*0 /LQX[ 5HG+DW3DFNDJH0DQDJHU

6,1,;DQG'&26[ SNJDGG'&26[ V\VDGP6,1,; 6XQ26 5XQWKHVXSSOLHGLQVWDOODWLRQVFULSWIURPWKH &'520 6XQ6RODULV SNJDGG 7DQGHP1RQ6WRS.HUQHO 5(6725(WKHQUXQWKHVXSSOLHGLQVWDOODWLRQ XWLOLW\LQVWPTP :LQGRZV

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. 2-30 WebSphere MQ System Administration I




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.




2-31

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.





Uempty

&UHDWH4XHXH0DQDJHU

FUWPTPT40JU1DPH
GOWPTP40JU1DPH

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. © Copyright IBM Corp. 1996, 2003



2-33

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.





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. Additional Information — None. Transition Statement — The next step is to start the queue manager.




2-35

Instructor Guide

6WDUW4XHXH0DQDJHU

VWUPTP40JU1DPH ,IVWDUWHGIRUWKHILUVWWLPHFUHDWHWKHV\VWHPDQGGHIDXOWREMHFWV

UXQPTVF40JU1DPHDPTVFRPDWVW EXWQRWRQD9HUVLRQTXHXHPDQDJHU

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 MQSeries for Tandem NonStop Kernel runmqsc /IN $SYSTEM.ZMQSSMPL.AMQSCOMA/ QMgrName Websphere MQ on UNIX systems runmqsc QMgrName < mqmtop/samp/amqscoma.tst 2-36 WebSphere MQ System Administration I




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.




2-37

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.





Uempty

:HE6SKHUH04046&&RPPDQGV

'(),1(4/2&$/0
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.




2-39

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.





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. Additional Information — None. Transition Statement — Next we look at how WebSphere MQ commands are entered.




2-41

Instructor Guide

5XQ:HE6SKHUH04&RPPDQGV

UXQPTVF40JU1DPH 6WDQGDUGLQSXWGHYLFH!UXQPTVF!VWDQGDUGRXWSXW GHYLFH 2SWLRQDOSDUDPHWHUV H'RQ WFRS\WKHVRXUFHWH[WWRWKHRXWSXWUHSRUW Y3HUIRUPDV\QWD[FKHFNRQO\

UXQPTVFH40JU1DPH UXQPTVFPTVFLQ!PTVFRXW

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





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.




2-43

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.





Uempty

&UHDWLQJD/RFDO4XHXH

'(),1(4/2&$/0
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.




2-45

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.





Uempty

Instructor Notes: Purpose — To explain how to create a local queue. Details — Nothing in addition to the student notes. Additional Information — None. Transition Statement — Next we see how to display the attributes of the WebSphere MQ objects we have created so far.




2-47

Instructor Guide

'LVSOD\LQJ$WWULEXWHV 'LVSOD\DOOWKHDWWULEXWHVRIDTXHXH ',63/$<48(8(;;; $// ',63/$<4/2&$/;;; 9DQG$6TXHXHPDQDJHUVRQO\ 'LVSOD\VHOHFWHGDWWULEXWHVRIDTXHXH ',63/$<48(8(;;; '(6&5*(7387 ',63/$<48(8(<<< 0$;'(37+&85'(37+

*HQHULFTXHXHQDPHVDUHDOORZHG ',646<67(0 'LVSOD\DOOWKHDWWULEXWHVRIWKHTXHXHPDQDJHUREMHFW ',63/$<40*5$// ',63/$<40*59DQG$6TXHXHPDQDJHUVRQO\

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.





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.




2-49

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 Additional Information — None. Transition Statement — Next we look at the other types of queue.





Uempty

2WKHU4XHXH7\SHV $OLDVTXHXH '(),1(4$/,$6$$$ 7$5*4;;; /RFDOGHILQLWLRQRIDUHPRWHTXHXHUHPRWHTXHXHGHILQLWLRQ '(),1(45(027(%%% 51$0(<<< 5401$0(40 0RGHOTXHXH 7(03'<1G\QDPLFTXHXHGHOHWHGZKHQFORVHG 3(50'<1G\QDPLFTXHXHPD\KROGSHUVLVWHQWPHVVDJHV '(),1(402'(/$164 '()7<3(7(03'<1

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 © Copyright IBM Corp. 1996, 2003



2-51

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.





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. Additional Information — None. Transition Statement — Next we look at some more WebSphere MQ commands that we can use.




2-53

Instructor Guide

0RUH:HE6SKHUH04&RPPDQGV $OWHUVHOHFWHGDWWULEXWHV $/7(54/2&$/;;; 387',6$%/(' $/7(54$/,$6$$$ 7$5*4<<< $/7(540*5'(6&5 1HZGHVFULSWLRQ 7KHIROORZLQJDUHRQO\YDOLGLIWKHTXHXHLVQRWLQXVH 'HOHWHDTXHXH '(/(7(4/2&$/;;; '(/(7(45(027(%%% 'HOHWHDOOPHVVDJHVRQDORFDOTXHXH &/($54/2&$/;;;

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





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. Additional Information — None. Transition Statement — Next we look at some useful sample programs that are supplied with WebSphere MQ.




2-55

Instructor Guide

6DPSOH3URJUDPV :KDW VDYDLODEOH &DQG&2%2/VRXUFH &H[HFXWDEOHV 5HDGIURPWKHVWDQGDUGLQSXWGHYLFHDQGSXWPHVVDJHV DPTVSXW41DPH>40JU1DPH@ *HWPHVVDJHVDQGZULWHWRWKHVWDQGDUGRXWSXWGHYLFH DPTVJHW41DPH>40JU1DPH@ 'LVSOD\PHVVDJHVLQFOXGLQJPHVVDJHGHVFULSWRUV DPTVEFJ41DPH40JU1DPH

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 MQSeries for Tandem NonStop Kernel $SYSTEM.ZMQSSMPL WebSphere MQ on UNIX systems 2-56 WebSphere MQ System Administration I




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.




2-57

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. Additional Information — None. Transition Statement — Finally, we describe how to end the operation of a queue manager.





Uempty

(QG4XHXH0DQDJHU &RQWUROOHGRUTXLHVFHG $OORZVFRQQHFWHGDSSOLFDWLRQVWRHQGEXWQRQHZRQHV HQGPTP40JU1DPH ,PPHGLDWH &RPSOHWHVDOOFXUUHQW04,FDOOVEXWQRQHZRQHV HQGPTPL40JU1DPH 3UHHPSWLYH 6WRSVZLWKRXWZDLWLQJIRUDSSOLFDWLRQVWRGLVFRQQHFW RUIRU04,FDOOVWRFRPSOHWH HQGPTPS40JU1DPH

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. © Copyright IBM Corp. 1996, 2003



2-59

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.





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.




2-61

Instructor Guide





Uempty

Checkpoint Unit 2 Checkpoint 1. T/F Queue manager names can be made up of any printable ASCII characters. Correct Answer: False 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




2-63

Instructor Guide

8QLW6XPPDU\ ,PSOHPHQWDWLRQSODQQLQJ &RQILJXULQJDTXHXHPDQDJHU ([HUFLVH


MQ157.0

Notes:





Uempty

Instructor Notes: Purpose — To summarize the unit. 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. Additional Information — None. Transition Statement — End of the unit. Next we shall look at the MQI and triggering.




2-65

Instructor Guide





Uempty

Unit 3. The MQI and Triggering What This Unit is About This unit commences with an introduction to some of the more important features of the MQI and is followed by a description of triggering in some detail. Finally, WebSphere MQ Publish/Subscribe, which requires application involvement, is covered from the administrative viewpoint. There is a practical exercise on configuring WebSphere MQ for triggering and reply-to queues.

What You Should Be Able to Do After completing this unit, you should be able to: • Describe some of the more important features of the MQI • Configure WebSphere MQ to enable triggering • Determine the cause if triggering fails to occur • Explain WebSphere MQ Publish/Subscribe and know the major administrative requirements

How You Will Check Your Progress Accountability: • Checkpoint questions • Machine exercises • Classroom discussion



SC34-6055


If iSeries: SC34-6070


WebSphere MQ for iSeries V5.3 System Administration

Unit 3. The MQI and Triggering


3-1

Instructor Guide

8QLW2EMHFWLYHV $IWHUFRPSOHWLQJWKLVXQLW\RXVKRXOGEHDEOHWR 3URYLGHDQRYHUYLHZRIWKH0HVVDJH4XHXLQJ,QWHUIDFH 'HVFULEHWKHWULJJHULQJSURFHVV (QDEOHWULJJHULQJIRUDORFDOTXHXH ([SODLQFRQGLWLRQVWKDWFDXVHWULJJHULQJWRIDLO ([DPLQHSXEOLVKVXEVFULEHDQGNQRZZKHUHLWLVVXSSRUWHG


MQ157.0

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.

3-2





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. After completing this unit, the student should be able to: • Describe some of the more important features of the MQI. • Configure WebSphere MQ to enable triggering. • Determine the cause if triggering fails to occur. • 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.




3-3

Instructor Guide

3-4





Uempty

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

Instructor Topic Introduction What students will do — Students will listen to a presentation on the MQI. How students will do it — No student activities are planned for this topic. What students will learn — Students will learn about the more important features of the MQI. How this will help students on their job — This knowledge will help the students to 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.




3-5

Instructor Guide

1RWDWLRQ :HE6SKHUH04$SSOLFDWLRQ3URJUDPPLQJ5HIHUHQFH 04387+FRQQ2EM'HVF0VJ'HVF3XW0VJ2SWV%XIIHU/HQJWK%XIIHU &RPS&RGH5HDVRQ

(TXLYDOHQWLQ& 04387+FRQQ 2EM'HVF 0VJ'HVF 3XW0VJ2SWV%XIIHU/HQJWK%XIIHU &RPS&RGH 5HDVRQ

(TXLYDOHQWLQ&2%2/ &$//0438786,1*+&2112%-'(6&06*'(6&38706*2376 %8))(5/(1*7+%8))(5&203&2'(5($621

Figure 3-2. Notation

MQ157.0

Notes:

3-6





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. Additional Information — None. 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.




3-7

Instructor Guide

&RPPRQ3DUDPHWHUV +FRQQFRQQHFWLRQKDQGOH 5HWXUQHGE\WKH04&211DQG04&211;FDOOV ,QSXWSDUDPHWHURQDOORWKHU04,FDOOV &RPS&RGHFRPSOHWLRQFRGH 04&&B2. 04&&B:$51,1* 04&&B)$,/(' 5HDVRQUHDVRQFRGH 045&B 045&B121(

Figure 3-3. Common Parameters

MQ157.0

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

3-8





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. Additional Information — None. Transition Statement — Next we look at the object descriptor, another parameter on the MQPUT1 call and an example of a structure in the MQI.




3-9

Instructor Guide

2EMHFW'HVFULSWRU 2EMHFW7\SH 0427B4TXHXH 0427B352&(66SURFHVV 0427B4B0*5TXHXHPDQDJHU 2EMHFW1DPH 0XVWEHEODQNLI2EMHFW7\SHLV0427B4B0*5 (YHU\REMHFWGHILQHGWRDTXHXHPDQDJHUKDVDXQLTXHQDPH ZLWKLQLWVW\SH 2EMHFW40JU1DPH %ODQNGHQRWHVWKHORFDOTXHXHPDQDJHU '\QDPLF41DPH 6SHFLILHVWKHQDPHRIWKHG\QDPLFTXHXHWREHFUHDWHG $OWHUQDWH8VHU,G $OWHUQDWLYHXVHULGHQWLILHUIRUFKHFNLQJWKHDXWKRUL]DWLRQWRRSHQ WKHREMHFW 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.





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. Additional Information — None. Transition Statement — Next we look more closely at the MQI calls starting with MQCONN, MQCONNX, and MQDISC.




3-11

Instructor Guide

&RQQHFWLQJDQG'LVFRQQHFWLQJ &RQQHFWTXHXHPDQDJHU 04&21140JU1DPH+FRQQ&RPS&RGH5HDVRQ

04&211;40JU1DPH&RQQHFW2SWV+FRQQ&RPS&RGH5HDVRQ :HE6SKHUH04TXHXHPDQDJHUV YHUVLRQFOLHQWVRQO\

'LVFRQQHFWTXHXHPDQDJHU 04',6&+FRQQ&RPS&RGH5HDVRQ

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.





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.




3-13

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. Additional Information — None. Transition Statement — Next we look at the MQOPEN and MQCLOSE calls.





Uempty

2SHQLQJDQG&ORVLQJDQ2EMHFW 2SHQREMHFW 0423(1+FRQQ2EM'HVF2SWLRQV+REM&RPS&RGH5HDVRQ 7KHREMHFWKDQGOH+REMLGHQWLILHVWKHREMHFWLQODWHUFDOOV 2SHQRSWLRQVFDQEHDGGHGWRJHWKHUIRUH[DPSOHLQ&

2SWLRQV 0422B,1387B6+$5('0422B)$,/B,)B48,(6&,1*

&ORVHREMHFW 04&/26(+FRQQ+REM2SWLRQV&RPS&RGH5HDVRQ

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. © Copyright IBM Corp. 1996, 2003



3-15

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.





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. Additional Information — None. Transition Statement — Next we look at the dynamic queue which is created by an MQOPEN call.




3-17

Instructor Guide

'\QDPLF4XHXH &UHDWHGZKHQDPRGHOTXHXHLVRSHQHG )ROORZLQJILHOGVLQWKHREMHFWGHVFULSWRUDUHVHWEHIRUHWKH 0423(1FDOO 2EMHFW1DPHLGHQWLILHVWKHPRGHOTXHXH '\QDPLF41DPHVSHFLILHVWKHQDPHRIWKHG\QDPLFTXHXHWR EHFUHDWHG $IWHUWKH0423(1FDOO 2EMHFW1DPHFRQWDLQVWKHQDPHRIWKHG\QDPLFTXHXH 7HPSRUDU\G\QDPLFTXHXH 'HOHWHGZKHQWKHTXHXHLVFORVHG 'RHVQRWVXUYLYHDTXHXHPDQDJHUUHVWDUW &DQVWRUHQRQSHUVLVWHQWPHVVDJHVRQO\ 3HUPDQHQWG\QDPLFTXHXH &DQEHGHOHWHGE\DQRSWLRQRQWKH04&/26(FDOO 6XUYLYHVDTXHXHPDQDJHUUHVWDUW &DQVWRUHSHUVLVWHQWPHVVDJHV

Figure 3-7. Dynamic Queue

MQ157.0

Notes: • A permanent dynamic queue may also be deleted by using the WebSphere MQ command DELETE QLOCAL.





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. Additional Information — None. Transition Statement — Next we look at the scope of the handles that are returned by the MQCONN and MQOPEN calls.




3-19

Instructor Guide

3XW0HVVDJH

MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer, CompCode, Reason)

0VJ'HVF

0HVVDJHGHVFULSWRU ,QSXWILHOGVVHWE\WKH DSSOLFDWLRQRXWSXWILHOGV E\WKHTXHXHPDQDJHU

3XW0VJ2SWV

%XIIHU/HQJWK

/HQJWKRIWKHPHVVDJHLQ %XIIHU

%XIIHU

0HVVDJHGDWD

2SWLRQVIRUH[DPSOH 04302B6<1&32,17 04302B)$,/B,)B48,(6&,1*

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. Hconn


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





structure, Options, is used by the application to specify options that control the action of MQPUT.

Uempty BufferLength

The length of the message in the Buffer. Buffer

The message data.




3-21

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. Additional Information — None. Transition Statement — Next we look at message priority.





Uempty

3ULRULW\ 3ULRULW\ )LHOGLQWKHPHVVDJHGHVFULSWRUVHWE\DQDSSOLFDWLRQWRRQHRI WKHIROORZLQJ $YDOXHLQWKHUDQJHORZHVW WRKLJKHVW 0435,B35,25,7
Figure 3-9. Priority

MQ157.0

Notes:




3-23

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. Additional Information — None. Transition Statement — Next we look at how to get a message from a queue.





Uempty

*HW0HVVDJH MQGET (Hconn, Hobj, MsgDesc, GetMsgOpts, BufferLength, Buffer, DataLength, CompCode, Reason)

*HW0VJ2SWV

%XIIHU/HQJWK

2SWLRQVIRUH[DPSOH 04*02B$&&(37B7581&$7('B06* 04*02B%52:6( 04*02B&219(57 04*02B)$,/B,)B48,(6&,1* 04*02B6<1&32,17 04*02B:$,7 :DLW,QWHUYDO

/HQJWKRIWKH%XIIHUDUHD

%XIIHU

$UHDWRFRQWDLQWKH PHVVDJH GDWD

'DWD/HQJWK

/HQJWKRIWKHPHVVDJH

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. Hconn


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 © Copyright IBM Corp. 1996, 2003



3-25

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.





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. Additional Information — None. Transition Statement — Next we look at the role of the reply-to queue.




3-27

Instructor Guide

5HSO\WR4XHXH 7KHTXHXHWRZKLFKUHSO\DQGUHSRUWPHVVDJHVVKRXOGEHVHQW 0HVVDJHGHVFULSWRUILHOGVVHWE\WKHDSSOLFDWLRQSULRUWRDQ04387 FDOO 5HSO\7R4 &DQEHWKHQDPHRIDG\QDPLFTXHXHRUDUHSO\WRTXHXHDOLDV 5HSO\7R40JU &DQEHVHWWREODQN 4XHXHQDPHUHVROXWLRQPD\RFFXURQDQ04387FDOO ,I5HSO\7R40JULVEODQNWKHQ LI5HSO\7R4LVDUHSO\WRTXHXHDOLDVWKHQ 5HSO\7R4DQG5HSO\7R40JUDUHVHWWRYDOXHVIURPWKHUHSO\WRTXHXH DOLDVGHILQLWLRQ HOVH 5HSO\7R40JULVVHWWRWKHQDPHRIWKHORFDOTXHXHPDQDJHU HQGLI HQGLI

Figure 3-11. Reply-to Queue

MQ157.0

Notes:





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. Additional Information — None. Transition Statement — Next we look at some more fields in the message descriptor.




3-29

Instructor Guide

0RUH)LHOGVLQWKH0HVVDJH'HVFULSWRU 0VJ7\SH

0407B'$7$*5$0 0407B5(48(67 0407B5(3/< 0407B5(3257

5HSRUW

5HSRUWRSWLRQVIRUH[DPSOH 0452B(;&(37,21 0452B(;3,5$7,21 0452B&2$ 0452B&2' 0452B',6&$5' 0452B3$1 0452B1$1

([SLU\ ([SLU\WLPH

)HHGEDFN

8VHGLQDUHSRUWPHVVDJH )HHGEDFNRUUHDVRQFRGHIRU H[DPSOH 04)%B(;3,5$7,21 04)%B&2$ 04)%B&2' 045&B4B)8// 045&B127B$87+25,=(' 04)%B48,7 04)%B3$1 04)%B1$1

Figure 3-12. More Fields in the Message Descriptor

MQ157.0

Notes:





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. Additional Information — None. Transition Statement — Next we look at message and correlation identifiers.




3-31

Instructor Guide

0HVVDJHDQG&RUUHODWLRQ,GHQWLILHUV 7ZRILHOGVLQWKHPHVVDJHGHVFULSWRU 0VJ,GPHVVDJHLGHQWLILHU ,IDQDSSOLFDWLRQVSHFLILHV040,B121(RQDQ04387FDOOWKH TXHXHPDQDJHUJHQHUDWHVDXQLTXHPHVVDJHLGHQWLILHU &RUUHO,GFRUUHODWLRQLGHQWLILHU ,QDUHSO\RUUHSRUWPHVVDJHLWLVQRUPDOO\FRSLHGIURPWKH0VJ,G RIWKHRULJLQDOPHVVDJH %RWKILHOGVDUHWUHDWHGDVELWVWULQJVE\WKHTXHXHPDQDJHU 1RWVXEMHFWWRDQ\GDWDFRQYHUVLRQ

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. 3-32 WebSphere MQ System Administration I




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.




3-33

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. Additional Information — None. Transition Statement — Next we look at the role of the MsgId and CorrelId fields when messages are being retrieved from a queue.





Uempty

5HWULHYLQJ0HVVDJHV :LWKVHOHFWLRQFULWHULD 6HW0VJ,GDQGRU&RUUHO,GSULRUWRDQ04*(7FDOO $OVRHQVXUHWKDW0DWFK2SWLRQVLQJHWPHVVDJHRSWLRQVLVVHWWR 0402B0$7&+B06*B,'0402B0$7&+B&255(/B,' 9HUVLRQDQGL6HULHVTXHXHPDQDJHUVRQO\ :LWKRXWVHOHFWLRQFULWHULD 5HVHW0VJ,GDQG&RUUHO,GWR040,B121(DQG04&,B121( UHVSHFWLYHO\EHIRUHHDFK04*(7FDOO 2UVHW0DWFK2SWLRQVLQJHWPHVVDJHRSWLRQVWR0402B121( 9HUVLRQDQGL6HULHVTXHXHPDQDJHUVRQO\ 2QUHWXUQIURPDQ04*(7FDOO0VJ,GDQG&RUUHO,GDUHVHWWRWKH YDOXHVIRUWKHPHVVDJHUHWULHYHG

Figure 3-14. Retrieving Messages

MQ157.0

Notes:




3-35

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. Additional Information — None. 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.





Uempty

2UGHURI5HWULHYLQJ0HVVDJHV 0HVVDJHVRQDTXHXHFDQEHUHWULHYHGE\DQDSSOLFDWLRQLQWKH VDPHRUGHUWKH\ZHUHSXWE\DQRWKHUDSSOLFDWLRQSURYLGHG 7KHPHVVDJHVDOOKDYHWKHVDPHSULRULW\ 7KHPHVVDJHVZHUHDOOSXWZLWKLQWKHVDPHXQLWRIZRUNRUDOO SXWRXWVLGHRIDXQLWRIZRUN 1RRWKHUDSSOLFDWLRQLVJHWWLQJPHVVDJHVIURPWKHTXHXH 7KHTXHXHLVORFDOWRWKHSXWWLQJDSSOLFDWLRQ %XWWKH\PD\EHLQWHUVSHUVHGZLWKPHVVDJHVSXWE\RWKHU DSSOLFDWLRQV ,IWKHTXHXHLVQRWORFDOWRWKHSXWWLQJDSSOLFDWLRQWKHRUGHURI UHWULHYDOLVVWLOOSUHVHUYHGSURYLGHG 7KHILUVWWKUHHFRQGLWLRQVDERYHVWLOODSSO\ 2QO\DVLQJOHSDWKLVFRQILJXUHGIRUWKHPHVVDJHV 1RPHVVDJHLVSXWRQDGHDGOHWWHUTXHXH 1RQRQSHUVLVWHQWPHVVDJHVDUHWUDQVPLWWHGRYHUDIDVWPHVVDJH FKDQQHO

Figure 3-15. Order of Retrieving Messages

MQ157.0

Notes:




3-37

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 Compaq OpenVMS 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. Additional Information — None.





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.




3-39

Instructor Guide

0HVVDJH*URXS Message group

Logical message 1

Logical message 2

Logical message 3

$PHVVDJHJURXS &RQVLVWVRIRQHRUPRUHORJLFDOPHVVDJHV $ORJLFDOPHVVDJHLV $SK\VLFDOPHVVDJHXQOHVVLWLVVSOLWLQWRVHJPHQWV ,GHQWLILHGE\WKH*URXS,GDQG0VJ6HT1XPEHUILHOGVLQWKH PHVVDJHGHVFULSWRU 1HHGHG 7RHQVXUHRUGHULQJRQUHWULHYDOZKHUHLWLVQRWDOUHDG\ JXDUDQWHHG 7RDOORZDQDSSOLFDWLRQWRJURXSWRJHWKHUUHODWHGPHVVDJHV 9HUVLRQDQGL6HULHVTXHXHPDQDJHUVRQO\ 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. 3-40 WebSphere MQ System Administration I




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.




3-41

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. Additional Information — None. Transition Statement — Next, we look at the concept of message segmentation.





Uempty

0HVVDJH6HJPHQWDWLRQ Message group

Logical message 1

Logical message 2

Logical message 3

Segment 2

Segment 1

$VHJPHQWLV $SK\VLFDOPHVVDJH ,GHQWLILHGE\WKH*URXS,G0VJ6HT1XPEHUDQG2IIVHWILHOGVLQ WKHPHVVDJHGHVFULSWRU 6HJPHQWDWLRQLVQHHGHGZKHQDPHVVDJHLVWRRODUJHIRUDQ DSSOLFDWLRQDTXHXHRUDTXHXHPDQDJHU $PHVVDJHFDQEHVHJPHQWHGDQGUHDVVHPEOHG %\WKHTXHXHPDQDJHU %\DQDSSOLFDWLRQ 9HUVLRQDQGL6HULHVTXHXHPDQDJHUVRQO\ 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.




3-43

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.





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. Additional Information — None. Transition Statement — To finish the topic, we shall now look at how a distribution list works.




3-45

Instructor Guide

'LVWULEXWLRQ/LVW Version 5 and iSeries queue managers only

CALL MQOPEN . . . CALL MQPUT . . .

DALLAS

HURSLEY

? PARIS

?

Distribution list 2EMHFW1DPH

2EMHFW40JU1DPH

DALLAS

SEATTLE

0$,/B,1B+856/(< 0$,/B,1B3$5,6 0$,/B,1B'$//$6 0$,/B,1B6($77/( MAIL_IN MAIL_IN 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 3-46 WebSphere MQ System Administration I




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.




3-47

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. Additional Information — None. Transition Statement — End of the topic. The next topic is about triggering.





Uempty

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

Instructor Topic Introduction 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. How this will help students on their job — This knowledge will help the students to understand the requirements of triggering from the point of view of administration.




3-49

Instructor Guide

&RPSRQHQWVRI7ULJJHULQJ 4XHXH0DQDJHU 3URJUDP%

$SSOLFDWLRQ 4XHXH

04*(7$4

3URJUDP$

04387$4

3URFHVV 2EMHFW

7ULJJHU0RQLWRU

04*(7,4

,QLWLDWLRQ 4XHXH

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.





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.




3-51

Instructor Guide

4XHXH$WWULEXWHV&RQWUROOLQJ7ULJJHULQJ '(),1(4/2&$/0
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.





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.




3-53

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.





Uempty

3URFHVV$WWULEXWHV '(),1(352&(66(&+2 $33/,&,' RSWPTPVDPSELQDPTVHFK $33/,&,'VWULQJ 1DPHRIWKHDSSOLFDWLRQWREHVWDUWHG $33/7<3(26 $33/7<3(81,; (195'$7$VWULQJ )RUXVHE\WKHWULJJHUPRQLWRU 86(5'$7$VWULQJ )RUXVHE\WKHWULJJHUPRQLWRURUWKHVWDUWHGDSSOLFDWLRQ

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




3-55

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. Additional Information — None. Transition Statement — Next we look at the conditions for a trigger event to occur.





Uempty

&RQGLWLRQVIRUD7ULJJHU(YHQW $PHVVDJHLVSXWRQDTXHXH 3ULRULW\RIWKHPHVVDJHLVQRWEHORZ75,*035, 1XPEHURIPHVVDJHVSUHYLRXVO\RQWKHTXHXHLVFRUUHFWIRU 75,*7<3( 4XHXHLVQRWDOUHDG\RSHQIRULQSXW),567DQG'(37+RQO\ 4XHXHLVHQDEOHGIRUJHWUHTXHVWV 3URFHVVREMHFWH[LVWV ,QLWLDWLRQTXHXHH[LVWVDQGLVHQDEOHGIRUSXWDQGJHWUHTXHVWV 7ULJJHUPRQLWRUKDVWKHLQLWLDWLRQTXHXHRSHQIRULQSXW 4XHXHLVGHILQHGDV75,**(5 4XHXHLVQRWGHILQHGDV75,*7<3(121(

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.




3-57

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.





Uempty

2WKHU&RQGLWLRQVIRUD7ULJJHU(YHQW $PHVVDJHLVSXWRQWKHTXHXHZKLFK :DVQRWSUHYLRXVO\HPSW\),567 +DG75,*'37+RUPRUHPHVVDJHV'(37+ DQGIRUWULJJHUW\SH),567DVXIILFLHQWLQWHUYDOKDVHODSVHGVLQFHWKHODVW

WULJJHUHYHQWDVGHWHUPLQHGE\WKH7ULJJHU,QWHUYDODWWULEXWHRIWKHTXHXH PDQDJHUREMHFW),567DQG'(37+RQO\

2QO\DSSOLFDWLRQVHUYLQJWKHTXHXHFORVHVLW),567DQG'(37+RQO\ $WWULEXWHRIWKHTXHXHFRQWUROOLQJWULJJHULQJLVFKDQJHG ,QLWLDWLRQTXHXHFKDQJHVIURPEHLQJGLVDEOHGWREHLQJHQDEOHGIRU SXWUHTXHVWV 4XHXHFKDQJHVIURPEHLQJGLVDEOHGWREHLQJHQDEOHGIRUJHW UHTXHVWV 7ULJJHUPRQLWRURSHQVWKHLQLWLDWLRQTXHXH )RUHDFKRIWKHDERYHFRQGLWLRQVDWULJJHUHYHQWZLOORQO\RFFXULI

$VXIILFLHQWQXPEHURIPHVVDJHVIRUWKHWULJJHUW\SHDUHDOUHDG\RQWKH TXHXH 2WKHUUHOHYDQWWULJJHUFRQGLWLRQVDUHDOVRVDWLVILHG

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.




3-59

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. Additional Information — None. Transition Statement — Next we look at the contents of a trigger message.





Uempty

)LHOGVLQWKH7ULJJHU0HVVDJH &RSLHGIURPWKHFRUUHVSRQGLQJDWWULEXWHVRIWKHDSSOLFDWLRQTXHXH 41DPH 7ULJJHU'DWD 3URFHVV1DPH &RSLHGIURPWKHFRUUHVSRQGLQJDWWULEXWHVRIWKHSURFHVVREMHFW $SSO7\SH $SSO,G (QY'DWD 8VHU'DWD

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.




3-61

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.





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. Additional Information — None. Transition Statement — Next we look more closely at the trigger monitor and what it does when it gets a trigger message.




3-63

Instructor Guide

7ULJJHU0RQLWRU 7RVWDUWDWULJJHUPRQLWRU UXQPTWUPP40JU1DPHT,QLWLDWLRQ41DPH &RPPDQGLVVXHGE\WULJJHUPRQLWRUWRVWDUWWKHDSSOLFDWLRQ $SSO,G!0470&!(QY'DWD! 2WKHUWULJJHUPRQLWRUV &OLHQWWULJJHUPRQLWRU$,;'LJLWDO2SHQ906DQG26:DUS RQO\ &,&6$,;26:DUSDQG:LQGRZVRQO\ $04675*DQG$046(59L6HULHVRQO\

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. 3-64 WebSphere MQ System Administration I




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.




3-65

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. Additional Information — None. Transition Statement — Next we look at how trigger monitor errors are handled.





Uempty

7ULJJHU0RQLWRU(UURUV 0HVVDJHVDUHSURGXFHGE\WKHIROORZLQJ 1RUPDODFWLYLWLHVIRUH[DPSOH 7ULJJHUPRQLWRUVWDUWHG :DLWLQJIRUDWULJJHUPHVVDJH 7ULJJHUPRQLWRUHQGHG

$EQRUPDOFRQGLWLRQVIRUH[DPSOH ,QLWLDWLRQTXHXHFRXOGQRWEHRSHQHG 8VHRIWULJJHUPRQLWRUQRWDXWKRUL]HG (UURUVWDUWLQJWULJJHUHGDSSOLFDWLRQ $PHVVDJHPD\EHZULWWHQWR 7KHVWDQGDUGRXWSXWGHYLFH $QHUURUORJ $WULJJHUPHVVDJHLVZULWWHQWRWKHGHDGOHWWHUTXHXHLIIRUH[DPSOH 7KHWULJJHUPHVVDJHVWUXFWXUHLVQRWYDOLG 7KHWULJJHUPHVVDJHVSHFLILHVDQXQVXSSRUWHGDSSOLFDWLRQW\SH 7KHWULJJHUPHVVDJHFDQQRWEHFRQYHUWHG

Figure 3-26. Trigger Monitor Errors

MQ157.0

Notes:




3-67

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. Additional Information — None. Transition Statement — End of the topic. There is now a practical exercise on configuring a queue manager for triggering.





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.

Instructor Topic Introduction 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. How this will help students on their job — This knowledge will help the students to understand the benefits of using Publish/Subscribe as well as what is necessary to work with it.




3-69

Instructor Guide

:HE6SKHUH043XEOLVK6XEVFULEH

3XEOLVKHU 7RSLF6SRUW

3XEOLVKHU 7RSLF6WRFN

3XEOLVKHU 7RSLF)LOPV

%52.(5

6XEVFULEHU 7RSLF6SRUW6WRFN

6XEVFULEHU 7RSLF)LOPV

6XEVFULEHU 7RSLF6SRUW

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.





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.




3-71

Instructor Guide

Instructor Notes: Purpose — To introduce WebSphere MQ Publish/Subscribe. Details — Nothing additional. Additional Information — None. Transition Statement — Next, a look at the installation of WebSphere MQ Publish/Subscribe.





Uempty

,QVWDOOLQJ046HULHV3XEOLVK6XEVFULEH 046HULHVRU:HE6SKHUH04IRU$,;+38;6XQ6RODULV/LQX[ DQG:LQGRZV9RUODWHU &6'VUHTXLUHGIRU9 2EWDLQYLDGRZQORDGDVD6XSSRUW3DF0$& &DWHJRU\ 6HSDUDWHILOHVIRUHDFKSODWIRUP 0$'*HWWLQJ6WDUWHGZLWK046HULHV3XEOLVK6XEVFULEH GRFXPHQW&DWHJRU\ 3ULQW8VHU*XLGHDQGIROORZLQVWUXFWLRQVWRUXQ,93

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.




3-73

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. Additional Information — None. Transition Statement — The major piece that requires administrative support is setting up the broker.





Uempty

6HWWLQJ8SWKH%URNHU 4XHXHVIRUHDFKEURNHUDXWRPDWLFDOO\GHILQHGZKHQEURNHUVWDUWVLI WKH\GRQRWH[LVW 6<67(0%52.(5&21752/48(8( 6<67(0%52.(5'()$8/7675($0 6<67(0%52.(5$'0,1675($0 6<67(0%52.(502'(/675($0 6<67(0%52.(5 &UHDWHGE\WKHEURNHUIRULQWHUQDOXVH $XWKRUL]HDSSOLFDWLRQVWRXVHWKHVHTXHXHV 8SGDWHFRQILJXUDWLRQLQIRUPDWLRQ ,QTPLQLRU:LQGRZV175HJLVWU\GHSHQGLQJRQSODWIRUPDQG UHOHDVHOHYHO

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.




3-75

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.





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.




3-77

Instructor Guide

&RQWUROOLQJWKH%URNHU 6WDUWLQJVWUPTEUN &DQEHWULJJHUHG 6WRSSLQJHQGPTEUN 'LVSOD\LQJGVSPTEUN 'HOHWLQJGOWPTEUN &OHDULQJFOUPTEUNH[FHSWLRQDOFRQGLWLRQ 0LJUDWLQJPLJPTEUN

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 3-78 WebSphere MQ System Administration I




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.




3-79

Instructor Guide

Instructor Notes: Purpose — Describe the control commands used to manage the broker. Details — Additional Information — None. Transition Statement — It is possible to extend the capability of the broker with regard to publications.





Uempty

0HVVDJH%URNHU([LWV $OORZFXVWRPL]DWLRQRISXEOLFDWLRQVDWEURNHU &DQDOWHUSXEOLFDWLRQDQG040' &RQILJXUHGLQTPLQLRU:LQGRZV175HJLVWU\ 6DPSOHH[LWSURYLGHG &KDQJHVGHVWLQDWLRQTXHXHRUTXHXHPDQDJHU

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.




3-81

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. Additional Information — None. Transition Statement — Now it is time to review the things learned in this unit and to do a practical exercise.





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. Correct Answer: False 2. A temporary dynamic queue can store: a. b. c. d.

Nonpersistent messages only. Both persistent and non-persistent messages. Reply messages only. 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. Correct Answer: True 5. Which of the following are valid control commands for controlling a broker? (Choose 2) a. b. c. d.

rcrmqbrk dspmqbrk crtmqbrk strmqbrk

Correct Answer: b, d




3-83

Instructor Guide

8QLW6XPPDU\ 7KH04, 7KHPDMRUFDOOV 04&211DQG04',6& 0423(1DQG04&/26( 04387DQG04*(7 6RPHRIWKHPRUHFRPPRQSDUDPHWHUVILHOGVDQGRSWLRQV 0HVVDJHJURXSDQGPHVVDJHVHJPHQWDWLRQ 'LVWULEXWLRQOLVW 7ULJJHULQJ )RFXVRQDGPLQLVWUDWLRQWDVNV 3XEOLVKVXEVFULEHHQDEOHVDSSOLFDWLRQVWRJHWDWGDWDZLWKRXW NQRZLQJWKHVRXUFHRUGHVWLQDWLRQRILW ([HUFLVH


MQ157.0

Notes: The message queue interface (MQI) is the API used in applications to call on the queue manager and its resources to perform work (putting messages on queues, getting messages from queues, changing queue attributes). Use of message-driven processing enables the starting of applications as they are needed, alleviating the requirement to manually start them. This is accomplished through the use of triggering. The WebSphere MQ Publish/Subscribe function allows decoupling of information providers from information recipients. The delivery of any information is handled by a network of brokers.





Uempty

Instructor Notes: Purpose — To summarize the unit. 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. Additional Information — None. Transition Statement — End of the unit. Next, we discuss robust messaging.




3-85

Instructor Guide





Uempty

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

What You Should Be Able to Do After completing this unit, you should be able to: • Determine the state of a queue manager and demonstrate how to recover from a problem • Design procedures to recover messages in the event of a failure • Describe where to look for error messages and other information which may help to identify the cause of a problem • Start and stop WebSphere MQ tracing function




SC34-6055





Unit 4. Robust Messaging


4-1

Instructor Guide

8QLW2EMHFWLYHV $IWHUFRPSOHWLQJWKLVXQLW\RXVKRXOGEHDEOHWR ([SODLQ:HE6SKHUH04DUFKLWHFWXUHDQGIUDPHZRUNDWDKLJKOHYHO 'HVFULEHSUREOHPGHWHUPLQDWLRQDLGVDQGKRZWRXVHWKHP 'HILQHPHVVDJHSHUVLVWHQFH 'HWDLOORJJLQJRSWLRQVRQYDULRXVTXHXHPDQDJHUV ([SODLQWKHSXUSRVHRIWUDQVDFWLRQDOSURFHVVLQJ &RQWUDVWORFDODQGJOREDOXQLWVRIZRUN /LVWH[WHUQDOWUDQVDFWLRQPDQDJHUVDQGZKHUHVXSSRUWHG


MQ157.0

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.

4-2





Uempty

Instructor Notes: Purpose — To highlight the unit objectives. Details — • The structure of WebSphere MQ is described as a basis for what follows. • Aids for problem determination. • Recovery and transactional support. After completing this unit, the student should be able to: • Determine the state of a queue manager and demonstrate how to recover from a problem. • Design procedures to recover messages in the event of a failure. • Describe where to look for error messages and other information which may help to identify the cause of a problem. • Start and stop WebSphere MQ tracing function. Transition Statement — First, a look at the functional components of a WebSphere MQ implementation.




4-3

Instructor Guide

4-4





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.

Instructor Topic Introduction What students will do — Students will listen to a presentation on the WebSphere MQ reference architecture. How students will do it — No student activities are planned for this topic. 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.




4-5

Instructor Guide

$SSOLFDWLRQ

&RPPDQG 6HUYHU

0HVVDJH &KDQQHO $JHQW

7ULJJHU 0RQLWRU

&RPPV

)XQFWLRQDO9LHZ

04,$SSOLFDWLRQ,QWHUIDFH

/RFDO4XHXH 0DQDJHU

&RPPRQ 6HUYLFHV

2$0 4 4 4 4

'$3

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.

4-6





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. Additional Information — None.




4-7

Instructor Guide

Transition Statement — This was a functional description. Next we look at the physical structure.

4-8





Uempty

3K\VLFDO9LHZ

$SSOLFDWLRQ 04,VWXE

([HFXWLRQ &RQWUROOHU

4XHXH 0DQDJHU 5HVRXUFHV

04&211

,3&& 0423(1 04*(7

/40 $JHQW /RJJHU

&KHFNSRLQW 3URFHVVRU

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.




4-9

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 4-10 WebSphere MQ System Administration I




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. Additional Information — None. Transition Statement — Next we look at the resulting process structure.




4-11

Instructor Guide

3URFHVVHV

([HFXWLRQ &RQWUROOHU

DPT][PD

/40 $JHQW DPT]ODD

/RJJHU

/RJ )RUPDWWHU

&KHFNSRLQW 3URFHVVRU

DPTKDVP[

DPTKDUP[

DPT]OOS

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.





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. Additional Information — None. Transition Statement — Next we look at the way that data associated with a queue manager is organized.




4-13

Instructor Guide

'LUHFWRU\6WUXFWXUH 3DWKWRWKHTXHXHPDQDJHUGLUHFWRU\ 3UHIL[ 046B5227>040@046HULHVIRU&RPSDT2SHQ906 ?040?046HULHVIRU26:DUSDQG:HE6SKHUHIRU:LQGRZV YDUPTP046HULHVIRU8QL[6\VWHPV /LWHUDO TPJUV 4XHXHPDQDJHUQDPH 7UDQVIRUPHGQDPHLIQRWDYDOLGILOHV\VWHPQDPH 1DPHRIDTXHXHRUDSURFHVVREMHFW 1RVLPSOHWUDQVIRUPDWLRQWRDILOHV\VWHPQDPH 8VHWKHFRQWUROFRPPDQGGVSPTIOVWRGHWHUPLQHWKHPDSSLQJ

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.





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 $DATA.QMGRD $DATA.QMGRL $DATA.QMGRM $DATA.QMGRS $DATA.QMGRX

FFST subvolume Data files subvolume Error log subvolume Message queue subvolume Channel synchronization subvolume OAM subvolume

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




4-15

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.





Uempty

Additional Information — None. Transition Statement — Next we look at configuration files.




4-17

Instructor Guide

&RQILJXUDWLRQ)LOHV 3XUSRVH 7RGHILQHYDOXHVIRULQGLYLGXDOTXHXHPDQDJHUVDQGIRU :HE6SKHUH04DVDZKROH 7RWDLORUDVSHFLILFTXHXHPDQDJHU 0HFKDQLVP &RQILJXUDWLRQILOHVFRQWDLQLQJKXPDQUHDGDEOHLQIRUPDWLRQ &UHDWLRQ 'XULQJLQVWDOODWLRQDQGTXHXHPDQDJHUFUHDWLRQ 0RGLILFDWLRQ %\FRPPDQGV )RUVSHFLILFSXUSRVHVE\HGLWLQJ 5HFRPPHQGDWLRQ %DFNXSDIWHUVLJQLILFDQWFKDQJHV

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. 4-18 WebSphere MQ System Administration I




Uempty

- The appropriate System Management Guide for each of the remaining queue managers. - WebSphere MQ Intercommunication.




4-19

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. Additional Information — None. Transition Statement — Next we look at the WebSphere MQ configuration file.





Uempty

:HE6SKHUH04&RQILJXUDWLRQ)LOH &UHDWHGZKHQ:HE6SKHUH04LVLQVWDOOHG PTVLQL 'HIDXOWORFDWLRQ 046B5227>040@046HULHVIRU&RPSDT2SHQ906 040GLUHFWRU\RIERRWGULYH046HULHVIRU26:DUS 6<67(0=0466<6046,1,046HULHVIRU7DQGHP16. YDUPTP:HE6SKHUH04IRU8QL[V\VWHPV &RQWHQW 3DWKWRILOHVDVVRFLDWHGZLWKHDFKTXHXHPDQDJHU 'HIDXOWORJSDUDPHWHUVQRWRQ046HULHVIRU7DQGHP 1RQ6WRS.HUQHORU:HE6SKHUH04:LQGRZV179 6WDQ]DIRUHDFKTXHXHPDQDJHU 1DPHRIWKHGHIDXOWTXHXHPDQDJHU :HE6SKHUH04IRU:LQGRZVVWRUHVVLPLODULQIRUPDWLRQLQWKH :LQGRZV5HJLVWU\QRPTVLQL

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.




4-21

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.





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. Additional Information — None. Transition Statement — Next we look an example of the WebSphere MQ configuration file.




4-23

Instructor Guide

046,1,&RQILJXUDWLRQ)LOH #***********************************************************************# #* 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 |

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.





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.




4-25

Instructor Guide

4XHXH0DQDJHU&RQILJXUDWLRQ)LOH &UHDWHGZKHQWKHTXHXHPDQDJHULVFUHDWHG TPLQL ,QWKHTXHXHPDQDJHUGLUHFWRU\ &RQWHQW 7KHTXHXHPDQDJHUORJFRQILJXUDWLRQ QRWRQ:HE6SKHUH04IRU7DQGHP1RQ6WRS.HUQHO 'HWDLOVRILQVWDOODEOHVHUYLFHFRPSRQHQWV 9DOXHVUHODWLQJWRWKHRSHUDWLRQRIFKDQQHOV &RPPXQLFDWLRQVSURWRFROFRQILJXUDWLRQSDUDPHWHUV ;$UHVRXUFHPDQDJHULQIRUPDWLRQ 9HUVLRQTXHXHPDQDJHUVRQO\ :HE6SKHUH04IRU:LQGRZVVWRUHVVLPLODULQIRUPDWLRQLQWKH :LQGRZV5HJLVWU\QRTPLQL

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.





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.




4-27

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. Additional Information — None. Transition Statement — We will look at an example of the queue manager configuration file.





Uempty

40,1,&RQILJXUDWLRQ)LOH #*******************************************************************# #* 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

Figure 4-10. QM.INI Configuration File

MQ157.0

Notes:




4-29

Instructor Guide

Instructor Notes: Purpose — To view the queue manager config file Details — Additional Information — 1. /usr/mqm/bin/amqfuno.o on AIX 2. /usr/mqm/lib/amqzfa on AIX Transition Statement — Next we will look at installable services.





Uempty

,QVWDOODEOH6HUYLFHV )RUPDOLQWHUIDFHVPRUHWKDQH[LWV 0XOWLSOHHQWU\SRLQWV )RUH[DPSOH 1DPH6HUYLFH ,QLWLDOL]H 7HUPLQDWH ,QVHUW 'HOHWH /RRNXS 6HUYLFHFRPSRQHQWVFDQEHFKDLQHG :HE6SKHUH046\VWHP$GPLQLVWUDWLRQ*XLGH

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.




4-31

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. Additional Information — None. Transition Statement — Next we look at the three installable services and the supplied service components.





Uempty

,QVWDOODEOH6HUYLFHVDQG6XSSOLHG&RPSRQHQWV 1DPHVHUYLFH '(),1(4/2&$/ 6HUYLFH4 6&23(&(//

6XSSOLHGFRPSRQHQWXVHV'&( :HE6SKHUH04IRU&RPSDT2SHQ906DQGWKH9HUVLRQ TXHXHPDQDJHUV $XWKRUL]DWLRQVHUYLFH 6XSSOLHGFRPSRQHQWLVWKH2EMHFW$XWKRULW\0DQDJHU2$0 :HE6SKHUH04IRU:LQGRZVL6HULHVDQGRQ81,;V\VWHPV 1RQVWRS.HUQHO046HULHVIRU&RPSDT7DQGHP 8VHULGHQWLILHUVHUYLFH 6XSSOLHGFRPSRQHQWRQ046HULHVIRU26:DUS

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. © Copyright IBM Corp. 1996, 2003



4-33

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.





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: Name=AuthorizationService EntryPoints=8 ServiceComponent: Service=AuthorizationService Name=MQSeries.UNIX.auth.service Module=mqmtop/bin/amqzfu.o ComponentDataSize=0

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. Additional Information — None. Transition Statement — Next we look at how to stop a queue manager manually in case it is ever necessary to do it.




4-35

Instructor Guide

6WRSSLQJD4XHXH0DQDJHU0DQXDOO\ 1RUPDOO\XVHHQGPTP 0D\WDNHWLPH *LYHLWDFKDQFH /$675(6257 )LQGWKHSURFHVVHVWKDWDUHVWLOOUXQQLQJ

SVHI_JUHSDPT 6WRSWKHPLQWKHIROORZLQJRUGHU DPTF&KDQQHOSURFHVVHVILUVW DPT][PD([HFXWLRQFRQWUROOHUODVW

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. 4-36 WebSphere MQ System Administration I




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.




4-37

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. Additional Information — None. Transition Statement — Next we look at how to remove a queue manager manually in case it is ever necessary to do it.





Uempty

5HPRYLQJD4XHXH0DQDJHU0DQXDOO\ 1RUPDOO\

GOWPTP40JU1DPH ,IWKHUHDUHSUREOHPV 'HOHWHWKHTXHXHPDQDJHUGLUHFWRU\DQGLWVFRQWHQWV 'HOHWHWKHDVVRFLDWHGORJGLUHFWRU\DQGLWVFRQWHQWV 5HPRYHWKHTXHXHPDQDJHU VVWDQ]DIURPWKH :HE6SKHUH04FRQILJXUDWLRQILOH 5HPRYHRUFKDQJHWKHDefaultQueueManagerVWDQ]DLI UHTXLUHG :HE6SKHUH04IRU:LQGRZVUHTXLUHVPDQXDOFKDQJHVLQWKH :LQGRZV5HJLVWU\

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.




4-39

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.





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. Additional Information — None. Transition Statement — End of the topic. The next topic is about problem determination.




4-41

Instructor Guide





Uempty

4.2 Problem Determination This topic describes aspects of problem determination.

Instructor Topic Introduction 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. How this will help students on their job — This knowledge will help the students to diagnose problems more readily.




4-43

Instructor Guide

&RQILJXUDWLRQDQG3UREOHP'HWHUPLQDWLRQ (UURUVFDQVWRSDTXHXHPDQDJHUEHLQJIRXQG 48(8(0$1$*(581$9$,/$%/( :KDWWRFKHFN 7KHFRQILJXUDWLRQILOHVH[LVW 7KH\KDYHWKHDSSURSULDWHSHUPLVVLRQV 7KH:HE6SKHUH04FRQILJXUDWLRQILOHRU:LQGRZV5HJLVWU\ UHIHUHQFHVWKHTXHXHPDQDJHUZLWKWKHFRUUHFWLQIRUPDWLRQIRU ORFDWLQJLWVILOHV

Figure 4-15. Configuration Files and Problem Determination

MQ157.0

Notes:





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.




4-45

Instructor Guide

(UURU0HVVDJHV 1RUPDOHUURUVLQFOXGLQJVRPHE\XVHUV ,QFRUUHFWSDUDPHWHURQDFRQWUROFRPPDQG 1/6HQDEOHG :ULWWHQWRWKHDVVRFLDWHGWHUPLQDOLIDQ\DQGWRDQHUURUORJILOH (UURUORJILOH $04(55/2* 2QHLQHDFKRIWKUHHHUURUGLUHFWRULHV 7ZRSUHYLRXVHUURUORJILOHVDUHDOVRNHSW $04(55/2* $04(55/2*

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.





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.




4-47

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. Additional Information — None. Transition Statement — Next we look at unexpected errors.





Uempty

)LUVW)DLOXUH6XSSRUW7HFKQRORJ\))67 8QH[SHFWHGHUURUV ,QWHUQDOTXHXHPDQDJHUIDLOXUH %XWQRWDXWRPDWLFDOO\DQ$3$5 0D\KDYHDVVRFLDWHGVWRUDJHGXPSV 'DWDWRKHOSDQDO\]HVRIWZDUHHYHQWV ,IDQHUURURFFXUV 1RWHDGHVFULSWLRQRIWKHSUREOHP /RRNIRUDQ\UHODWHGHUURUORJHQWULHV ,GHQWLI\DQ\))67UHSRUWV

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.




4-49

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.





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 xc

Function 012

Probe 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. Additional Information — None. Transition Statement — Next we look at tracing.




4-51

Instructor Guide

7UDFH ([WUDLQIRUPDWLRQPD\EHQHHGHGWRILQGDSUREOHP )LOHVFDQEHYHU\ODUJH &DQEHOLPLWHGE\WLPHRUFRPSRQHQW &DQDOVRWUDFHWKH04, 8VHIXODLGWRDSSOLFDWLRQGHEXJJLQJ )RUGHWDLOVRQKRZWRSURGXFHDWUDFH :HE6SKHUH046\VWHP$GPLQVWUDWLRQ*XLGHIRUD9HUVLRQ TXHXHPDQDJHU :HE6SKHUH04IRUL6HULHV96\VWHP$GPLQLVWUDWLRQ *XLGH 7KHUHOHYDQW6\VWHP0DQDJHPHQW*XLGHIRUHDFKRIWKH UHPDLQLQJTXHXHPDQDJHUV

Figure 4-18. Trace

MQ157.0

Notes:





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. Additional Information — None. Transition Statement — End of the topic. The next topic is about transactions and recovery.




4-53

Instructor Guide





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.

Instructor Topic Introduction 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.




4-55

Instructor Guide

0HVVDJH3HUVLVWHQFH $SSOLFDWLRQ 3URJUDP 3HUVLVWHQWPHVVDJH

04387

4XHXH 0DQDJHU 4XHXH

Log &&5&

3HUVLVWHQWPHVVDJHVDUHUHFRYHUHGRQ UHVWDUWLIQHFHVVDU\ 4XHXH 1RQSHUVLVWHQWPHVVDJH

1RQSHUVLVWHQWPHVVDJHVDUHH[SUHVVO\ GLVFDUGHGRQUHVWDUW /RJJLQJKDVDSHUIRUPDQFHLPSDFW

04387

&&5&

'HI3HUVLVWHQFHDWWULEXWHRIDTXHXH $Q\TXHXHPD\VWRUHERWKSHUVLVWHQW DQGQRQSHUVLVWHQWPHVVDJHVH[FHSWD WHPSRUDU\G\QDPLFTXHXH

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.





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. Additional Information — None. Transition Statement — Next we look at the types of logging available.




4-57

Instructor Guide

7\SHVRI/RJ &,5&8/$5 /RJILOHVYLHZHGDVD FORVHGORRS $PRXQWRIGLVNVSDFH UHTXLUHGIRUWKHORJGRHV QRWLQFUHDVHZLWKWLPH

/,1($5 /RJILOHVYLHZHGDVD VHTXHQFH /RJILOHQHYHUGHOHWHG%87 %HFRPHVLQDFWLYHZKHQLW FRQWDLQVQRHQWULHV UHTXLUHGWRUHVWDUWWKH TXHXHPDQDJHU &DQEHDUFKLYHGZKHQ LWEHFRPHVLQDFWLYH

1HHGHGIRUPHGLD UHFRYHU\

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.





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. Additional Information — None. Transition Statement — Next we look at how persistent messages are recovered when necessary.




4-59

Instructor Guide

5HFRYHULQJ3HUVLVWHQW0HVVDJHV ,IQHFHVVDU\SHUVLVWHQWPHVVDJHVDUHUHFRYHUHG DXWRPDWLFDOO\ZKHQWKHTXHXHPDQDJHULVUHVWDUWHG $GDPDJHGORFDOTXHXHPD\RQO\EHGHWHFWHGODWHU 5HSRUWHGDVREMHFWGDPDJHG 1RUPDOO\QHHGVWREHUHFRYHUHGPDQXDOO\ ,QRUGHUWRUHVWDUWDTXHXHPDQDJHURQO\UHTXLUHV /RJUHFRUGVZULWWHQVLQFHWKHODVWFKHFNSRLQW /RJUHFRUGVZULWWHQE\WUDQVDFWLRQVWKDWZHUHVWLOODFWLYHDWWKH WLPHWKHTXHXHPDQDJHUVWRSSHG

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.





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. Additional Information — None. Transition Statement — Next we look at media recovery.




4-61

Instructor Guide

'DPDJHG2EMHFWVDQG0HGLD5HFRYHU\ :HE6SKHUH04REMHFWVFDQEHPDUNHGDVGDPDJHG &RUUXSWGDWDLQWKHTXHXHILOH 0LVVLQJTXHXHILOH 'LVNIDLOXUH 'DPDJHGREMHFWVFDQEHGHOHWHG $GDPDJHGREMHFWFDQEHUHFUHDWHGIURPD/,1($5ORJ .QRZQDVPHGLDUHFRYHU\ 0HGLDLPDJHVRIVRPHREMHFWVDUHUHFRUGHGDXWRPDWLFDOO\E\WKH TXHXHPDQDJHUDWFHUWDLQWLPHV 5HFRUGWKHPHGLDLPDJHRIDORFDOTXHXHRQDUHJXODUEDVLV XVLQJWKHFRQWUROFRPPDQGrcdmqimg 0HGLDUHFRYHU\ $XWRPDWLFLIDGDPDJHGREMHFWLVGHWHFWHGGXULQJUHVWDUW )RUDORFDOTXHXHLWLVQRUPDOO\GRQHE\XVLQJWKHFRQWURO FRPPDQGrcrmqobj

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.





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. Additional Information — None. Transition Statement — Next we look at how to dump a formatted version of the log on a Version 5 queue manager.




4-63

Instructor Guide

'XPSLQJWKH/RJ 8VHGPSPTORJWRGXPSDIRUPDWWHGYHUVLRQRIWKHORJ 4XHXHPDQDJHUPXVWQRWEHUXQQLQJ %\GHIDXOWWKHGXPSFRPPHQFHVIURPWKHKHDGRIWKHORJ 2SWLRQDOO\WKHGXPSFDQFRPPHQFHIURP 7KHEDVHRIWKHORJ $ORJUHFRUGLGHQWLILHGE\DVSHFLILHGORJVHTXHQFHQXPEHU /61 $ORJILOHLGHQWLILHGE\DVSHFLILHGH[WHQWQXPEHUOLQHDUORJV RQO\ /RJUHFRUGVIRUPDWWHGLQFOXGH 3XWDQGJHWRISHUVLVWHQWPHVVDJHV 7UDQVDFWLRQHYHQWV &UHDWLRQDOWHUDWLRQDQGGHOHWLRQRI:HE6SKHUH04REMHFWV 9HUVLRQTXHXHPDQDJHUVRQO\

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.





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. Additional Information — None. Transition Statement — Next we turn to transactions and the support for syncpoint control.




4-65

Instructor Guide

6\QFSRLQW&RQWURO 04*(7FXVWRPHURUGHU 8SGDWH'% 04387GLVSDWFKUHTXHVW 04387GHOLYHU\FRQILUPDWLRQ &RPPLW 2SWLRQRQ04387DQG04*(7FDOOV 12B6<1&32,17PHVVDJHLVDGGHGRUUHPRYHGLPPHGLDWHO\ 6<1&32,17UHVXOWRIDQ04387RUDQ04*(7FDOORQO\ EHFRPHVYLVLEOHZKHQWKHXQLWRIZRUNLVFRPPLWWHG 'HIDXOWLVSODWIRUPGHSHQGHQW $GGLWLRQDORSWLRQRQDQ04*(7FDOO 6<1&32,17B,)B3(56,67(17DPHVVDJHLVRQO\JRWZLWKLQ V\QFSRLQWFRQWUROLILWLVSHUVLVWHQW

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.





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. Additional Information — None. Transition Statement — Next we look at the design implications of implementing a business transaction as multiple asynchronous units of work.




4-67

Instructor Guide

&RPSHQVDWLQJ7UDQVDFWLRQV 046HULHV$V\QFKURQRXV0RGHO $V\QFKURQRXV PRGHO

:ULWH

'%

3XW 8QLWRIZRUN 6\QFSRLQW

T

4 8QLWRIZRUN

*HW :ULWH 6\QFSRLQW

'%

8QLWRIZRUN

/RFDOV\QFSRLQWSDUWLFLSDWLRQ FRPPLWWHGFKDQJHV ([DPSOHV 'HELWDFFRXQW 6HQGFUHGLWPHVVDJH

$FFRXQWQRWNQRZQ 6HQGGHELWUHYHUVDO

8SGDWHWUDYHOLWLQHUDU\ 6HQGIOLJKWUHVHUYDWLRQ

)XOO\ERRNHG 6HQGQHDUHVWDOWHUQDWLYH

&RQILUPRUGHU 6HQGVKLSSLQJUHTXHVW

2XWRIVWRFNVRUHRUGHU 6HQGUHYLVHGGHOLYHU\GDWH

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.





Uempty

Instructor Notes: Purpose — To explain the design implications of implementing a business transaction as multiple asynchronous units of work. Details — Nothing additional. Additional Information — None. Transition Statement — Now we look more closely at the options for syncpoint coordination when using WebSphere MQ. We start with local units of work.




4-69

Instructor Guide

&RRUGLQDWLQJ/RFDO8QLWVRI:RUN $ORFDOXQLWRIZRUNLVRQHLQZKLFKWKHRQO\ UHVRXUFHVEHLQJXSGDWHGDUHWKRVHRIWKHTXHXH PDQDJHU

04*(7PHVVDJHIURPVHUYHU TXHXH 04387H[WUDUHTXHVWV 04387UHSO\PHVVDJH LIHUURU 04%$&. LI2. 04&0,7

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.





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. Additional Information — None. Transition Statement — We now look at global units of work and the options for coordinating them.




4-71

Instructor Guide

,QWHUQDO&RRUGLQDWLRQRI*OREDO8QLWVRI:RUN $JOREDOXQLWRIZRUNLVRQHLQZKLFKWKH UHVRXUFHVRIRWKHUUHVRXUFHPDQDJHUVDUHDOVR EHLQJXSGDWHG

04%(*,1 04*(7PHVVDJHIURPVHUYHUTXHXH (;(&64/,16(57GDWDEDVHUHFRUG 04387UHSO\PHVVDJH LIHUURU 04%$&. LI2. 04&0,7

9HUVLRQTXHXHPDQDJHUVRQO\

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.





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. Additional Information — None. Transition Statement — Next we look at which XA-compliant database managers are supported by the Version 5 queue managers.




4-73

Instructor Guide

'DWDEDVH&RRUGLQDWLRQ 6XSSRUWHGGDWDEDVHPDQDJHUV '% $,;+38;/LQX[26:DUS6XQ6RODULV:LQGRZV 2UDFOH $,;&RPSDT7UX81,;+38;6XQ6RODULV 6\EDVH $,;6XQ6RODULV:LQGRZV 5HVWULFWLRQV $Q:HE6SKHUH04FOLHQWFDQQRWSDUWLFLSDWHLQDJOREDOXQLWRI ZRUN 2QO\RQHTXHXHPDQDJHUPD\SDUWLFLSDWHLQDJOREDOXQLWRIZRUN 1RUPDOO\XSGDWHVWR:HE6SKHUH04DQGGDWDEDVHUHVRXUFHV PXVWEHPDGHRQWKHVDPHV\VWHP 'DWDEDVHVHUYHUPD\EHRQDGLIIHUHQWV\VWHPSURYLGHGLWFDQ VXSSO\DQ;$FRPSOLDQWFOLHQWIHDWXUH

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. 4-74 WebSphere MQ System Administration I




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.




4-75

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. Details — Nothing additional. Additional Information — None. Transition Statement — Next we look at the choices available for the external coordination of global units of work.





Uempty

([WHUQDO&RRUGLQDWLRQRI*OREDO8QLWVRI:RUN $,;

7;6HULHVIRU$,; %($7X[HGR :HE6SKHUH

L6HULHV

L6HULHVFRPPLWPHQWFRQWURO

&,&6

&RPSDT7UX81,; '&26[1&581,;6,1,; %($7X[HGR

26:DUS

&,&67UDQVDFWLRQ6HUYHUIRU 26

6XQ6RODULV

7;6HULHVIRU6XQ6RODULV %($7X[HGR 7UDQVDUF(QFLQD0RQLWRU :HE6SKHUH

7DQGHP1RQ6WRS.HUQHO 700370)

:LQGRZV

+38;

7;6HULHVIRU+3 %($7X[HGR :HE6SKHUH

/LQX[

7;6HULHVIRU:LQGRZV %($7X[HGR 0LFURVRIW7UDQVDFWLRQ6HUYHU

6LQJOHSKDVHFRPPLWSURWRFRORQO\

:HE6SKHUH

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. © Copyright IBM Corp. 1996, 2003



4-77

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





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. Additional Information — None. Transition Statement — Next we look at how WebSphere MQ can be used with CICS transactions.




4-79

Instructor Guide

&,&67UDQVDFWLRQV $&,&6WUDQVDFWLRQPD\LVVXH04,FDOOV $&,&6WULJJHUPRQLWRUFDQVWDUWD&,&6WUDQVDFWLRQ ZKHQDPHVVDJHDUULYHVRQDTXHXH $,;26:DUSDQG:LQGRZVRQO\

2QO\RQHTXHXHPDQDJHUFDQEHDFFHVVHGDWDWLPHIURPDVLQJOH &,&6UHJLRQ XVLQJ&,&6ZLWKDWZRSKDVHFRPPLWSURWRFRORQ$,;+38;6,1,;6XQ6RODULV DQG:LQGRZV

$&,&6WUDQVDFWLRQFDQDFFHVVDQ\TXHXHPDQDJHURQD V\VWHPEXWFDQFRQQHFWWRRQO\RQHDWDWLPH

XVLQJ&,&6ZLWKDVLQJOHSKDVHFRPPLWSURWRFRORQ26:DUSDQG:LQGRZV

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.





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. Additional Information — None. 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?




4-81

Instructor Guide

,QGHSHQGHQW&RRUGLQDWLRQ 04*(7PHVVDJHIURPVHUYHUTXHXHQRWH0VJ,G 3URFHVVPHVVDJH 04387PHVVDJHV '%XSGDWHV '%XSGDWHVSHFLDOUHFRUGVWRUHFXUUHQW0VJ,G '%FRPPLW """"" 04&0,7

'%UHDGVSHFLDOUHFRUG 04*(7VSHFLILF0VJ,GIURPVHUYHUTXHXH LISUHVHQWWKHUHZDVDIDLOXUHLQWKH ZLQGRZ 04387PHVVDJHVZLWKRXW'%XSGDWHV 04&0,7

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.





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. Additional Information — None. Transition Statement — Next there is a practical exercise on recovery.




4-83

Instructor Guide





Uempty

Checkpoint Unit 4 Checkpoint 1. T/F Authorization Service are not supported on iSeries. Correct Answer: True 2. The two types of logging supported on HP-UX are: a. b. c. d.

journaling linear circular 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. b. c. d.

QMGRERR ERRORS amqerr01.log 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. Correct Answer: False 5. What type of log can a damaged object be re-created from? a. b. c. d.

circular journal receiver linear queue manager log

Correct Answer: c




4-85

Instructor Guide

8QLW6XPPDU\ $UFKLWHFWXUH 3UREOHPGHWHUPLQDWLRQ 0HVVDJHSHUVLVWHQFHORJJLQJDQGUHFRYHU\ 7UDQVDFWLRQDOVXSSRUW ([HUFLVH


MQ157.0

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.





Uempty

Instructor Notes: Purpose — To summarize the unit. 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. Additional Information — None. Transition Statement — End of the unit. Next, we will look at connecting queue managers and the implications for applications.




4-87

Instructor Guide





Uempty

Unit 5. Distributed Queue Management What This Unit is About This unit describes various aspects of distributed queue management. • Configuring WebSphere MQ for distributed queuing • Application data conversion • Remote administration • Handling exceptions

What You Should Be Able to Do After completing this unit, you should be able to: • Given a WebSphere MQ network, demonstrate how to create the required WebSphere MQ objects • Given network design goals, select the appropriate channel configuration • Given a scenario containing alias queues, local definitions of remote queues, reply-to queue aliases, and queue manager aliases, predict the final destination of a message • Configure TCP/IP to enable its use by WebSphere MQ and identify where the configuration of other communications protocols is described • Distinguish between the various ways of starting and stopping a message channel • Describe how to start and stop a message channel • Determine the state of a message channel • Given an error on a message channel, determine the possible cause • Give examples of the steps that can be taken to find a 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


Unit 5. Distributed Queue Management


5-1

Instructor Guide

• Configure a simple cluster of queue managers


References

5-2

SC34-6055


SC34-6059

WebSphere MQ Intercommunication

SC34-6061

WebSphere MQ Queue Manager Clusters





Uempty

8QLW2EMHFWLYHV $IWHUFRPSOHWLQJWKLVXQLW\RXVKRXOGEHDEOHWR /HDUQKRZWRFRQILJXUH:HE6SKHUH04FKDQQHOV 'HILQHRWKHUUHTXLUHGREMHFWVIRUGLVWULEXWHGTXHXLQJ ([SODLQKRZWRVWDUWDQGVWRSFKDQQHOV 'HVFULEHVWHSVQHFHVVDU\WRGHWHUPLQHVRXUFHRIFKDQQHO SUREOHPV /LVWFRQVLGHUDWLRQVIRUGDWDFRQYHUVLRQ 'HVFULEHLQVWUXPHQWDWLRQHYHQWVDQGWKHLUXVH ([SODLQGHDGOHWWHUTXHXHVDQGWKHLUXVH ,PSOHPHQWDFRQILJXUDWLRQWKDWXVHVG\QDPLFZRUNORDG PDQDJHPHQW&/867(56


MQ157.0

Notes: This unit is, perhaps, one of the most important in the entire course. Channel configuration and operations can be confusing. Once you have completed this unit and the practical exercise, you will have a better idea of what is involved. With additional practice and use when you return to your job, you will find that they are not as difficult as they appear.




5-3

Instructor Guide

5-4





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. After completing this unit, the student should be able to: • Given a WebSphere MQ network, demonstrate how to create the required WebSphere MQ objects. • Given network design goals, select the appropriate channel configuration. • Given a scenario containing alias queues, local definitions of remote queues, reply-to queue aliases, and queue manager aliases, predict the final destination of a message. • Configure TCP/IP to enable its use by WebSphere MQ and identify where the configuration of other communications protocols is described. • Distinguish between the various ways of starting and stopping a message channel. • Describe how to start and stop a message channel. • Determine the state of a message channel. • Given an error on a message channel, determine the possible cause. • Give examples of the steps that can be taken to find a 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.




5-5

Instructor Guide

5-6





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.

Instructor Topic Introduction 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.




5-7

Instructor Guide

,GHQWLI\LQJD4XHXHLQWKH04, $TXHXHLVLGHQWLILHGE\ 7KHQDPHRIWKHTXHXH 7KHQDPHRIWKHTXHXHPDQDJHUZKLFKRZQVWKHTXHXH $TXHXHPD\EHUHIHUHQFHGLQWZRSODFHV 2EMHFWGHVFULSWRURQDQ0423(1RU04387FDOO 2EMHFW1DPH 2EMHFW40JU1DPH 0HVVDJHGHVFULSWRUWRVSHFLI\DUHSO\WRTXHXH 5HSO\7R4 5HSO\7R40JU ,QDQREMHFWGHVFULSWRULI2EMHFW40JU1DPHLVEODQNWKHTXHXH ZLWKWKHQDPHVSHFLILHGLQ2EMHFW1DPHPXVWEHGHILQHGLQRQHRI WKHIROORZLQJSODFHV 7KHORFDOTXHXHPDQDJHU 7KHQDPHVHUYLFH

Figure 5-2. Identifying a Queue in the MQI

MQ157.0

Notes:

5-8





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. Additional Information — None. Transition Statement — Next a reminder of the components of assured delivery.




5-9

Instructor Guide

$VVXUHG'HOLYHU\ 40

04387 LIFF 2. FRQWLQXH

0 & $

'(&QHW ,3;63; 1HW%,26 7&3,3 61$/8 8'3

40 0 & $

04*(7

'HVWLQDWLRQ TXHXH

7UDQVPLVVLRQ TXHXH

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.





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. Additional Information — None. Transition Statement — Next we look at how to define queues that are used in distributed queuing.




5-11

Instructor Guide

4XHXH'HILQLWLRQVIRU'LVWULEXWHG4XHXLQJ /RFDOGHILQLWLRQRIDUHPRWHTXHXH '(),1(45(027(%%% 51$0(<<< 5401$0(40

$WUDQVPLVVLRQTXHXHPXVWEHFUHDWHGDWWKHVHQGLQJHQGRIHDFK PHVVDJHFKDQQHO 86$*(;0,74 LQGLFDWHVLWVSXUSRVH 2WKHUZLVHLWPD\KDYHDQ\RIWKHDWWULEXWHVRIDORFDOTXHXH

'(),1(4/2&$/40 86$*(;0,74

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.





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. Additional Information — None. Transition Statement — Next we look a little more closely at the ends of a message channel.




5-13

Instructor Guide

0HVVDJH&KDQQHO&RPELQDWLRQV

6(1'(5

5(48(67(5

6(59(5

5(&(,9(5

6(59(5

5(48(67(5

6(1'(5

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.





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. Additional Information — None. Transition Statement — Next we look more closely at the attributes of a message channel.




5-15

Instructor Guide

$WWULEXWHVRID0HVVDJH&KDQQHO 5HTXLUHGIRUGHILQLWLRQ FKDQQHOQDPH &+/7<3( 7537<3(

8SWRFKDUDFWHUV 6'55&9569554675 '(&1(7/81(7%,26 63;7&3EXWQRWUHTXLUHGRQD9HUVLRQ

TXHXHPDQDJHU

8'3$,;RQO\ IRU6'5DQG54675RQO\RSWLRQDOIRU695 &211$0(VWULQJ IRU6'5DQG695RQO\ ;0,74VWULQJ 5HTXLUHGIRU61$/8

RQ046HULHVIRU26:DUS6XQ26DQG 7DQGHP1RQ6WRS.HUQHORQO\

02'(1$0(VWULQJ 731$0(VWULQJ

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





Uempty

TRPTYPE is not specified, the value is taken from the appropriate default channel object.




5-17

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) Additional Information — None. Transition Statement — Next we look at an example containing some channel definitions.





Uempty

([DPSOH +XUVOH\

'DOODV

'()&+/ +XUVOH\B'DOODV &+/7<3(6'5 7537<3(7&3 &211$0( ;0,74 'DOODV

'()&+/ +XUVOH\B'DOODV &+/7<3(5&95 7537<3(7&3

'()&+/ 'DOODVB+XUVOH\ &+/7<3(5&95 7537<3(7&3

'()&+/ 'DOODVB+XUVOH\ &+/7<3(6'5 7537<3(7&3 &211$0( ;0,74 +XUVOH\

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.




5-19

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. Additional Information — None. Transition Statement — Next we look at how a queue manager decides which transmission queue to use for a message destined for a remote queue.





Uempty

&KRRVLQJD7UDQVPLVVLRQ4XHXH $ORFDOGHILQLWLRQRIDUHPRWHTXHXHFDQVSHFLI\ '(),1(45(027(%%% 51$0(<<< 5401$0(40 ;0,74 ([SUHVV

7KHQDPHRIWKHWUDQVPLVVLRQTXHXHLVLQIHUUHGIURPWKH QDPHRIWKHUHPRWHTXHXHPDQDJHU $GHIDXOWWUDQVPLVVLRQTXHXHFDQEHVSHFLILHGE\DQ DWWULEXWHRIWKHTXHXHPDQDJHUREMHFW

$/7(540*5'();0,74+267

Figure 5-8. Choosing a Transmission Queue

MQ157.0

Notes:




5-21

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. Additional Information — None. Transition Statement — Next we look at the queue manager alias.





Uempty

4XHXH0DQDJHU$OLDV 40&

40$

40%

40'

40( 40)

$GHIDXOWWUDQVPLVVLRQTXHXHDOORZVDPHVVDJHWREH GHOLYHUHGWKURXJKPXOWLSOHTXHXHPDQDJHUV $TXHXHPDQDJHUDOLDVPD\DOVREHQHHGHG )RUH[DPSOHLQ40$

'(),1(45(027(40) 5401$0(40) ;0,7440%

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.




5-23

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. Additional Information — None. Transition Statement — A queue manager alias can also be used when you need to separate message flows between two queue managers.





Uempty

6HSDUDWLQJ0HVVDJH)ORZV 40

40 40 40

;

4/6(59

40$

4/5(3/<

40$

<

/RFDO'HIRI5HP4

'()45456(59 51$0(4/6(59 5401$0(40 ;0,7440$

5HSO\BWRB4DOLDV

'()45455(3/<$ 514/5(3/< 5401$0(40$

40DOLDV5HSO\0VJ

'()4540$ 5401$0(40

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.




5-25

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. Additional Information — None. Transition Statement — Next we look at how to configure TCP/IP for WebSphere MQ.





Uempty

&RQILJXULQJ7&3,3IRU:HE6SKHUH04 &RQILJXUHWKHLQHWGDHPRQLQHWG 26:DUS

$,;

?0371?(7&?6(59,&(6

:HE6SKHUH04

HWFVHUYLFHV

WFS046HULHV HWFLQHWGFRQI

:HE6SKHUH04VWUHDPWFSQRZDLWPTPXVUPTPELQDPTFUVWDDPTFUVWD>P40JU1DPH@

?0371?(7&?,1(7'/67

:HE6SKHUH04WFSF?PTP?ELQ?DPTFUVWD>P40JU1DPH@ RUXVHWKH:HE6SKHUH04OLVWHQHUUXQPTOVU

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.




5-27

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.





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




5-29

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.





Uempty

6WDUWLQJD0HVVDJH&KDQQHO :HE6SKHUH04FRPPDQGV 3,1*&+$11(/40$B40% 67$57&+$11(/40$B40%

&RQWUROFRPPDQG UXQPTFKOF40$B40%

&KDQQHODWWULEXWHVFRPSDUHG %$7&+6= 0$;06*/ 6(4:5$3 +%,17:HE6SKHUH04IRU]26L6HULHVDQG9HUVLRQTXHXHPDQDJHUVRQO\ 13063((':HE6SKHUH04IRU]26L6HULHVDQG9HUVLRQTXHXHPDQDJHUV 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.




5-31

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





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.

Uempty

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.




5-33

Instructor Guide

&KDQQHO,QLWLDWRU 67$57&+,1,7,1,74 &KDQQHO,QLW4

7ULJJHUPRQLWRUIRUWUDQVPLVVLRQTXHXHV 6WDUWVDQ0&$DWWKHVHQGLQJHQGRIDPHVVDJHFKDQQHO 8VHU'DWDDWWULEXWHRIWKHSURFHVVREMHFWVSHFLILHVWKHFKDQQHO QDPH 2U7ULJJHUGDWDDWWULEXWHRIWKHWUDQVPLVVLRQTXHXHVSHFLILHVWKH FKDQQHOQDPH9HUVLRQDQGL6HULHVTXHXHPDQDJHUVRQO\ $OVRDFRQWUROFRPPDQG UXQPTFKLT&KDQQHO,QLW4

&KDQQHOFRQWUROSDUDPHWHUV ',6&,17 6+25757<6+257705 /21*57</21*705

0557<05705QRW046HULHVIRU:LQGRZV 0&$7<3(046HULHVIRU26:DUSDQG :HE6SKHUH04IRU:LQGRZVRQO\ %$7&+,179HUVLRQDQG]26RQO\

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.





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. • On MQSeries for Tandem NonStop Kernel, as an alternative to using the control command runmqchi, you may use the default channel initiator which is configured in the TS/MP server class MQS-CHANINIT00 and start it by using the PATHCOM commands THAW SERVER and START SERVER. Full details of this option can be found in the MQSeries for Tandem NonStop Kernel System Management Guide. The WebSphere MQ command START CHINIT is not supported on this queue manager. • The channel control parameters shown on the visual can be specified on the DEFINE CHANNEL command. DISCINT

(SDR and SVR) Maximum time to wait for a message on the transmission queue if it is empty. If no message arrives within this time, the channel closes down.

SHORTRTY, SHORTTMR(SDR and SVR) Short retry count and short retry time interval to control repeated attempts to establish a communications connection. LONGRTY, LONGTMR(SDR and SVR) Long retry count and long retry time interval to control further repeated attempts to establish a communications connection. MRRTY, MRTMR(RCVR and RQSTR) Message-retry count and message-retry interval when attempting to put a message on a destination queue. If every attempt fails, the MCA decides that it cannot deliver the message. MCATYPE

(SDR, SVR, and RQSTR) The value of this parameter may be THREAD or PROCESS. If THREAD is specified, each channel runs as a thread within the channel initiator process. If PROCESS is specified, each channel runs as a separate process. This parameter is only supported on MQSeries for OS/2 Warp and WebSphere MQ for Windows.

BATCHINT

(SDR and SVR) The period of time during which a channel will keep a batch open if there are no messages on the transmission queue. This should be set to a value considerably less than the value of DISCINT. This parameter is only valid on a Version 5 queue manager.




5-35

Instructor Guide

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





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. Additional Information — None. Transition Statement — End of topic. Next, there are some considerations for applications in a mixed network, starting with data representation.




5-37

Instructor Guide

&KDQQHO6WDWHV ,1$&7,9(

67$57 67$57 &+$11(/

7LPHIRU QH[W DWWHPSW

'LVFRQQHFW LQWHUYDO H[SLUHV

67$57,1*

,1,7,$/,6,1*

UXQPTFKO

3$86('

67233(' 5(75<,1*

6723RUQRQUHWU\DEOH HUURURUUHWU\OLPLWUHDFKHG

%,1',1* 6WDWXV 2.

5811,1*

%LQGIDLOV

5(48(67,1*

(UURURU6723RU GLVFLQWH[SLUHV

5HWU\DEOHHUURU

67233,1*

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.





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.




5-39

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.





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.

Instructor Topic Introduction 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.




5-41

Instructor Guide

'DWD5HSUHVHQWDWLRQ 0HVVDJHVLQDKHWHURJHQHRXVQHWZRUN &KDUDFWHUILHOGVPD\QHHGWUDQVODWLRQ 1XPHULFILHOGVPD\QHHGWUDQVIRUPDWLRQ 0HVVDJHGHVFULSWRUDFFRPSDQLHVHYHU\PHVVDJH 'HOLYHUHGWRWKHUHFHLYLQJDSSOLFDWLRQ $OZD\VFRQYHUWHGE\:HE6SKHUH04 $SSOLFDWLRQGDWD )LHOGVLQWKHPHVVDJHGHVFULSWRUGHVFULEHWKHIRUPDWDQG UHSUHVHQWDWLRQ 'DWDFRQYHUVLRQVXSSRUWLVDYDLODEOH

Figure 5-15. Data Representation

MQ157.0

Notes:





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. Additional Information — None. Transition Statement — Next we look at the three fields in the message descriptor which are concerned with application data conversion.




5-43

Instructor Guide

7KUHH)LHOGVLQWKH0HVVDJH'HVFULSWRU (QFRGLQJ 5HSUHVHQWDWLRQRIWKHQXPHULFGDWDLQWKHPHVVDJH L6HULHV:LQGRZVDQGVRIRUWK 04(1&B1$7,9( &RGHG&KDU6HW,G 5HSUHVHQWDWLRQRIWKHFKDUDFWHUGDWDLQWKHPHVVDJH 04&&6,B4B0*5 )RUPDW ,QGLFDWHVWKHQDWXUHRIWKHGDWDLQWKHPHVVDJH 9DOXHV04DUHUHVHUYHGIRU:HE6SKHUH04

Figure 5-16. Three Fields in the Message Descriptor

MQ157.0

Notes:





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. Additional Information — None. Transition Statement — Next we look at how application data conversion is requested.




5-45

Instructor Guide

5HTXHVWLQJ$SSOLFDWLRQ'DWD&RQYHUVLRQ 5HTXHVWGDWDFRQYHUVLRQRQWKH04*(7FDOO 04*02B&219(57 (QFRGLQJDQG&RGHG&KDU6HW,G 2QLQSXWUHTXHVWHGUHSUHVHQWDWLRQRIWKHPHVVDJH 2QRXWSXWZKDWWKHDSSOLFDWLRQDFWXDOO\UHFHLYHV &RQYHUVLRQSHUIRUPHGLIQHFHVVDU\RQWKHEDVLVRIZKDWLV FRQWDLQHGLQWKH)RUPDWILHOG $ZDUQLQJDQGWKHPHVVDJHUHWXUQHGLQLWVRULJLQDOIRUPLIWKH FRQYHUVLRQFDQQRWEHGRQH 2WKHUZLVHUHTXHVWGDWDFRQYHUVLRQDWWKHVHQGLQJHQGRID PHVVDJHFKDQQHO &219(57<(6 8QFRQYHUWHGPHVVDJHVDUHSXWRQWKHGHDGOHWWHUTXHXHDWWKH VHQGLQJHQG

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.





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. Additional Information — None. Transition Statement — Next, what kinds of application data conversion can WebSphere MQ perform?




5-47

Instructor Guide

:KDW$SSOLFDWLRQ'DWD &RQYHUVLRQ&DQ%H'RQH" 6RPHIRUPDWVDUHEXLOWLQDQGWKHGDWDFRQYHUVLRQLV SHUIRUPHGE\DEXLOWLQFRQYHUVLRQURXWLQH $PHVVDJHFRQVLVWLQJHQWLUHO\RIFKDUDFWHUV $PHVVDJHVWUXFWXUHGHILQHGE\:HE6SKHUH04 $XVHUZULWWHQGDWDFRQYHUVLRQH[LWLVUHTXLUHGZKHQ 7KHIRUPDWRIDPHVVDJHLVGHILQHGE\WKHDSSOLFDWLRQQRWE\ :HE6SKHUH04 $PHVVDJHZLWKDEXLOWLQIRUPDWIDLOVWRFRQYHUW 7KHUHLVDQ:HE6SKHUH04XWLOLW\WRKHOSZULWHDGDWDFRQYHUVLRQH[LW

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.





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. Additional Information — None. Transition Statement — Next we look at how to create a conversion exit.




5-49

Instructor Guide

:ULWLQJD'DWD&RQYHUVLRQ([LW 1DPH\RXUPHVVDJHIRUPDW &UHDWH&VWUXFWXUHGHILQLWLRQVWRUHSUHVHQWWKHPHVVDJH 3DVVWKH&VWUXFWXUHGHILQLWLRQVWKURXJKDXWLOLW\

FUWPTFY[IRUPDWLQFRQYFRGHRXW &RPSOHWHWKHSURJUDP 5HQDPHWKHVXSSOLHGVNHOHWRQVRXUFHILOH ,PEHGWKHFRGHIUDJPHQWVJHQHUDWHGE\WKHXWLOLW\ ,IQHFHVVDU\DGGDQ\VSHFLDOL]HGFRGH %XLOGWKHSURJUDPLQWRDQH[HFXWDEOH :DWFKWKHOLQNRSWLRQV

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.





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. Additional Information — None. Transition Statement — Next, we look at how a queue manager uses a data conversion exit.




5-51

Instructor Guide

+RZD'DWD&RQYHUVLRQ([LW,V8VHG 7KHTXHXHPDQDJHUGHWHFWVZKHWKHUGDWDFRQYHUVLRQLVUHTXLUHG )RUDEXLOWLQIRUPDWWKHTXHXHPDQDJHUSHUIRUPVWKH FRQYHUVLRQ )RUDIRUPDWWKDWLVQRWEXLOWLQRULIDEXLOWLQFRQYHUVLRQURXWLQH IDLOVWKHTXHXHPDQDJHULQYRNHVWKHUHOHYDQWGDWDFRQYHUVLRQ H[LW 7KHGDWDFRQYHUVLRQH[LWLV ,QYRNHGDFFRUGLQJWRWKHFDOOGHILQLWLRQ04'$7$&219(;,7 3DVVHGWKH04';3VWUXFWXUHDVRQHRILWVSDUDPHWHUV 7KHTXHXHPDQDJHUFKHFNVWKH([LW5HVSRQVHILHOGLQ04';3 2.GHOLYHUVWKHFRQYHUWHGPHVVDJHWRWKHDSSOLFDWLRQ )$,/('SURSDJDWHV&RPS&RGHDQG5HDVRQIURPWKHH[LWDQG GHOLYHUVWKHXQFRQYHUWHGPHVVDJHWRWKHDSSOLFDWLRQ $SSOLFDWLRQGDWDGHOLYHUHGPD\GHSHQGRQWKHWUXQFDWLRQRSWLRQ VSHFLILHG

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

MQ157.0

Notes:





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. Additional Information — None. Transition Statement — Next we review what applications should do in a heterogeneous network of queue managers.




5-53

Instructor Guide

:KDW$SSOLFDWLRQV6KRXOG'R 3XWPHVVDJHVZLWKWKHIROORZLQJYDOXHVLQWKH(QFRGLQJDQG &RGHG&KDU6HW,GILHOGV 04(1&B1$7,9(IRUQDWLYHHQFRGLQJ 04&&6,B4B0*5IRUWKHVDPH&&6,'DVWKHTXHXH PDQDJHU 3XWDOOPHVVDJHVZLWKDIRUPDWQDPH 04)07B675,1*IRUDPHVVDJHFRQVLVWLQJHQWLUHO\RI FKDUDFWHUV 8VHWKH04*02B&219(57RSWLRQRQWKH04*(7FDOO &KHFNZKDWLVGHOLYHUHGE\WKHFDOO ,IQHFHVVDU\XVH&219(57<(6 DWWKHVHQGLQJHQGRI DPHVVDJHFKDQQHO

Figure 5-21. What Applications Should Do

MQ157.0

Notes:





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. Additional Information — None. Transition Statement — Next we look at the command server.




5-55

Instructor Guide

&RPPDQG6HUYHU &RPPDQGTXHXH 6<67(0$'0,1&200$1'48(8( 0HVVDJHVFRQWDLQ3URJUDPPDEOH&RPPDQG)RUPDW3&) FRPPDQGV &RPPDQGVHUYHUSURFHVVHVWKHPHVVDJHVLQWKLVTXHXH

VWUPTFVY40JU1DPH (QDEOHVQHWZRUNDGPLQLVWUDWLRQDSSOLFDWLRQV 6LQJOHSRLQWRIFRQWURO

Figure 5-22. Command Server

MQ157.0

Notes: • Related control commands are as follows. endmqcsv

Ends the command server.

dspmqcsv

Displays the status of the command server.

• On WebSphere MQ for iSeries, the corresponding CL commands are: - STRMQMCSVR, Start MQM Command Server - ENDMQMCSVR, End MQM Command Server - DSPMQMCSVR, Display MQM Command Server • On MQSeries for Tandem NonStop Kernel, as an alternative to using the control command strmqcsv, you may use the command server which is configured in the TS/MP server class MQS-CMDSERV00 and start it by using the PATHCOM commands THAW SERVER and START SERVER. Full details of this option can be found in the MQSeries for Tandem NonStop Kernel System Management Guide. • WebSphere MQ for z/OS has a system-command input queue which is monitored by a command server. However, the command server only accepts messages containing 5-56 WebSphere MQ System Administration I




Uempty

WebSphere MQ commands. PCF commands are not supported by WebSphere MQ for z/OS.




5-57

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. Additional Information — None. Transition Statement — Next we look at the range of PCF support.





Uempty

6XSSRUWIRU3&)&RPPDQGV $OOTXHXHPDQDJHUVKDYHDFRPPDQGVHUYHUZKLFKDFFHSWV3&) FRPPDQGVH[FHSW :HE6SKHUH04IRU26 /HYHOTXHXHPDQDJHUV $GPLQLVWUDWLRQXWLOLWLHVZKLFKLVVXH3&)FRPPDQGV 6XSSRUW3DFVIRU:HE6SKHUH04IRU$,;:LQGRZVDQG04 6HULHVIRU26:DUS 9HQGRUSURGXFWV UXQPTVFZLQGLUHFWPRGH $SSOLFDWLRQVXVLQJWKH04$,9DQGODWHU :HE6SKHUH04$GPLQLVWUDWLRQ,QWHUIDFH

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.




5-59

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.





Uempty

3URJUDP([DPSOH $SSOLFDWLRQ

&RPPDQG6HUYHU

04387

04*(7 'HWHUPLQHZKLFK TXHXHVKDYHH[SLUHG DQGIRUHDFKRQH

04&0'B,148,5(B4 JHQHULFTXHXHQDPH

TXHXHQDPH UHWHQWLRQLQWHUYDO FUHDWLRQGDWH FUHDWLRQWLPH

04*(7 ,QTXLUHDWWULEXWHVRI VHOHFWHGTXHXHV

04387 5HVSRQVHIRUHDFK PDWFKLQJTXHXH

04*(7

04387 04&0'B'(/(7(B4 TXHXHQDPH

'HOHWHQDPHGTXHXH

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. © Copyright IBM Corp. 1996, 2003



5-61

Instructor Guide

-The command server deletes the "expired" queues.





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. Additional Information — None. Transition Statement — Next we look at the indirect mode of using runmqsc.




5-63

Instructor Guide

,QGLUHFW0RGH UXQPTVFZ40JU1DPH (DFK:HE6SKHUH04FRPPDQGLVVHQWZLWKLQDQ(VFDSH3&) FRPPDQGWRWKHFRPPDQGTXHXHRIWKHQDPHGTXHXHPDQDJHU &RQQHFWVWRWKHGHIDXOWTXHXHPDQDJHU (VFDSH3&)FRPPDQGSURFHVVHGDWWKHWDUJHWTXHXHPDQDJHU :DLWVIRUWKHUHSOLHV 7LPHOLPLWIRUWKHZDLW :ULWHVDUHSRUWEDVHGRQWKHUHSOLHVUHFHLYHG &DQDOVRVHQGD:HE6SKHUH04FRPPDQGWRWKH V\VWHPFRPPDQGLQSXWTXHXHRIDQ]26TXHXHPDQDJHU [SDUDPHWHU

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.





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. Additional Information — None. Transition Statement — Next we look at instrumentation events.




5-65

Instructor Guide

,QVWUXPHQWDWLRQ(YHQWV +DYHDTXHXHPDQDJHUUHSRUWDSUREOHPFRQGLWLRQLPPHGLDWHO\ 1XPEHURIPHVVDJHVRQDTXHXHLVLQFUHDVLQJ *HWUHTXHVWVDUHLQKLELWHGIRUDTXHXH 0HVVDJHFKDQQHOKDVVWRSSHG (QDEOHGHYHQWVDUHUHSRUWHGDVHYHQWPHVVDJHVRQ HYHQWTXHXHV 6<67(0$'0,140*5(9(17 6<67(0$'0,13(5)0(9(17 6<67(0$'0,1&+$11(/(9(17 6<67(0$'0,1&21),*(9(17

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.





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 © Copyright IBM Corp. 1996, 2003



5-67

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.





Uempty

5HVSRQGLQJWRDQ,QVWUXPHQWDWLRQ(YHQW 4XHXHPDQDJHUHYHQWV (QDEOHDTXHXHIRUSXWRUJHWUHTXHVWVLILWLVQRWLQWHQWLRQDOO\ GLVDEOHG &RUUHFWWKHDXWKRUL]DWLRQVIRUDTXHXHRUVWRSXQDXWKRUL]HG XVHUVWU\LQJWRSXWPHVVDJHVRQWKHTXHXH 3HUIRUPDQFHHYHQWV 6WDUWDSURFHVVWRFOHDUWKHEDFNORJRIPHVVDJHV 6XVSHQGDSURFHVVWKDWLVSXWWLQJWRRPDQ\PHVVDJHVRQD TXHXH &KDQQHOHYHQWV 5HVWDUWDFKDQQHO 3URFHVVWKHGHDGOHWWHUTXHXH

Figure 5-27. Responding to an Instrumentation Event

MQ157.0

Notes:




5-69

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. Additional Information — None. Transition Statement — Next we look at the dead letter queue.





Uempty

'HDG/HWWHU4XHXH 04387 WR4

W4

0 & $

0 & $

'/4

4

'/4

8VHGZKHQSUREOHPVDUHGHWHFWHGDV\QFKURQRXVO\

'HVWLQDWLRQTXHXHQRWDYDLODEOH $SSOLFDWLRQGDWDFRQYHUVLRQIDLOVDWWKHVHQGLQJHQGRIDPHVVDJHFKDQQHO

0HVVDJHFKDQQHOVWRSVLIWKHORFDOGHDGOHWWHUTXHXHLVQRW DYDLODEOHZKHQLWLVUHTXLUHG

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.




5-71

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.





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. Additional Information — None. Transition Statement — Next we look at a facility to process the undelivered messages.




5-73

Instructor Guide

'HDG/HWWHU4XHXH+DQGOHU UXQPTGOT5XOHVB7DEOH 5XOHVWDEOHFRQWDLQVDVHWRIUXOHV (DFKUXOHFRQVLVWVRISDWWHUQPDWFKLQJNH\ZRUGVDQGDQDFWLRQ )RUHDFKPHVVDJHRQWKHGHDGOHWWHUTXHXHHDFKUXOHZKRVH SDWWHUQPDWFKHVWKHPHVVDJHLVDWWHPSWHGLQWXUQ $PHVVDJHFDQEHUHWULHGIRUZDUGHGGLVFDUGHGRULJQRUHG $PHVVDJHFDQEHIRUZDUGHGZLWKRUZLWKRXWWKHGHDGOHWWHU KHDGHU &DQKDYHPXOWLSOHLQVWDQFHVHDFKZLWKDGLIIHUHQWUXOHVWDEOH 6RXUFHRIDVDPSOHGHDGOHWWHUTXHXHKDQGOHULVVXSSOLHGDVZHOO '(674040 $&7,21):' ):'4 '(674 ):'4040$ 06*7<3(0407B5(3257 )(('%$&.04)%B(;3,5$7,21 $&7,21',6&$5' 5($621045&B4B)8// $&7,215(75< '(674;<= $&7,21):' ):'4;<=B'($'4 ):'40

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).





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. Additional Information — None. Transition Statement — Next we look at a possible strategy for using dead letter queues.




5-75

Instructor Guide

8VLQJ'HDG/HWWHU4XHXHV &UHDWHDGHDGOHWWHUTXHXHRQDOOTXHXHPDQDJHUV 8VHPHVVDJHUHWU\RQPHVVDJHFKDQQHOVIRUWUDQVLHQWFRQGLWLRQV &RQVLGHUUHWXUQWRVHQGHU 8VHDGHDGOHWWHUTXHXHKDQGOHU 7ULJJHUZKHQDPHVVDJHDUULYHVRQWKHGHDGOHWWHUTXHXH 3RVVLEO\DWWHPSWIXUWKHUUHWULHV ,IXQVXFFHVVIXOIRUZDUGWRDQDSSOLFDWLRQGHDGOHWWHUTXHXH DVVRFLDWHGZLWK 7KHGHVWLQDWLRQTXHXH 7KHDSSOLFDWLRQVSHFLILHGE\WKH3XW$SSO1DPHILHOGLQWKH PHVVDJHGHVFULSWRU 'RQ WDOORZDQDSSOLFDWLRQGHDGOHWWHUTXHXHWREHFRPHIXOO

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.





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. Additional Information — None. 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.




5-77

Instructor Guide





Uempty

5.3 WebSphere MQ Clusters Instructor Topic Introduction 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.




5-79

Instructor Guide

:KDW,VD&OXVWHU"

40 40 40 40

&/867(5

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.





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.




5-81

Instructor Guide

&OXVWHU6XSSRUW2EMHFWV 40

40

&OXVWHU 6HQGHU&KO

&OXVWHU 7UDQVPLVVLRQ 4XHXH

40

/RFDO $SSOLFDWLRQ 4XHXHV

&OXVWHU &RPPDQG4XHXH &OXVWHU 5HSRVLWRU\4XHXH

40

&OXVWHU 5HFHLYHU&KO

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





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.




5-83

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.





Uempty

0RUH$ERXW5HSRVLWRULHV

&/866'5

40

)8// 5(326,725<

40 SDUWLDO UHSRVLWRU\

40

40

)8// 5(326,725<

SDUWLDO UHSRVLWRU\

,I40IDLOV40ZRXOGFRQQHFWWR40 DVLWVIXOOUHSRVLWRU\V\VWHP

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




5-85

Instructor Guide

information may be updated and extended during operation through inquiries of a full repository.





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.




5-87

Instructor Guide

6HWWLQJ8SD&OXVWHU ON QM1: ALTER QMGR REPOS(EDUC) DEFINE CHANNEL(TO.QM1) + CHLTYPE(CLUSRCVR)CONNAME(...) + CLUSTER(EDUC) DEFINE CHANNEL(TO.QM4) + CHLTYPE(CLUSSDR) CONNAME(...) + CLUSTER(EDUC) + DESCR('To Other Full Repository') DEFINE QLOCAL(QUEUE1) + CLUSTER(EDUC)

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. 5-88 WebSphere MQ System Administration I




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.




5-89

Instructor Guide

'+&36XSSRUWLQ&OXVWHUV :HE6SKHUH049HQKDQFHPHQWVWRVXSSRUW'+&3LQFOXVWHUV 'HILQHDFOXVWHUUHFHLYHUFKDQQHOZLWKRXWVSHFLI\LQJWKHTXHXH PDQDJHUVQHWZRUNDGGUHVV

DEFINE CHANNEL(TO.QM1) + CHLTYPE(CLUSRCVR) TRPTYPE(TCP) + CLUSTER(EDUC) 'HILQHDFOXVWHUVHQGHUFKDQQHOZLWKRXWVSHFLI\LQJWKHQDPHRI WKHUHSRVLWRU\TXHXHPDQDJHU

DEFINE CHANNEL(TO.+QMNAME+) + CHLTYPE(CLUSSDR) TRPTYPE(TCP) + CONNAME(...) CLUSTER(EDUC)

Figure 5-35. DHCP Support in Clusters

MQ157.0

Notes: WebSphere MQ V5.2 and later includes two enhancements pertaining to the use of clusters. • A cluster-receiver channel can be defined without specifying the queue managers network address. When no CONNAME is defined and TCP/IP is used, WebSphere MQ generates a CONNAME, assuming the default port and using the current IP address of the system. This facility is useful when the systems in the cluster use Dynamic Host Configuration Protocol (DHCP). • A cluster-sender channel can be defined without specifying the name of the repository queue manager. When the naming conventions used for channels in the cluster includes the name of the queue manager, a CLUSSDR definition can use the +QMNAME+ construction. WebSphere MQ substitutes the correct repository queue manager name in place of +QMNAME+. 5-90 WebSphere MQ System Administration I




Uempty

The above example is for definitions required on QM1.




5-91

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.





Uempty

0XOWLSOH4XHXH2FFXUUHQFH :RUNORDG%DODQFLQJ 40 0423(1 41$0(7$5*(74

DEF QL(TARGET.Q) CLUSTER(EDUC)

7$5*(74 40

40

&/: (;,7

7$5*(74 40

ALTER QMGR CLWEXIT(myexit)

&/867(5('8&

7$5*(74

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. © Copyright IBM Corp. 1996, 2003



5-93

Instructor Guide

Instructor Notes: Purpose — To introduce the workload management capabilities of the WebSphere MQ cluster function. Details — Refer to chapter 5 of WebSphere MQ Queue Manager Clusters manual. 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.





Uempty

:RUNORDG%DODQFLQJ5HURXWLQJ

40

"MQOPEN(TARGET.Q) MQOO_BIND_NOT_FIXED" MQPUT MQPUT MQPUT

40

FKDQQHOWR40 IDLOV

7$5*(74

40 7$5*(74

&/867(5('8&

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.




5-95

Instructor Guide

• Make sure that all of the instances of the queue have the same priority, default persistence and defbind values.





Uempty

Instructor Notes: Purpose — To explain the reroute options available as a queue definition attribute and as an MQI open option. Details — Refer to chapter 5 of WebSphere MQ Queue Manager Clusters manual. 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.




5-97

Instructor Guide

&OXVWHU5HODWHG4XHXH0DQDJHU$WWULEXWHV 5(326&OXVWHU1DPH 5(3261/1DPHOLVW1DPH &/:/'$7$'DWDWREHSDVVHGWRWKHZRUNORDGH[LW FKDUPD[VWULQJ &/:/(;,7&OXVWHU8VHUZRUNORDGH[LWQDPH &/://(1PD[RIE\WHVRIPHVVDJHGDWDSDVVHGWR FOXVWHUZRUNORDGH[LW

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.





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.




5-99

Instructor Guide

&RQWUROOLQJ&OXVWHUV&OXVWHU&RPPDQGV 6863(1'40*5 5(680(40*5 5()5(6+&/867(5FOXVWHUQDPH 5(632612<(6 5(6(7&/867(5FOXVWHUQDPH 401$0(TPQDPH $&7,21)25&(5(029( 48(8(612<(6

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.





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: RESET CLUSTER (clustername) QMID(qmid) ACTION(FORCEREMOVE) QUEUES(NO) You cannot specify both QMNAME and QMID.




5-101

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. Additional Information — 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. RESET CLUSTER (clustername) QMNAME(qmname) ACTION(FORCEREMOVE) QUEUES(NO) RESET CLUSTER (clustername) 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.





Uempty

&RQWUROOLQJ&OXVWHUV',63/$<&/8640*5 ',63/$<&/8640*5 &/867(5QDPH &+$11(/QDPH UHWXUQV &/86'$7( &/867,0( '()7<3( 407<3(

WKHGDWHDQGWLPHZKHQWKHGHILQLWLRQEHFDPH DYDLODEOHWRWKHORFDOTPJU KRZWKHFOXVWHUTPJUZDVGHILQHG WKHIXQFWLRQRIWKHTPJULQWKHFOXVWHU ZKHWKHULWSURYLGHVIXOORUSDUWLDOUHSRVLWRU\ VHUYLFH LQWHUQDOO\JHQHUDWHGXQLTXHTPJUQDPH WKHFXUUHQWVWDWXVRIWKHFKDQQHOIRUWKLVTPJU PD\EHDQ\YDOLGFKDQQHOVWDWXV \HV_QRDVDUHVXOWRID6863(1'40*5FPG

40,' 67$786 6863(1'

$GGLWLRQDOO\FKDQQHODWWULEXWHVDUHUHWXUQHGIRUDOORUWKH JHQHULFDOO\ QDPHGFKDQQHOV

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.




5-103

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.





Uempty

&OXVWHU5HODWHG4XHXH&RQVLGHUDWLRQV 6SHFLDO'LVSOD\RSWLRQ ',63/$<48(8(&/86,1)2 &OXVWHU$OLDV4XHXHV '()4$38%/,& 7$5*(7/2&$/4 &/867(5,7$/< &OXVWHU4XHXH0DQDJHU$OLDVHV '()45520( 51$0( 5401$0(3,6$ ;0,74;4 &/867(5,7$/<

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. © Copyright IBM Corp. 1996, 2003



5-105

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.





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.




5-107

Instructor Guide





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. Correct Answer: True 2. If the SEQWRAP value on a SENDER channel is different from the value on the RECEIVER, what will happen? a. b. c. d.

They negotiate to the lower value at channel startup time. The channel will not start. They negotiate to the higher value at channel startup time. 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. Correct Answer: False




5-109

Instructor Guide

8QLW6XPPDU\ &RQILJXUDWLRQIRUGLVWULEXWHGTXHXLQJ 7KH04,LQWKHQHWZRUN $SSOLFDWLRQGDWDFRQYHUVLRQ 5HPRWHDGPLQLVWUDWLRQ ,QVWUXPHQWDWLRQHYHQWV 5HSRUWV 'HDGOHWWHUTXHXH &OXVWHUVXSSRUWDYDLODEOHZLWK:HE6SKHUH049 ([HUFLVHVDQG


MQ157.0

Notes: This unit described how to configure WebSphere MQ for distributed queuing and there was a practical exercise in getting messages to flow between queue managers. We also discussed other aspects of WebSphere MQ administration in a network, viz application data conversion, remote administration, 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.





Uempty

Instructor Notes: Purpose — To summarize the unit. 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. Additional Information — None. Transition Statement — End of the unit. Next, some more about distributed queuing.




5-111

Instructor Guide





Uempty

Unit 6. More on Distributed Queuing What This Unit is About This unit describes further aspects of distributed queuing. • WebSphere MQ Family SupportPacs • WebSphere MQ clients • Security

What You Should Be Able to Do After completing this unit, you should be able to: • Describe how to install and configure an WebSphere MQ client • Identify the security features of WebSphere MQ • Describe how message context fields and options can be used as a component of application security • Describe how Secure Sockets Layer works • Distinguish one channel exit from another

How You Will Check Your Progress Accountability: • Checkpoint questions • Machine exercises • Classroom discussions



SC34-6055





Unit 6. More on Distributed Queuing


6-1

Instructor Guide

8QLW2EMHFWLYHV $IWHUFRPSOHWLQJWKLVXQLW\RXVKRXOGEHDEOHWR 'HVFULEH6XSSRUW3DFVDQGKRZWRJHWWKHP ([SODLQ:HE6SKHUH04FOLHQWV 6HWXSDVLPSOH:HE6SKHUH04FOLHQWFRQILJXUDWLRQ 'HVFULEHWKHDFFHVVFRQWUROIHDWXUHVDYDLODEOHRQYDULRXV :HE6SKHUH04TXHXHPDQDJHUV 'HVFULEHKRZ6HFXUH6RFNHWV/D\HU66/ ZRUNV /LVWFKDQQHOH[LWVDQGGHILQHWKHLUXVH .QRZZKHUHWRILQGLQIRUPDWLRQRQZULWLQJVHFXULW\H[LWV


MQ157.0

Notes: You will learn where WebSphere MQ clients are supported, how to install and configure them, and where they are best used. WebSphere MQ offers security features that make the product robust enough for use in a complex production system. In addition, extensions are provided where additional capabilities are desired (for example, SSSL, exits and installable services). You will learn about the various capabilities and how they are implemented.

6-2





Uempty

Instructor Notes: Purpose — Highlight the unit objectives. Details — This unit describes the WebSphere MQ Family SupportPacs, WebSphere MQ clients, and security. After completing this unit, the student should be able to: • Describe how to install and configure an WebSphere MQ client. • Identify the security features of WebSphere MQ. • Describe how message context fields and options can be used as a component of application security. • 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.




6-3

Instructor Guide

6-4





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.

Instructor Topic Introduction What students will do — Students will listen to a presentation on WebSphere MQ Family SupportPacs. How students will do it — No student activities are planned for this topic. 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.




6-5

Instructor Guide

2YHUYLHZRI6XSSRUW3DFV 7UDQVDFWLRQ3URFHVVLQJ6XSSRUW3DFV 6SHFLILFIXQFWLRQVRUVHUYLFHV &RQWULEXWRUVWKURXJKRXW,%0 $YDLODEOHZRUOGZLGH (QKDQFH&,&6DQG:HE6SKHUH04SURGXFWV $YDLODEOHLQIRXUFDWHJRULHV )HHEDVHGVHUYLFHV 1RWDYDLODEOHIRUGRZQORDG )UHHZDUH 3URYLGHG$6,6ZLWKQRZDUUDQW\RUGHIHFWFRUUHFWLRQ 3URGXFW([WHQVLRQV )XOO\VXSSRUWHG 7KLUG3DUW\&RQWULEXWLRQV 3URYLGHG$6,6ZLWKQRZDUUDQW\RUGHIHFWFRUUHFWLRQ

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

6-6





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.




6-7

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.

6-8





Uempty

([DPSOH0' :HE6SKHUH046WDQGDUGVDQGFRQYHQWLRQV 7KLV6XSSRUW3DFDLPVWRUHFRPPHQGVRPHVWDQGDUGVDQGKLQWV HQFRPSDVVLQJDOODVSHFWVRI:HE6SKHUH04DQGDOORZLQJ :HE6SKHUH04WREHH[SORLWHGWKHZD\LWZDVGHVLJQHG 7KLV6XSSRUW3DFDSSOLHVWRDOO:HE6SKHUH04SODWIRUPV

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.




6-9

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. Additional Information — None. Transition Statement — Next we look at a SupportPac which can be used on a variety of platforms.





Uempty

([DPSOH02 :HE6SKHUH04IRU$,;DQG046HULHVIRU26:DUS8WLOLWLHV 7KUHHVDPSOHXWLOLWLHV (YHQWTXHXHPRQLWRU 'HDGOHWWHUTXHXHPRQLWRU 3URJUDPWRUHPRYHH[SLUHGPHVVDJHV 8VHIXOVDPSOHVRXUFHFRGH 7RSDUVHDQHYHQWPHVVDJH 7RUHDGDGHDGOHWWHUKHDGHU 7RREWDLQLQIRUPDWLRQIURPWKHFRPPDQGVHUYHU

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. © Copyright IBM Corp. 1996, 2003



6-11

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.





Uempty

Instructor Notes: Purpose — To describe another SupportPac. Details — Nothing additional. 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.




6-13

Instructor Guide

([DPSOH06 :HE6SKHUH04VDYHV4XHXH0DQDJHUREMHFWGHILQLWLRQVXVLQJ 3&)V ,QWHUURJDWHVWKHDWWULEXWHVRIDOOWKHREMHFWVGHILQHGWRDTXHXH PDQDJHUHLWKHUORFDORUUHPRWH DQGVDYHVWKHPWRDILOH 6XLWDEOHIRUXVHZLWK581046& &DQEHXVHGZLWKDQ\RIWKH:HE6SKHUH04IDPLO\WKDWVXSSRUWV 3&)V

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.





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.




6-15

Instructor Guide





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.

Instructor Topic Introduction 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. How this will help students on their job — This knowledge will help the students design and support a WebSphere MQ network which exploits this facility.




6-17

Instructor Guide

:HE6SKHUH04&OLHQW &OLHQWV\VWHP

6HUYHUV\VWHP

:04 DSSOLFDWLRQ

:04 TXHXH PDQDJHU

&OLHQW FRQQHFWLRQ

6HUYHU FRQQHFWLRQ



$VVXUHGGHOLYHU\ 4XHXHVWRUDJH 'DWDFRQYHUVLRQ $GPLQLVWUDWLRQ 5HFRYHU\ 6\QFSRLQWFRQWURO

04,FKDQQHO

Figure 6-6. WebSphere MQ Client

MQ157.0

Notes:





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. Additional Information — None. Transition Statement — Next we look in a little more detail at how a WebSphere MQ client application operates.




6-19

Instructor Guide

:HE6SKHUH04&OLHQWV([SODLQHG $SSOLFDWLRQ &OLHQW &RGH &RQQHFWLRQ

6HUYHU &RQQHFWLRQ

04&211

04&211

0423(1

0423(1

04*(7

04*(7

04387

04387

04&/26(

04&/26(

04',6&

04',6&

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.





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.




6-21

Instructor Guide

6\QFSRLQW&RQWURO $SSOLFDWLRQ &RGH 04*(7 04387

04

&,&6 '%

6\QFSRLQW

$:HE6SKHUH04FOLHQWDSSOLFDWLRQPD\SDUWLFLSDWHLQDORFDOXQLW RIZRUNLQYROYLQJ:HE6SKHUH04UHVRXUFHV 8VHVWKH04&0,7DQG04%$&.FDOOVIRUWKLVSXUSRVH $:HE6SKHUH04FOLHQWDSSOLFDWLRQFDQQRWSDUWLFLSDWHLQDJOREDO XQLWRIZRUNLQYROYLQJ:HE6SKHUH04UHVRXUFHV

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.





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. Additional Information — None. Transition Statement — Next we look at how a WebSphere MQ client is installed.




6-23

Instructor Guide

,QVWDOODWLRQ 0HWKRG9HUVLRQRQO\ ,QVWDOOIURPWKH:HE6SKHUH04&OLHQW&'520VXSSOLHGZLWKWKH SURGXFW 0HWKRG )RUDFOLHQWSODWIRUPZKLFKLVWKHVDPHDVWKHVHUYHUSODWIRUP 6HOHFWWKHUHTXLUHGFOLHQWFRPSRQHQWGXULQJWKHVWDQGDUGLQVWDOO 0HWKRG ,QVWDOOWKHFOLHQWFRPSRQHQWRQWKHVHUYHUV\VWHP &RS\WKHILOHVRIWKHFOLHQWFRPSRQHQWWRWKHFOLHQWV\VWHP 0RGLI\&21),*6<6$872(;(&%$7DQGVRIRUWK 0HWKRG ,QVWDOOIURPD6XSSRUW3DF


MQ157.0

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.





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.




6-25

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. 6-26 WebSphere MQ System Administration I




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.




6-27

Instructor Guide

'HILQLQJDQ04,&KDQQHO 8VHWKH'(),1(&+$11(/FRPPDQGZLWKSDUDPHWHUV &+/7<3( &/17&211RU695&211 7537<3( '(&1(7/81(7%,2663;RU7&3 &211$0(VWULQJ )RUDFOLHQWFRQQHFWLRQRQO\ 401$0(VWULQJ )RUDFOLHQWFRQQHFWLRQRQO\ 1RRSHUDWLRQDOLQYROYHPHQWRQDQ04,FKDQQHO $Q04,FKDQQHOVWDUWVZKHQDFOLHQWDSSOLFDWLRQLVVXHV 04&211RU04&211;FDOORQ9FOLHQWV $Q04,FKDQQHOVWRSVZKHQDFOLHQWDSSOLFDWLRQLVVXHV04',6&

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.





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.




6-29

Instructor Guide

7ZR:D\VRI&RQILJXULQJDQ04,&KDQQHO 0HWKRG 2QWKHVHUYHUV\VWHPGHILQHDVHUYHUFRQQHFWLRQ 2QWKHFOLHQWV\VWHPVHWWKHHQYLURQPHQWYDULDEOH 046(59(5 &KDQQHO1DPH7UDQVSRUW7\SH&RQQHFWLRQ1DPH 0HWKRG 2QWKHVHUYHUV\VWHPGHILQHDFOLHQWFRQQHFWLRQDQGDVHUYHU FRQQHFWLRQ ,IQRWRQDILOHVHUYHUFRS\WKHFOLHQWFKDQQHOGHILQLWLRQWDEOH IURPWKHVHUYHUV\VWHPWRWKHFOLHQWV\VWHP 2QWKHFOLHQWV\VWHPVHWWKHHQYLURQPHQWYDULDEOHV 04&+//,% 3DWKWRWKHGLUHFWRU\FRQWDLQLQJWKHFOLHQWFKDQQHO GHILQLWLRQWDEOH 04&+/7$% 1DPHRIWKHILOHFRQWDLQLQJWKHFOLHQWFKDQQHO GHILQLWLRQWDEOH

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.





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.




6-31

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. 6-32 WebSphere MQ System Administration I




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.

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

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.




6-33

Instructor Guide

&KDQQHO,QVWDQFHV 046(59(5 -83,7(56957&3-83,7(5

046(59(5 -83,7(56957&3-83,7(5

,2

0XOWLSOHLQVWDQFHV RIWKHVDPH 04,FKDQQHO

(8523$ 046(59(5 -83,7(56957&3-83,7(5

*$1<0('( 046(59(5 -83,7(56957&3-83,7(5

'(),1(&+$11(/-83,7(5695 &+/7<3(695&211 7537<3(7&3 &$//,672

-83,7(5

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. 6-34 WebSphere MQ System Administration I




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.




6-35

Instructor Guide

Instructor Notes: Purpose — To introduce channel instances. Details — Nothing in addition to the student notes. Additional Information — None. Transition Statement — Next we look at how a channel can be defined dynamically on WebSphere MQ products.





Uempty

$XWRGHILQLWLRQRI&KDQQHOV $SSOLHVRQO\WRWKHHQGRIDFKDQQHOZLWKW\SH 5HFHLYHU 6HUYHUFRQQHFWLRQ )XQFWLRQLQYRNHGZKHQDQLQFRPLQJUHTXHVWLVUHFHLYHGWRVWDUWD FKDQQHOEXWWKHUHLVQRFKDQQHOGHILQLWLRQ &KDQQHOGHILQLWLRQLVFUHDWHGDXWRPDWLFDOO\XVLQJWKHPRGHO 6<67(0$8725(&(,9(5 6<67(0$872695&211 3DUWQHU VYDOXHVDUHXVHGIRU &KDQQHOQDPH 6HTXHQFHQXPEHUZUDSYDOXH :HE6SKHUH04DQG046HULHV9HUVLRQRUODWHU

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.




6-37

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.





Uempty

6.3 Security This topic describes the security features of WebSphere MQ.

Instructor Topic Introduction 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. How this will help students on their job — This knowledge will help the students design and support an WebSphere MQ network where security is a requirement.




6-39

Instructor Guide

:HE6SKHUH046HFXULW\,PSOHPHQWDWLRQV 2EMHFW$XWKRULW\0DQDJHU2$0 IDFLOLW\ 'LVWULEXWHG&RPSXWLQJ(QYLURQPHQW'&( 6HFXULW\ &KDQQHO6HFXULW\XVLQJ6HFXUH6RFNHWV/D\HU66/

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.





Uempty

Instructor Notes: Purpose — To discuss the security implementation available for WebSphere MQ. Details — Additional Information — Transition Statement — Next let’s look at WebSphere MQ access control.




6-41

Instructor Guide

:HE6SKHUH04$FFHVV&RQWURO2YHUYLHZ *UDQXODUDFFHVVFRQWUROIDFLOLWLHV 3URYLGHGYLD:HE6SKHUH04,QVWDOODEOH6HUYLFHV :KLFKXVHU":KLFKUHVRXUFH":KDWW\SHVRIDFFHVV" :HE6SKHUH04DFFHVVFRQWURODWXVHUDQGRUJURXSOHYHO 81,;XVHJURXSVRQO\ 8VHUQDPHPXVWH[LVWHYHU\RQHLVLQQRERG\

:LQGRZVXVHVXVHULGVDQGRUJURXSV 6\VWHPOHYHOXVHULGVRQO\DUHVXSSRUWHG

1RVXSSRUWIRU'&(SULQFLSDOV7;6HULHVXVHULGVDQGVRIRUWK

$OWHUQDWHXVHULGVPD\EHVSHFLILHG :KHQVXLWDEO\DXWKRUL]HG )LUVWOHYHOQDPHRQO\LVFRQWUROOHG $OLDV4XHXHV5HPRWH4XHXHV 5HVROYHGQDPHLVQRWVLJQLILFDQW

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.





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.




6-43

Instructor Guide

Instructor Notes: Purpose — To discuss WebSphere MQ access control. Details — Additional Information — None. Transition Statement — Next we look at what access control function is provided with each queue manager.





Uempty

2EMHFW$XWKRULW\0DQDJHU,QVWDOODEOH6HUYLFH :HE6SKHUH04 40JU

2EMHFW$XWKRULW\0DQDJHU $FFHVV &RQWURO OLVWV

'RFXPHQWHG,QWHUIDFH 8VHU UHSODFHDEOH ([WHQGDEOH &RPPRQ$&/PDQDJHUIRUGLVWULEXWHGTXHXHPDQDJHUV 81,; :LQGRZV 7DQGHP2SHQ906DQGVRIRUWK L6HULHVDWOHYHO 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.




6-45

Instructor Guide

Instructor Notes: Purpose — Details — MQSeries for OS/2 Warp 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 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 user’s 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 6-46 WebSphere MQ System Administration I




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.




6-47

Instructor Guide

2EMHFW$XWKRULW\0DQDJHU,QVWDOODEOH6HUYLFHV $FFHVVFRQWUROOLVWVDUH:HE6SKHUH04VSHFLILF 1RWLQWHJUDWHGZLWKV\VWHPOHYHOVHFXULW\

&KDQJHVWRXVHU V26DXWKRULW\LVQ WUHFRJQL]HGXQWLO40JUUHVWDUW 1HZ5()5(6+6(&85,7
2QH$&/VHWSHUTXHXHPDQDJHU

1RWVKDUHGEHWZHHQTXHXHPDQDJHUV

$FFHVVFRQWUROIRU:HE6SKHUH04REMHFWV 4XHXHPDQDJHU 4XHXHV 3URFHVVHV 1DPHOLVWV 1RWFKDQQHOV 2$0FDQEHGLVDEOHG 1RWUHFRPPHQGHG 9HU\GLIILFXOWWRUHHVWDEOLVKXQLIRUPDXWKRULW\FKHFNLQJ

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.





Uempty

Instructor Notes: Purpose — To discuss the implementation of the OAM. Details — Additional Information — None. Transition Statement — Next we look at how OAM is using access control lists with WebSphere MQ.




6-49

Instructor Guide

2EMHFW$XWKRULW\0DQDJHU $FFHVV&RQWURO/LVWV 2QHDXWKRULW\ILOHSHUREMHFW 3OXVJOREDOSHUPLVVLRQVILOHV (DFKILOHKDVRQHVWDQ]DSHUSULQFLSDO 3ULQFLSDO $XWKRULW\ ELWSDWWHUQ

:LQGRZV172$0E\SDVVHVDXWKILOHVIRUFHUWDLQFODVVHVRISULQFLSDO 6<67(0ORFDO$GPLQLVWUDWRUVJURXSORFDOPTPJURXS 04REMHFWSHUPLVVLRQV SHUPLVVLRQV *OREDOSHUPLVVLRQVIRUH[DPSOHFRQQHFWDOWXVUVHWDOOVHWLG 2EMHFWSHUPLVVLRQVIRUH[DPSOHEURZVHSXWJHWDQGDOOPTL $GPLQLVWUDWLRQSHUPLVVLRQVIRUH[DPSOHFUWGOWFKJGOWDQGDOODGP 8VHGPRVWO\IRU3&)FRPPDQGV 3OXVDOODQGQRQH (DFKSHUPLVVLRQFRUUHVSRQGVWRDELWLQWKHSHUPLVVLRQELWSDWWHUQ &RQQHFW [ 3XW [

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.





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. Additional Information — None. Transition Statement — Next we look at changes introduced by MQSeries V5.2




6-51

Instructor Guide

2EMHFW$XWKRULW\0DQDJHU 7KH046HULHV8SGDWH :HE6SKHUH049KDVDQHZGHIDXOW2$0LPSOHPHQWDWLRQ 7KLVKDVWKHVDPHDFFHVVFRQWUROIXQFWLRQ %XW 7KHDXWKILOHVKDYHEHHQUHPRYHG &RQILJXUDWLRQLVQRZVWRUHGLQ:HE6SKHUH04PHVVDJHV :KLFKPHDQV 7KHUHLVQRQHHGWRLQGHSHQGHQWO\EDFNXSWKHDXWKILOHV 5HFRYHU\RI$&/VLVDXWRPDWLFDWTXHXHPDQDJHUUHVWDUW ([LVWLQJDXWKILOHVDUHDXWRPDWLFDOO\PLJUDWHGWRQHZIRUPDW 1HZFRPPDQGDPTRDPG GXPSVWKH$&/VLQUHDGDEOHIRUPDW 1HZ2$0DOVRVXSSRUWVWKH5()5(6+6(&85,7<046& FRPPDQG &KDQJHVWRDXVHU V26DXWKRULWLHVWKDWLVWKHJURXSVHW FDQQRZ EHUHDGZLWKRXWUHVWDUWLQJDTXHXHPDQDJHU 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.





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. Additional Information — None. Transition Statement — Next we look at WebSphere MQ V5.3 enhancements.




6-53

Instructor Guide

2EMHFW$XWKRULW\0DQDJHU9 $XWKRUL]DWLRQ)LOHV

6HDPOHVVPLJUDWLRQRIDXWKILOHVIRUH[LVWLQJTXHXHPDQDJHUV $XWKILOHVFDQEHPDLQWDLQHG

*HQHULF3URILOHV

$ELOLW\WRXVHZLOGFDUGVLQ$&/VSHFLILFDWLRQV "

VHWPTDXWQ$% WSXWSIUHG

%HVWPDWFK DOJRULWKPXVHGWRVHOHFWZKLFKSURILOHDSSOLHV

5HGXFHVQXPEHURIDGPLQDFWLRQV

3HUPLVVLRQVFDQEHHVWDEOLVKHGEHIRUHTXHXHVGHILQHG

1HZFRPPDQGVDQGRSWLRQVIRUGLVSOD\LQJLQIRUPDWLRQ 7RGXPSFRPSOHWHFRQILJXUDWLRQVIRUHDV\YLHZLQJ :KRKDVDFFHVVWRZKDW

%DVHGRQ5$&)SURILOHGHILQLWLRQV

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).





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. Additional Information — None. Transition Statement — Next we look at several of WebSphere MQ control commands that provide the management vehicle for WebSphere MQ objects.




6-55

Instructor Guide

6HFXULW\0DQDJHPHQWVHWPTDXW &KDQJHWKHDXWKRUL]DWLRQV TPJU TXHXHV SURFHVVHV QDPHOLVWV DXWKLQIR66/FKDQQHOVHFXULW\ 3ULQFLSDORUJURXSOHYHOFRQWURO 8VHUOHYHORUJURXSOHYHOFRQWURO *UDQXODUFRQWURORIDFFHVV 1RJHQHULFIXQFWLRQV 6XSSRUWVJHQHULFSURILOHV setmqaut -m QMgr -t Objtype -n Profile [-p principalname | -g groupname] permissions stemqaut -m JUPITER -t queue -g VOYAGER

-n MOON.*

+browse +get

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) 6-56 WebSphere MQ System Administration I




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.




6-57

Instructor Guide

Instructor Notes: Purpose — To discuss the setmqaut control command. Details — Additional Information — None. Transition Statement — Next we look at displaying WebSphere MQ security.





Uempty

6HFXULW\0DQDJHPHQWGVSPTDXW 'LVSOD\FXUUHQWDXWKRUL]DWLRQV TPJU TXHXHV SURFHVVHV QDPHOLVWV DXWKLQIR66/FKDQQHOVHFXULW\ 3ULQFLSDORUJURXSOHYHOFRQWURO 8VHUOHYHORUJURXSOHYHOFRQWURO 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 ...

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.




6-59

Instructor Guide

Instructor Notes: Purpose — To discuss the dspmqaut control command. Details — Additional Information — None. Transition Statement — Next we look at WebSphere MQ control command that allows the administrator to dump the current authorizations associated with a specified profile.





Uempty

6HFXULW\0DQDJHPHQWGPSPTDXW 'XPSFXUUHQWDXWKRUL]DWLRQV TPJU TXHXHV SURFHVVHV QDPHOLVWV DXWKLQIR66/FKDQQHOVHFXULW\ 3ULQFLSDORUJURXSOHYHOFRQWURO

GPSPTDXWP4PJUW2EMW\SHQ3URILOH>SSULQFLSDOQDPH_JJURXSQDPH@ GPSPTDXWPTPQDEFWTSXVHU

7KHUHVXOWLQJGXPSZRXOGGLVSOD\ SURILOHDE REMHFWW\SHTXHXH HQWLW\XVHU W\SHSULQFLSDO DXWKRULW\JHWEURZVHSXWLQT

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.




6-61

Instructor Guide

Instructor Notes: Purpose — To discuss the dmpmqaut control command. Details — Additional Information — None. Transition Statement — Next we will look at WebSphere MQ control program security.





Uempty

$FFHVV&RQWUROIRU :HE6SKHUH04&RQWURO3URJUDPV 0RVW:HE6SKHUH04FRQWUROSURJUDPV )RUH[DPSOHFUWPTPVWUPTPUXQPTVFVHWPTDXW +DYHUHVWULFWHGDFFHVV 81,;UHVWULFWVXVHUVWRWKHPTPJURXS

&RQILJXUDWLRQDVDSDUWRI:HE6SKHUH04LQVWDOODWLRQ &RQWUROLPSRVHGE\WKHRSHUDWLQJV\VWHPQRW2$0

2SHQ906UHVWULFWVXVHUVWRWKRVHJUDQWHGWKH040LGHQWLILHU 7DQGHP16.DOORZV 040JURXS 683(5683(5,'

:LQGRZVDOORZV

PTPJURXS $GPLQLVWUDWRUVJURXS 6\VWHPXVHULG

UXQPTVFQHHGVWREHUHVWULFWHG $VFKDQQHOVDUHQRWFRQWUROOHGE\:04DGPLQLVWUDWLRQ$&/V

Figure 6-24. Access Control for WebSphere MQ Control Programs

MQ157.0

Notes:




6-63

Instructor Guide

Instructor Notes: Purpose — To discuss how WebSphere MQ is handled for various platforms. Details — Additional Information — None. Transition Statement — Next we look at security checking in the MQI.





Uempty

$XWKRULW\&KHFNLQJLQWKH04, 04,FDOOVZLWKVHFXULW\FKHFNLQJ 04&21104&211; 0423(1 04387LPSOLFLW0423(1 04&/26(VRPHWLPHV 04&/26( )RU'\QDPLFTXHXHV

:HE6SKHUH04HYHQWVDVDXGLWUHFRUGV (YHQWVZULWWHQWR6<67(0$'0,140*5(9(17TXHXH 'RFXPHQHWHGLQ:HE6SKHUH04(YHQW0RQLWRULQJPDQXDO 5HDVRQFRGH045&B127B$87+25,=('UHWXUQHGLIQRW DXWKRUL]HG

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.




6-65

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.





Uempty

6HFXULW\DQG'LVWULEXWHG4XHXLQJ 3XWDXWKRULW\ 2SWLRQIRUWKHUHFHLYLQJHQGRIDPHVVDJHFKDQQHO 'HIDXOWXVHULGHQWLILHULVXVHG &RQWH[WXVHULGHQWLILHULVXVHG

7UDQVPLVVLRQTXHXH 0HVVDJHVGHVWLQHGIRUDUHPRWHTXHXHPDQDJHUDUHSXWRQD WUDQVPLVVLRQTXHXHE\WKHORFDOTXHXHPDQDJHU

$QDSSOLFDWLRQVKRXOGQRWQRUPDOO\QHHGWRSXWPHVVDJHVGLUHFWO\RQD WUDQVPLVVLRQTXHXHRUQHHGDXWKRULW\WRGRVR

2QO\VSHFLDOV\VWHPSURJUDPVVKRXOGSXWPHVVDJHVGLUHFWO\RQD WUDQVPLVVLRQTXHXHDQGVKRXOGKDYHWKHDXWKRULW\WRGRVR

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.




6-67

Instructor Guide

Instructor Notes: Purpose — To explain some aspects of security that apply to messages destined for a remote queue manager. Details — Nothing additional. Additional Information — None. Transition Statement — Next we look at message context which allows the identity of the sender to flow with a message.





Uempty

0HVVDJH&RQWH[W %

'

48(8( 48(8(

& $

48(8(

,QIRUPDWLRQDERXWVRXUFHRIPHVVDJH ,GHQWLW\VHFWLRQXVHUUHODWHG 2ULJLQVHFWLRQSURJUDPUHODWHG 3DUWRI0HVVDJH'HVFULSWRU &DQEHSDVVHGLQUHODWHGPHVVDJH

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.




6-69

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. Additional Information — None. Transition Statement — Next we look at the context fields.





Uempty

7KH&RQWH[W)LHOGV ,GHQWLW\FRQWH[W 8VHU,GHQWLILHU $FFRXQWLQJ7RNHQ 'LJLWDO2SHQ906 1XPHULFJURXS,'DQGXVHU,' 8,& LQ$6&,,FKDUDFWHUV 26:DUS'26FOLHQW :LQGRZVFOLHQW:LQGRZV $6&,,FKDUDFWHU 26 -REDFFRXQWLQJFRGH 81,; 1XPHULFXVHU,'LQ$6&,, FKDUDFWHUV

2ULJLQFRQWH[W 3XW$SSO7\SH 04$7B$,;04$7B&,&6DQG VRIRUWK

3XW$SSO1DPH 3XW'DWH <<<<00''*07

3XW7LPH ++00667+*07

$SSO2ULJLQ'DWD %ODQN

$SSO,GHQWLW\'DWD %ODQN

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.




6-71

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.





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.




6-73

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. Additional Information — None. Transition Statement — There is no need to have the queue manager set the context fields if they are not going to be used.





Uempty

1R&RQWH[W 5HTXHVWHGE\DSXWPHVVDJHRSWLRQ 04302B12B&217(;7 4XHXHPDQDJHUFOHDUVDOOWKHFRQWH[WILHOGVVSHFLILFDOO\ 3XW$SSO7\SHLVVHWWR04$7B12B&217(;7 7RUHTXHVWGHIDXOWFRQWH[WRUQRFRQWH[WUHTXLUHVQRPRUH DXWKRULW\WKDQWKDWUHTXLUHGWRSXWWKHPHVVDJHRQWKHTXHXH

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.




6-75

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. Additional Information — None. Transition Statement — Next we look at how the context of a message can be preserved when forwarding the message.





Uempty

3DVVLQJ&RQWH[W

' % 48(8( 48(8(

3XWPHVVDJHVRQ4XHXHZLWKVDPH LGHQWLW\FRQWH[WDVPHVVDJHWDNHQIURP 4XHXH 2SHQ4XHXHDV6DYH$OO&RQWH[W 3XWPHVVDJHVZLWK3DVV,GHQWLW\ &RQWH[W 2UWUDQVIHU1R&RQWH[W

$

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.




6-77

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.





Uempty

$OWHUQDWH8VHU$XWKRULW\

' % 48(8( 48(8(

3XWPHVVDJHZLWK$ VDXWKRULW\ %QHHGVDSSURSULDWHDXWKRULW\ 8VHU,'WDNHQIURP0HVVDJH&RQWH[W +RZLWLVUHTXHVWHG $OWHUQDWH8VHU,'ILHOGLQ2EMHFW'HVFULSWRU 2SWLRQRQ0423(1RU04387

$

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.




6-79

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.





Uempty

6HWWLQJ&RQWH[W 7ZRRSHQRSWLRQVWKDWUHTXLUHDXWKRULW\WRXVH 0422B6(7B,'(17,7
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.




6-81

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. Additional Information — None. Transition Statement — Next we look at channel exit programs which have a particular relevance to security.





Uempty

&KDQQHO([LW3URJUDPV &XUUHQW:HE6SKHUH04&KDQQHO([LW3URJUDPV

$XWRGHILQLWLRQ 6HFXULW\ 0 & $

04387

6HFXULW\ 6HQG

5HFHLYH

0 & $

0HVVDJH

04*(7

0HVVDJH 0HVVDJHUHWU\

7UDQVPLVVLRQ TXHXH

'HVWLQDWLRQ TXHXH

6LJQLILFDQWVHWXSUHTXLUHGIRUXVHUH[LWV 1RW RXWWKHER[ VHFXULW\ 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 © Copyright IBM Corp. 1996, 2003



6-83

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.





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. © Copyright IBM Corp. 1996, 2003



6-85

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. • • • •

Application data conversion 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:





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.




6-87

Instructor Guide

&KDQQHO([LW3URJUDPVRQ04,&KDQQHOV $XWRGHILQLWLRQ 6HFXULW\ 04&211 0423(1 04387

& / 1 7 & 2 1 1

6HFXULW\ 6HQG

5HFHLYH

6 9 5 & 2 1 1

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.





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. Additional Information — None. Transition Statement — Next we will look at Secure Sockets Layer and what it provides in WebSphere MQ V5.3.




6-89

Instructor Guide

6HFXUH6RFNHWV/D\HU 3URWRFROWRDOORZWUDQVPLVVLRQRIVHFXUHGDWDRYHUDQLQVHFXUH QHWZRUN &RPELQHVWKHVHWHFKQLTXHV 6\PPHWULF6HFUHW.H\HQFU\SWLRQ $V\PPHWULF3XEOLF.H\HQFU\SWLRQ 'LJLWDO6LJQDWXUH 'LJLWDO&HUWLILFDWHV 3URWHFWLRQ &OLHQW6HUYHU 4PJU40JUFKDQQHOV 7RFRPEDW6HFXULW\3UREOHPV (DYHVGURSSLQJ (QFU\SWLRQWHFKQLTXHV 7DPSHULQJ 'LJLWDO6LJQDWXUH ,PSHUVRQDWLRQ 'LJLWDO&HUWLILFDWHV 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?





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.




6-91

Instructor Guide

66/+DQGVKDNH +L IURP -LOO

-LOO

-DFN

7KH&OLHQW+HOOR -LOOVHQGV-DFNVRPHUDQGRPWH[W $OVRVHQGVZKDW&LSKHU6SHFVDQGFRPSUHVVLRQPHWKRGV VKHFDQXVH -LOOLVWKHFOLHQW Figure 6-36. SSL Handshake

MQ157.0

Notes:





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




6-93

Instructor Guide

66/+DQGVKDNH +LIURP -LOO

-LOO -DFN V'LJLWDO &HUWLILFDWH

-DFN

+LIURP-DFN -DFN V&HUW &HUW5HTXHVW

&$6LJ

7KH6HUYHU+HOOR -DFNVHQGV-LOOVRPHUDQGRPWH[W -DFNFKRRVHVWKH&LSKHU6SHFDQGFRPSUHVVLRQ PHWKRGWREHXVHGIURP-LOO VOLVW 7KH6HUYHU&HUWLILFDWH 7KH&OLHQW&HUWLILFDWH5HTXHVW Figure 6-37. SSL Handshake

MQ157.0

Notes:





Uempty

Instructor Notes: Purpose — To attempt to explain what is involved in the SSL handshake. 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). Transition Statement — Step 3




6-95

Instructor Guide


-LOO -DFN V'LJLWDO &HUWLILFDWH

&$ 3XEOLF

-DFN


&$6LJ

,W V-DFN 3XEOLF

-

9HULI\6HUYHU&HUWLILFDWH &KHFN9DOLGLW\3HULRG 'HFU\SWXVLQJ&$ V3XEOLF.H\YHULILHVWKDW&$LVWUXVWHG &KHFN'RPDLQ1DPHDQGRU'LVWLQJXLVKHG1DPH $OVRUHFHLYHV-DFN V3XEOLF.H\ Figure 6-38. SSL Handshake

MQ157.0

Notes:





Uempty

Instructor Notes: Purpose — To attempt to explain what is involved in the SSL handshake. 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. Transition Statement — Step 4




6-97

Instructor Guide


-LOO

-DFN


6HFUHW.H\ -LOO V&HUW

,W V-DFN 3XEOLF

-

-LOO V'LJLWDO &HUWLILFDWH

&$6LJ

&OLHQW.H\([FKDQJH -LOOVHQGV-DFNWKH6HFUHW.H\WRXVH 7KLVLVHQFU\SWHGZLWK-DFN V3XEOLF.H\ $OVRVHQGVKHUFHUWLILFDWH

Figure 6-39. SSL Handshake

MQ157.0

Notes:





Uempty

Instructor Notes: Purpose — To attempt to explain what is involved in the SSL handshake. 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. Transition Statement — Step 5




6-99

Instructor Guide


-LOO

-DFN



,W V-DFN 3XEOLF

-

-LOO V'LJLWDO &HUWLILFDWH

&$ 3XEOLF

&$6LJ

,W V-LOO

9HULI\&OLHQW&HUWLILFDWH 'HFU\SWXVLQJ&$ VSXEOLF.H\


MQ157.0

Notes:





Uempty

Instructor Notes: Purpose — To attempt to explain what is involved in the SSL handshake. 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.




6-101

Instructor Guide

66/+DQGVKDNH

+LIURP -LOO

-LOO

-DFN



,W V-DFN 3XEOLF

3ULYDWH PHVVDJHVXVLQJ 6HFUHW.H\

,W V-LOO

6HQG,QIRUPDWLRQXVLQJDJUHHG6HFUHW.H\ 5DQGRPO\JHQHUDWHGWLPHNH\ 7KLVLVQRZDVHFXUHOLQH


MQ157.0

Notes:





Uempty

Instructor Notes: Purpose — To attempt to explain what is involved in the SSL handshake. 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.




6-103

Instructor Guide

40*5$WWULEXWHVIRU66/ $/7(540*5FRPPDQG 66/.(<5

6HWVWKH66/.H\5HSRVLWRU\

66/&5/1/

6HWVWKH66/&5/1DPHOLVW

66/&5<3

6HWVWKH66/&U\SWR+DUGZDUH

66/7$6.6

6HWVWKH66/7DVNV

Figure 6-42. QMGR Attributes for SSL

MQ157.0

Notes:





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.




6-105

Instructor Guide

40*5$XWKHQWLFDWLRQ2EMHFW $/7(5$87+,1)2 '(),1($87+,1)2 '(/(7($87+,1)2 ',63/$<$87+,1)2

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.





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.




6-107

Instructor Guide

&KDQQHO$WWULEXWHVIRU66/ '(),1(RU$/7(5&+$11(/ 66/&,3+ 66/3((5 66/&$87+

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.





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. Additional Information — Transition Statement — Next we will look at the approach to security when running WebSphere MQ client applications.




6-109

Instructor Guide

$FFHVV&RQWUROIRUD:HE6SKHUH04&OLHQW $FFHVVFRQWUROLVEDVHGRQDXVHU,'XVHGE\WKHVHUYHUFRQQHFWLRQ SURFHVV 9DOXHRI0&$8VHU,GHQWLILHULQ04&'GHWHUPLQHVWKLVXVHU,' 6HFXULW\H[LWVDWERWKHQGVRIWKH04,FKDQQHO &OLHQWVHFXULW\H[LWFDQIORZDXVHU,'DQGSDVVZRUG 6HUYHUVHFXULW\H[LWFDQDXWKHQWLFDWHWKHXVHU,'DQGVHW 0&$8VHU,GHQWLILHU 1RVHFXULW\H[LWDWWKHFOLHQWHQGRIWKH04,FKDQQHO 9DOXHVRI

/RJJHGBLQ86(5,'RU 04B86(5B,'DQG04B3$66:25'IORZWRWKHVHUYHUV\VWHP

6HUYHUVHFXULW\H[LWFDQDXWKHQWLFDWHWKHXVHU,'DQGVHW 0&$8VHU,GHQWLILHU

1RVHFXULW\H[LWDWHLWKHUHQGRIWKH04,FKDQQHO 0&$8VHU,GHQWLILHUKDVWKHYDOXHRI0&$86(5LILWLVQRQEODQN 0&$8VHU,GHQWLILHUKDVWKHYDOXHRIIORZHGXVHU,'RWKHUZLVH

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.





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. Additional Information — None. Transition Statement — Next we look at Userids with remote queueing and clients.




6-111

Instructor Guide

5HPRWH4XHXLQJDQG&OLHQWV &KDQQHO([LWV $QXPEHURIFKDQQHOH[LWVDUHDYDLODEOHLQWKHSURGXFWDQGDV 6XSSRUW3DFV 6HYHUDOYHQGRUVLQWKLVPDUNHWWRR 0&$86(5 7KHGHIDXOWVHWWLQJLVZLGHRSHQHVSHFLDOO\IRUFOLHQWDWWDFK 0D\ZDQWWRVHWWKLVWRUHVWULFWZKRFDQDFFHVV\RXUTXHXH PDQDJHU 04B86(5B,'HQYLURQPHQWYDULDEOH 7KLVZDVUHPRYHGIRU:LQGRZV17DQG81,;LQWKHUHOHDVH FOLHQWHQYLURQPHQWV 7KHORJJHGLQXVHUQDPHLVQRZDXWRPDWLFDOO\XVHG %XWWKLVLVQRWDXWKHQWLFDWHGDWWKHVHUYHU\RXPD\VWLOOQHHG VHFXULW\H[LWV

Figure 6-46. Remote Queueing and Clients

MQ157.0

Notes:





Uempty

Instructor Notes: Purpose — Details — Additional Information — None. Transition Statement — Next we look at supplied sample channel exit programs.




6-113

Instructor Guide

6XSSOLHG&KDQQHO([LW3URJUDPV 9HUVLRQTXHXHPDQDJHUVRQO\ 6HFXULW\PHVVDJHVHQGDQGUHFHLYHH[LWV :LQGRZVFOLHQWVXSSOLHVVHFXULW\VHQGDQGUHFHLYHH[LWV ([LWSURJUDPVVXSSOLHGLQVRXUFHDQGREMHFWIRUPDW 8VHV'&(6HFXULW\IRU $XWKHQWLFDWLRQRISDUWQHUE\WRNHQH[FKDQJH 'DWDHQFU\SWLRQGHFU\SWLRQ

Figure 6-47. Supplied Channel Exit Programs

MQ157.0

Notes:





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. Additional Information — None. Transition Statement — End of the topic. Next there is a practical exercise to do a simple client connection and to demonstrate autodefinition.




6-115

Instructor Guide





Uempty

Checkpoint Unit 6 Checkpoint 1. T/F All SupportPacs are AS-IS code. Correct Answer: False 2. T/F A client channel does not require a START CHANNEL command. Correct Answer: True 3. On a Version 5.1 client, what additional method is available to identify the server connection desired? a. b. c. d.

Use SET MQSERVER environment variable Use the MQCONNX call Use a client channel table 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. Correct Answer: False




6-117

Instructor Guide

8QLW6XPPDU\ :HE6SKHUH046XSSRUW3DFV :HE6SKHUH04FOLHQWV 6HFXULW\ ([HUFLVH


MQ157.0

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.





Uempty

Instructor Notes: Purpose — To summarize the unit. Details — Nothing additional. Additional Information — None. Transition Statement — End of the unit.




6-119

Instructor Guide





Uempty

Unit 7. WebSphere MQ for Windows (optional) What This Unit is About This unit describes focusing on those aspects of its administration which are unique to the product.

What You Should Be Able to Do After completing this unit, you should be able to: • 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

How You Will Check Your Progress Accountability: • Checkpoint questions • Classroom discussions


Unit 7. WebSphere MQ for Windows (optional)


7-1

Instructor Guide

8QLW2EMHFWLYHV $IWHUFRPSOHWLQJWKLVXQLW\RXVKRXOGEHDEOHWR ,QWURGXFHWKH:HE6SKHUH04IRU:LQGRZV/HDIQRGH TXHXH PDQDJHUV 3URYLGHDQRYHUYLHZRIDYDLODEOHIXQFWLRQ 'HWDLOOLPLWDWLRQV 'HVFULEHLQVWDOODWLRQDQGDGPLQLVWUDWLRQ ([SODLQFKDQQHOLPSOHPHQWDWLRQIRUOHDIQRGHTXHXHPDQDJHUV


MQ157.0

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.

7-2





Uempty

Instructor Notes: Purpose — Highlight the unit objectives. 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 WebSphere MQ for Windows. 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




7-3

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. After completing this unit, the student should be able to: • 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.

7-4





Uempty

7.1 WebSphere MQ for Windows (optional) This topic is about the administration of WebSphere MQ for Windows.

Instructor Topic Introduction What students will do — Students will listen to a presentation on and may see a demonstration of it. How students will do it — No student activities are planned for this topic. 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.




7-5

Instructor Guide

3RVLWLRQLQJ 6PDOOIRRWSULQWRUOLJKWZHLJKWTXHXHPDQDJHU /HDIQRGHTXHXHPDQDJHU 7KHUHIRUH 1RWLQWHQGHGDVDQLQWHUPHGLDWHTXHXHPDQDJHU 'RHVQRWVXSSRUW:HE6SKHUH04FOLHQWV :RXOGW\SLFDOO\UXQRQDZRUNVWDWLRQQRWSRZHUIXOHQRXJKWRDFW DVDVHUYHU 0LQLPDOXVHUFRQWDFWZLWK:HE6SKHUH04IXQFWLRQ 7&3,3VXSSRUWRQO\

Figure 7-2. Positioning

MQ157.0

Notes:

7-6





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. Additional Information — None. Transition Statement — There are two current versions of WebSphere MQ for Windows. Next we look at how each is positioned.




7-7

Instructor Guide

9HUVLRQV 9HUVLRQ ELWTXHXHPDQDJHU 6XSSRUWHGHQYLURQPHQWV :LQGRZV :LQGRZVIRU:RUNJURXSV :LQGRZVLQELWFRPSDWLELOLW\PRGH :,126RQ26:DUS9RUODWHU 9HUVLRQ ELWTXHXHPDQDJHU 6XSSRUWHGHQYLURQPHQWV :LQGRZV :LQGRZV179

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.

7-8





Uempty

Instructor Notes: Purpose — To introduce the two versions of WebSphere MQ for Windows and their intended environments. Details — Nothing in addition to the student notes. Additional Information — None. 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.




7-9

Instructor Guide

)DPLO\'LIIHUHQFHV :HE6SKHUH04IRU:LQGRZVGRHVQRWVXSSRUW $XWKRULW\FKHFNLQJ &HUWDLQ04,IXQFWLRQ &KDQQHODXWRGHILQLWLRQ &KDQQHOKHDUWEHDWV &KDQQHOLQVWDQFHV &RQILJXUDWLRQILOHV &RQWH[WSDVVLQJ &RQWUROFRPPDQGV 'DWDFRQYHUVLRQ 'HDGOHWWHUTXHXHV

'LVWULEXWLRQOLVWV ,QVWDOODEOHVHUYLFHVDQGFRPSRQHQWV 0HGLDUHFRYHU\ 0HVVDJHUHWU\ 046HULHVFOLHQWV 7ULJJHULQJ 4XHXHPDQDJHUTXLHVFLQJ 5HPRWHDGPLQLVWUDWLRQXVLQJ046HULHVFRPPDQGV 7ZRSKDVHFRPPLWSURWRFRODVDUHVRXUFHPDQDJHU 8VHUZULWWHQ0&$V

:HE6SKHUH04IRU:LQGRZV9HUVLRQVXSSRUWV &RPPDQGVHUYHUDQG3&)FRPPDQGV )DVWQRQSHUVLVWHQWPHVVDJHV ,QVWUXPHQWDWLRQHYHQWV 6HWVLJQDORSWLRQRQWKH04*(7FDOO

EXWQRW:HE6SKHUH04IRU:LQGRZV9HUVLRQ

Figure 7-4. Family Differences

MQ157.0

Notes:





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. WebSphere MQ clients 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. © Copyright IBM Corp. 1996, 2003



7-11

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. Additional Information — None. 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.





Uempty

&KDQQHO*URXS $QDPHGFROOHFWLRQRIFKDQQHOV :KHQ\RXVWDUWDFKDQQHOJURXSDOOFKDQQHOVLQWKHJURXSDUH VWDUWHGDWWKDWWLPH ,QFOXGHVRQO\FKDQQHOVIRUZKLFKDFDOOHU0&$QHHGVWREHVWDUWHG &DQLQFOXGHWKH:HE6SKHUH04OLVWHQHU $TXHXHPDQDJHUFDQRZQPDQ\FKDQQHOJURXSVEXW RQO\RQHFKDQQHOJURXSFDQEHDFWLYHDWDWLPH $FKDQQHOPD\EHORQJWRPRUHWKDQRQHFKDQQHOJURXS

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.




7-13

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.





Uempty

Instructor Notes: Purpose — To explain the concept of a channel group. Details — Nothing in addition to the student notes. Additional Information — None. Transition Statement — The other WebSphere MQ component unique to WebSphere MQ for Windows is the connection. Next we examine this concept.




7-15

Instructor Guide

&RQQHFWLRQ 6XSSRUWHGE\9HUVLRQRQO\ $QDPHGFRPSRQHQWWRKLGHWKHFRPSOH[LWLHVRITXHXH PDQDJHUVFKDQQHOJURXSVDQGSKRQHERRNHQWULHV 7KUHHW\SHV 6WDQGDORQHFRQQHFWLRQDTXHXHPDQDJHU /$1FRQQHFWLRQ DTXHXHPDQDJHUD FKDQQHOJURXS 'LDOXSFRQQHFWLRQ DTXHXHPDQDJHUD FKDQQHOJURXS DSKRQHERRNHQWU\ :KHQ\RXVWDUWDFRQQHFWLRQDOOFRPSRQHQWVEHORQJLQJWRWKH FRQQHFWLRQDUHVWDUWHGDWWKDWWLPH $TXHXHPDQDJHUDFKDQQHOJURXSRUDSKRQHERRNHQWU\FDQ EHORQJWRPRUHWKDQRQHFRQQHFWLRQEXWRQO\RQHFRQQHFWLRQFDQ EHDFWLYHDWDWLPH

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





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.




7-17

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. Additional Information — None. Transition Statement — Next we examine the dial-up support provided by WebSphere MQ for Windows.





Uempty

'LDOXS6XSSRUW 9HUVLRQ 1HHGWRZULWHWZREDWFKILOHV 7RVWDUWWKHGLDOXSGHYLFH 7RVWRSWKHGLDOXSGHYLFH

6DPSOHEDWFKILOHVDUHSURYLGHGZLWKFRPPHQWV 1HHGWRFUHDWHDWUDQVSRUWOLQNGHFODULQJWKHQDPHVRIWKHWZR EDWFKILOHV 9HUVLRQ 8VHVWKHEXLOWLQGLDOXSVXSSRUWSURYLGHGE\:LQGRZV 1HHGWRFUHDWH

$GLDOXSQHWZRUNLQJFRQQHFWLRQLQ:LQGRZV SKRQHERRNHQWU\LQ :HE6SKHUH04 $Q:HE6SKHUH04GLDOXSFRQQHFWLRQUHIHUHQFLQJDSKRQHERRNHQWU\

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.




7-19

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.





Uempty

Instructor Notes: Purpose — To explain what dial-up support is provided by WebSphere MQ for Windows. Details — Nothing in addition to the student notes. Additional Information — None. Transition Statement — Next we look at how WebSphere MQ for Windows is installed.




7-21

Instructor Guide

,QVWDOODWLRQ 6WDQGDUGSURFHGXUH :LQGRZVDQG:LQGRZV17 6HOHFW,QVWDOOIURP$GG5HPRYH3URJUDPVLQ&RQWURO3DQHO 2WKHUHQYLURQPHQWV 6HOHFW5XQIURP)LOHPHQXDQGH[HFXWH$?,167$// 9HUVLRQRQO\VHOHFWZKLFKFRPSRQHQWVWRLQVWDOO %DVH 2QOLQHLQIRUPDWLRQ 7RRONLWDQGVDPSOHV 9HUVLRQRQO\WZRW\SHVRILQVWDOODWLRQ &RPSDFW &RPSOHWH $XWRPDWLFLQVWDOODWLRQSRVVLEOH $XWRPDWHGLQVWDOODWLRQYHULILFDWLRQDYDLODEOH


MQ157.0

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.





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.




7-23

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. Additional Information — None. 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.





Uempty

$GPLQLVWUDWLRQRQ9HUVLRQ ,QVWDOODWLRQFUHDWHVDQ:HE6SKHUH04IRU:LQGRZVSURJUDP JURXSSURYLGLQJDFFHVVWR

8WLOLWLHV

6DPSOHSURJUDPV

&UHDWHFRPSRQHQWV 'HOHWHFRPSRQHQWV 6WDQGDUGFRQWUROV $GYDQFHGFRQWUROV 046&FRPPDQGV &UHDWHDQG*R ,QVWDOODWLRQ 9HULI\,QVWDOO 6HUYLFH,QIRUPDWLRQ 6HUYLFH7UDFH

3XWWLQJPHVVDJHV *HWWLQJPHVVDJHV %URZVLQJPHVVDJHV

2QOLQHLQIRUPDWLRQ &RPPDQG5HIHUHQFH 8VHU V*XLGH 4XLFN7RXU

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.




7-25

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 7-26 WebSphere MQ System Administration I




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.

Uempty

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.




7-27

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. Additional Information — None. Transition Statement — Next we look at the administration interfaces provided by WebSphere MQ for Windows Version 2.1.





Uempty

$GPLQLVWUDWLRQRQ9HUVLRQ :HE6SKHUH04UXQVZKHQHYHU:LQGRZVLVUXQQLQJ :HE6SKHUH04LFRQRQWKH:LQGRZVWDVNEDU :HE6SKHUH043URSHUWLHVGLDORJER[FDQEHRSHQHG %\GRXEOHFOLFNLQJRQWKH:HE6SKHUH04LFRQ %\VHOHFWLQJ2SHQ:HE6SKHUH043URSHUWLHVIURPWKH :HE6SKHUH04LFRQPHQX )URPWKH:LQGRZV&RQWURO3DQHO %\VHOHFWLQJWKHVKRUWFXWIURPWKH:HE6SKHUH04IRU:LQGRZV IROGHU DQGSURYLGHVDFFHVVWRWKHIROORZLQJSDJHV &RQQHFWLRQV &RPSRQHQWV 2SWLRQV

046& &RPPDQG6HUYHU 6HUYLFH

6KRUWFXWVIURPWKH:HE6SKHUH04IRU:LQGRZVIROGHUWR &RPPDQG5HIHUHQFH 046HULHV3URSHUWLHV 4XLFN7RXU

5HJLVWUDWLRQ 6HUYLFH7UDFH 8VHU V*XLGH

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. © Copyright IBM Corp. 1996, 2003



7-29

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 WebSphere MQ for Windows Version 2.1. - The WebSphere MQ Properties dialogue box.





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.




7-31

Instructor Guide

Instructor Notes: Purpose — To explain how administration function is accessed on WebSphere MQ for Windows Version 2.1. Details — Nothing in addition to the student notes. Additional Information — None. 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.





Uempty

6XSSRUWHG046HULHV&RPPDQGV $OOUHOHYDQW'(),1($/7(5DQG'(/(7(FRPPDQGV 7KHIROORZLQJ',63/$
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




7-33

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.





Uempty

Instructor Notes: Purpose — To summarize which WebSphere MQ commands are supported by WebSphere MQ for Windows. Details — Nothing in addition to the student notes. Additional Information — None. 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.




7-35

Instructor Guide

,QLWLDOL]DWLRQ,1, )LOHRQ9HUVLRQ &5($7(04,1,LQWKH?04:GLUHFWRU\ &RQWDLQVGHILQLWLRQVZKLFKDUHUHDGDQGH[HFXWHGE\WKH &UHDWHDQG*RXWLOLW\ 7KHGHILQLWLRQVFDQEHXVHGWR &UHDWHDOOWKH:HE6SKHUH04FRPSRQHQWVUHTXLUHGE\DXVHURQ DZRUNVWDWLRQ 6WDUW6WDQGDUG&RQWUROVRU$GYDQFHGFRQWUROVDXWRPDWLFDOO\RU DGGRQHRIWKHVHWRWKH:LQGRZV6WDUW8SJURXS 7KHGHIDXOW,1,ILOHRQWKHLQVWDOODWLRQGLVNHWWHVFDQEHUHSODFHG

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 7-36 WebSphere MQ System Administration I




Uempty

Windows, optionally verify the installation, run the Create and Go utility, and then start an application.




7-37

Instructor Guide

Instructor Notes: Purpose — To explain the concept of an initialization, or INI, file on WebSphere MQ for Windows Version 2.0. Details — Nothing in addition to the student notes. Additional Information — None. Transition Statement — Next we look at how the equivalent function is provided on WebSphere MQ for Windows Version 2.1.





Uempty

046HULHV'HILQLWLRQ04' )LOHRQ9HUVLRQ &5($7(0404'LQWKH?3URJUDP)LOHV?046HULHVIRU:LQGRZV GLUHFWRU\ :KHQLWLVUXQLWFDQ &UHDWHDOOWKH:HE6SKHUH04FRPSRQHQWVUHTXLUHGE\DXVHURQ DZRUNVWDWLRQ 'HVLJQDWHRQHFRQQHFWLRQWREHVWDUWHGDXWRPDWLFDOO\ZKHQHYHU :HE6SKHUH04VWDUWV ,WLVUXQ $XWRPDWLFDOO\DVSDUWRIWKHLQVWDOODWLRQSURFHVV 6XEVHTXHQWO\ZKHQHYHU:HE6SKHUH04VWDUWV &KHFNVWKHGDWHWLPHDQGVL]HRIWKH04'ILOHDQGSURPSWV WKHXVHU %\VHOHFWLQJ5XQ04'ILOHQRZIURPWKH:HE6SKHUH04LFRQ PHQX 0DLQGLIIHUHQFHVFRPSDUHGWRDQ,1,ILOHRQ9HUVLRQ 1RXVHUDFWLRQUHTXLUHGWRUXQDQ04'ILOH 0RUHNH\ZRUGV 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.




7-39

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.





Uempty

Instructor Notes: Purpose — To explain the concept of an WebSphere MQ definition, or MQD, file on WebSphere MQ for Windows Version 2.1. Details — Nothing in addition to the student notes. Additional Information — None. Transition Statement — Next we look at an example of an MQD file.




7-41

Instructor Guide

([DPSOHRIDQ04')LOH [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

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.





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.




7-43

Instructor Guide

Instructor Notes: Purpose — To show an simple example of an MQD file and to explain some of its more important features. Details — Nothing in addition to the student notes. Additional Information — None. Transition Statement — End of the topic. There now follows the final exercise and checkpoints followed by a summary of this unit.





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. b. c. d.

Command server Dead letter queue Requester channels 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. b. c. d.

Windows 3.1 Windows NT Windows for Workgroups 3.11 WIN-OS/2

Correct Answer: b Only 32-bit implementations are supported on 2.1.




7-45

Instructor Guide

8QLW6XPPDU\ 3RVLWLRQLQJ 6RPHGLIIHUHQFHVFRPSDUHGWRRWKHU:HE6SKHUH04TXHXH PDQDJHUV DQGVRPHXQLTXHIHDWXUHV *8,IRUDGPLQLVWUDWLRQZHOOLQWHJUDWHGLQWRWKH:LQGRZV HQYLURQPHQW 0LQLPDOXVHUFRQWDFWZLWK:HE6SKHUH04IXQFWLRQ )LQDOFKHFNSRLQWWHVW


MQ157.0

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.





Uempty

Instructor Notes: Purpose — To summarize the unit. Details — As this ends course - be sure to thank students. Additional Information — None. Transition Statement — End of the unit and the course.




7-47

Instructor Guide





Uempty

Appendix A. Checkpoint Solutions Unit 1 1. T/ F

WebSphere MQ only supports asynchronous messaging.

Correct Answer: False 2. WebSphere MQ assured delivery means that: a. b. c. d.

A report of delivery will always be sent back. Unless the entire system goes down, no messages are lost. Messages may be duplicated but never lost. 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. Correct Answer: False 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


Appendix A. Checkpoint Solutions


A-1

Instructor Guide

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. Correct Answer: False 2. A temporary dynamic queue can store: a. b. c. d.

Nonpersistent messages only. Both persistent and non-persistent messages. Reply messages only. 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. Correct Answer: True 5. Which of the following are valid control commands for controlling a broker? (Choose 2) a. b. c. d.

rcrmqbrk dspmqbrk crtmqbrk strmqbrk

Correct Answer: b, d Unit 4 1. T/F Authorization Service are not supported on iSeries. Correct Answer: True 2. The two types of logging supported on HP-UX are: a. journaling b. linear A-2





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. b. c. d.

QMGRERR ERRORS amqerr01.log 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. Correct Answer: False 5. What type of log can a damaged object be re-created from? a. b. c. d.

circular journal receiver linear 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. Correct Answer: True 2. If the SEQWRAP value on a SENDER channel is different from the value on the RECEIVER, what will happen? a. b. c. d.

They negotiate to the lower value at channel startup time. The channel will not start. They negotiate to the higher value at channel startup time. 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. © Copyright IBM Corp. 1996, 2003



A-3

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. Correct Answer: False Unit 6 1. T/F All SupportPacs are AS-IS code. Correct Answer: False 2. T/F A client channel does not require a START CHANNEL command. Correct Answer: True 3. On a Version 5.1 client, what additional method is available to identify the server connection desired? a. b. c. d.

Use SET MQSERVER environment variable Use the MQCONNX call Use a client channel table 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. Correct Answer: False 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. b. c. d.

Command server Dead letter queue Requester channels 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-4





Uempty

a. b. c. d.

Windows 3.1 Windows NT Windows for Workgroups 3.11 WIN-OS/2

Correct Answer: b Only 32-bit implementations are supported on 2.1.




A-5

Instructor Guide

A-6





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. MQCC_ (Completion code) MQCC_UNKNOWN

-1

X ‘ FFFFFFFF

MQCC_OK

0

X’00000000’

MQCC_WARNING

1

X’ 00000001’

MQCC_FAILED

2

X’ 00000002’

MQFB_ (Feedback)

MQFB_NONE

0

X’00000000’

MQFB_SYSTEM_FIRST

1

X’00000001’

MQFB_QUIT

256

X’00000100’

MQFB_EXPIRATION

258

X’00000102’

MQFB_COA

259

X’00000103’

MQFB_COD

260

X’00000104’

MQFB_CHANNEL_COMPLETED

262

X’00000106’

MQFB_CHANNEL_FAIL_RETRY

263

X’00000107’


Appendix B. Selected WebSphere MQ Constants


B-1

Instructor Guide

MQFB_CHANNEL_FAIL

264

X’00000108’

MQFB_APPL_CANNOT_BE_STARTED

265

X’00000109’

MQFB_TM_ERROR

266

X’0000010A’

MQFB_APPL_TYPE_ERROR

267

X’0000010B’

MQFB_STOPPED_BY_MSG_EXIT

268

X’0000010C’

MQFB_XMIT_Q_MSG_ERROR

271

X’0000010F

MQFB_PAN

275

X’00000113’

MQFB_NAN

276

X’00000114’

MQFB_STOPPED_BY_CHAD_EXIT

277

X’00000115’

MQFB_NOT_A_REPOSITORY_MSG

280

X’00000118’

MQFB_DATA_LENGTH_ZERO

291

X’00000123’

MQFB_DATA_LENGTH_NEGATIVE

292

X’00000124’

MQFB_DATA_LENGTH_TOO_BIG

293

X’00000125’

MQFB_BUFFER_OVERFLOW

294

X’00000126’

MQFB_LENGTH_OFF_BY_ONE

295

X’00000127’

MQFB_IIH_ERROR

296

X’00000128’

MQFB_NOT_AUTHORIZED_FOR_IMS

298

X’0000012A’

MQFB_IMS_ERROR

300

X’0000012C’

MQFB_IMS_FIRST

301

X’0000012D’

MQFB_IMS_LAST

399

X’0000018F’

MQFB_CICS_INTERNAL_ERROR

401

X’00000191’

MQFB_CICS_NOT_AUTHORIZED

402

X’00000192’

MQFB_CICS_BRIDGE_FAILURE

403

X’00000193’

MQFB_CICS_CORREL_ID_ERROR

404

X’00000194’

MQFB_CICS_CCSID_ERROR

405

X’00000195’

MQFB_CICS_ENCODING_ERROR

406

X’00000196’

MQFB_CICS_CIH_ERROR

407

X’00000197’

B-2





Uempty MQFB_CICS_UOW_ERROR

408

X’00000198’

MQFB_CICS_COMMAREA_ERROR

409

X’00000199’

MQFB_CICS_APPL_NOT_STARTED

410

X’0000019A’

MQFB_CICS_APPL_ABENDED

411

X’0000019B’

MQFB_CICS_DLQ_ERROR

412

X’0000019C’

MQFB_CICS_UOW_BACKED_OUT

413

X’0000019D’

MQFB_SYSTEM_LAST

65535

X’0000FFFF’

MQFB_APPL_FIRST

65536

X’00010000’

MQFB_APPL_LAST

999999999

X’3B9AC9FF’

MQRC_NONE

0

X’00000000’

MQRC_APPL_FIRST

900

X’00000384’

MQRC_APPL_LAST

999

X’000003E7’

MQRC_ALIAS_BASE_Q_TYPE_ERROR

2001

X’000007D1’

MQRC_ALREADY_CONNECTED

2002

X’000007D2’

MQRC_BACKED_OUT

2003

X’000007D3’

MQRC_BUFFER_ERROR

2004

X’000007D4’

MQRC_BUFFER_LENGTH_ERROR

2005

X’000007D5’

MQRC_CHAR_ATTR_LENGTH_ERROR

2006

X’000007D6’

MQRC_CHAR_ATTRS_ERROR

2007

X’000007D7’

MQRC_CHAR_ATTRS_TOO_SHORT

2008

X’000007D8’

MQRC_CONNECTION_BROKEN

2009

X’000007D9’

MQRC_DATA_LENGTH_ERROR

2010

X’000007DA’

MQRC_DYNAMIC_Q_NAME_ERROR

2011

X’000007DB’

MQRC_ENVIRONMENT_ERROR

2012

X’000007DC’

MQRC_EXPIRY_ERROR

2013

X’000007DD’

MQRC_ (Reason code)




B-3

Instructor Guide

MQRC_FEEDBACK_ERROR

2014

X’000007DE’

MQRC_GET_INHIBITED

2016

X’000007E0’

MQRC_HANDLE_NOT_AVAILABLE

2017

X’000007E1’

MQRC_HCONN_ERROR

2018

X’000007E2’

MQRC_HOBJ_ERROR

2019

X’000007E3’

MQRC_INHIBIT_VALUE_ERROR

2020

X’000007E4’

MQRC_INT_ATTR_COUNT_ERROR

2021

X’000007E5’

MQRC_INT_ATTR_COUNT_TOO_SMALL

2022

X’000007E6’

MQRC_INT_ATTRS_ARRAY_ERROR

2023

X’000007E7’

MQRC_SYNCPOINT_LIMIT_REACHED

2024

X’000007E8’

MQRC_MAX_CONNS_LIMIT_REACHED

2025

X’000007E9’

MQRC_MD_ERROR

2026

X’000007EA’

MQRC_MISSING_REPLY_TO_Q

2027

X’000007EB’

MQRC_MSG_TYPE_ERROR

2029

X’000007ED’

MQRC_MSG_TOO_BIG_FOR_Q

2030

X’000007EE’

MQRC_MSG_TOO_BIG_FOR_Q_MGR

2031

X’000007EF’

MQRC_NO_MSG_AVAILABLE

2033

X’000007F1’

MQRC_NO_MSG_UNDER_CURSOR

2034

X’000007F2’

MQRC_NOT_AUTHORIZED

2035

X’000007F3’

MQRC_NOT_OPEN_FOR_BROWSE

2036

X’000007F4’

MQRC_NOT_OPEN_FOR_INPUT

2037

X’000007F5’

MQRC_NOT_OPEN_FOR_INQUIRE

2038

X’000007F6’

MQRC_NOT_OPEN_FOR_OUTPUT

2039

X’000007F7’

MQRC_NOT_OPEN_FOR_SET

2040

X’000007F8’

MQRC_OBJECT_CHANGED

2041

X’000007F9’

MQRC_OBJECT_IN_USE

2042

X’000007FA’

MQRC_OBJECT_TYPE_ERROR

2043

X’000007FB’

B-4





Uempty MQRC_OD_ERROR

2044

X’000007FC’

MQRC_OPTION_NOT_VALID_FOR_TYPE

2045

X’000007FD’

MQRC_OPTIONS_ERROR

2046

X’000007FE’

MQRC_PERSISTENCE_ERROR

2047

X’000007FF’

MQRC_PERSISTENT_NOT_ALLOWED

2048

X’00000800’

MQRC_PRIORITY_EXCEEDS_MAXIMUM

2049

X’00000801’

MQRC_PRIORITY_ERROR

2050

X’00000802’

MQRC_PUT_INHIBITED

2051

X’00000803’

MQRC_Q_DELETED

2052

X’00000804’

MQRC_Q_FULL

2053

X’00000805’

MQRC_Q_NOT_EMPTY

2055

X’00000807’

MQRC_Q_SPACE_NOT_AVAILABLE

2056

X’00000808’

MQRC_Q_TYPE_ERROR

2057

X’00000809’

MQRC_Q_MGR_NAME_ERROR

2058

X’0000080A’

MQRC_Q_MGR_NOT_AVAILABLE

2059

X’0000080B’

MQRC_REPORT_OPTIONS_ERROR

2061

X’0000080D’

MQRC_SECOND_MARK_NOT_ALLOWED

2062

X’0000080E’

MQRC_SECURITY_ERROR

2063

X’0000080F’

MQRC_SELECTOR_COUNT_ERROR

2065

X’00000811’

MQRC_SELECTOR_LIMIT_EXCEEDED

2066

X’00000812’

MQRC_SELECTOR_ERROR

2067

X’00000813’

MQRC_SELECTOR_NOT_FOR_TYPE

2068

X’00000814’

MQRC_SIGNAL_OUTSTANDING

2069

X’00000815’

MQRC_SIGNAL_REQUEST_ACCEPTED

2070

X’00000816’

MQRC_STORAGE_NOT_AVAILABLE

2071

X’00000817’

MQRC_SYNCPOINT_NOT_AVAILABLE

2072

X’00000818’

MQRC_TRIGGER_CONTROL_ERROR

2075

X’0000081B’




B-5

Instructor Guide

MQRC_TRIGGER_DEPTH_ERROR

2076

X0000081C’

MQRC_TRIGGER_MSG_PRIORITY_ERR

2077

X’0000081D’

MQRC_TRIGGER_TYPE_ERROR

2078

X’0000081E’

MQRC_TRUNCATED_MSG_ACCEPTED

2079

X’0000081F’

MQRC_TRUNCATED_MSG_FAILED

2080

X’00000820’

MQRC_UNKNOWN_ALIAS_BASE_Q

2082

X’00000822’

MQRC_UNKNOWN_OBJECT_NAME

2085

X’00000825’

MQRC_UNKNOWN_OBJECT_Q_MGR

2086

X’00000826’

MQRC_UNKNOWN_REMOTE_Q_MGR

2087

X’00000827’

MQRC_WAIT_INTERVAL_ERROR

2090

X’0000082A’

MQRC_XMIT_Q_TYPE_ERROR

2091

X’0000082B’

MQRC_XMIT_Q_USAGE_ERROR

2092

X’0000082C’

MQRC_NOT_OPEN_FOR_PASS_ALL

2093

X’0000082D’

MQRC_NOT_OPEN_FOR_PASS_IDENT

2094

X’0000082E’

MQRC_NOT_OPEN_FOR_SET_ALL

2095

X’0000082F’

MQRC_NOT_OPEN_FOR_SET_IDENT

2096

X’00000830’

MQRC_CONTEXT_HANDLE_ERROR

2097

X’00000831’

MQRC_CONTEXT_NOT_AVAILABLE

2098

X’00000832’

MQRC_SIGNAL1_ERROR

2099

X’00000833’

MQRC_OBJECT_ALREADY_EXISTS

2100

X’00000834’

MQRC_OBJECT_DAMAGED

2101

X’00000835’

MQRC_RESOURCE_PROBLEM

2102

X’00000836’

MQRC_ANOTHER_Q_MGR_CONNECTED

2103

X’00000837’

MQRC_UNKNOWN_REPORT_OPTION

2104

X’00000838’

MQRC_STORAGE_CLASS_ERROR

2105

X’00000839’

MQRC_COD_NOT_VALID_FOR_XCF_Q

2106

X’0000083A’

MQRC_XWAIT_CANCELED

2107

X’0000083B

B-6





Uempty MQRC_XWAIT_ERROR

2108

X’0000083C’

MQRC_SUPPRESSED_BY_EXIT

2109

X’0000083D’

MQRC_FORMAT_ERROR

2110

X’0000083E’

MQRC_SOURCE_CCSID_ERROR

2111

X’0000083F’

MQRC_SOURCE_INTEGER_ENC_ERROR

2112

X’00000840’

MQRC_SOURCE_DECIMAL_ENC_ERROR

2113

X’00000841’

MQRC_SOURCE_FLOAT_ENC_ERROR

2114

X’00000842’

MQRC_TARGET_CCSID_ERROR

2115

X’00000843’

MQRC_TARGET_INTEGER_ENC_ERROR

2116

X’00000844’

MQRC_TARGET_DECIMAL_ENC_ERROR

2117

X’00000845’

MQRC_TARGET_FLOAT_ENC_ERROR

2118

X’00000846’

MQRC_NOT_CONVERTED

2119

X’00000847’

MQRC_CONVERTED_MSG_TOO_BIG

2120

X’00000848’

MQRC_TRUNCATED

2120

X’00000848

MQRC_NO_EXTERNAL_PARTICIPANTS

2121

X’00000849’

MQRC_PARTICIPANT_NOT_AVAILABLE

2122

X’0000084A’

MQRC_OUTCOME_MIXED

2123

X’0000084B’

MQRC_OUTCOME_PENDING

2124

X’0000084C’

MQRC_BRIDGE_STARTED

2125

X’0000084D’

MQRC_BRIDGE_STOPPED

2126

X’0000084E’

MQRC_ADAPTER_STORAGE_SHORTAGE

2127

X’0000084F’

MQRC_UOW_IN_PROGRESS

2128

X’00000850’

MQRC_ADAPTER_CONN_LOAD_ERROR

2129

X’00000851’

MQRC_ADAPTER_SERV_LOAD_ERROR

2130

X’00000852’

MQRC_ADAPTER_DEFS_ERROR

2131

X’00000853’

MQRC_ADAPTER_DEFS_LOAD_ERROR

2132

X’00000854’

MQRC_ADAPTER_CONV_LOAD_ERROR

2133

X’00000855’




B-7

Instructor Guide

MQRC_BO_ERROR

2134

X’00000856’

MQRC_DH_ERROR

2135

X’00000857’

MQRC_MULTIPLE_REASONS

2136

X’00000858’

MQRC_OPEN_FAILED

2137

X’00000859’

MQRC_ADAPTER_DISC_LOAD_ERROR

2138

X’0000085A’

MQRC_CNO_ERROR

2139

X’0000085B’

MQRC_CICS_WAIT_FAILED

2140

X’0000085C’

MQRC_DLH_ERROR

2141

X’0000085D’

MQRC_HEADER_ERROR

2142

X’0000085E’

MQRC_SOURCE_LENGTH_ERROR

2143

X’0000085F’

MQRC_TARGET_LENGTH_ERROR

2144

X’00000860’

MQRC_SOURCE_BUFFER_ERROR

2145

X’00000861’

MQRC_TARGET_BUFFER_ERROR

2146

X’00000862’

MQRC_IIH_ERROR

2148

X’00000864’

MQRC_PCF_ERROR

2149

X’00000865’

MQRC_DBCS_ERROR

2150

X’00000866’

MQRC_OBJECT_NAME_ERROR

2152

X’00000868’

MQRC_OBJECT_Q_MGR_NAME_ERROR

2153

X’00000869’

MQRC_RECS_PRESENT_ERROR

2154

X’0000086A’

MQRC_OBJECT_RECORDS_ERROR

2155

X’0000086B’

MQRC_RESPONSE_RECORDS_ERROR

2156

X’0000086C’

MQRC_ASID_MISMATCH

2157

X’0000086D’

MQRC_PMO_RECORD_FLAGS_ERROR

2158

X’0000086E’

MQRC_PUT_MSG_RECORDS_ERROR

2159

X’0000086F’

MQRC_CONN_ID_IN_USE

2160

X’00000870’

MQRC_Q_MGR_QUIESCING

2161

X’00000871’

MQRC_Q_MGR_STOPPING

2162

X’00000872’

B-8





Uempty MQRC_DUPLICATE_RECOV_COORD

2163

X’00000873’

MQRC_PMO_ERROR

2173

X’0000087D’

MQRC_API_EXIT_LOAD_ERROR

2183

X’00000887’

MQRC_REMOTE_Q_NAME_ERROR

2184

X’00000888’

MQRC_INCONSISTENT_PERSISTENCE

2185

X’00000889’

MQRC_GMO_ERROR

2186

X’0000088A’

MQRC_STOPPED_BY_CLUSTER_EXIT

2188

X’0000088C’

MQRC_CLUSTER_RESOLUTION_ERROR

2189

X’0000088D’

MQRC_CONVERTED_STRING_TOO_BIG

2190

X’0000088E’

MQRC_TMC_ERROR

2191

X’0000089f’

MQRC_PAGESET_FULL

2192

X’00000890’

MQRC_PAGESET_ERROR

2193

X’00000891’

MQRC_NAME_NOT_VALID_FOR_TYPE

2194

X’00000892’

MQRC_UNEXPECTED_ERROR

2195

X’00000893’

MQRC_UNKNOWN_XMIT_Q

2196

X’00000894’

MQRC_UNKNOWN_DEF_XMIT_Q

2197

X’00000895’

MQRC_DEF_XMIT_Q_TYPE_ERROR

2198

X’00000896’

MQRC_DEF_XMIT_Q_USAGE_ERROR

2199

X’00000897’

MQRC_NAME_IN_USE

2201

X’00000899’

MQRC_CONNECTION_QUIESCING

2202

X’0000089A’

MQRC_CONNECTION_STOPPING

2203

X’0000089B’

MQRC_ADAPTER_NOT_AVAILABLE

2204

X’0000089C’

MQRC_MSG_ID_ERROR

2206

X’0000089E’

MQRC_CORREL_ID_ERROR

2207

X’0000089F’

MQRC_FILE_SYSTEM_ERROR

2208

X’000008A0’

MQRC_NO_MSG_LOCKED

2209

X’000008A1’

MQRC_FILE_NOT_AUDITED

2216

X’000008A8’




B-9

Instructor Guide

MQRC_CONNECTION_NOT_AUTHORIZED

2217

X’000008A9’

MQRC_MSG_TOO_BIG_FOR_CHANNEL

2218

X’000008AA’

MQRC_CALL_IN_PROGRESS

2219

X’000008AB’

MQRC_RMH_ERROR

2220

X’000008AC’

MQRC_Q_MGR_ACTIVE

2222

X’000008AE’

MQRC_Q_MGR_NOT_ACTIVE

2223

X’000008AF’

MQRC_Q_DEPTH_HIGH

2224

X’000008B0’

MQRC_Q_DEPTH_LOW

2225

X’000008B1’

MQRC_Q_SERVICE_INTERVAL_HIGH

2226

X’000008B2’

MQRC_Q_SERVICE_INTERVAL_OK

2227

X’000008B3’

MQRC_UNIT_OF_WORK_NOT_STARTED

2232

X’000008B8’

MQRC_CHANNEL_AUTO_DEF_OK

2233

X’000008B9’

MQRC_CHANNEL_AUTO_DEF_ERROR

2234

X’000008BA’

MQRC_CFH_ERROR

2235

X’000008BB’

MQRC_CFIL_ERROR

2236

X’000008BC’

MQRC_CFIN_ERROR

2237

X’000008BD’

MQRC_CFSL_ERROR

2238

X’000008BE’

MQRC_CFST_ERROR

2239

X’000008BF’

MQRC_INCOMPLETE_GROUP

2241

X’000008C1’

MQRC_INCOMPLETE_MSG

2242

X’000008C2’

MQRC_INCONSISTENT_CCSIDS

2243

X’000008C3’

MQRC_INCONSISTENT_ENCODINGS

2244

X’000008C4’

MQRC_INCONSISTENT_UOW

2245

X’000008C5’

MQRC_INVALID_MSG_UNDER_CURSOR

2246

X’000008C6’

MQRC_MATCH_OPTIONS_ERROR

2247

X’000008C7’

MQRC_MDE_ERROR

2248

X’000008C8’

MQRC_MSG_FLAGS_ERROR

2249

X’000008C9’

B-10 WebSphere MQ System Administration I




Uempty MQRC_MSG_SEQ_NUMBER_ERROR

2250

X’000008CA’

MQRC_OFFSET_ERROR

2251

X’000008CB’

MQRC_ORIGINAL_LENGTH_ERROR

2252

X’000008CC’

MQRC_SEGMENT_LENGTH_ZERO

2253

X’000008CD’

MQRC_UOW_NOT_AVAILABLE

2255

X’000008CF’

MQRC_WRONG_GMO_VERSION

2256

X’000008D0’

MQRC_WRONG_MD_VERSION

2257

X’000008D1’

MQRC_GROUP_ID_ERROR

2258

X’000008D2’

MQRC_INCONSISTENT_BROWSE

2259

X’000008D3’

MQRC_XQH_ERROR

2260

X’000008D4’

MQRC_SRC_ENV_ERROR

2261

X’000008D5’

MQRC_SRC_NAME_ERROR

2262

X’000008D6

MQRC_DEST_ENV_ERROR

2263

X’000008D7’

MQRC_DEST_NAME_ERROR

2264

X’000008D8’

MQRC_TM_ERROR

2265

X’000008D9’

MQRC_CLUSTER_EXIT_ERROR

2266

X’000008DA’

MQRC_CLUSTER_EXIT_LOAD_ERROR

2267

X’000008DB’

MQRC_CLUSTER_PUT_INHIBITED

2268

X’000008DC’

MQRC_NO_DESTINATIONS_AVAILABLE

2270

X’000008DE’

MQRC_CONNECTION_ERROR

2273

X’000008E1’

MQRC_OPTION_ENVIRONMENT_ERROR

2274

X’000008E2’

MQRC_CD_ERROR

2275

X’000008E5’

MQRC_CLIENT_CONN_ERROR

2278

X’000008E6’

MQRC_CHANNEL_STOPPED_BY_USER

2279

X’000008E7’

MQRC_HCONFIG_ERROR

2280

X’000008E8’

MQRC_FUNCTION_ERROR

2281

X’000008E9’

MQRC_CHANNEL_STARTED

2282

X’000008EA’




B-11

Instructor Guide

MQRC_CHANNEL_STOPPED

2283

X’000008EB’

MQRC_CHANNEL_CONV_ERROR

2284

X’000008EC’

MQRC_SERVICE_NOT_AVAILABLE

2285

X’000008ED’

MQRC_INITIALIZATION_FAILED

2286

X’000008EE’

MQRC_TERMINATION_FAILED

2287

X’000008EF’

MQRC_UNKNOWN_Q_NAME

2288

X’000008F0’

MQRC_SERVICE_ERROR

2289

X’000008F1’

MQRC_Q_ALREADY_EXISTS

2290

X’000008F2’

MQRC_USER_ID_NOT_AVAILABLE

2291

X’000008F3’

MQRC_UNKNOWN_ENTITY

2292

X’000008F4’

MQRC_UNKNOWN_AUTH_ENTITY

2293

X’000008F5’

MQRC_UNKNOWN_REF_OBJECT

2294

X’000008F6’

MQRC_CHANNEL_ACTIVATED

2295

X’000008F7’

MQRC_CHANNEL_NOT_ACTIVATED

2296

X’000008F8’

MQRC_UOW_CANCELED

2297

X’000008F9’

MQRC_SELECTOR_TYPE_ERROR

2299

X’000008FB’

MQRC_COMMAND_TYPE_ERROR

2300

X’000008FC’

MQRC_MULTIPLE_INSTANCE_ERROR

2301

X’000008FD’

MQRC_SYSTEM_ITEM_NOT_ALTERABLE

2302

X’000008FE’

MQRC_BAG_CONVERSION_ERROR

2303

X’000008FF’

MQRC_SELECTOR_OUT_OF_RANGE

2304

X’00000900’

MQRC_SELECTOR_NOT_UNIQUE

2305

X’00000901’

MQRC_INDEX_NOT_PRESENT

2306

X’00000902’

MQRC_STRING_ERROR

2307

X’00000903’

MQRC_ENCODING_NOT_SUPPORTED

2308

X’00000904’

MQRC_SELECTOR_NOT_PRESENT

2309

X’00000905’

MQRC_OUT_SELECTOR_ERROR

2310

X’00000906’





Uempty MQRC_STRING_TRUNCATED

2311

X’00000907’

MQRC_SELECTOR_WRONG_TYPE

2312

X’00000908’

MQRC_INCONSISTENT_ITEM_TYPE

2313

X’00000909’

MQRC_INDEX_ERROR

2314

X’0000090A’

MQRC_SYSTEM_BAG_NOT_ALTERABLE

2315

X’0000090B’

MQRC_ITEM_COUNT_ERROR

2316

X’0000090C’

MQRC_FORMAT_NOT_SUPPORTED

2317

X’0000090D’

MQRC_SELECTOR_NOT_SUPPORTED

2318

X’0000090E’

MQRC_ITEM_VALUE_ERROR

2319

X’0000090F’

MQRC_HBAG_ERROR

2320

X’00000910’

MQRC_PARAMETER_MISSING

2321

X’00000911’

MQRC_CMD_SERVER_NOT_AVAILABLE

2322

X’00000912’

MQRC_STRING_LENGTH_ERROR

2323

X’00000913’

MQRC_INQUIRY_COMMAND_ERROR

2324

X’00000914’

MQRC_NESTED_BAG_NOT_SUPPORTED

2325

X’00000915’

MQRC_BAG_WRONG_TYPE

2326

X’00000916’

MQRC_ITEM_TYPE_ERROR

2327

X’00000917’

MQRC_SYSTEM_BAG_NOT_DELETABLE

2328

X’00000918’

MQRC_SYSTEM_ITEM_NOT_DELETABLE

2329

X’00000919’

MQRC_CODED_CHAR_SET_ID_ERROR

2330

X’0000091A’

MQRC_MSG_TOKEN_ERROR

2331

X’0000091B’

MQRC_MISSING_WIH

2332

X’0000091C’

MQRC_WIH_ERROR

2333

X’0000091D’




B-13

Instructor Guide





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.


Appendix C. Bibliography


C-1

Instructor Guide

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: • WebSphere MQ for AIX V5.3 • WebSphere MQ for HP-UX V5.3 C-2





Uempty

• WebSphere MQ for Linux for Intel V5.3 • WebSphere MQ for Linux for zSeries V5.3 • WebSphere MQ for Sun Solaris 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 iSeries WebSphere MQ for Linux for Intel and zSeries WebSphere MQ for Solaris WebSphere MQ for Windows WebSphere MQ for z/OS

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 HP-UX, V5.3 WebSphere MQ for iSeries, V5.3 WebSphere MQ for Linux for Intel, 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




C-3

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 MQSeries for Sun Solaris, Intel Platform Edition, V5.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 AIX, V5.3 WebSphere MQ for HP-UX V5.3 WebSphere MQ for iSeries, V5.3 WebSphere MQ for Linux for Intel and zSeries, V5.3 WebSphere MQ for Solaris, V5.3 WebSphere MQ for Windows, V5.3 WebSphere MQ for z/OS, 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 AIX WebSphere MQ for HP-UX WebSphere MQ for iSeries WebSphere MQ for Linux for Intel

C-4





Uempty

• • • •

WebSphere MQ for WebSphere MQ for WebSphere MQ for WebSphere MQ for

Linux for zSeries Solaris Windows z/OS

Unless otherwise stated, the information also applies to these products: • MQSeries for OS/2 Warp, V5.1 • MQSeries for Compaq Tru64 UNIX, V5.1 • MQSeries for Sun Solaris, Intel Platform Edition, 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 WebSphere MQ for WebSphere MQ for WebSphere MQ for WebSphere MQ for WebSphere MQ for WebSphere MQ for WebSphere MQ for

AIX, V5.3 HP-UX, V5.3 iSeries, V5.3 Linux for Intel, V5.3 Linux for zSeries, V5.3 Solaris, V5.3 Windows, V5.3 z/OS, 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 WebSphere MQ for AIX V5.3 Quick Beginnings, GC34-6076 WebSphere MQ for HP-UX WebSphere MQ for HP-UX V5.2 Quick Beginnings, GC34-6077 WebSphere MQ for iSeries WebSphere MQ for iSeries V5.3 Quick Beginnings, GC34-6072 WebSphere MQ for iSeries V5.3 System Administration Guide, SC34-6070




C-5

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 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 WebSphere MQ for WebSphere MQ for WebSphere MQ for WebSphere MQ for WebSphere MQ for WebSphere MQ for

z/OS V5.3 Program Directory, GI10-2548 z/OS Concepts and Planning Guide V5.3, GC34-6051 z/OS System Setup Guide V5.3, SC34-6052 z/OS System Administration Guide V5.3, SC34-6053 z/OS Problem Determination Guide V5.3, GC34-6054 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 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 MQSeries for OS/2 Warp V5.1 Quick Beginnings, GC33-1868 MQSeries link for R/3 MQSeries link for R/3 Version 1.2 User’s Guide, GC33-1934

C-6





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 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 User’s 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 AIX V5.3 WebSphere MQ for HP-UX V5.3 WebSphere MQ for iSeries V5.3 WebSphere MQ for Linux V5.3 WebSphere MQ for Sun Solaris V5.3 WebSphere MQ for Windows V5.3 WebSphere MQ for z/OS V5.3




C-7

Instructor Guide

• MQSeries for OS/2 Warp V5.1 • 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 AIX V5.3 WebSphere MQ for HP-UX V5.3 WebSphere MQ for iSeries V5.3 WebSphere MQ for Linux V5.3 WebSphere MQ for Sun Solaris V5.3 WebSphere MQ for Windows V5.3 WebSphere MQ for z/OS V5.3 MQSeries for OS/2 Warp V5.1 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

C-8





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.


Appendix D. Glossary of terms and abbreviations


D-1

Instructor Guide

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

D-2





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.




D-3

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. D-4





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. © Copyright IBM Corp. 1996, 2003



D-5

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.

D-6





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.




D-7

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.

D-8





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.




D-9

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.

D-10 WebSphere MQ System Administration I




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. © Copyright IBM Corp. 1996, 2003



D-11

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. D-12 WebSphere MQ System Administration I




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.




D-13

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.





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.




D-15

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. D-16 WebSphere MQ System Administration I




Uempty

null character. The character that is represented byX’00.

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.




D-17

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.





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 © Copyright IBM Corp. 1996, 2003



D-19

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.





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. © Copyright IBM Corp. 1996, 2003



D-21

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.





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.




D-23

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. D-24 WebSphere MQ System Administration I




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. © Copyright IBM Corp. 1996, 2003



D-25

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. D-26 WebSphere MQ System Administration I




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.




D-27

Instructor Guide




V1.2.2

backpg

®

MQ15 - WebSphere MQ System Administration I

Recommend Documents