Administering WebSphere MQ

IBM WebSphere MQ

Administering IBM WebSphere MQVersion 7 Release 5

NoteBefore using this information and the product it supports, read the information in Notices on page 1175.

This edition applies to version 7 release 5 of WebSphere MQ and to all subsequent releases and modifications untilotherwise indicated in new editions.

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in anyway it believes appropriate without incurring any obligation to you.

Copyright IBM Corporation 2007, 2014.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

ContentsFigures . . . . . . . . . . . . . . vii

Tables . . . . . . . . . . . . . . . ix

Administering WebSphere MQ . . . . . 1Local and remote administration. . . . . . . . 3How to use WebSphere MQ control commands . . . 4Automating administration tasks . . . . . . . 4

Introduction to Programmable Command Formats 5Using the MQAI to simplify the use of PCFs . . 15

Introduction to the WebSphere MQ AdministrationInterface (MQAI) . . . . . . . . . . . . 16

WebSphere MQ Administration Interface (MQAI) 17Administration using the WebSphere MQ Explorer 52

What you can do with the WebSphere MQExplorer . . . . . . . . . . . . . . 53Setting up the WebSphere MQ Explorer . . . . 55Security on Windows . . . . . . . . . . 61Extending the WebSphere MQ Explorer . . . . 64

Using the WebSphere MQ Taskbar application(Windows only) . . . . . . . . . . . . . 64

The WebSphere MQ alert monitor application(Windows only) . . . . . . . . . . . . 64

Administering local WebSphere MQ objects . . . 65Starting and stopping a queue manager . . . . 65Stopping a queue manager manually . . . . . 67Performing local administration tasks usingMQSC commands . . . . . . . . . . . 69Working with queue managers . . . . . . . 77Working with local queues . . . . . . . . 79Working with alias queues . . . . . . . . 85Working with model queues. . . . . . . . 86Working with administrative topics . . . . . 87Working with subscriptions . . . . . . . . 90Working with services . . . . . . . . . . 93Managing objects for triggering . . . . . . 100

Administering remote WebSphere MQ objects . . 102Channels, clusters, and remote queuing . . . 102Remote administration from a local queuemanager . . . . . . . . . . . . . . 104Creating a local definition of a remote queue 110Using remote queue definitions as aliases . . . 112Data conversion . . . . . . . . . . . 113

Administering WebSphere MQ Telemetry . . . . 114Configuring a queue manager for telemetry onLinux and AIX . . . . . . . . . . . . 115Configuring a queue manager for telemetry onWindows . . . . . . . . . . . . . . 117Configure distributed queuing to send messagesto MQTT clients . . . . . . . . . . . 119MQTT client identification, authorization, andauthentication . . . . . . . . . . . . 121Telemetry channel authentication using SSL . . 128Publication privacy on telemetry channels . . . 130

SSL configuration of MQTT clients andtelemetry channels . . . . . . . . . . 131Telemetry channel JAAS configuration . . . . 136WebSphere MQ Telemetry daemon for devicesconcepts . . . . . . . . . . . . . . 138

Administering multicast . . . . . . . . . . 149Getting started with multicast . . . . . . . 150WebSphere MQ Multicast topic topology . . . 151Controlling the size of multicast messages . . . 152Enabling data conversion for Multicastmessaging . . . . . . . . . . . . . 154Multicast application monitoring . . . . . . 154Multicast message reliability . . . . . . . 155Advanced multicast tasks . . . . . . . . 156

Administering HP Integrity NonStop Server . . . 159Manually starting the TMF/Gateway fromPathway . . . . . . . . . . . . . . 159Stopping the TMF/Gateway from Pathway . . 159

Security. . . . . . . . . . . . . . 161Security overview . . . . . . . . . . . . 161

Security concepts and mechanisms . . . . . 161WebSphere MQ security mechanisms . . . . 177

Planning for your security requirements . . . . 203Planning identification and authentication . . . 204Planning authorization . . . . . . . . . 206Planning confidentiality . . . . . . . . . 217Planning data integrity . . . . . . . . . 226Planning auditing . . . . . . . . . . . 226Planning security by topology . . . . . . . 228Firewalls and Internet pass-thru . . . . . . 239

Setting up security . . . . . . . . . . . 239Setting up security on Windows, UNIX andLinux systems . . . . . . . . . . . . 239Setting up security on HP Integrity NonStopServer . . . . . . . . . . . . . . . 265Setting up WebSphere MQ MQI client security 266Working with SSL or TLS . . . . . . . . 269

Identifying and authenticating users. . . . . . 300Privileged users . . . . . . . . . . . 302Identifying and authenticating users using theMQCSP structure . . . . . . . . . . . 303Implementing identification and authenticationin security exits . . . . . . . . . . . 303Identity mapping in message exits . . . . . 304Identity mapping in the API exit andAPI-crossing exit . . . . . . . . . . . 305Working with revoked certificates . . . . . 306

Authorizing access to objects . . . . . . . . 315Controlling access to objects by using the OAMon UNIX, Linux and Windows systems. . . . 315Granting required access to resources . . . . 324Authority to administer WebSphere MQ onUNIX, Linux, and Windows systems . . . . 352

Copyright IBM Corp. 2007, 2014 iii

Authority to work with WebSphere MQ objectson UNIX, Linux and Windows systems. . . . 354Implementing access control in security exits 359Implementing access control in message exits 360Implementing access control in the API exit andAPI-crossing exit . . . . . . . . . . . 361

Confidentiality of messages . . . . . . . . 361Connecting two queue managers using SSL orTLS. . . . . . . . . . . . . . . . 361Connecting a client to a queue manager securely 367Specifying CipherSpecs . . . . . . . . . 373Resetting SSL and TLS secret keys . . . . . 377Implementing confidentiality in user exitprograms . . . . . . . . . . . . . . 378

Data integrity of messages . . . . . . . . . 380Connecting two queue managers using SSL orTLS. . . . . . . . . . . . . . . . 381Connecting a client to a queue manager securely 389Specifying CipherSpecs . . . . . . . . . 394

Auditing . . . . . . . . . . . . . . . 398Keeping clusters secure . . . . . . . . . . 398

Stopping unauthorized queue managers sendingmessages . . . . . . . . . . . . . . 398Stopping unauthorized queue managers puttingmessages on your queues . . . . . . . . 399Authorizing putting messages on remote clusterqueues . . . . . . . . . . . . . . 399Preventing queue managers joining a cluster 400Forcing unwanted queue managers to leave acluster . . . . . . . . . . . . . . . 401Preventing queue managers receiving messages 402SSL and clusters . . . . . . . . . . . 402

Publish/subscribe security . . . . . . . . . 404Example publish/subscribe security setup . . . 412Subscription security . . . . . . . . . . 421

WebSphere MQ Advanced Message Security . . . 422WebSphere MQ AMS overview . . . . . . 423Installing WebSphere MQ Advanced MessageSecurity . . . . . . . . . . . . . . 445Using keystores and certificates . . . . . . 445Security policies . . . . . . . . . . . 453Problems and solutions . . . . . . . . . 469

Monitoring and performance . . . . . 471Event monitoring . . . . . . . . . . . . 471

Instrumentation events . . . . . . . . . 472Performance events . . . . . . . . . . 485Configuration events . . . . . . . . . . 502Command events . . . . . . . . . . . 506Logger events . . . . . . . . . . . . 508Sample program to monitor instrumentationevents . . . . . . . . . . . . . . . 515

Message monitoring . . . . . . . . . . . 523Activities and operations . . . . . . . . 523Message route techniques . . . . . . . . 525Activity recording . . . . . . . . . . . 527Trace-route messaging . . . . . . . . . 532WebSphere MQ display route application . . . 546Activity report reference. . . . . . . . . 565Trace-route message reference . . . . . . . 590Trace-route reply message reference . . . . . 601

Accounting and statistics messages . . . . . . 603Accounting messages. . . . . . . . . . 604Statistics messages. . . . . . . . . . . 608Displaying accounting and statistics information 613Accounting and statistics message reference . . 618

Application activity trace . . . . . . . . . 666Collecting application activity trace information 666Application activity trace message reference . . 673

Real-time monitoring . . . . . . . . . . . 738Attributes that control real-time monitoring . . 739Displaying queue and channel monitoring data 740Monitoring queues . . . . . . . . . . 742Monitoring channels . . . . . . . . . . 744The Windows performance monitor . . . . . 750

Troubleshooting and support . . . . 751Troubleshooting overview . . . . . . . . . 751Making initial checks on Windows, UNIX andLinux systems . . . . . . . . . . . . . 753

Has WebSphere MQ run successfully before? 754Have any changes been made since the lastsuccessful run? . . . . . . . . . . . . 754Are there any error messages or return codes toexplain the problem? . . . . . . . . . . 755Can you reproduce the problem? . . . . . . 756Are you receiving an error code when creatingor starting a queue manager? (Windows only) . 756Does the problem affect only remote queues? 756Have you obtained incorrect output? . . . . 757Are some of your queues failing?. . . . . . 759Have you failed to receive a response from aPCF command? . . . . . . . . . . . 759Has the application run successfully before? . . 760Is your application or system running slowly? 761Does the problem affect specific parts of thenetwork? . . . . . . . . . . . . . . 762Does the problem occur at specific times of theday? . . . . . . . . . . . . . . . 762Is the problem intermittent? . . . . . . . 762

Dealing with problems . . . . . . . . . . 762Resolving problems with commands . . . . 763Resolving problems with queue managers . . . 763Resolving problems with queue managerclusters . . . . . . . . . . . . . . 764Resolving problems with undelivered messages 775TLS/SSL troubleshooting information . . . . 776Resolving problems with WebSphere MQ MQIclients . . . . . . . . . . . . . . . 786

Troubleshooting WebSphere MQ client for HPIntegrity NonStop Server . . . . . . . . . 787Troubleshooting for WebSphere MQ Telemetry . . 787

Location of telemetry logs, error logs, andconfiguration files . . . . . . . . . . . 787MQTT v3 Java client reason codes . . . . . 790Tracing the telemetry (MQXR) service . . . . 790Tracing the MQTT v3 Java client . . . . . . 792System requirements for using SHA-2 ciphersuites with MQTT channels. . . . . . . . 793Resolving problem: MQTT client does notconnect . . . . . . . . . . . . . . 794

iv IBM WebSphere MQ: Administering

Resolving problem: MQTT client connectiondropped . . . . . . . . . . . . . . 795Resolving problem: Lost messages in an MQTTapplication . . . . . . . . . . . . . 796Resolving problem: Telemetry (MQXR) servicedoes not start . . . . . . . . . . . . 798Resolving problem: JAAS login module notcalled by the telemetry service. . . . . . . 799Resolving problem: Starting or running thedaemon . . . . . . . . . . . . . . 802Resolving problem: MQTT clients notconnecting to the daemon . . . . . . . . 803

Troubleshooting channel authentication records . . 803Multicast troubleshooting . . . . . . . . . 803

Testing multicast applications on anon-multicast network . . . . . . . . . 804Setting the appropriate network for multicasttraffic . . . . . . . . . . . . . . . 804Multicast topic string is too long . . . . . . 804Multicast topic topology issues . . . . . . 805

Using logs . . . . . . . . . . . . . . 807Error logs on Windows, UNIX and Linuxsystems . . . . . . . . . . . . . . 807Error logs on HP Integrity NonStop Server . . 810

Using trace . . . . . . . . . . . . . . 811Using trace on Windows . . . . . . . . 812Using trace on UNIX and Linux systems . . . 813Using trace on HP Integrity NonStop Server . . 816Tracing Secure Sockets Layer (SSL) iKeymanand iKeycmd functions . . . . . . . . . 817Tracing additional WebSphere MQ Javacomponents . . . . . . . . . . . . . 818

Problem determination in DQM . . . . . . . 821Error message from channel control . . . . . 822Ping . . . . . . . . . . . . . . . 822Dead-letter queue considerations . . . . . . 822Validation checks . . . . . . . . . . . 823In-doubt relationship . . . . . . . . . . 823Channel startup negotiation errors . . . . . 823Shared channel recovery. . . . . . . . . 823When a channel refuses to run . . . . . . 824Retrying the link . . . . . . . . . . . 826Data structures . . . . . . . . . . . . 826User exit problems . . . . . . . . . . 826Disaster recovery . . . . . . . . . . . 826Channel switching. . . . . . . . . . . 827Connection switching. . . . . . . . . . 827

Client problems . . . . . . . . . . . 827Error logs . . . . . . . . . . . . . 828Message monitoring . . . . . . . . . . 829

First Failure Support Technology (FFST) . . . . 829FFST: WebSphere MQ for Windows . . . . . 829FFST: WebSphere MQ for UNIX and Linuxsystems . . . . . . . . . . . . . . 832FFST: WebSphere MQ for HP Integrity NonStopServer . . . . . . . . . . . . . . . 834

IBM Support Assistant (ISA) . . . . . . . . 836Installing the IBM Support Assistant (ISA). . . 836Updating the IBM Support Assistant (ISA) . . 837

Searching knowledge bases . . . . . . . . . 838Searching the IBM database for similarproblems, and solutions . . . . . . . . . 839

Contacting IBM Software Support . . . . . . 845Determine the effect of the problem on yourbusiness . . . . . . . . . . . . . . 846Describe your problem and gather backgroundinformation . . . . . . . . . . . . . 847Submit your problem to IBM Software Support 847Dealing with the support center . . . . . . 848Collecting documentation for the problem. . . 851Sending the documentation to the change team 852Resolving a problem . . . . . . . . . . 852

Getting product fixes . . . . . . . . . . . 853Recovering after failure . . . . . . . . . . 854

Disk drive failures. . . . . . . . . . . 855Damaged queue manager object . . . . . . 856Damaged single object . . . . . . . . . 856Automatic media recovery failure . . . . . 856

Reason codes . . . . . . . . . . . . . 856API completion and reason codes . . . . . 856PCF reason codes . . . . . . . . . . 1072Secure Sockets Layer (SSL) and TransportLayer Security (TLS) return codes . . . . . 1149WCF custom channel exceptions. . . . . . 1153

Index . . . . . . . . . . . . . . 1163

Notices . . . . . . . . . . . . . 1175Programming interface information. . . . . . 1176Trademarks. . . . . . . . . . . . . . 1177

Sending your comments to IBM . . . 1179

Contents v

vi IBM WebSphere MQ: Administering

Figures1. Hierarchy of MQAI concepts . . . . . . . 432. Adding data items . . . . . . . . . . 463. Modifying a single data item. . . . . . . 484. Modifying all data items . . . . . . . . 485. Truncating a bag . . . . . . . . . . . 496. Converting bags to PCF messages . . . . . 497. Converting PCF messages to bag form . . . 508. Deleting a single data item . . . . . . . 509. Deleting all data items . . . . . . . . . 5110. Nesting . . . . . . . . . . . . . . 5211. Extract from an MQSC command file . . . . 7312. Extract from an MQSC command report file 7413. Example script for running MQSC commands

from a batch file . . . . . . . . . . . 7614. Typical output from a DISPLAY QMGR

command . . . . . . . . . . . . . 7815. Typical results from queue browser . . . . 8416. Remote administration using MQSC

commands . . . . . . . . . . . . 10517. Setting up channels and queues for remote

administration . . . . . . . . . . . 10618. installMQXRService_unix.mqsc. . . . . . 11719. Set default transmission queue . . . . . . 11820. installMQXRService_win.mqsc . . . . . . 11821. Defining a cluster topic on Windows 12022. MQI Object descriptor to send a message to

an MQTT v3 client destination . . . . . . 12023. JMS destination to send a message to an

MQTT v3 client . . . . . . . . . . . 12124. MQTT Client code snippet . . . . . . . 13525. AcceptAllProvider.java . . . . . . . . 13526. AcceptAllTrustManagerFactory.java . . . . 13627. AcceptAllX509TrustManager.java . . . . . 13628. Sample jaas.config file . . . . . . . . 13729. Sample JAASLoginModule.Login() method 13830. Connecting WebSphere MQ Telemetry

daemon for devices to WebSphere MQ . . . 13931. Publish everything to the remote broker 14132. Publish everything to the remote broker -

explicit. . . . . . . . . . . . . . 14133. Publish everything to the local broker 14134. Publish everything from the export topic at

the local broker to the import topic at theremote broker . . . . . . . . . . . 142

35. Publish everything to the import topic at thelocal broker from the export topic at theremote broker . . . . . . . . . . . 142

36. Publish everything from the 1884/ mountpoint to the remote broker with the originaltopic strings. . . . . . . . . . . . . 142

37. Separate the topic spaces of clients connectedto different daemons . . . . . . . . . 143

38. Separate the topic spaces of clients connectedto the same daemon . . . . . . . . . 143

39. Remap different topics for publicationsflowing in both directions . . . . . . . 143

40. !Remap the same topics for publicationsflowing in both directions . . . . . . . 144

41. !Remap the same topics for publicationsflowing in both directions, using both. . . . 144

42. Daemon configuration file . . . . . . . 14943. Password file, passwords.txt . . . . . . 14944. Access control file, acl.txt . . . . . . . 14945. Symmetric key cryptography . . . . . . 16446. Asymmetric key cryptography . . . . . . 16447. Obtaining a digital certificate . . . . . . 16948. Chain of trust . . . . . . . . . . . 17049. Overview of the SSL or TLS handshake 17350. The digital signature process . . . . . . 17651. Security in a client/server connection 20552. Link level security and application level

security . . . . . . . . . . . . . 21853. Security, message, send, and receive exits on

a message channel . . . . . . . . . . 22454. Flows for session level authentication 23355. WebSphere MQ support for conversation

level authentication . . . . . . . . . 23556. Sample LDIF file for a Certificate Authority.

This might vary from implementation toimplementation. . . . . . . . . . . 310

57. Example of an LDAP Directory InformationTree structure . . . . . . . . . . . 311

58. Configuration resulting from this task 36259. Configuration resulting from this task 36460. Queue managers allowing one-way

authentication . . . . . . . . . . . 36661. Configuration resulting from this task 36862. Configuration resulting from this task 37063. Client and queue manager allowing

anonymous connection . . . . . . . . 37264. Configuration resulting from this task 38365. Configuration resulting from this task 38566. Queue managers allowing one-way

authentication . . . . . . . . . . . 38767. Configuration resulting from this task 39068. Configuration resulting from this task 39269. Client and queue manager allowing

anonymous connection . . . . . . . . 39370. Publish/subscribe security relationships 40571. Topic object access example . . . . . . . 41272. Example of granting access to a topic within

a topic tree . . . . . . . . . . . . 41373. Granting access to specific topics within a

topic tree . . . . . . . . . . . . . 41474. Example of granting access control to avoid

additional messages. . . . . . . . . . 41675. Granting publish access to a topic. . . . . 41776. Granting publish access to a topic within a

topic tree . . . . . . . . . . . . . 41877. Granting access for publishing and

subscribing . . . . . . . . . . . . 42078. Understanding instrumentation events 473

Copyright IBM Corp. 2007, 2014 vii

79. Monitoring queue managers across differentplatforms, on a single node . . . . . . . 475

80. Understanding queue service interval events 48781. Queue service interval events - example 1 49182. Queue service interval events - example 2 49383. Queue service interval events - example 3 49484. Queue depth events (1) . . . . . . . . 49985. Queue depth events (2) . . . . . . . . 50186. Requesting activity reports, Diagram 1 55487. Requesting activity reports, Diagram 2 55588. Requesting activity reports, Diagram 3 55689. Requesting activity reports, Diagram 4 55790. Requesting a trace-route reply message,

Diagram 1 . . . . . . . . . . . . 55891. Requesting a trace-route reply message,



Diagram 4 . . . . . . . . . . . . 56094. Delivering activity reports to the system

queue, Diagram 1 . . . . . . . . . . 56195. Delivering activity reports to the system

queue, Diagram 2 . . . . . . . . . . 56196. Diagnosing a channel problem . . . . . . 56497. Telemetry configuration directory on

Windows . . . . . . . . . . . . . 788

98. Telemetry configuration directory on AIX orLinux . . . . . . . . . . . . . . 788

99. Sample service.env for Windows. . . . . 789100. WMQ Installation directory\data\qmgrs\

qMgrName\mqxr\mqxr_win.properties . . . . 800101. WMQ Installation directory\data\qmgrs\

qMgrName\mqxr\jaas.config . . . . . . . 800102. WMQ Installation directory\data\qmgrs\

qMgrName\service.env . . . . . . . . 800103. Classpath output from runMQXRService.bat 801104. WMQ Installation directory\data\qmgrs\

qMgrName\errors\mqxr.log . . . . . . . 801105. Exception thrown connecting

com.ibm.mq.id.PubAsyncRestartable . . . . 801106. mqxr.log - error loading JAAS configuration 802107. Sample WebSphere MQ error log . . . . . 808108. Sample WebSphere MQ error log . . . . . 811109. Sample com.ibm.mq.commonservices

properties file . . . . . . . . . . . 820110. Sample WebSphere MQ for Windows First

Failure Symptom Report . . . . . . . . 831111. FFST report for WebSphere MQ for UNIX

systems . . . . . . . . . . . . . 833112. Sample FFST data . . . . . . . . . . 835113. Sample problem reporting sheet . . . . . 849

viii IBM WebSphere MQ: Administering

Tables1. Windows, HP Integrity NonStop Server, UNIX

and Linux systems - object authorities . . . 132. Name resolution of an MQTT queue manager

alias. . . . . . . . . . . . . . . 1193. Name resolution of an MQTT client remote

queue definition . . . . . . . . . . 1214. Filepaths by platform for JRE SSL

configuration files . . . . . . . . . . 1345. Messaging attributes and how they relate to

multicast . . . . . . . . . . . . . 1536. WebSphere MQ message properties to

WebSphere MQ LLM property mappings . . 1587. Suite B security levels with allowed

CipherSpecs and digital signature algorithms . 1888. Relationships between CipherSpecs and

digital certificates . . . . . . . . . . 1949. Supported NIST elliptic curves. . . . . . 19610. Precedence order of substrings . . . . . . 20211. PCF commands and their equivalent OAM

commands . . . . . . . . . . . . 21312. The user ID used by a server-connection

channel . . . . . . . . . . . . . 21513. Security authorization needed for MQCONN

calls. . . . . . . . . . . . . . . 24814. Security authorization needed for MQOPEN

calls. . . . . . . . . . . . . . . 24815. Security authorization needed for MQPUT1

calls. . . . . . . . . . . . . . . 24916. Security authorization needed for MQCLOSE

calls. . . . . . . . . . . . . . . 25017. Privileged users by platform . . . . . . 30318. Granting partial administrative access to a

subset of queue manager resources . . . . 32419. Granting full administrative access to a subset

of queue manager resources . . . . . . 32920. Controlling user access to topics . . . . . 34921. Example topic object authorities . . . . . 40722. User IDs used for security checks for

commands . . . . . . . . . . . . 41123. Example topic object access . . . . . . . 41224. Access requirements for example topics and

topic objects . . . . . . . . . . . . 41325. Access requirements for example topics and

topic objects . . . . . . . . . . . . 41526. Example publish access requirements 41727. Example publish access requirements 41828. Example publishing and subscribing access

requirements . . . . . . . . . . . . 42029. Complete list of access authorities resulting

from security examples . . . . . . . . 42130. Default publication context information 42131. dspmqspl command flags. . . . . . . . 46032. Enabling queue manager events using MQSC

commands . . . . . . . . . . . . 481

33. Enabling channel and bridge events usingMQSC commands . . . . . . . . . . 482

34. Performance event statistics . . . . . . . 48635. Enabling queue service interval events using

MQSC . . . . . . . . . . . . . . 48936. Event statistics summary for example 1 49237. Event statistics summary for example 2 49438. Event statistics summary for example 3 49539. Event statistics summary for queue depth

events (example 1) . . . . . . . . . . 50040. Summary showing which events are enabled 50041. Event statistics summary for queue depth

events (example 2) . . . . . . . . . . 50242. Summary showing which events are enabled 50243. TraceRoute PCF group . . . . . . . . 53844. Group name . . . . . . . . . . . . 54345. Parameter name . . . . . . . . . . 54346. Parameter value . . . . . . . . . . 54347. Color information . . . . . . . . . . 54548. Color name . . . . . . . . . . . . 54549. . . . . . . . . . . . . . . . . 54550. Activity report format. . . . . . . . . 56651. Trace-route message format . . . . . . . 59252. Trace-route reply message format . . . . . 60253. Detail level of channel statistics information

collection . . . . . . . . . . . . . 61154. MQI accounting message structure . . . . 61955. Array indexed by object type . . . . . . 66556. Array indexed by persistence value . . . . 66657. Parameter/value pairs that can be used in the

activity trace configuration file . . . . . . 66958. Appclass values and how they correspond to

the APICallerType and APIEnvironment fields 67159. AppActivityDistList group MQCFGR

structure . . . . . . . . . . . . . 70460. Monitoring levels . . . . . . . . . . 73961. Substates seen with status binding or

requesting . . . . . . . . . . . . 74662. Sender and receiver MCA substates . . . . 74763. MQTT v3 Java client reason codes . . . . 79064. Symptom table . . . . . . . . . . . 80265. Queue manager error log directory . . . . 80966. System error log directory . . . . . . . 81067. Client error log directory. . . . . . . . 81068. Keywords defined for use in a free format

search . . . . . . . . . . . . . . 84169. Keywords defined for use in a structured

format search . . . . . . . . . . . 84270. SDB format symptom-to-keyword

cross-reference . . . . . . . . . . . 84371. WebSphere MQ component and resource

manager identifiers . . . . . . . . . 84472. SSL return codes . . . . . . . . . . 114973. Certificate validation errors . . . . . . 1151

Copyright IBM Corp. 2007, 2014 ix

x IBM WebSphere MQ: Administering

Administering WebSphere MQAdministering queue managers and associated resources includes the tasks that you perform frequentlyto activate and manage those resources. Choose the method you prefer to administer your queuemanagers and associated resources.

You can administer WebSphere MQ objects locally or remotely, see Local and remote administrationon page 3.

There are a number of different methods that you can use to create and administer your queue managersand their related resources in WebSphere MQ. These methods include command-line interfaces, agraphical user interface, and an administration API. See the sections and links in this topic for moreinformation about each of these interfaces.

There are different sets of commands that you can use to administer WebSphere MQ depending on yourplatform:v WebSphere MQ control commandsv WebSphere MQ Script (MQSC) commandsv Programmable Command Formats (PCFs) on page 2

There are also the other following options for creating and managing WebSphere MQ objects:v The WebSphere MQ Explorer on page 2v The Windows Default Configuration application on page 3v The Microsoft Cluster Service (MSCS) on page 3

You can automate some administration and monitoring tasks for both local and remote queue managersby using PCF commands. These commands can also be simplified through the use of the WebSphere MQAdministration Interface (MQAI) on some platforms. For more information about automatingadministration tasks, see Automating administration tasks on page 4.

WebSphere MQ control commands

Control commands allow you to perform administrative tasks on queue managers themselves.

WebSphere MQ for Windows, UNIX and Linux systems provides the control commands that you issue atthe system command line.

The control commands are described in Creating and managing queue managers. For the commandreference for the control commands, see WebSphere MQ Control commands WebSphere MQ Controlcommands.

WebSphere MQ Script (MQSC) commandsUse MQSC commands to manage queue manager objects, including the queue manager itself, queues,process definitions, namelists, channels, client connection channels, listeners, services, and authenticationinformation objects.

You issue MQSC commands to a queue manager by using the runmqsc command. You can do thisinteractively, issuing commands from a keyboard, or you can redirect the standard input device (stdin) torun a sequence of commands from an ASCII text file. In both cases, the format of the commands is thesame.

Copyright IBM Corp. 2007, 2014 1

You can run the runmqsc command in three modes, depending on the flags set on the command:v Verification mode, where the MQSC commands are verified on a local queue manager, but are not runv Direct mode, where the MQSC commands are run on a local queue managerv Indirect mode, where the MQSC commands are run on a remote queue manager

Object attributes specified in MQSC commands are shown in this section in uppercase (for example,RQMNAME), although they are not case-sensitive. MQSC command attribute names are limited to eightcharacters.

MQSC commands are available on all platforms. MQSC commands are summarized in Comparingcommand sets.

On Windows, UNIX or Linux, you can use the MQSC as single commands issued at the systemcommand line. To issue more complicated, or multiple commands, the MQSC can be built into a file thatyou run from the Windows, UNIX or Linux system command line. MQSC can be sent to a remote queuemanager. For full details, see MQSC reference.

Script (MQSC) Commands on page 69 contains a description of each MQSC command and its syntax.

See Performing local administration tasks using MQSC commands on page 69 for more informationabout using MQSC commands in local administration.

Programmable Command Formats (PCFs)Programmable Command Formats (PCFs) define command and reply messages that can be exchangedbetween a program and any queue manager (that supports PCFs) in a network. You can use PCFcommands in a systems management application program for administration of WebSphere MQ objects:authentication information objects, channels, channel listeners, namelists, process definitions, queuemanagers, queues, services, and storage classes. The application can operate from a single point in thenetwork to communicate command and reply information with any queue manager, local, or remote,using the local queue manager.

For more information about PCFs, see Introduction to Programmable Command Formats on page 5.

For definition of PCFs and structures for the commands and responses, see Programmable commandformats reference.

The WebSphere MQ Explorer

Using the WebSphere MQ Explorer, you can perform the following actions:v Define and control various resources including queue managers, queues, process definitions, namelists,channels, client connection channels, listeners, services, and clusters.

v Start or stop a local queue manager and its associated processes.v View queue managers and their associated objects on your workstation or from other workstations.v Check the status of queue managers, clusters, and channels.v Check to see which applications, users, or channels have a particular queue open, from the queuestatus.

On Windows and Linux systems, you can start WebSphere MQ Explorer by using the system menu, theMQExplorer executable file, or the strmqcfg command.

On Linux, to start the WebSphere MQ Explorer successfully, you must be able to write a file to yourhome directory, and the home directory must exist.

2 IBM WebSphere MQ: Administering

You can use WebSphere MQ Explorer to administer remote queue managers on other platforms includingz/OS, for details and to download the SupportPac MS0T, see http://www.ibm.com/support/docview.wss?uid=swg24021041.

See Administration using the WebSphere MQ Explorer on page 52 for more information.

The Windows Default Configuration application

You can use the Windows Default Configuration program to create a starter (or default) set of WebSphereMQ objects. A summary of the default objects created is listed in Table 1: Objects created by the Windowsdefault configuration application.

The Microsoft Cluster Service (MSCS)Microsoft Cluster Service (MSCS) enables you to connect servers into a cluster, giving higher availabilityof data and applications, and making it easier to manage the system. MSCS can automatically detect andrecover from server or application failures.

It is important not to confuse clusters in the MSCS sense with WebSphere MQ clusters. The distinction is:

WebSphere MQ clustersare groups of two or more queue managers on one or more computers, providing automaticinterconnection, and allowing queues to be shared among them for load balancing andredundancy.

MSCS clustersGroups of computers, connected together and configured in such a way that, if one fails, MSCSperforms a failover, transferring the state data of applications from the failing computer to anothercomputer in the cluster and reinitiating their operation there.

Supporting the Microsoft Cluster Service (MSCS) provides detailed information about how to configureyour WebSphere MQ for Windows system to use MSCS.Related concepts:Administering local WebSphere MQ objects on page 65This section tells you how to administer local WebSphere MQ objects to support application programsthat use the Message Queue Interface (MQI). In this context, local administration means creating,displaying, changing, copying, and deleting WebSphere MQ objects.Administering remote WebSphere MQ objects on page 102

Related information:WebSphere MQ technical overviewPlanningConfiguringTransactional support scenariosConsiderations when contact is lost with the XA resource manager

Local and remote administrationYou can administer WebSphere MQ objects locally or remotely.

Local administration means carrying out administration tasks on any queue managers you have defined onyour local system. You can access other systems, for example through the TCP/IP terminal emulationprogram telnet, and carry out administration there. In WebSphere MQ, you can consider this as localadministration because no channels are involved, that is, the communication is managed by the operatingsystem.

Administering WebSphere MQ 3

WebSphere MQ supports administration from a single point of contact through what is known as remoteadministration. This allows you to issue commands from your local system that are processed on anothersystem and applies also to the WebSphere MQ Explorer. For example, you can issue a remote commandto change a queue definition on a remote queue manager. You do not have to log on to that system,although you do need to have the appropriate channels defined. The queue manager and commandserver on the target system must be running.

Some commands cannot be issued in this way, in particular, creating or starting queue managers andstarting command servers. To perform this type of task, you must either log onto the remote system andissue the commands from there or create a process that can issue the commands for you. This restrictionapplies also to the WebSphere MQ Explorer.

Administering remote WebSphere MQ objects on page 102 describes the subject of remoteadministration in greater detail.

How to use WebSphere MQ control commandsThis section describes how to use the WebSphere MQ control commands.

If you want to issue control commands, your user ID must be a member of the mqm group. For moreinformation about this, see Authority to administer WebSphere MQ on UNIX, Linux and Windowssystems. In addition, note the following environment-specific information:

WebSphere MQ for WindowsAll control commands can be issued from a command line. Command names and their flags arenot case sensitive: you can enter them in uppercase, lowercase, or a combination of uppercaseand lowercase. However, arguments to control commands (such as queue names) are casesensitive.

In the syntax descriptions, the hyphen (-) is used as a flag indicator. You can use the forwardslash (/) instead of the hyphen.

WebSphere MQ for UNIX and Linux systemsAll WebSphere MQ control commands can be issued from a shell. All commands arecase-sensitive.

A subset of the control commands can be issued using the WebSphere MQ Explorer.

For more information, see The WebSphere MQ control commands

Automating administration tasksYou might decide that it would be beneficial to your installation to automate some administration andmonitoring tasks. You can automate administration tasks for both local and remote queue managers usingprogrammable command format (PCF) commands. This section assumes that you have experience ofadministering WebSphere MQ objects.

PCF commands

WebSphere MQ programmable command format (PCF) commands can be used to programadministration tasks into an administration program. In this way, from a program you can manipulatequeue manager objects (queues, process definitions, namelists, channels, client connection channels,listeners, services, and authentication information objects), and even manipulate the queue managersthemselves.


PCF commands cover the same range of functions provided by MQSC commands. You can write aprogram to issue PCF commands to any queue manager in the network from a single node. In this way,you can both centralize and automate administration tasks.

Each PCF command is a data structure that is embedded in the application data part of a WebSphere MQmessage. Each command is sent to the target queue manager using the MQI function MQPUT in thesame way as any other message. Providing the command server is running on the queue managerreceiving the message, the command server interprets it as a command message and runs the command.To get the replies, the application issues an MQGET call and the reply data is returned in another datastructure. The application can then process the reply and act accordingly.

Note: Unlike MQSC commands, PCF commands and their replies are not in a text format that you canread.

Briefly, these are some of the things needed to create a PCF command message:

Message descriptorThis is a standard WebSphere MQ message descriptor, in which:v Message type (MsqType) is MQMT_REQUEST.v Message format (Format) is MQFMT_ADMIN.

Application dataContains the PCF message including the PCF header, in which:v The PCF message type (Type) specifies MQCFT_COMMAND.v The command identifier specifies the command, for example, Change Queue(MQCMD_CHANGE_Q).

For a complete description of the PCF data structures and how to implement them, see Introduction toProgrammable Command Formats.

PCF object attributesObject attributes in PCF are not limited to eight characters as they are for MQSC commands. They areshown in this guide in italics. For example, the PCF equivalent of RQMNAME is RemoteQMgrName.

Escape PCFs

Escape PCFs are PCF commands that contain MQSC commands within the message text. You can usePCFs to send commands to a remote queue manager. For more information about escape PCFs, seeEscape.

Introduction to Programmable Command FormatsProgrammable Command Formats (PCFs) define command and reply messages that can be exchangedbetween a program and any queue manager (that supports PCFs) in a network. PCFs simplify queuemanager administration and other network administration. They can be used to solve the problem ofcomplex administration of distributed networks especially as networks grow in size and complexity.

The Programmable Command Formats described in this product documentation are supported by:v IBM WebSphere MQ for AIX

v IBM WebSphere MQ for HP-UXv IBM WebSphere MQ for Linuxv IBM WebSphere MQ for Solarisv IBM WebSphere MQ for Windowsv IBM WebSphere MQ for HP Integrity NonStop Server v5.3


The problem PCF commands solve

The administration of distributed networks can become complex. The problems of administrationcontinue to grow as networks increase in size and complexity.

Examples of administration specific to messaging and queuing include:v Resource management.For example, queue creation and deletion.

v Performance monitoring.For example, maximum queue depth or message rate.

v Control.For example, tuning queue parameters such as maximum queue depth, maximum message length, andenabling and disabling queues.

v Message routing.Definition of alternative routes through a network.

WebSphere MQ PCF commands can be used to simplify queue manager administration and othernetwork administration. PCF commands allow you to use a single application to perform networkadministration from a single queue manager within the network.

What are PCFs?

PCFs define command and reply messages that can be exchanged between a program and any queuemanager (that supports PCFs) in a network. You can use PCF commands in a systems managementapplication program for administration of WebSphere MQ objects: authentication information objects,channels, channel listeners, namelists, process definitions, queue managers, queues, services, and storageclasses. The application can operate from a single point in the network to communicate command andreply information with any queue manager, local, or remote, using the local queue manager.

Each queue manager has an administration queue with a standard queue name and your application cansend PCF command messages to that queue. Each queue manager also has a command server to servicethe command messages from the administration queue. PCF command messages can therefore beprocessed by any queue manager in the network and the reply data can be returned to your application,using your specified reply queue. PCF commands and reply messages are sent and received using thenormal Message Queue Interface (MQI).

For a list of the available PCF commands, including their parameters, see Definitions of theProgrammable Command Formats.

Using Programmable Command FormatsYou can use PCFs in a systems management program for WebSphere MQ remote administration.

This section includes:v PCF command messages on page 7v Responses on page 9v Rules for naming WebSphere MQ objectsv Authority checking for PCF commands on page 12


PCF command messages:

PCF command messages consist of a PCF header, parameters identified in that header and alsouser-defined message data. The messages are issued using Message Queue interface calls.

Each command and its parameters are sent as a separate command message containing a PCF headerfollowed by a number of parameter structures; for details of the PCF header, see MQCFH - PCF header,and for an example of a parameter structure, see MQCFST - PCF string parameter. The PCF headeridentifies the command and the number of parameter structures that follow in the same message. Eachparameter structure provides a parameter to the command.

Replies to the commands, generated by the command server, have a similar structure. There is a PCFheader, followed by a number of parameter structures. Replies can consist of more than one message butcommands always consist of one message only.

On platforms other than z/OS, the queue to which the PCF commands are sent is always called theSYSTEM.ADMIN.COMMAND.QUEUE.

How to issue PCF command messages

Use the normal Message Queue Interface (MQI) calls, MQPUT, MQGET, and so on, to put and retrievePCF command and response messages to and from their queues.

Note:

Ensure that the command server is running on the target queue manager for the PCF command toprocess on that queue manager.

For a list of supplied header files, see WebSphere MQ COPY, header, include and module files.

Message descriptor for a PCF command

The WebSphere MQ message descriptor is fully documented in MQMD - Message descriptor.

A PCF command message contains the following fields in the message descriptor:

ReportAny valid value, as required.

MsgTypeThis field must be MQMT_REQUEST to indicate a message requiring a response.

ExpiryAny valid value, as required.

FeedbackSet to MQFB_NONE

EncodingIf you are sending to Windows, UNIX or Linux systems, set this field to the encoding used for themessage data; conversion is performed if necessary.

CodedCharSetIdIf you are sending to Windows, UNIX or Linux systems, set this field to the coded character-setidentifier used for the message data; conversion is performed if necessary.

FormatSet to MQFMT_ADMIN.


PriorityAny valid value, as required.

PersistenceAny valid value, as required.

MsgIdThe sending application can specify any value, or MQMI_NONE can be specified to request thequeue manager to generate a unique message identifier.

CorrelIdThe sending application can specify any value, or MQCI_NONE can be specified to indicate nocorrelation identifier.

ReplyToQThe name of the queue to receive the response.

ReplyToQMgrThe name of the queue manager for the response (or blank).

Message context fieldsThese fields can be set to any valid values, as required. Normally the Put message optionMQPMO_DEFAULT_CONTEXT is used to set the message context fields to the default values.

If you are using a version-2 MQMD structure, you must set the following additional fields:

GroupIdSet to MQGI_NONE

MsgSeqNumberSet to 1

OffsetSet to 0

MsgFlagsSet to MQMF_NONE

OriginalLengthSet to MQOL_UNDEFINED

Sending user data

The PCF structures can also be used to send user-defined message data. In this case the messagedescriptor Format field must be set to MQFMT_PCF.

Sending and receiving PCF messages in a specified queue:

Sending PCF messages to a specified queue

To send a message to a specified queue, the mqPutBag call converts the contents of the specified bag intoa PCF message and sends the message to the specified queue. The contents of the bag are left unchangedafter the call.

As input to this call, you must supply:v An MQI connection handle.v An object handle for the queue on which the message is to be placed.v A message descriptor. For more information about the message descriptor, see MQMD - Messagedescriptor.

v Put Message Options using the MQPMO structure. For more information about the MQPMO structure,see MQPMO - Put-message options.


v The handle of the bag to be converted to a message.

Note: If the bag contains an administration message and the mqAddInquiry call was used to insertvalues into the bag, the value of the MQIASY_COMMAND data item must be an INQUIRE commandrecognized by the MQAI.

For a full description of the mqPutBag call, see mqPutBag.

Receiving PCF messages from a specified queue

To receive a message from a specified queue, the mqGetBag call gets a PCF message from a specifiedqueue and converts the message data into a data bag.

As input to this call, you must supply:v An MQI connection handle.v An object handle of the queue from which the message is to be read.v A message descriptor. Within the MQMD structure, the Format parameter must be MQFMT_ADMIN,MQFMT_EVENT, or MQFMT_PCF.

Note: If the message is received within a unit of work (that is, with the MQGMO_SYNCPOINToption) and the message has an unsupported format, the unit of work can be backed out. The messageis then reinstated on the queue and can be retrieved using the MQGET call instead of the mqGetBagcall. For more information about the message descriptor, see MQGMO - Get-message options.

v Get Message Options using the MQGMO structure. For more information about the MQGMOstructure, see MQMD - Message Descriptor.

v The handle of the bag to contain the converted message.

For a full description of the mqGetBag call, see mqGetBag.

Responses:

In response to each command, the command server generates one or more response messages. A responsemessage has a similar format to a command message.

The PCF header has the same command identifier value as the command to which it is a response (seeMQCFH - PCF header for details). The message identifier and correlation identifier are set according tothe report options of the request.

If the PCF header type of the command message is MQCFT_COMMAND, standard responses only aregenerated. Such commands are supported on all platforms except z/OS. Older applications do notsupport PCF on z/OS; the WebSphere MQ Windows Explorer is one such application (however, theVersion 6.0 or later WebSphere MQ Explorer does support PCF on z/OS).

If the PCF header type of the command message is MQCFT_COMMAND_XR, either extended orstandard responses are generated. Such commands are supported on z/OS and some other platforms.Commands issued on z/OS generate only extended responses. On other platforms, either type ofresponse might be generated.

If a single command specifies a generic object name, a separate response is returned in its own messagefor each matching object. For response generation, a single command with a generic name is treated asmultiple individual commands (except for the control field MQCFC_LAST or MQCFC_NOT_LAST).Otherwise, one command message generates one response message.


Certain PCF responses might return a structure even when it is not requested. This structure is shown inthe definition of the response (Definitions of the Programmable Command Formats) as always returned.The reason that, for these responses, it is necessary to name the objects in the response to identify whichobject the data applies.

Message descriptor for a response

A response message has the following fields in the message descriptor:

MsgTypeThis field is MQMT_REPLY.

MsgIdThis field is generated by the queue manager.

CorrelIdThis field is generated according to the report options of the command message.

FormatThis field is MQFMT_ADMIN.

EncodingSet to MQENC_NATIVE.

CodedCharSetIdSet to MQCCSI_Q_MGR.

PersistenceThe same as in the command message.

PriorityThe same as in the command message.

The response is generated with MQPMO_PASS_IDENTITY_CONTEXT.

Standard responses:

Command messages with a header type of MQCFT_COMMAND, standard responses are generated. Suchcommands are supported on all platforms except z/OS.

There are three types of standard response:v OK responsev Error responsev Data response

OK response

This response consists of a message starting with a command format header, with a CompCode field ofMQCC_OK or MQCC_WARNING.

For MQCC_OK, the Reason is MQRC_NONE.

For MQCC_WARNING, the Reason identifies the nature of the warning. In this case the command formatheader might be followed by one or more warning parameter structures appropriate to this reason code.

In either case, for an inquire command further parameter structures might follow as described in thefollowing sections.


Error response

If the command has an error, one or more error response messages are sent (more than one might be senteven for a command that would normally have only a single response message). These error responsemessages have MQCFC_LAST or MQCFC_NOT_LAST set as appropriate.

Each such message starts with a response format header, with a CompCode value of MQCC_FAILED and aReason field that identifies the particular error. In general, each message describes a different error. Inaddition, each message has either zero or one (never more than one) error parameter structures followingthe header. This parameter structure, if there is one, is an MQCFIN structure, with a Parameter fieldcontaining one of the following:v MQIACF_PARAMETER_IDThe Value field in the structure is the parameter identifier of the parameter that was in error (forexample, MQCA_Q_NAME).

v MQIACF_ERROR_IDThis value is used with a Reason value (in the command format header) ofMQRC_UNEXPECTED_ERROR. The Value field in the MQCFIN structure is the unexpected reasoncode received by the command server.

v MQIACF_SELECTORThis value occurs if a list structure (MQCFIL) sent with the command contains a duplicate selector orone that is not valid. The Reason field in the command format header identifies the error, and the Valuefield in the MQCFIN structure is the parameter value in the MQCFIL structure of the command thatwas in error.

v MQIACF_ERROR_OFFSETThis value occurs when there is a data compare error on the Ping Channel command. The Value fieldin the structure is the offset of the Ping Channel compare error.

v MQIA_CODED_CHAR_SET_IDThis value occurs when the coded character-set identifier in the message descriptor of the incomingPCF command message does not match that of the target queue manager. The Value field in thestructure is the coded character-set identifier of the queue manager.

The last (or only) error response message is a summary response, with a CompCode field ofMQCC_FAILED, and a Reason field of MQRCCF_COMMAND_FAILED. This message has no parameterstructure following the header.

Data response

This response consists of an OK response (as described earlier) to an inquire command. The OK responseis followed by additional structures containing the requested data as described in Definitions of theProgrammable Command Formats.

Applications must not depend upon these additional parameter structures being returned in anyparticular order.


Authority checking for PCF commands:

When a PCF command is processed, the UserIdentifier from the message descriptor in the commandmessage is used for the required WebSphere MQ object authority checks. Authority checking isimplemented differently on each platform as described in this topic.

The checks are performed on the system on which the command is being processed; therefore this userID must exist on the target system and have the required authorities to process the command. If themessage has come from a remote system, one way of achieving the ID existing on the target system is tohave a matching user ID on both the local and remote systems.

Windows UNIX Linux

WebSphere MQ for Windows, UNIX and Linux systems

In order to process any PCF command, the user ID must have dsp authority for the queue manager objecton the target system. In addition, WebSphere MQ object authority checks are performed for certain PCFcommands, as shown in Table 1 on page 13.

To process any of the following commands the user ID must belong to group mqm.

Note: For Windows only, the user ID can belong to group Administrators or group mqm.v Change Channelv Copy Channelv Create Channelv Delete Channelv Ping Channelv Reset Channelv Start Channelv Stop Channelv Start Channel Initiatorv Start Channel Listenerv Resolve Channelv Reset Clusterv Refresh Clusterv Suspend Queue Managerv Resume Queue Manager

WebSphere MQ for HP Integrity NonStop Server

In order to process any PCF command, the user ID must have dsp authority for the queue manager objecton the target system. In addition, WebSphere MQ object authority checks are performed for certain PCFcommands, as shown in Table 1 on page 13.

To process any of the following commands the user ID must belong to group mqm:v Change Channelv Copy Channelv Create Channelv Delete Channelv Ping Channelv Reset Channel


v Start Channelv Stop Channelv Start Channel Initiatorv Start Channel Listenerv Resolve Channelv Reset Clusterv Refresh Clusterv Suspend Queue Managerv Resume Queue Manager

WebSphere MQ Object authorities

Table 1. Windows, HP Integrity NonStop Server, UNIX and Linux systems - object authoritiesCommand WebSphere MQ object authority Class authority (for object

type)

Change Authentication Information dsp and chg n/a

Change Channel dsp and chg n/a

Change Channel Listener dsp and chg n/a

Change Client Connection Channel dsp and chg n/a

Change Namelist dsp and chg n/a

Change Process dsp and chg n/a

Change Queue dsp and chg n/a

Change Queue Manager chg see Note 3 and Note 5 n/a

Change Service dsp and chg n/a

Clear Queue clr n/a

Copy Authentication Information dsp crt

Copy Authentication Information(Replace) see Note 1

from: dsp to: chg crt

Copy Channel dsp crt

Copy Channel (Replace) see Note 1 from: dsp to: chg crt

Copy Channel Listener dsp crt

Copy Channel Listener (Replace) seeNote 1


Copy Client Connection Channel dsp crt

Copy Client Connection Channel(Replace) see Note 1


Copy Namelist dsp crt

Copy Namelist (Replace) see Note 1 from: dsp to: dsp and chg crt

Copy Process dsp crt

Copy Process (Replace) see Note 1 from: dsp to: chg crt

Copy Queue dsp crt

Copy Queue (Replace) see Note 1 from: dsp to: dsp and chg crt

Create Authentication Information (system default authentication information) dsp crt

Create Authentication Information(Replace) see Note 1

(system default authentication information) dspto: chg

crt


Table 1. Windows, HP Integrity NonStop Server, UNIX and Linux systems - object authorities (continued)Command WebSphere MQ object authority Class authority (for object

type)

Create Channel (system default channel) dsp crt

Create Channel (Replace) see Note 1 (system default channel) dsp to: chg crt

Create Channel Listener (system default listener) dsp crt

Create Channel Listener (Replace) seeNote 1

(system default listener) dsp to: chg crt

Create Client Connection Channel (system default channel) dsp crt

Create Client Connection Channel(Replace) see Note 1

(system default channel) dsp to: chg crt

Create Namelist (system default namelist) dsp crt

Create Namelist (Replace) see Note 1 (system default namelist) dsp to: dsp and chg crt

Create Process (system default process) dsp crt

Create Process (Replace) see Note 1 (system default process) dsp to: chg crt

Create Queue (system default queue) dsp crt

Create Queue (Replace) see Note 1 (system default queue) dsp to: dsp and chg crt

Create Service (system default queue) dsp crt

Create Service (Replace) see Note 1 (system default queue) dsp to: chg crt

Delete Authentication Information dsp and dlt n/a

Delete Authority Record (queue manager object) chg see Note 4 see Note 4

Delete Channel dsp and dlt n/a

Delete Channel Listener dsp and dlt n/a

Delete Client Connection Channel dsp and dlt n/a

Delete Namelist dsp and dlt n/a

Delete Process dsp and dlt n/a

Delete Queue dsp and dlt n/a

Delete Service dsp and dlt n/a

Inquire Authentication Information dsp n/a

Inquire Authority Records see Note 4 see Note 4

Inquire Channel dsp n/a

Inquire Channel Listener dsp n/a

Inquire Channel Status (forChannelType MQCHT_CLSSDR)

inq n/a

Inquire Client Connection Channel dsp n/a

Inquire Namelist dsp n/a

Inquire Process dsp n/a

Inquire Queue dsp n/a

Inquire Queue Manager see note 3 n/a

Inquire Queue Status dsp n/a

Inquire Service dsp n/a

Ping Channel ctrl n/a

Ping Queue Manager see note 3 n/a


Table 1. Windows, HP Integrity NonStop Server, UNIX and Linux systems - object authorities (continued)Command WebSphere MQ object authority Class authority (for object

type)

Refresh Queue Manager (queue manager object) chg n/a

Refresh Security (for SecurityTypeMQSECTYPE_SSL)

(queue manager object) chg n/a

Reset Channel ctrlx n/a

Reset Queue Manager (queue manager object) chg n/a

Reset Queue Statistics dsp and chg n/a

Resolve Channel ctrlx n/a

Set Authority Record (queue manager object) chg see Note 4 see Note 4

Start Channel ctrl n/a

Stop Channel ctrl n/a

Stop Connection (queue manager object) chg n/a

Start Listener ctrl n/a

Stop Listener ctrl n/a

Start Service ctrl n/a

Stop Service ctrl n/a

Escape see Note 2 see Note 2

Notes:

1. This command applies if the object to be replaced does exist, otherwise the authority check is as forCreate, or Copy without Replace.

2. The required authority is determined by the MQSC command defined by the escape text, and it isequivalent to one of the previous commands.

3. In order to process any PCF command, the user ID must have dsp authority for the queue managerobject on the target system.

4. This PCF command is authorized unless the command server has been started with the -a parameter.By default the command server starts when the Queue Manager is started, and without the -aparameter. See the System Administration Guide for further information.

5. Granting a user ID chg authority for a queue manager gives the ability to set authority records for allgroups and users. Do not grant this authority to ordinary users or applications.

WebSphere MQ also supplies some channel security exit points so that you can supply your own userexit programs for security checking. Details are given in Displaying a channel manual.

Using the MQAI to simplify the use of PCFsThe MQAI is an administration interface to WebSphere MQ that is available on the AIX, HP-UX, Linux,Solaris, and Windows platforms.

The MQAI performs administration tasks on a queue manager through the use of data bags. Data bagsallow you to handle properties (or parameters) of objects in a way that is easier than using PCFs.

Use the MQAI in the following ways:

To simplify the use of PCF messagesThe MQAI is an easy way to administer WebSphere MQ; you do not have to write your own PCFmessages, avoiding the problems associated with complex data structures.


To pass parameters in programs written using MQI calls, the PCF message must contain thecommand and details of the string or integer data. To do this, you need several statements inyour program for every structure, and memory space must be allocated. This task can be longand laborious.

Programs written using the MQAI pass parameters into the appropriate data bag and you needonly one statement for each structure. The use of MQAI data bags removes the need for you tohandle arrays and allocate storage, and provides some degree of isolation from the details of thePCF.

To handle error conditions more easilyIt is difficult to get return codes back from PCF commands, but the MQAI makes it easier for theprogram to handle error conditions.

After you have created and populated your data bag, you can send an administration command messageto the command server of a queue manager, using the mqExecute call, which waits for any responsemessages. The mqExecute call handles the exchange with the command server and returns responses in aresponse bag.

For more information about the MQAI, see Introduction to the WebSphere MQ Administration Interface(MQAI).

Introduction to the WebSphere MQ Administration Interface (MQAI)WebSphere MQ Administration Interface (MQAI) is a programming interface to WebSphere MQ. Itperforms administration tasks on a WebSphere MQ queue manager using data bags to handle properties(or parameters) of objects in a way that is easier than using Programmable Command Formats (PCFs).

MQAI concepts and terminology

The MQAI is a programming interface to WebSphere MQ, using the C language and also Visual Basic forWindows. It is available on platforms other than z/OS.

It performs administration tasks on a WebSphere MQ queue manager using data bags. Data bags allowyou to handle properties (or parameters) of objects in a way that is easier than using the otheradministration interface, Programmable Command Formats (PCFs). The MQAI offers easier manipulationof PCFs than using the MQGET and MQPUT calls.

For more information about data bags, see Data bags on page 42. For more information about PCFs, seeIntroduction to Programmable Command Formats on page 5

Use of the MQAI

You can use the MQAI to:v Simplify the use of PCF messages. The MQAI is an easy way to administer WebSphere MQ; you do nothave to write your own PCF messages and thus avoid the problems associated with complex datastructures.

v Handle error conditions more easily. It is difficult to get return codes back from the WebSphere MQscript (MQSC) commands, but the MQAI makes it easier for the program to handle error conditions.

v Exchange data between applications. The application data is sent in PCF format and packed andunpacked by the MQAI. If your message data consists of integers and character strings, you can usethe MQAI to take advantage of WebSphere MQ built-in data conversion for PCF data. This avoids theneed to write data-conversion exits. For more information on using MQAI to administer WebSphereMQ and to exchange data between applications, see Using the MQAI to simplify the use of PCFs onpage 15.


Examples of using the MQAI

The list shown gives some example programs that demonstrate the use of MQAI. The samples performthe following tasks:1. Create a local queue. Creating a local queue (amqsaicq.c)2. Display events on the screen using a simple event monitor. Displaying events using an event

monitor (amqsaiem.c) on page 223. Print a list of all local queues and their current depths. Inquiring about queues and printing

information (amqsailq.c) on page 364. Print a list of all channels and their types. Inquire channel objects (amqsaicl.c) on page 30

Building your MQAI application

To build your application using the MQAI, you link to the same libraries as you do for WebSphere MQ.For information on how to build your WebSphere MQ applications, see Building a WebSphere MQapplication.

Hints and tips for configuring WebSphere MQ using MQAI

The MQAI uses PCF messages to send administration commands to the command server rather thandealing directly with the command server itself. Tips for configuring WebSphere MQ using the MQAI canbe found in Hints and tips for configuring WebSphere MQ on page 41

WebSphere MQ Administration Interface (MQAI)WebSphere MQ for Windows, AIX, Linux, HP-UX, and Solaris support the WebSphere MQAdministration Interface (MQAI). The MQAI is a programming interface to WebSphere MQ that givesyou 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 easilythan using PCFs directly by way of the MQAI.

The MQAI provides easier programming access to PCF messages by passing parameters into the databag, so that only one statement is required for each structure. This access removes the need for theprogrammer to handle arrays and allocate storage, and provides some isolation from the details of PCF.

The MQAI administers WebSphere MQ by sending PCF messages to the command server and waiting fora response.

The MQAI is described in the second section of this manual. See the Using Java documentation for adescription of a component object model interface to the MQAI.

Creating a local queue (amqsaicq.c)/******************************************************************************//* *//* Program name: AMQSAICQ.C *//* *//* Description: Sample C program to create a local queue using the *//* WebSphere MQ Administration Interface (MQAI). *//* *//* Statement: Licensed Materials - Property of IBM *//* *//* 84H2000, 5765-B73 *//* 84H2001, 5639-B42 *//* 84H2002, 5765-B74 *//* 84H2003, 5765-B75 *//* 84H2004, 5639-B43 *//* */


/* (C) Copyright IBM Corp. 1999, 2005 *//* *//******************************************************************************//* *//* Function: *//* AMQSAICQ is a sample C program that creates a local queue and is an *//* example of the use of the mqExecute call. *//* *//* - The name of the queue to be created is a parameter to the program. *//* *//* - A PCF command is built by placing items into an MQAI bag. *//* These are:- *//* - The name of the queue *//* - The type of queue required, which, in this case, is local. *//* *//* - The mqExecute call is executed with the command MQCMD_CREATE_Q. *//* The call generates the correct PCF structure. *//* The call receives the reply from the command server and formats into *//* the response bag. *//* *//* - The completion code from the mqExecute call is checked and if there *//* is a failure from the command server then the code returned by the *//* command server is retrieved from the system bag that is *//* embedded in the response bag to the mqExecute call. *//* *//* Note: The command server must be running. *//* *//* */

/******************************************************************************//* *//* AMQSAICQ has 2 parameters - the name of the local queue to be created *//* - the queue manager name (optional) *//* *//******************************************************************************//******************************************************************************//* Includes *//******************************************************************************/#include #include #include #include

#include /* MQI */#include /* PCF */#include /* MQAI */

void CheckCallResult(MQCHAR *, MQLONG , MQLONG );void CreateLocalQueue(MQHCONN, MQCHAR *);

int main(int argc, char *argv[]){

MQHCONN hConn; /* handle to WebSphere MQ connection */MQCHAR QMName[MQ_Q_MGR_NAME_LENGTH+1]=""; /* default QMgr name */MQLONG connReason; /* MQCONN reason code */MQLONG compCode; /* completion code */MQLONG reason; /* reason code */

/***************************************************************************//* First check the required parameters *//***************************************************************************/printf("Sample Program to Create a Local Queue\n");if (argc < 2){

printf("Required parameter missing - local queue name\n");exit(99);

}


/***************************************************************************//* Connect to the queue manager *//***************************************************************************/if (argc > 2)

strncpy(QMName, argv[2], (size_t)MQ_Q_MGR_NAME_LENGTH);MQCONN(QMName, &hConn, &compCode, &connReason);

/******************************************************************************//* Report reason and stop if connection failed *//******************************************************************************/

if (compCode == MQCC_FAILED){

CheckCallResult("MQCONN", compCode, connReason);exit( (int)connReason);

}

/******************************************************************************//* Call the routine to create a local queue, passing the handle to the *//* queue manager and also passing the name of the queue to be created. *//******************************************************************************/

CreateLocalQueue(hConn, argv[1]);

/***************************************************************************//* Disconnect from the queue manager if not already connected *//***************************************************************************/if (connReason != MQRC_ALREADY_CONNECTED){

MQDISC(&hConn, &compCode, &reason);CheckCallResult("MQDISC", compCode, reason);

}return 0;

}/******************************************************************************//* *//* Function: CreateLocalQueue *//* Description: Create a local queue by sending a PCF command to the command *//* server. *//* *//******************************************************************************//* *//* Input Parameters: Handle to the queue manager *//* Name of the queue to be created *//* *//* Output Parameters: None *//* *//* Logic: The mqExecute call is executed with the command MQCMD_CREATE_Q. *//* The call generates the correct PCF structure. *//* The default options to the call are used so that the command is sent*//* to the SYSTEM.ADMIN.COMMAND.QUEUE. *//* The reply from the command server is placed on a temporary dynamic *//* queue. *//* The reply is read from the temporary queue and formatted into the *//* response bag. *//* *//* The completion code from the mqExecute call is checked and if there *//* is a failure from the command server then the code returned by the *//* command server is retrieved from the system bag that is *//* embedded in the response bag to the mqExecute call. *//* *//******************************************************************************/void CreateLocalQueue(MQHCONN hConn, MQCHAR *qName){

MQLONG reason; /* reason code */MQLONG compCode; /* completion code */


MQHBAG commandBag = MQHB_UNUSABLE_HBAG; /* command bag for mqExecute */MQHBAG responseBag = MQHB_UNUSABLE_HBAG;/* response bag for mqExecute */MQHBAG resultBag; /* result bag from mqExecute */MQLONG mqExecuteCC; /* mqExecute completion code */MQLONG mqExecuteRC; /* mqExecute reason code */

printf("\nCreating Local Queue %s\n\n", qName);

/***************************************************************************//* Create a command Bag for the mqExecute call. Exit the function if the *//* create fails. *//***************************************************************************/mqCreateBag(MQCBO_ADMIN_BAG, &commandBag, &compCode, &reason);CheckCallResult("Create the command bag", compCode, reason);if (compCode !=MQCC_OK)

return;

/***************************************************************************//* Create a response Bag for the mqExecute call, exit the function if the *//* create fails. *//***************************************************************************/mqCreateBag(MQCBO_ADMIN_BAG, &responseBag, &compCode, &reason);CheckCallResult("Create the response bag", compCode, reason);if (compCode !=MQCC_OK)

return;

/***************************************************************************//* Put the name of the queue to be created into the command bag. This will *//* be used by the mqExecute call. *//***************************************************************************/mqAddString(commandBag, MQCA_Q_NAME, MQBL_NULL_TERMINATED, qName, &compCode,

&reason);CheckCallResult("Add q name to command bag", compCode, reason);

/***************************************************************************//* Put queue type of local into the command bag. This will be used by the *//* mqExecute call. *//***************************************************************************/mqAddInteger(commandBag, MQIA_Q_TYPE, MQQT_LOCAL, &compCode, &reason);CheckCallResult("Add q type to command bag", compCode, reason);

/***************************************************************************//* Send the command to create the required local queue. *//* The mqExecute call will create the PCF structure required, send it to *//* the command server and receive the reply from the command server into *//* the response bag. *//***************************************************************************/mqExecute(hConn, /* WebSphere MQ connection handle */

MQCMD_CREATE_Q, /* Command to be executed */MQHB_NONE, /* No options bag */commandBag, /* Handle to bag containing commands */responseBag, /* Handle to bag to receive the response*/MQHO_NONE, /* Put msg on SYSTEM.ADMIN.COMMAND.QUEUE*/MQHO_NONE, /* Create a dynamic q for the response */&compCode, /* Completion code from the mqExecute */&reason); /* Reason code from mqExecute call */

if (reason == MQRC_CMD_SERVER_NOT_AVAILABLE){

printf("Please start the command server: \n")MQDISC(&hConn, &compCode, &reason);CheckCallResult("MQDISC", compCode, reason);exit(98);

}


/***************************************************************************//* Check the result from mqExecute call and find the error if it failed. *//***************************************************************************/if ( compCode == MQCC_OK )

printf("Local queue %s successfully created\n", qName);else{

printf("Creation of local queue %s failed: Completion Code = %dqName, compCode, reason);

if (reason == MQRCCF_COMMAND_FAILED){

/*********************************************************************//* Get the system bag handle out of the mqExecute response bag. *//* This bag contains the reason from the command server why the *//* command failed. *//*********************************************************************/mqInquireBag(responseBag, MQHA_BAG_HANDLE, 0, &resultBag, &compCode,

&reason);CheckCallResult("Get the result bag handle", compCode, reason);

/*********************************************************************//* Get the completion code and reason code, returned by the command *//* server, from the embedded error bag. *//*********************************************************************/mqInquireInteger(resultBag, MQIASY_COMP_CODE, MQIND_NONE, &mqExecuteCC,

&compCode, &reason);CheckCallResult("Get the completion code from the result bag",

compCode, reason);mqInquireInteger(resultBag, MQIASY_REASON, MQIND_NONE, &mqExecuteRC,

&compCode, &reason);CheckCallResult("Get the reason code from the result bag", compCode,

reason);printf("Error returned by the command server: Completion code = %d :

Reason = %d\n", mqExecuteCC, mqExecuteRC);}

}/***************************************************************************//* Delete the command bag if successfully created. *//***************************************************************************/if (commandBag != MQHB_UNUSABLE_HBAG){

mqDeleteBag(&commandBag, &compCode, &reason);CheckCallResult("Delete the command bag", compCode, reason);

}

/***************************************************************************//* Delete the response bag if successfully created. *//***************************************************************************/if (responseBag != MQHB_UNUSABLE_HBAG){

mqDeleteBag(&responseBag, &compCode, &reason);CheckCallResult("Delete the response bag", compCode, reason);

}} /* end of CreateLocalQueue */

/******************************************************************************//* *//* Function: CheckCallResult *//* *//******************************************************************************//* *//* Input Parameters: Description of call *//* Completion code *//* Reason code *//* *//* Output Parameters: None */


/* *//* Logic: Display the description of the call, the completion code and the *//* reason code if the completion code is not successful *//* *//******************************************************************************/void CheckCallResult(char *callText, MQLONG cc, MQLONG rc){

if (cc != MQCC_OK)printf("%s failed: Completion Code = %d :

Reason = %d\n", callText, cc, rc);

}

Displaying events using an event monitor (amqsaiem.c)******************************************************************************//* *//* Program name: AMQSAIEM.C *//* *//* Description: Sample C program to demonstrate a basic event monitor *//* using the WebSphere MQ Admin Interface (MQAI). *//* Licensed Materials - Property of IBM *//* *//* 63H9336 *//* (c) Copyright IBM Corp. 1999, 2005 All Rights Reserved. *//* *//* US Government Users Restricted Rights - Use, duplication or *//* disclosure restricted by GSA ADP Schedule Contract with *//* IBM Corp. *//******************************************************************************//* *//* Function: *//* AMQSAIEM is a sample C program that demonstrates how to write a simple *//* event monitor using the mqGetBag call and other MQAI calls. *//* *//* The name of the event queue to be monitored is passed as a parameter *//* to the program. This would usually be one of the system event queues:- *//* SYSTEM.ADMIN.QMGR.EVENT Queue Manager events *//* SYSTEM.ADMIN.PERFM.EVENT Performance events *//* SYSTEM.ADMIN.CHANNEL.EVENT Channel events *//* SYSTEM.ADMIN.LOGGER.EVENT Logger events *//* *//* To monitor the queue manager event queue or the performance event queue,*//* the attributes of the queue manager needs to be changed to enable *//* these events. For more information about this, see Part 1 of the *//* Programmable System Management book. The queue manager attributes can *//* be changed using either MQSC commands or the MQAI interface. *//* Channel events are enabled by default. *//* *//* Program logic *//* Connect to the Queue Manager. *//* Open the requested event queue with a wait interval of 30 seconds. *//* Wait for a message, and when it arrives get the message from the queue *//* and format it into an MQAI bag using the mqGetBag call. *//* There are many types of event messages and it is beyond the scope of *//* this sample to program for all event messages. Instead the program *//* prints out the contents of the formatted bag. *//* Loop around to wait for another message until either there is an error *//* or the wait interval of 30 seconds is reached. *//* *//******************************************************************************//* *//* AMQSAIEM has 2 parameters - the name of the event queue to be monitored *//* - the queue manager name (optional) *//* *//*****************************************************************************

/******************************************************************************/


/* Includes *//******************************************************************************/#include #include #include #include

#include /* MQI */#include /* PCF */#include /* MQAI */

/******************************************************************************//* Macros *//******************************************************************************/#if MQAT_DEFAULT == MQAT_WINDOWS_NT

#define Int64 "I64"#elif defined(MQ_64_BIT)

#define Int64 "l"#else

#define Int64 "ll"#endif

/******************************************************************************//* Function prototypes *//******************************************************************************/void CheckCallResult(MQCHAR *, MQLONG , MQLONG);void GetQEvents(MQHCONN, MQCHAR *);int PrintBag(MQHBAG);int PrintBagContents(MQHBAG, int);

/******************************************************************************//* Function: main *//******************************************************************************/int main(int argc, char *argv[]){

MQHCONN hConn; /* handle to connection */MQCHAR QMName[MQ_Q_MGR_NAME_LENGTH+1]=""; /* default QM name */MQLONG reason; /* reason code */MQLONG connReason; /* MQCONN reason code */MQLONG compCode; /* completion code */

/***************************************************************************//* First check the required parameters *//***************************************************************************/printf("Sample Event Monitor (times out after 30 secs)\n");if (argc < 2){

printf("Required parameter missing - event queue to be monitored\n");exit(99);

}

/**************************************************************************//* Connect to the queue manager *//**************************************************************************/if (argc > 2)

strncpy(QMName, argv[2], (size_t)MQ_Q_MGR_NAME_LENGTH);MQCONN(QMName, &hConn, &compCode, &connReason);/***************************************************************************//* Report the reason and stop if the connection failed *//***************************************************************************/if (compCode == MQCC_FAILED){

CheckCallResult("MQCONN", compCode, connReason);exit( (int)connReason);

}

/***************************************************************************/


/* Call the routine to open the event queue and format any event messages *//* read from the queue. *//***************************************************************************/GetQEvents(hConn, argv[1]);

/***************************************************************************//* Disconnect from the queue manager if not already connected *//***************************************************************************/if (connReason != MQRC_ALREADY_CONNECTED){

MQDISC(&hConn, &compCode, &reason);CheckCallResult("MQDISC", compCode, reason);

}

return 0;

}

/******************************************************************************//* *//* Function: CheckCallResult *//* *//******************************************************************************//* *//* Input Parameters: Description of call *//* Completion code *//* Reason code *//* *//* Output Parameters: None *//* *//* Logic: Display the description of the call, the completion code and the *//* reason code if the completion code is not successful *//* *//******************************************************************************/void CheckCallResult(char *callText, MQLONG cc, MQLONG rc){

if (cc != MQCC_OK)printf("%s failed: Completion Code = %d : Reason = %d\n",

callText, cc, rc);

}

/******************************************************************************//* *//* Function: GetQEvents *//* *//******************************************************************************//* *//* Input Parameters: Handle to the queue manager *//* Name of the event queue to be monitored *//* *//* Output Parameters: None *//*/* Logic: Open the event queue. *//* Get a message off the event queue and format the message into *//* a bag. *//* A real event monitor would need to be programmed to deal with *//* each type of event that it receives from the queue. This is *//* outside the scope of this sample, so instead, the contents of *//* the bag are printed. *//* The program waits for 30 seconds for an event message and then *//* terminates if no more messages are available. *//* *//******************************************************************************/void GetQEvents(MQHCONN hConn, MQCHAR *qName){

MQLONG openReason; /* MQOPEN reason code */


MQLONG reason; /* reason code */MQLONG compCode; /* completion code */MQHOBJ eventQueue; /* handle to event queue */

MQHBAG eventBag = MQHB_UNUSABLE_HBAG; /* event bag to receive event msg */MQOD od = {MQOD_DEFAULT}; /* Object Descriptor */MQMD md = {MQMD_DEFAULT}; /* Message Descrip

Documents

Administering WebSphere MQ