System Administration Guide · 2018. 9. 27. · WebSphere MQ Script (MQSC) commands . . . 16 PCF commands .....16 Administration on WebSphere MQ for Windows . . 16 Using the WebSphere

WebSphere MQ

System Administration Guide

SC34-6068-01

��

Note!Before using this information and the product it supports, be sure to read the general information under Appendix I,“Notices” on page 515.

Second edition (October 2002)

This is the second edition of this book that applies to WebSphere MQ. It applies to the following products:v WebSphere MQ for AIX, V5.3v WebSphere MQ for HP-UX, V5.3v WebSphere MQ for Linux for Intel, V5.3v WebSphere MQ for Linux for zSeries, V5.3v WebSphere MQ for Solaris, V5.3v WebSphere MQ for Windows, V5.3and to any subsequent releases and modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 1994, 2002. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

||

Contents

Figures . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . xiii

About this book . . . . . . . . . . . xvWho this book is for . . . . . . . . . . . xvWhat you need to know to understand this book. . xv

Terms used in this book . . . . . . . . . xviUsing WebSphere MQ for Windows . . . . . xviUsing WebSphere MQ for UNIX systems . . . xviThe calls MQCONN and MQCONNX . . . . xvii

What’s new for this release . . . . . xixA change of name . . . . . . . . . . . . xixUsing installable services . . . . . . . . . xixUsing API exits . . . . . . . . . . . . . xixUsing the Microsoft® Cluster Server (MSCS) . . . xixUsing the Microsoft Transaction Server (MTS) . . . xxSecure Sockets Layer (SSL) support . . . . . . xxDumping authorities . . . . . . . . . . . xxiOAM generic profiles . . . . . . . . . . . xxiInstallable services . . . . . . . . . . . . xxiSetting your license units . . . . . . . . . xxi

Part 1. Introduction . . . . . . . . . 1

Chapter 1. Introduction to WebSphereMQ . . . . . . . . . . . . . . . . . 3WebSphere MQ and message queuing . . . . . . 3

Time-independent applications . . . . . . . 3Message-driven processing . . . . . . . . 3

Messages and queues . . . . . . . . . . . 3What is a message? . . . . . . . . . . . 4What is a queue? . . . . . . . . . . . . 4

Objects . . . . . . . . . . . . . . . . 5Object names . . . . . . . . . . . . . 6Managing objects . . . . . . . . . . . . 6Object attributes . . . . . . . . . . . . 6WebSphere MQ queues . . . . . . . . . . 7WebSphere MQ queue managers . . . . . . 9Process definitions . . . . . . . . . . . 10Channels . . . . . . . . . . . . . . 10Clusters . . . . . . . . . . . . . . 10Namelists . . . . . . . . . . . . . . 10Authentication information objects. . . . . . 11System default objects . . . . . . . . . . 11

Clients and servers . . . . . . . . . . . . 11WebSphere MQ applications in a client-serverenvironment . . . . . . . . . . . . . 12

Extending queue manager facilities . . . . . . 12User exits . . . . . . . . . . . . . . 12Installable services . . . . . . . . . . . 12

Security . . . . . . . . . . . . . . . 13Object Authority Manager (OAM) facility . . . 13

DCE security . . . . . . . . . . . . . 13Channel security using SSL . . . . . . . . 13

Transactional support . . . . . . . . . . . 13

Chapter 2. An introduction toWebSphere MQ administration . . . . 15Local and remote administration . . . . . . . 15Performing administration tasks using commands 15

Control commands . . . . . . . . . . . 16WebSphere MQ Script (MQSC) commands . . . 16PCF commands . . . . . . . . . . . . 16

Administration on WebSphere MQ for Windows . . 16Using the WebSphere MQ Explorer . . . . . 17Using the WebSphere MQ Services snap-in . . . 17Using the Windows Default Configurationapplication . . . . . . . . . . . . . 17Using the Microsoft Cluster Server (MSCS) . . . 18

Understanding WebSphere MQ file names . . . . 18Queue manager name transformation. . . . . 18Object name transformation . . . . . . . . 19

Part 2. Using commands toadminister WebSphere MQ . . . . . 21

Chapter 3. Managing queue managersusing control commands . . . . . . . 23Using control commands . . . . . . . . . . 23

Using control commands on Windows systems 23Using control commands on UNIX systems. . . 24

Creating a queue manager . . . . . . . . . 24Guidelines for creating queue managers . . . . 25Creating a default queue manager . . . . . . 27Making an existing queue manager the default 28Backing up configuration files after creating aqueue manager . . . . . . . . . . . . 28

Starting a queue manager . . . . . . . . . 29Starting a queue manager automatically . . . . 29

Stopping a queue manager . . . . . . . . . 29Quiesced shutdown . . . . . . . . . . 29Immediate shutdown . . . . . . . . . . 29Preemptive shutdown . . . . . . . . . . 30If you have problems shutting down a queuemanager . . . . . . . . . . . . . . 30

Restarting a queue manager . . . . . . . . . 30Deleting a queue manager . . . . . . . . . 30

Chapter 4. Administering localWebSphere MQ objects . . . . . . . 33Supporting application programs that use the MQI 33Performing local administration tasks using MQSCcommands. . . . . . . . . . . . . . . 34

WebSphere MQ object names . . . . . . . 35Standard input and output . . . . . . . . 35Using MQSC commands interactively . . . . 35

© Copyright IBM Corp. 1994, 2002 iii

||

||||||||||||||||||||||

||

||

||

Running MQSC commands from text files . . . 36Running MQSC commands from batch files . . 39Resolving problems with MQSC commands . . 40

Working with queue managers . . . . . . . . 41Displaying queue manager attributes . . . . . 41Altering queue manager attributes. . . . . . 42

Working with local queues . . . . . . . . . 42Defining a local queue. . . . . . . . . . 43Displaying default object attributes . . . . . 44Copying a local queue definition . . . . . . 44Changing local queue attributes . . . . . . 45Clearing a local queue . . . . . . . . . . 45Deleting a local queue . . . . . . . . . . 45Browsing queues . . . . . . . . . . . 46Monitoring local queues with the WindowsPerformance Monitor . . . . . . . . . . 47Enabling large queues . . . . . . . . . . 48

Working with alias queues . . . . . . . . . 48Defining an alias queue . . . . . . . . . 49Using other commands with alias queues . . . 50

Working with model queues. . . . . . . . . 50Defining a model queue . . . . . . . . . 50Using other commands with model queues. . . 51

Managing objects for triggering. . . . . . . . 51Defining an application queue for triggering . . 51Defining an initiation queue . . . . . . . . 52Defining a process . . . . . . . . . . . 52Displaying attributes of a process definition . . 53

Chapter 5. Automating administrationtasks . . . . . . . . . . . . . . . 55PCF commands . . . . . . . . . . . . . 55

PCF object attributes . . . . . . . . . . 56Escape PCFs . . . . . . . . . . . . . 56Using the MQAI to simplify the use of PCFs . . 56Active Directory Services Interfaces . . . . . 57

Chapter 6. Administering remoteWebSphere MQ objects . . . . . . . 59Channels, clusters, and remote queuing . . . . . 59

Remote administration using clusters . . . . . 60Remote administration from a local queue manager 61

Preparing queue managers for remoteadministration . . . . . . . . . . . . 61Preparing channels and transmission queues forremote administration . . . . . . . . . . 62Managing the command server for remoteadministration . . . . . . . . . . . . 64Issuing MQSC commands on a remote queuemanager . . . . . . . . . . . . . . 65Recommendations for issuing commandsremotely . . . . . . . . . . . . . . 66If you have problems using MQSC commandsremotely . . . . . . . . . . . . . . 66

Creating a local definition of a remote queue . . . 66Understanding how local definitions of remotequeues work . . . . . . . . . . . . . 67An alternative way of putting messages on aremote queue. . . . . . . . . . . . . 68Using other commands with remote queues . . 68

Defining a transmission queue . . . . . . . 68Using remote queue definitions as aliases . . . . 69

Queue manager aliases . . . . . . . . . 69Reply-to queue aliases . . . . . . . . . . 69

Data conversion . . . . . . . . . . . . . 70When a queue manager cannot convert messagesin built-in formats . . . . . . . . . . . 70File ccsid.tbl . . . . . . . . . . . . . 70Converting messages in user-defined formats . . 71Changing the queue manager CCSID . . . . . 71

Part 3. Using snap-ins to administerWebSphere MQ . . . . . . . . . . 73

Chapter 7. Administration using theWebSphere MQ Explorer . . . . . . . 75What you can do with the WebSphere MQ Explorer 75

Deciding whether to use the WebSphere MQExplorer . . . . . . . . . . . . . . 76

Setting up the WebSphere MQ Explorer . . . . . 76Prerequisite software . . . . . . . . . . 76Required definitions for administration . . . . 77Cluster membership . . . . . . . . . . 77Security . . . . . . . . . . . . . . 78Data conversion . . . . . . . . . . . . 78

Using the WebSphere MQ Explorer . . . . . . 79Showing and hiding queue managers andclusters . . . . . . . . . . . . . . . 79Saving and loading console files . . . . . . 79Switching off the automatic population facility 80

Chapter 8. Administration using theWebSphere MQ Services snap-in . . . 81What you can do with the WebSphere MQ Servicessnap-in . . . . . . . . . . . . . . . . 81Using the WebSphere MQ Services snap-in . . . . 82

Using the WebSphere MQ alert monitorapplication . . . . . . . . . . . . . 82WebSphere MQ Services snap-in recoveryfacilities . . . . . . . . . . . . . . 83

Security . . . . . . . . . . . . . . . 83Changing the user name associated withWebSphere MQ Services . . . . . . . . . 84Controlling access . . . . . . . . . . . 84Changing the password of the AMQMSRVN useraccount . . . . . . . . . . . . . . . 85

Part 4. Configuring WebSphere MQ 87

Chapter 9. Configuring WebSphere MQ 89Changing configuration information on Windowssystems. . . . . . . . . . . . . . . . 89

Migrating to the Windows Registry . . . . . 89Viewing configuration information . . . . . 90

Changing configuration information on UNIXsystems. . . . . . . . . . . . . . . . 90

Editing configuration files . . . . . . . . 90The WebSphere MQ configuration file, mqs.ini . 91

iv System Administration Guide

||

Queue manager configuration files, qm.ini . . . 92Attributes for changing WebSphere MQconfiguration information . . . . . . . . . 94

All queue managers . . . . . . . . . . 94Client exit path . . . . . . . . . . . . 95Default queue manager . . . . . . . . . 95Exit properties . . . . . . . . . . . . 95Log defaults for WebSphere MQ . . . . . . 96Advanced Configuration and Power Interface(ACPI) . . . . . . . . . . . . . . . 98API exits . . . . . . . . . . . . . . 99Queue managers . . . . . . . . . . . 99

Changing queue manager configurationinformation . . . . . . . . . . . . . . 100

Installable services. . . . . . . . . . . 100Queue manager logs . . . . . . . . . . 102Restricted mode . . . . . . . . . . . 104XA resource managers . . . . . . . . . 104Channels . . . . . . . . . . . . . . 105LU62, NETBIOS, TCP, and SPX . . . . . . 107Exit path . . . . . . . . . . . . . . 109User datagram protocol (UDP) . . . . . . 110The TRANSPORT stanza . . . . . . . . 111

Chapter 10. WebSphere MQ security 113Authority to administer WebSphere MQ . . . . 113

Managing the mqm group . . . . . . . . 114Authority to work with WebSphere MQ objects . . 114

When security checks are made . . . . . . 115How access control is implemented byWebSphere MQ. . . . . . . . . . . . 115Identifying the user ID . . . . . . . . . 116Alternate-user authority . . . . . . . . . 118Context authority . . . . . . . . . . . 118

Creating and managing groups . . . . . . . 119Windows NT . . . . . . . . . . . . 119HP-UX . . . . . . . . . . . . . . 120AIX . . . . . . . . . . . . . . . 120Solaris . . . . . . . . . . . . . . . 121Linux . . . . . . . . . . . . . . . 121

Using the OAM to control access to objects . . . 122Giving access to a WebSphere MQ object . . . 122Using OAM generic profiles . . . . . . . 123Displaying access settings . . . . . . . . 126Changing and revoking access to a WebSphereMQ object . . . . . . . . . . . . . 127Preventing security access checks. . . . . . 127

Channel security . . . . . . . . . . . . 127Protecting the definitions associated withchannels . . . . . . . . . . . . . . 128Transmission queues . . . . . . . . . . 129Channel exits . . . . . . . . . . . . 129Protecting channels with SSL . . . . . . . 129

How authorizations work . . . . . . . . . 131Authorizations for MQI calls . . . . . . . 131Authorizations for MQSC commands in escapePCFs . . . . . . . . . . . . . . . 133Authorizations for PCF commands . . . . . 134

Guidelines for Windows 2000 . . . . . . . . 135When you get a ’group not found’ error . . . 135

When you have problems with WebSphere MQand domain controllers . . . . . . . . . 136Applying security template files . . . . . . 137Nested groups . . . . . . . . . . . . 138

Chapter 11. Transactional support . . 139Introducing units of work . . . . . . . . . 139Scenario 1: Queue manager performs thecoordination. . . . . . . . . . . . . . 140

Database coordination . . . . . . . . . 140DB2 configuration . . . . . . . . . . . 147Oracle configuration . . . . . . . . . . 149Sybase configuration . . . . . . . . . . 151Multiple database configurations . . . . . . 152Security considerations . . . . . . . . . 153Administration tasks . . . . . . . . . . 154XA dynamic registration. . . . . . . . . 158

Scenario 2: Other software provides thecoordination. . . . . . . . . . . . . . 161

External syncpoint coordination . . . . . . 161Using CICS . . . . . . . . . . . . . 162Using the Microsoft Transaction Server (MTS) 165

Chapter 12. The WebSphere MQdead-letter queue handler . . . . . . 167Invoking the DLQ handler . . . . . . . . . 167

The sample DLQ handler, amqsdlq . . . . . 168The DLQ handler rules table . . . . . . . . 168

Control data. . . . . . . . . . . . . 168Rules (patterns and actions) . . . . . . . 169Rules table conventions . . . . . . . . . 172

How the rules table is processed . . . . . . . 174Ensuring that all DLQ messages are processed 175

An example DLQ handler rules table . . . . . 175

Chapter 13. Supporting the MicrosoftCluster Server (MSCS) . . . . . . . 179Introducing MSCS clusters . . . . . . . . . 179Setting up WebSphere MQ for MSCS clustering 181

Setup symmetry . . . . . . . . . . . 181MSCS security . . . . . . . . . . . . 181Using multiple queue managers with MSCS . . 182Cluster modes . . . . . . . . . . . . 182

Creating a queue manager for use with MSCS . . 183Creating a queue manager from a commandprompt . . . . . . . . . . . . . . 183Creating a queue manager using the WebSphereMQ Explorer . . . . . . . . . . . . 183

Moving a queue manager to MSCS storage . . . 184Putting a queue manager under MSCS control . . 185Removing a queue manager from MSCS control 187

Taking a queue manager offline from MSCS . . 187Returning a queue manager from MSCS storage 187

Hints and tips on using MSCS. . . . . . . . 188Verifying that MSCS is working . . . . . . 188Using the IBM MQSeries Service . . . . . . 188Manual startup . . . . . . . . . . . . 188MSCS and queue managers . . . . . . . 189Always use MSCS to manage clusters . . . . 190Working in Active/Active mode . . . . . . 190

Contents v

||

||

||

||

|||||||||||||||||||||

||

|||||||||||||||||||||||||||||||||||||||||||||||

PostOnlineCommand and PreOfflineCommand 190Using preferred nodes . . . . . . . . . 191Performance benchmarking. . . . . . . . 191

WebSphere MQ MSCS support utility programs 191

Part 5. Recovery and problemdetermination . . . . . . . . . . 193

Chapter 14. Recovery and restart . . . 195Making sure that messages are not lost (logging) 195

What logs look like . . . . . . . . . . 195Types of logging . . . . . . . . . . . 196

Using checkpointing to ensure complete recovery 198Checkpointing with long-running transactions 199

Calculating the size of the log . . . . . . . . 200Managing logs . . . . . . . . . . . . . 202

What happens when a disk gets full. . . . . 202Managing log files. . . . . . . . . . . 203

Using the log for recovery . . . . . . . . . 204Recovering from power loss or communicationsfailures . . . . . . . . . . . . . . 204Recovering damaged objects . . . . . . . 204

Protecting WebSphere MQ log files . . . . . . 206Backing up and restoring WebSphere MQ . . . . 206

Backing up WebSphere MQ . . . . . . . 206Restoring WebSphere MQ . . . . . . . . 207

Recovery scenarios . . . . . . . . . . . 208Disk drive failures. . . . . . . . . . . 208Damaged queue manager object . . . . . . 209Damaged single object . . . . . . . . . 209Automatic media recovery failure . . . . . 209

Dumping the contents of the log using thedmpmqlog command. . . . . . . . . . . 209

Chapter 15. Problem determination 215Preliminary checks . . . . . . . . . . . 215

Has WebSphere MQ run successfully before? 215Are there any error messages?. . . . . . . 216Are there any return codes explaining theproblem? . . . . . . . . . . . . . . 216Can you reproduce the problem? . . . . . . 216Have any changes been made since the lastsuccessful run? . . . . . . . . . . . . 216Has the application run successfully before? . . 216Problems with commands . . . . . . . . 218Does the problem affect specific parts of thenetwork? . . . . . . . . . . . . . . 218Does the problem occur at specific times of theday? . . . . . . . . . . . . . . . 218Is the problem intermittent? . . . . . . . 218Have you applied any service updates? . . . 218

Looking at problems in more detail . . . . . . 219Have you obtained incorrect output? . . . . 219Have you failed to receive a response from aPCF command? . . . . . . . . . . . 221Are some of your queues failing?. . . . . . 222Does the problem affect only remote queues? 223Is your application or system running slowly? 223

Application design considerations . . . . . . 224Effect of message length . . . . . . . . . 224

Effect of message persistence . . . . . . . 224Searching for a particular message . . . . . 225Queues that contain messages of differentlengths . . . . . . . . . . . . . . 225Frequency of syncpoints . . . . . . . . . 225Use of the MQPUT1 call. . . . . . . . . 225Number of threads in use . . . . . . . . 225

Error logs . . . . . . . . . . . . . . 225Log files . . . . . . . . . . . . . . 226Ignoring error codes under Windows systems 227Operator messages . . . . . . . . . . 227

Dead-letter queues . . . . . . . . . . . 227Configuration files and problem determination . . 228Tracing . . . . . . . . . . . . . . . 228

Tracing WebSphere MQ for Windows . . . . 228Tracing WebSphere MQ for AIX . . . . . . 229Tracing WebSphere MQ for HP-UX, WebSphereMQ for Solaris, and WebSphere MQ for Linuxfor Intel and Linux for zSeries . . . . . . . 232Tracing Secure Sockets Layer (SSL) on UNIXsystems . . . . . . . . . . . . . . 236

First-failure support technology (FFST) . . . . . 236FFST: WebSphere MQ for Windows . . . . . 236FFST: WebSphere MQ for UNIX systems . . . 237

Problem determination with clients . . . . . . 239Terminating clients . . . . . . . . . . 239Error messages with clients. . . . . . . . 239

Part 6. WebSphere MQ controlcommands . . . . . . . . . . . . 241

Chapter 16. How to use WebSphereMQ control commands . . . . . . . 243Names of WebSphere MQ objects. . . . . . . 243How to read syntax diagrams . . . . . . . . 244Example syntax diagram . . . . . . . . . 245Syntax help . . . . . . . . . . . . . . 246

Examples . . . . . . . . . . . . . . 246

Chapter 17. The control commands 247amqmcert (manage certificates) . . . . . . . 249amqmdain (WebSphere MQ services control) . . . 253crtmqcvx (data conversion) . . . . . . . . . 257crtmqm (create queue manager) . . . . . . . 259dltmqm (delete queue manager) . . . . . . . 263dmpmqaut (dump authority) . . . . . . . . 265dmpmqlog (dump log) . . . . . . . . . . 268dspmq (display queue managers). . . . . . . 270dspmqaut (display authority) . . . . . . . . 271dspmqcap (display license units) . . . . . . . 275dspmqcsv (display command server) . . . . . 276dspmqfls (display files) . . . . . . . . . . 277dspmqtrc (display formatted trace output). . . . 279dspmqtrn (Display transactions) . . . . . . . 280endmqcsv (end command server). . . . . . . 281endmqlsr (end listener) . . . . . . . . . . 282endmqm (end queue manager) . . . . . . . 283endmqtrc (end trace) . . . . . . . . . . . 285rcdmqimg (record media image) . . . . . . . 286

vi System Administration Guide

||||||||

|||

||

||

||

rcrmqobj (recreate object) . . . . . . . . . 288rsvmqtrn (resolve transactions) . . . . . . . 290runmqchi (run channel initiator) . . . . . . . 292runmqchl (run channel) . . . . . . . . . . 293runmqdlq (run dead-letter queue handler). . . . 294runmqlsr (run listener) . . . . . . . . . . 295runmqsc (run MQSC commands) . . . . . . . 297runmqtmc (start client trigger monitor) . . . . . 300runmqtrm (start trigger monitor) . . . . . . . 301setmqaut (set or reset authority) . . . . . . . 302setmqcap (set license units) . . . . . . . . . 308setmqcrl (set certificate revocation list (CRL) LDAPserver definitions) . . . . . . . . . . . . 309setmqscp (set service connection points) . . . . 311strmqcsv (start command server) . . . . . . . 313strmqm (start queue manager). . . . . . . . 314strmqtrc (Start trace) . . . . . . . . . . . 316

Chapter 18. Using the IKEYCMDinterface to manage keys andcertificates on UNIX systems . . . . 319Setting up to use IKEYCMD . . . . . . . . 319IKEYCMD syntax . . . . . . . . . . . . 320IKEYCMD commands . . . . . . . . . . 320

Commands for a CMS key database only . . . 320Commands for CMS or PKCS #12 key databases 321Commands for cryptographic device operations 323

IKEYCMD options. . . . . . . . . . . . 324

Part 7. WebSphere MQ installableservices and the API exit . . . . . 327

Chapter 19. Installable services andcomponents . . . . . . . . . . . . 333Why installable services? . . . . . . . . . 333Functions and components . . . . . . . . . 334

Entry-points . . . . . . . . . . . . . 335Return codes . . . . . . . . . . . . 335Component data . . . . . . . . . . . 335

Initialization. . . . . . . . . . . . . . 336Primary initialization . . . . . . . . . . 336Secondary initialization . . . . . . . . . 336Primary termination . . . . . . . . . . 336Secondary termination . . . . . . . . . 336

Configuring services and components . . . . . 336Service stanza format. . . . . . . . . . 337Service stanza format for Windows systems . . 337Service component stanza format . . . . . . 337

Creating your own service component . . . . . 338Using multiple service components . . . . . . 338

Example of using multiple components. . . . 339Omitting entry points when using multiplecomponents . . . . . . . . . . . . . 339Example of entry points used with multiplecomponents . . . . . . . . . . . . . 339

Chapter 20. Authorization service. . . 341Object authority manager (OAM). . . . . . . 341

Defining the service to the operating system . . 341

Refreshing the OAM after changing a user’sauthorization . . . . . . . . . . . . 341Migrating from MQSeries . . . . . . . . 342

Authorization service on UNIX systems . . . . 342Configuring authorization service stanzas: UNIXsystems . . . . . . . . . . . . . . 343

Authorization service on Windows systems . . . 343Configuring authorization service stanzas:Windows systems . . . . . . . . . . . 343

Authorization service interface . . . . . . . 344

Chapter 21. Name service . . . . . . 347How the name service works . . . . . . . . 347

Name service interface . . . . . . . . . 348Using DCE to share queues on different queuemanagers. . . . . . . . . . . . . . . 349

Configuration tasks for shared queues . . . . 349DCE configuration . . . . . . . . . . . 350

Chapter 22. Installable servicesinterface reference information. . . . 353How the functions are shown . . . . . . . . 354

Parameters and data types . . . . . . . . 354MQZEP – Add component entry point . . . . . 355

Syntax. . . . . . . . . . . . . . . 355Parameters . . . . . . . . . . . . . 355C invocation. . . . . . . . . . . . . 356

MQHCONFIG – Configuration handle . . . . . 356C declaration . . . . . . . . . . . . 356

PMQFUNC – Pointer to function . . . . . . . 356C declaration . . . . . . . . . . . . 356

MQZ_CHECK_AUTHORITY – Check authority 357Syntax. . . . . . . . . . . . . . . 357Parameters . . . . . . . . . . . . . 357C invocation. . . . . . . . . . . . . 361

MQZ_CHECK_AUTHORITY_2 – Check authority(extended) . . . . . . . . . . . . . . 362


MQZ_COPY_ALL_AUTHORITY – Copy allauthority . . . . . . . . . . . . . . . 367


MQZ_DELETE_AUTHORITY – Delete authority 370Syntax. . . . . . . . . . . . . . . 370Parameters . . . . . . . . . . . . . 370C invocation. . . . . . . . . . . . . 371

MQZ_ENUMERATE_AUTHORITY_DATA –Enumerate authority data . . . . . . . . . 373


MQZ_GET_AUTHORITY – Get authority . . . . 376Syntax. . . . . . . . . . . . . . . 376Parameters . . . . . . . . . . . . . 376C invocation. . . . . . . . . . . . . 378

MQZ_GET_AUTHORITY_2 – Get authority(extended) . . . . . . . . . . . . . . 379

Contents vii

|||||

||||||||||||||||||

|||||

|||||||||


MQZ_GET_EXPLICIT_AUTHORITY – Get explicitauthority . . . . . . . . . . . . . . . 382


MQZ_GET_EXPLICIT_AUTHORITY_2 – Getexplicit authority (extended) . . . . . . . . 385


MQZ_INIT_AUTHORITY – Initialize authorizationservice. . . . . . . . . . . . . . . . 388


MQZ_REFRESH_CACHE – Refresh allauthorizations . . . . . . . . . . . . . 391


MQZ_SET_AUTHORITY – Set authority . . . . 393Syntax. . . . . . . . . . . . . . . 393Parameters . . . . . . . . . . . . . 393C invocation. . . . . . . . . . . . . 395

MQZ_SET_AUTHORITY_2 – Set authority(extended) . . . . . . . . . . . . . . 396


MQZ_TERM_AUTHORITY – Terminateauthorization service . . . . . . . . . . . 399


MQZAD – Authority data . . . . . . . . . 401Fields . . . . . . . . . . . . . . . 401C declaration . . . . . . . . . . . . 403

MQZED – Entity descriptor . . . . . . . . 404Fields . . . . . . . . . . . . . . . 404C declaration . . . . . . . . . . . . 405

MQZ_DELETE_NAME – Delete name . . . . . 406Syntax. . . . . . . . . . . . . . . 406Parameters . . . . . . . . . . . . . 406C invocation. . . . . . . . . . . . . 407

MQZ_INIT_NAME – Initialize name service . . . 408Syntax. . . . . . . . . . . . . . . 408Parameters . . . . . . . . . . . . . 408C invocation. . . . . . . . . . . . . 409

MQZ_INSERT_NAME – Insert name . . . . . 411Syntax . . . . . . . . . . . . . . . 411Parameters . . . . . . . . . . . . . 411C invocation. . . . . . . . . . . . . 412

MQZ_LOOKUP_NAME – Lookup name . . . . 413Syntax. . . . . . . . . . . . . . . 413Parameters . . . . . . . . . . . . . 413C invocation. . . . . . . . . . . . . 414

MQZ_TERM_NAME – Terminate name service . . 416Syntax. . . . . . . . . . . . . . . 416

Parameters . . . . . . . . . . . . . 416C invocation. . . . . . . . . . . . . 417

Chapter 23. API exits . . . . . . . . 419Why use API exits. . . . . . . . . . . . 419How you use API exits . . . . . . . . . . 419

How to configure WebSphere MQ for API exits 419How to write an API exit . . . . . . . . 420

What happens when an API exit runs? . . . . . 421Configuring API exits . . . . . . . . . . 421

Configuring API exits on UNIX systems . . . 421Configuring API exits on Windows systems . . 423

Chapter 24. API exit referenceinformation . . . . . . . . . . . . 425General usage notes . . . . . . . . . . . 425MQACH – API exit chain header . . . . . . . 427

Fields . . . . . . . . . . . . . . . 427C declaration . . . . . . . . . . . . 429

MQAXC – API exit context . . . . . . . . . 430Fields . . . . . . . . . . . . . . . 430C declaration . . . . . . . . . . . . 433

MQAXP – API exit parameter . . . . . . . . 434Fields . . . . . . . . . . . . . . . 434C declaration . . . . . . . . . . . . 441

MQXEP – Register entry point. . . . . . . . 442Syntax. . . . . . . . . . . . . . . 442Parameters . . . . . . . . . . . . . 442C invocation. . . . . . . . . . . . . 444

MQ_BACK_EXIT – Back out changes . . . . . 445Syntax. . . . . . . . . . . . . . . 445Parameters . . . . . . . . . . . . . 445C invocation. . . . . . . . . . . . . 445

MQ_BEGIN_EXIT – Begin unit of work . . . . 446Syntax. . . . . . . . . . . . . . . 446Parameters . . . . . . . . . . . . . 446C invocation. . . . . . . . . . . . . 446

MQ_CLOSE_EXIT – Close object . . . . . . . 447Syntax. . . . . . . . . . . . . . . 447Parameters . . . . . . . . . . . . . 447C invocation. . . . . . . . . . . . . 447

MQ_CMIT_EXIT – Commit changes . . . . . . 448Syntax. . . . . . . . . . . . . . . 448Parameters . . . . . . . . . . . . . 448C invocation. . . . . . . . . . . . . 448

MQ_CONNX_EXIT – Connect queue manager(extended) . . . . . . . . . . . . . . 449

Syntax. . . . . . . . . . . . . . . 449Parameters . . . . . . . . . . . . . 449Usage notes . . . . . . . . . . . . . 449C invocation. . . . . . . . . . . . . 450

MQ_DISC_EXIT – Disconnect queue manager . . 451Syntax. . . . . . . . . . . . . . . 451Parameters . . . . . . . . . . . . . 451C invocation. . . . . . . . . . . . . 451

MQ_GET_EXIT – Get message . . . . . . . 452Syntax. . . . . . . . . . . . . . . 452Parameters . . . . . . . . . . . . . 452Usage notes . . . . . . . . . . . . . 452C invocation. . . . . . . . . . . . . 453

viii System Administration Guide

|||||||||

||||||

||||||||||||||||||

||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

MQ_INIT_EXIT – Initialize exit environment . . . 454Syntax. . . . . . . . . . . . . . . 454Parameters . . . . . . . . . . . . . 454Usage notes . . . . . . . . . . . . . 454C invocation. . . . . . . . . . . . . 454

MQ_INQ_EXIT – Inquire object attributes . . . . 455Syntax. . . . . . . . . . . . . . . 455Parameters . . . . . . . . . . . . . 455C invocation. . . . . . . . . . . . . 455

MQ_OPEN_EXIT – Open object . . . . . . . 457Syntax. . . . . . . . . . . . . . . 457Parameters . . . . . . . . . . . . . 457C invocation. . . . . . . . . . . . . 457

MQ_PUT_EXIT – Put message. . . . . . . . 458Syntax. . . . . . . . . . . . . . . 458Parameters . . . . . . . . . . . . . 458Usage notes . . . . . . . . . . . . . 458C invocation. . . . . . . . . . . . . 458

MQ_PUT1_EXIT – Put one message . . . . . . 460Syntax. . . . . . . . . . . . . . . 460Parameters . . . . . . . . . . . . . 460C invocation. . . . . . . . . . . . . 460

MQ_SET_EXIT – Set object attributes . . . . . 462Syntax. . . . . . . . . . . . . . . 462Parameters . . . . . . . . . . . . . 462C invocation. . . . . . . . . . . . . 462

MQ_TERM_EXIT – Terminate exit environment 464Syntax. . . . . . . . . . . . . . . 464Parameters . . . . . . . . . . . . . 464Usage notes . . . . . . . . . . . . . 464C invocation. . . . . . . . . . . . . 464

Chapter 25. WebSphere MQ constants 465List of constants . . . . . . . . . . . . 465

MQ_* (Lengths of character string and bytefields) . . . . . . . . . . . . . . . 465MQACH_* (API exit chain header length) . . . 465MQACH_* (API exit chain header structureidentifier). . . . . . . . . . . . . . 465MQACH_* (API exit chain header version) . . 466MQAXC_* (API exit context structure identifier) 466MQAXC_* (API exit context version) . . . . 466MQAXP_* (API exit parameter structureidentifier). . . . . . . . . . . . . . 466MQAXP_* (API exit parameter version) . . . 466MQCC_* (Completion code) . . . . . . . 466MQFB_* (Feedback) . . . . . . . . . . 466MQOT_* (Object type) . . . . . . . . . 467MQRC_* (Reason code) . . . . . . . . . 467MQSID_* (Security identifier) . . . . . . . 467MQXACT_* (API exit caller type). . . . . . 467MQXCC_* (Exit response) . . . . . . . . 468MQXE_* (API exit environment) . . . . . . 468MQXF_* (API exit function identifier) . . . . 468MQXPDA_* (API exit problem determinationarea) . . . . . . . . . . . . . . . 468MQXR_* (Exit reason) . . . . . . . . . 468MQXR2_* (Secondary exit response) . . . . . 469MQXT_* (Exit identifier). . . . . . . . . 469MQXUA_* (Exit user area) . . . . . . . . 469MQZAD_* (Authority data structure identifier) 469

MQZAD_* (Authority data version) . . . . . 469MQZAET_* (Authority service entity type) . . 469MQZAO_* (Authority service authorizationtype) . . . . . . . . . . . . . . . 469MQZAS_* (Authority service version) . . . . 470MQZCI_* (Continuation indicator) . . . . . 470MQZED_* (Entity descriptor structure identifier) 470MQZED_* (Entity descriptor version) . . . . 470MQZID_* (Function identifier, all services) . . 470MQZID_* (Function identifier, authority service) 471MQZID_* (Function identifier, name service) 471MQZID_* (Function identifier, userid service) 471MQZIO_* (Initialization options) . . . . . . 471MQZNS_* (Name service version) . . . . . 471MQZSE_* (Start-enumeration indicator) . . . 471MQZTO_* (Termination options) . . . . . . 471MQZUS_* (Userid service version) . . . . . 472

Part 8. Appendixes . . . . . . . . 473

Appendix A. System and defaultobjects . . . . . . . . . . . . . . 475Windows default configuration objects . . . . . 476

Appendix B. Directory structure(Windows systems) . . . . . . . . . 479

Appendix C. Directory structure (UNIXsystems) . . . . . . . . . . . . . 481

Appendix D. Stopping and removingqueue managers manually. . . . . . 485Stopping a queue manager manually . . . . . 485

Stopping queue managers in WebSphere MQ forWindows . . . . . . . . . . . . . . 485Stopping queue managers in WebSphere MQ forUNIX systems . . . . . . . . . . . . 485

Removing queue managers manually . . . . . 486Removing queue managers in WebSphere MQfor Windows . . . . . . . . . . . . 486Removing queue managers in WebSphere MQfor UNIX systems . . . . . . . . . . . 487

Appendix E. Comparing commandsets . . . . . . . . . . . . . . . 489Commands for queue manager administration . . 489Commands for command server administration 489Commands for queue administration . . . . . 490Commands for process administration . . . . . 490Commands for channel administration . . . . . 490Other control commands . . . . . . . . . 491

Appendix F. Using the User DatagramProtocol . . . . . . . . . . . . . 493Configuring WebSphere MQ for UDP . . . . . 493

Examples of MQSC command files . . . . . 493The retry exit . . . . . . . . . . . . . 495Hints and tips . . . . . . . . . . . . . 497

Contents ix

||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

||||||||||||||||

||

|||||||

||

||

||

Appendix G. WebSphere MQ and UNIXSystem V IPC resources. . . . . . . 499Clearing WebSphere MQ shared memory resources 499Shared memory on AIX and using EXTSHM . . . 499

Appendix H. Example of a log file . . 501

Appendix I. Notices . . . . . . . . . 515

Trademarks . . . . . . . . . . . . . . 516

Index . . . . . . . . . . . . . . . 519

Sending your comments to IBM . . . 535

x System Administration Guide

|||||||

Figures

1. Queues, messages, and applications . . . . 332. Extract from an MQSC command file . . . . 373. Extract from an MQSC command report file 384. Example script for running MQSC commands

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

command . . . . . . . . . . . . . 426. Typical results from queue browser . . . . 477. Remote administration using MQSC

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

administration . . . . . . . . . . . 629. Example of a WebSphere MQ configuration file

for UNIX systems . . . . . . . . . . 9210. Example queue manager configuration file for

WebSphere MQ for UNIX systems . . . . . 9311. Sample XAResourceManager entry for DB2

on UNIX platforms . . . . . . . . . 14812. Sample XAResourceManager entry for Oracle

on UNIX platforms . . . . . . . . . 15013. Example contents of

$SYBASE/$SYBASE_OCS/xa_config . . . . 15114. Sample XAResourceManager entry for Sybase

on UNIX platforms . . . . . . . . . 15215. Sample XAResourceManager entries for

multiple DB2 databases . . . . . . . . 15316. Sample XAResourceManager entries for a

DB2 and Oracle database . . . . . . . 153

17. Sample dspmqtrn output . . . . . . . 15618. Commented- out XAResourceManager stanza

on UNIX systems . . . . . . . . . . 15819. Two-computer MSCS cluster . . . . . . 18020. Checkpointing . . . . . . . . . . . 19921. Checkpointing with a long-running

transaction . . . . . . . . . . . . 20022. Sample WebSphere MQ for Windows trace 22923. Sample WebSphere MQ for AIX trace 23224. Sample WebSphere MQ for HP-UX trace 23325. Sample WebSphere MQ for Solaris trace 23426. Sample WebSphere MQ for Linux for Intel

and Linux for zSeries trace . . . . . . . 23527. Sample WebSphere MQ for Windows First

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

systems . . . . . . . . . . . . . 23829. Understanding services, components, and

entry points . . . . . . . . . . . . 33530. UNIX authorization service stanzas in qm.ini 34331. Name service stanzas in qm.ini (for UNIX

systems) . . . . . . . . . . . . . 34932. Default directory structure (UNIX systems)

after a queue manager has been started . . . 48233. The supplied file EARTH.TST . . . . . . 49434. The supplied file MOON.TST . . . . . . 49535. Example dmpmqlog output . . . . . . . 501

© Copyright IBM Corp. 1994, 2002 xi

||||||||||||||||||

|||||||

|||||||||||||||||

xii System Administration Guide

Tables

1. Categories of control commands . . . . . 232. Platforms and command levels . . . . . . 773. User rights granted for MUSR_MQADMIN 854. List of possible ISO CCSIDs . . . . . . . 955. Default outstanding connection requests

(TCP) . . . . . . . . . . . . . . 1086. Default outstanding connection requests

(SPX) . . . . . . . . . . . . . . 1097. Security authorization needed for MQCONN

calls. . . . . . . . . . . . . . . 1328. Security authorization needed for MQOPEN

calls. . . . . . . . . . . . . . . 1329. Security authorization needed for MQPUT1

calls. . . . . . . . . . . . . . . 13210. Security authorization needed for MQCLOSE

calls. . . . . . . . . . . . . . . 13211. MQSC commands and security authorization

needed. . . . . . . . . . . . . . 13412. PCF commands and security authorization

needed. . . . . . . . . . . . . . 13413. What happens when a database server

crashes. . . . . . . . . . . . . . 14114. What happens when an application program

crashes. . . . . . . . . . . . . . 14215. XA switch function pointers. . . . . . . 14316. Summary of XA function calls . . . . . . 16017. CICS task termination exits . . . . . . . 16418. Log overhead sizes (all values are

approximate). . . . . . . . . . . . 20119. MQS_TRACE_OPTIONS settings . . . . . 23020. How to read syntax diagrams . . . . . . 24421. Security authorities from the dspmqaut

command . . . . . . . . . . . . . 272

22. Specifying authorities for different objecttypes . . . . . . . . . . . . . . 305

23. Options that can be used with the IKEYCMDinterface . . . . . . . . . . . . . 324

24. Installable service components summary 33325. Example of entry-points for an installable

service . . . . . . . . . . . . . . 33926. Installable services functions . . . . . . 35327. Fields in MQZAD . . . . . . . . . . 40128. Fields in MQZED . . . . . . . . . . 40429. Fields in MQACH . . . . . . . . . . 42730. Fields in MQAXC . . . . . . . . . . 43031. Fields in MQAXP . . . . . . . . . . 43432. System and default objects: queues . . . . 47533. System and default objects: channels 47634. System and default objects: namelists 47635. System and default objects: processes 47636. Objects created by the Windows default

configuration application. . . . . . . . 47737. WebSphere MQ for Windows directory

structure . . . . . . . . . . . . . 47938. Content of a \queue-manager-name\ folder

for WebSphere MQ for Windows . . . . . 48039. Default content of a /var/mqm/qmgrs/qmname/

directory on UNIX systems . . . . . . . 48340. Commands for queue manager

administration . . . . . . . . . . . 48941. Commands for command server

administration . . . . . . . . . . . 48942. Commands for queue administration 49043. Commands for process administration 49044. Commands for channel administration 49045. Other control commands. . . . . . . . 491

© Copyright IBM Corp. 1994, 2002 xiii

||||||||||||||||

|||

||||||

||

||||||

xiv System Administration Guide

About this book

This book applies to the following WebSphere® MQ Version 5.3 products:v WebSphere MQ for AIX®, V5.3v WebSphere MQ for HP-UX, V5.3v WebSphere MQ for Linux for Intel and Linux for zSeries, V5.3v WebSphere MQ for Solaris, V5.3v WebSphere MQ for Windows®, V5.3Other WebSphere MQ Version 5.3 products (on iSeries™ and zSeries™) have theirown System Administration Guides. See WebSphere MQ Bibliography and Glossary formore information.

These products provide application programming services that enable applicationprograms to communicate with each other using message queues. This form ofcommunication is referred to as commercial messaging. The applications involvedcan exist on different nodes on a wide variety of machine and operating systemtypes. They use a common application programming interface, called the MessageQueue Interface or MQI, so that programs developed on one platform can readilybe transferred to another.

This book describes the system administration aspects of the WebSphere MQVersion 5.3 products, and the services they provide to support commercialmessaging. This includes managing the queues that applications use to receivetheir messages, and ensuring that applications have access to the queues that theyrequire.

Installation of WebSphere MQ is described in the following:v WebSphere MQ for AIX, V5.3 Quick Beginningsv WebSphere MQ for HP-UX, V5.3 Quick Beginningsv WebSphere MQ for Linux for Intel and Linux for zSeries, V5.3 Quick Beginningsv WebSphere MQ for Solaris, V5.3 Quick Beginningsv WebSphere MQ for Windows, V5.3 Quick Beginnings

Post-installation configuration of a distributed queuing network is described inWebSphere MQ Intercommunication.

Who this book is forThis book is for system administrators and system programmers who manage theconfiguration and administration tasks for WebSphere MQ. It is also useful toapplication programmers who must have some understanding of WebSphere MQadministration tasks.

What you need to know to understand this bookTo use this book, you need a good understanding of the operating systemsdescribed here and of the utilities associated with them. You do not need to haveworked with message queuing products before, but you should understand thebasic concepts of message queuing.

© Copyright IBM Corp. 1994, 2002 xv

|||

Terms used in this bookIn this book, the term Version 5.3 products means:

WebSphere MQ for AIX, V5.3WebSphere MQ for HP-UX, V5.3WebSphere MQ for Linux for Intel and Linux for zSeries, V5.3WebSphere MQ for Solaris, V5.3WebSphere MQ for Windows, V5.3

The term WebSphere MQ for UNIX® systems means:WebSphere MQ for AIX, V5.3WebSphere MQ for HP-UX, V5.3WebSphere MQ for Linux for Intel and Linux for zSeries, V5.3WebSphere MQ for Solaris, V5.3

We also use the term UNIX systems as a general terms for the UNIX platforms.

The term WebSphere MQ for Windows systems means WebSphere MQ runningon the Windows platforms:

Windows NT®

Windows 2000Windows XP

We also use the term Windows systems or just Windows as general terms forthese Windows platforms.

Using WebSphere MQ for WindowsExamples in this book relevant to WebSphere MQ for Windows can use NewTechnology file system (NTFS), high performance file system (HPFS), or fileallocation table (FAT) file names.

The examples are valid for all file-naming systems, the name being transformed ifnecessary when the FAT system is in use. Name transformation is described in“Understanding WebSphere MQ file names” on page 18.

Using WebSphere MQ for UNIX systemsWhen you use WebSphere MQ on UNIX systems, MQCONN sets up its ownsignal handler for the signals SIGSEGV and SIGBUS. User handlers for thesesignals are restored after every MQI call.

The remaining signals are handled differently.SIGINTSIGQUITSIGFPESIGTERMSIGHUP

If any handler for this group of signals receives an interrupt within an MQI call,the application handler must exit the application.

On non-threaded applications, WebSphere MQ uses the UNIX interval timerITIMER_REAL to generate SIGALRM signals. Any previous SIGALRM handler andtimer interval is saved on entry to MQI and restored on exit. Any timer interval setis therefore frozen while within MQI.

About this book

xvi System Administration Guide

|

||||||

|||||

|

|||||

||

The calls MQCONN and MQCONNXReferences in this book to the call MQCONN (connect queue manager) can bereplaced by references to the call MQCONNX (connect queue manager extended);MQCONNX requires an additional parameter. For more information about thesecalls, see the WebSphere MQ Application Programming Reference.

About this book

About this book xvii

xviii System Administration Guide

What’s new for this release

This section describes the new function, of interest to system administrators, thathas been added for this release of WebSphere MQ.

A change of nameWith the release of Version 5 Release 3, we have rebranded MQSeries® to show itsclose relationship with the IBM® WebSphere brand of products that enablee-business. Throughout this book, and the rest of the library, MQSeries is nowknown by its new name, WebSphere MQ.

Using installable servicesWebSphere MQ installable services:v Provide you with the flexibility of choosing whether to use components

provided by WebSphere MQ products, or replace or augment them with others.v Allow vendors to participate, by providing components that might use new

technologies, without making internal changes to WebSphere MQ products.v Allow WebSphere MQ to exploit new technologies faster and cheaper, and so

provide products earlier and at lower prices.

Previously, information on installable services was in MQSeries ProgrammableSystem Management We have now moved them into this book, in Part 7,“WebSphere MQ installable services and the API exit” on page 327.

MQSeries Programmable System Management has been completely removed. Otherinformation that used to be in it has moved into the following books:v Event monitoring is now in WebSphere MQ Event Monitoring.v Programmable command formats are now in WebSphere MQ Programmable

Command Formats and Administration Interface.

Using API exitsAPI exits let you write code that changes the behavior of WebSphere MQ API calls,such as MQPUT and MQGET, and then insert that code immediately before orimmediately after those calls. The insertion is automatic; the queue manager drivesthe exit code at the registered points.

In Chapter 23, “API exits” on page 419, this book explains why you might want touse API exits, describes what administration tasks are involved in enabling them,and gives a brief introduction to writing API exits. For more detailed informationabout writing API exits, aimed at application programmers, see the WebSphere MQApplication Programming Guide.

Using the Microsoft® Cluster Server (MSCS)The Microsoft Cluster Server (MSCS) enables you to connect servers into a cluster,giving higher availability of data and applications, and making it easier to managethe system. MSCS can automatically detect and recover from server or applicationfailures.

© Copyright IBM Corp. 1994, 2002 xix

|

|

||

||

||||

||

|

||

||

||

|||

||

|

||

||

||||

|||||

||

||||

Chapter 13, “Supporting the Microsoft Cluster Server (MSCS)” on page 179provides detailed information on how to set up WebSphere MQ to take advantageof MSCS support.

Using the Microsoft Transaction Server (MTS)WebSphere MQ support for Microsoft Transaction Server (MTS) enables MTSbusiness objects to use WebSphere MQ. MTS helps users run business logicapplications in a typical middle tier server. MTS divides work up into activities,which are (typically) short independent chunks of business logic, such as transferfunds from account A to account B.

“Using the Microsoft Transaction Server (MTS)” on page 165 provides informationon how to set up WebSphere MQ to take advantage of MTS support.

Secure Sockets Layer (SSL) supportThe Secure Sockets Layer (SSL) protocol provides channel security, with protectionagainst eavesdropping, tampering, and impersonation.

SSL is an industry-standard protocol that provides a data security layer betweenapplication protocols and the communications layer, usually TCP/IP. The SSLprotocol was designed by the Netscape Development Corporation, and is widelydeployed in both Internet applications and intranet applications. SSL definesmethods for data encryption, server authentication, message integrity, and clientauthentication for a TCP/IP connection.

SSL uses public key and symmetric techniques to provide the following securityservices:

Message privacySSL uses a combination of public-key and symmetric-key encryption toensure message privacy. Before exchanging messages, an SSL server and anSSL client perform an electronic handshake during which they agree to usea session key and an encryption algorithm. All messages sent between theclient and the server are then encrypted. Encryption ensures that themessage remains private even if eavesdroppers intercept it.

Message integritySSL uses the combination of a shared secret key and message hashfunctions. This ensures that nothing changes the content of a message as ittravels between client and server.

Mutual authenticationDuring the initial SSL handshake, the server uses a public-key certificate toconvince the client of the server’s identity. Optionally, the client can alsoexchange a public-key certificate with the server to ensure the authenticityof the client.

This book describes changes to the setmqaut, dspmqaut, dmpmqaut, rcrmqobj,rcdmqimg, and dspmqfls commands to support the SSL authenticationinformation object. It also describes the amqmcert command for managingcertificates on Windows systems, and the IKEYCMD interface for managing keysand certificates on UNIX systems.

“Protecting channels with SSL” on page 129 introduces the main features of SSL.Support for SSL introduces several new MQSC commands and queue manager

xx System Administration Guide

|||

||

|||||

||

||

||

||||||

||

|||||||

||||

|||||

|||||

||

attributes. See the WebSphere MQ Script (MQSC) Command Reference for details ofthese. For a comprehensive review of security in WebSphere MQ includinginformation on SSL, see WebSphere MQ Security.

Dumping authoritiesA new command, dmpmqaut command lets you dump the current authorizationsto a specified object. We describe it in “dmpmqaut (dump authority)” on page 265.

OAM generic profilesOAM generic profiles enable you to set the authority a user has to many objects atonce, rather than having to issue separate setmqaut commands against eachindividual object when it is created. “Using OAM generic profiles” on page 123provides detailed information on using generic profiles.

Installable servicesThe installable services information, previously available in the ProgrammableSystem Management book, is now included in this book, starting at Part 7,“WebSphere MQ installable services and the API exit” on page 327.

Setting your license unitsTo fulfil the conditions of your license agreement with IBM, you must havepurchased sufficient license units for the number of processors on which you arerunning WebSphere MQ. The installation dialog checks for this when you installWebSphere MQ

This book describes commands you can use to set (setmqcap) and display(dspmqcap) your license units (see “setmqcap (set license units)” on page 308 and“dspmqcap (display license units)” on page 275).

What’s new for this release xxi

|||

||

||

||

||||

||

|||

||

||||

|||

xxii System Administration Guide

Part 1. Introduction

Chapter 1. Introduction to WebSphere MQ . . . 3WebSphere MQ and message queuing . . . . . . 3

Time-independent applications . . . . . . . 3Message-driven processing . . . . . . . . 3

Messages and queues . . . . . . . . . . . 3What is a message? . . . . . . . . . . . 4

Message lengths . . . . . . . . . . . 4How do applications send and receivemessages? . . . . . . . . . . . . . 4

What is a queue? . . . . . . . . . . . . 4Predefined queues and dynamic queues . . . 5Retrieving messages from queues . . . . . 5

Objects . . . . . . . . . . . . . . . . 5Object names . . . . . . . . . . . . . 6Managing objects . . . . . . . . . . . . 6Object attributes . . . . . . . . . . . . 6WebSphere MQ queues . . . . . . . . . . 7

Defining queues . . . . . . . . . . . 7Queues used by WebSphere MQ. . . . . . 8

WebSphere MQ queue managers . . . . . . 9Process definitions . . . . . . . . . . . 10Channels . . . . . . . . . . . . . . 10Clusters . . . . . . . . . . . . . . 10Namelists . . . . . . . . . . . . . . 10Authentication information objects. . . . . . 11System default objects . . . . . . . . . . 11

Clients and servers . . . . . . . . . . . . 11WebSphere MQ applications in a client-serverenvironment . . . . . . . . . . . . . 12

Extending queue manager facilities . . . . . . 12User exits . . . . . . . . . . . . . . 12Installable services . . . . . . . . . . . 12

Security . . . . . . . . . . . . . . . 13Object Authority Manager (OAM) facility . . . 13DCE security . . . . . . . . . . . . . 13Channel security using SSL . . . . . . . . 13

Transactional support . . . . . . . . . . . 13

Chapter 2. An introduction to WebSphere MQadministration . . . . . . . . . . . . . 15Local and remote administration . . . . . . . 15Performing administration tasks using commands 15

Control commands . . . . . . . . . . . 16WebSphere MQ Script (MQSC) commands . . . 16PCF commands . . . . . . . . . . . . 16

Administration on WebSphere MQ for Windows . . 16Using the WebSphere MQ Explorer . . . . . 17Using the WebSphere MQ Services snap-in . . . 17Using the Windows Default Configurationapplication . . . . . . . . . . . . . 17Using the Microsoft Cluster Server (MSCS) . . . 18

Understanding WebSphere MQ file names . . . . 18Queue manager name transformation. . . . . 18Object name transformation . . . . . . . . 19

© Copyright IBM Corp. 1994, 2002 1

||

||

||

2 System Administration Guide

Chapter 1. Introduction to WebSphere MQ

This chapter introduces the WebSphere MQ Version 5.3 products from anadministrator’s perspective, and describes the basic concepts of WebSphere MQand messaging. It contains these sections:v “WebSphere MQ and message queuing”v “Messages and queues”v “Objects” on page 5v “Clients and servers” on page 11v “Extending queue manager facilities” on page 12v “Security” on page 13v “Transactional support” on page 13

WebSphere MQ and message queuingWebSphere MQ allows application programs to use message queuing to participatein message-driven processing. Application programs can communicate acrossdifferent platforms by using the appropriate message queuing software products.For example, HP-UX and z/OS® applications can communicate throughWebSphere MQ for HP-UX and WebSphere MQ for z/OS respectively. Theapplications are shielded from the mechanics of the underlying communications.

WebSphere MQ products implement a common application programming interfaceknown as the message queue interface (or MQI) wherever the applications run. Thismakes it easier for you to port application programs from one platform to another.

WebSphere MQ also provides a high level message handling API that makes iteasier for programmers to deploy an intelligent network for business processintegration within and between enterprises. This is called the Application MessagingInterface (AMI). The AMI moves many message-handling functions normallyperformed by messaging applications into the middleware layer, where a set ofpolicies defined by the enterprise is applied on the application’s behalf.

The MQI and AMI are described in detail in the WebSphere MQ ApplicationProgramming Reference.

Time-independent applicationsWith message queuing, the exchange of messages between the sending andreceiving programs is independent of time. This means that the sending andreceiving application programs are decoupled; the sender can continue processingwithout having to wait for the receiver to acknowledge receipt of the message. Thetarget application does not even have to be running when the message is sent. Itcan retrieve the message after it is has been started.

Message-driven processingWhen messages arrive on a queue, they can automatically start an applicationusing triggering. If necessary, the applications can be stopped when the message (ormessages) have been processed.

Messages and queuesMessages and queues are the basic components of a message queuing system.

© Copyright IBM Corp. 1994, 2002 3

What is a message?A message is a string of bytes that is meaningful to the applications that use it.Messages are used to transfer information from one application program to another(or between different parts of the same application). The applications can berunning on the same platform, or on different platforms.

WebSphere MQ messages have two parts:v The application data. The content and structure of the application data is defined

by the application programs that use it.v A message descriptor. The message descriptor identifies the message and contains

additional control information, such as the type of message and the priorityassigned to the message by the sending application.The format of the message descriptor is defined by WebSphere MQ. For acomplete description of the message descriptor, see the WebSphere MQApplication Programming Reference manual.

Message lengthsThe default maximum message length is 4 MB, although you can increase this to amaximum length of 100 MB (where 1 MB equals 1 048 576 bytes). In practice, themessage length might be limited by:v The maximum message length defined for the receiving queuev The maximum message length defined for the queue managerv The maximum message length defined by the queuev The maximum message length defined by either the sending or receiving

applicationv The amount of storage available for the message

It might take several messages to send all the information that an applicationrequires.

How do applications send and receive messages?Application programs send and receive messages using MQI calls.

For example, to put a message onto a queue, an application:1. Opens the required queue by issuing an MQI MQOPEN call2. Issues an MQI MQPUT call to put the message onto the queue

Another application can retrieve the message from the same queue by issuing anMQI MQGET call

For more information about MQI calls, see the WebSphere MQ ApplicationProgramming Reference.

What is a queue?A queue is a data structure used to store messages.

Each queue is owned by a queue manager. The queue manager is responsible formaintaining the queues it owns, and for storing all the messages it receives ontothe appropriate queues. The messages might be put on the queue by applicationprograms, or by a queue manager as part of its normal operation.

WebSphere MQ Version 5.3 supports queues over 2 GB in size; “Enabling largequeues” on page 48 discusses this in more detail. For information about planning

Messages and queues


|

|

||

the amount of storage you need for queues, see the Quick Beginnings guide foryour platform, or visit the WebSphere MQ Web site for platform-specificperformance reports:http://www.ibm.com/software/ts/mqseries/

Predefined queues and dynamic queuesQueues can be characterized by the way they are created:v Predefined queues are created by an administrator using the appropriate MQSC

or PCF commands. Predefined queues are permanent; they exist independentlyof the applications that use them and survive WebSphere MQ restarts.

v Dynamic queues are created when an application issues an MQOPEN requestspecifying the name of a model queue. The queue created is based on a templatequeue definition, which is called a model queue. You can create a model queueusing the MQSC command DEFINE QMODEL. The attributes of a model queue(for example, the maximum number of messages that can be stored on it) areinherited by any dynamic queue that is created from it.Model queues have an attribute that specifies whether the dynamic queue is tobe permanent or temporary. Permanent queues survive application and queuemanager restarts; temporary queues are lost on restart.

Retrieving messages from queuesSuitably authorized applications can retrieve messages from a queue according tothe following retrieval algorithms:v First-in-first-out (FIFO).v Message priority, as defined in the message descriptor. Messages that have the

same priority are retrieved on a FIFO basis.v A program request for a specific message.

The MQGET request from the application determines the method used.

ObjectsMany of the tasks described in this book involve manipulating WebSphere MQobjects. The object types are queue managers, queues, process definitions,channels, namelists, and authentication information objects.

The manipulation or administration of objects includes:v Starting and stopping queue managers.v Creating objects, particularly queues, for applications.v Working with channels to create communication paths to queue managers on

other (remote) systems. This is described in detail in WebSphere MQIntercommunication.

v Creating clusters of queue managers to simplify the overall administrationprocess, and to balance workload.

This book contains detailed information about administration in the followingchapters:v Chapter 2, “An introduction to WebSphere MQ administration” on page 15v Chapter 3, “Managing queue managers using control commands” on page 23v Chapter 4, “Administering local WebSphere MQ objects” on page 33v Chapter 5, “Automating administration tasks” on page 55v Chapter 6, “Administering remote WebSphere MQ objects” on page 59

Messages and queues

Chapter 1. Introduction to WebSphere MQ 5

|||

v Chapter 7, “Administration using the WebSphere MQ Explorer” on page 75v Chapter 8, “Administration using the WebSphere MQ Services snap-in” on page

81

Object namesThe naming convention adopted for WebSphere MQ objects depends on the object.

Each instance of a queue manager is known by its name. This name must beunique within the network of interconnected queue managers, so that one queuemanager can unambiguously identify the target queue manager to which anygiven message is sent.

For the other types of object, each object has a name associated with it and can bereferred to by that name. These names must be unique within one queue managerand object type. For example, you can have a queue and a process with the samename, but you cannot have two queues with the same name.

In WebSphere MQ, names can have a maximum of 48 characters, with theexception of channels which have a maximum of 20 characters. For moreinformation about names, see “Names of WebSphere MQ objects” on page 243.

Managing objectsYou can create, alter, display, and delete objects using:v Control commands, which are typed in from a keyboardv MQSC commands, which can be typed in from a keyboard or read from a filev Programmable Command Format (PCF) messages, which can be used in an

automation programv WebSphere MQ Administration Interface (MQAI) calls in a programv For WebSphere MQ for Windows only:

– MQAI Component Object Model (COM) calls in a program– Active Directory Service interface (ADSI) calls in a program– The WebSphere MQ Explorer snap-in and WebSphere MQ Services snap-in

running under the Microsoft Management Console (MMC)– The Windows NT Default Configuration application

For more information about these methods, see Chapter 2, “An introduction toWebSphere MQ administration” on page 15.

Object attributesThe properties of an object are defined by its attributes. Some you can specify,others you can only view. For example, the maximum message length that a queuecan accommodate is defined by its MaxMsgLength attribute; you can specify thisattribute when you create a queue. The DefinitionType attribute specifies how thequeue was created; you can only display this attribute.

In WebSphere MQ, there are two ways of referring to an attribute:v Using its PCF name, for example, MaxMsgLength.v Using its MQSC command name, for example, MAXMSGL.

This book mainly describes how to specify attributes using MQSC commands, andso it refers to most attributes using their MQSC command names, rather than theirPCF names.

Objects


||

|

WebSphere MQ queuesThere are four types of queue object available in WebSphere MQ.

Local queue objectA local queue object identifies a local queue belonging to the queuemanager to which the application is connected. All queues are local queuesin the sense that each queue belongs to a queue manager and, for thatqueue manager, the queue is a local queue.

Remote queue objectA remote queue object identifies a queue belonging to another queuemanager. This queue must be defined as a local queue to that queuemanager. The information you specify when you define a remote queueobject allows the local queue manager to find the remote queue manager,so that any messages destined for the remote queue go to the correctqueue manager.

Before applications can send messages to a queue on another queuemanager, you must have defined a transmission queue and channelsbetween the queue managers, unless you have grouped one or more queuemanagers together into a cluster. For more information about clusters, see“Remote administration using clusters” on page 60.

Alias queue objectAn alias queue allows applications to access a queue by referring to itindirectly in MQI calls. When an alias queue name is used in an MQI call,the name is resolved to the name of either a local or a remote queue at runtime. This allows you to change the queues that applications use withoutchanging the application in any way; you merely change the alias queuedefinition to reflect the name of the new queue to which the alias resolves.

An alias queue is not a queue, but an object that you can use to accessanother queue.

Model queue objectA model queue defines a set of queue attributes that are used as a templatefor creating a dynamic queue. Dynamic queues are created by the queuemanager when an application issues an MQOPEN request specifying aqueue name that is the name of a model queue. The dynamic queue that iscreated in this way is a local queue whose attributes are taken from themodel queue definition. The dynamic queue name can be specified by theapplication, or the queue manager can generate the name and return it tothe application.

Dynamic queues defined in this way can be temporary queues, which donot survive product restarts, or permanent queues, which do.

Defining queuesQueues are defined to WebSphere MQ using:v The MQSC command DEFINEv The PCF Create Queue command

The commands specify the type of queue and its attributes. For example, a localqueue object has attributes that specify what happens when applications referencethat queue in MQI calls. Examples of attributes are:v Whether applications can retrieve messages from the queue (GET enabled)v Whether applications can put messages on the queue (PUT enabled)

Objects


v Whether access to the queue is exclusive to one application or shared betweenapplications

v The maximum number of messages that can be stored on the queue at the sametime (maximum queue depth)

v The maximum length of messages that can be put on the queue

For further details about defining queue objects, see the WebSphere MQ Script(MQSC) Command Reference or WebSphere MQ Programmable Command Formats andAdministration Interface.

Queues used by WebSphere MQWebSphere MQ uses some local queues for specific purposes related to itsoperation. You must define these queues before WebSphere MQ can use them.

Initiation queuesInitiation queues are queues that are used in triggering. A queue managerputs a trigger message on an initiation queue when a trigger event occurs.A trigger event is a logical combination of conditions that is detected by aqueue manager. For example, a trigger event might be generated when thenumber of messages on a queue reaches a predefined depth. This eventcauses the queue manager to put a trigger message on a specified initiationqueue. This trigger message is retrieved by a trigger monitor, a specialapplication that monitors an initiation queue. The trigger monitor thenstarts the application program that was specified in the trigger message.

If a queue manager is to use triggering, at least one initiation queue mustbe defined for that queue manager. See “Managing objects for triggering”on page 51 and “runmqtrm (start trigger monitor)” on page 301. For more

information about triggering, see the WebSphere MQ ApplicationProgramming Guide.

Transmission queuesTransmission queues are queues that temporarily store messages that aredestined for a remote queue manager. You must define at least onetransmission queue for each remote queue manager to which the localqueue manager is to send messages directly. These queues are also used inremote administration; see “Remote administration from a local queuemanager” on page 61. For information about the use of transmissionqueues in distributed queuing, see WebSphere MQ Intercommunication.

Each queue manager can have a default transmission queue. When aqueue manager that is not part of a cluster puts a message onto a remotequeue, the default action, if there is no transmission queue with the samename as the destination queue manager, is to use the default transmissionqueue.

Cluster transmission queuesEach queue manager within a cluster has a cluster transmission queuecalled SYSTEM.CLUSTER.TRANSMIT.QUEUE. A definition of this queue iscreated by default when you define a queue manager.

A queue manager that is part of the cluster can send messages on thecluster transmission queue to any other queue manager that is in the samecluster.

During name resolution, the cluster transmission queue takes precedenceover the default transmission queue.

Objects


|||

When a queue manager is part of a cluster, the default action is to use theSYSTEM.CLUSTER.TRANSMIT.QUEUE, except when the destinationqueue manager is not part of the cluster.

Dead-letter queuesA dead-letter (undelivered-message) queue is a queue that stores messagesthat cannot be routed to their correct destinations. This occurs when, forexample, the destination queue is full. The supplied dead-letter queue iscalled SYSTEM.DEAD.LETTER.QUEUE.

For distributed queuing, define a dead-letter queue on each queuemanager involved.

Command queuesThe command queue, SYSTEM.ADMIN.COMMAND.QUEUE, is a localqueue to which suitably authorized applications can send MQSCcommands for processing. These commands are then retrieved by aWebSphere MQ component called the command server. The commandserver validates the commands, passes the valid ones on for processing bythe queue manager, and returns any responses to the appropriate reply-toqueue.

A command queue is created automatically for each queue manager whenthat queue manager is created.

Reply-to queuesWhen an application sends a request message, the application that receivesthe message can send back a reply message to the sending application.This message is put on a queue, called a reply-to queue, which is normallya local queue to the sending application. The name of the reply-to queue isspecified by the sending application as part of the message descriptor.

Event queuesInstrumentation events can be used to monitor queue managersindependently of MQI applications.

When an instrumentation event occurs, the queue manager puts an eventmessage on an event queue. This message can then be read by amonitoring application, which might inform an administrator or initiatesome remedial action if the event indicates a problem.

Note: Trigger events are quite different from instrumentation events in thattrigger events are not caused by the same conditions, and do notgenerate event messages.

For more information about instrumentation events, see WebSphere MQEvent Monitoring.

WebSphere MQ queue managersA queue manager provides queuing services to applications, and manages thequeues that belong to it. It ensures that:v Object attributes are changed according to the commands received.v Special events such as trigger events or instrumentation events are generated

when the appropriate conditions are met.v Messages are put on the correct queue, as requested by the application making

the MQPUT call. The application is informed if this cannot be done, and anappropriate reason code is given.

Objects


Each queue belongs to a single queue manager and is said to be a local queue tothat queue manager. The queue manager to which an application is connected issaid to be the local queue manager for that application. For the application, thequeues that belong to its local queue manager are local queues.

A remote queue is a queue that belongs to another queue manager. A remote queuemanager is any queue manager other than the local queue manager. A remotequeue manager can exist on a remote machine across the network, or might existon the same machine as the local queue manager. WebSphere MQ supportsmultiple queue managers on the same machine.

A queue manager object can be used in some MQI calls. For example, you caninquire about the attributes of the queue manager object using the MQI callMQINQ.

Process definitionsA process definition object defines an application that starts in response to a triggerevent on a WebSphere MQ queue manager. See the “Initiation queues” entry under“Queues used by WebSphere MQ” on page 8 for more information.

The process definition attributes include the application ID, the application type,and data specific to the application.

ChannelsChannels are objects that provide a communication path from one queue managerto another. Channels are used in distributed queuing to move messages from onequeue manager to another. They shield applications from the underlyingcommunications protocols. The queue managers might exist on the same, ordifferent, platforms. For queue managers to communicate with one another, youmust define one channel object at the queue manager that is to send messages, andanother, complementary one, at the queue manager that is to receive them.

For information on channels and how to use them, see WebSphere MQIntercommunication.

ClustersIn a traditional WebSphere MQ network using distributed queuing, every queuemanager is independent. If one queue manager needs to send messages to anotherqueue manager, it must define a transmission queue, a channel to the remotequeue manager, and a remote queue definition for every queue to which it wantsto send messages.

A cluster is a group of queue managers set up in such a way that the queuemanagers can communicate directly with one another over a single network,without the need for transmission queue, channel, and remote queue definitions.

For information about clusters, see Chapter 6, “Administering remote WebSphereMQ objects” on page 59, and WebSphere MQ Queue Manager Clusters.

NamelistsA namelist is a WebSphere MQ object that contains a list of other WebSphere MQobjects. Typically, namelists are used by applications such as trigger monitors,where they are used to identify a group of queues. The advantage of using anamelist is that it is maintained independently of applications; it can be updated

Objects


without stopping any of the applications that use it. Also, if one application fails,the namelist is not affected and other applications can continue using it.

Namelists are also used with queue manager clusters to maintain a list of clustersreferred to by more than one WebSphere MQ object.

Authentication information objectsThe queue manager authentication information object forms part of WebSphereMQ support for Secure Sockets Layer (SSL) security. It provides the definitionsneeded to check certificate revocation lists (CRLs) using LDAP servers. CRLs allowCertification Authorities to revoke certificates that can no longer be trusted.

This book describes using the setmqaut, dspmqaut, dmpmqaut, rcrmqobj,rcdmqimg, and dspmqfls commands with the authentication information object.For an overview of SSL and the use of the authentication information objects, seeWebSphere MQ Security.

System default objectsThe system default objects are a set of object definitions that are createdautomatically whenever a queue manager is created. You can copy and modify anyof these object definitions for use in applications at your installation.

Default object names have the stem SYSTEM.DEFAULT; for example, the defaultlocal queue is SYSTEM.DEFAULT.LOCAL.QUEUE, and the default receiverchannel is SYSTEM.DEFAULT.RECEIVER. You cannot rename these objects; defaultobjects of these names are required.

When you define an object, any attributes that you do not specify explicitly arecopied from the appropriate default object. For example, if you define a localqueue, those attributes that you do not specify are taken from the default queueSYSTEM.DEFAULT.LOCAL.QUEUE.

See Appendix A, “System and default objects” on page 475 for more informationabout system defaults.

Clients and serversWebSphere MQ supports client-server configurations for its applications.

A WebSphere MQ client is a component that allows an application running on asystem to issue MQI calls to a queue manager running on another system. Theoutput from the call is sent back to the client, which passes it back to theapplication.

A WebSphere MQ server is a queue manager that provides queuing services to oneor more clients. All the WebSphere MQ objects, for example queues, exist only onthe queue manager machine (the WebSphere MQ server machine), and not on theclient. A WebSphere MQ server can also support local WebSphere MQ applications.

The difference between a WebSphere MQ server and an ordinary queue manager isthat a server has a dedicated communications link with each client. For moreinformation about creating channels for clients and servers, see WebSphere MQIntercommunication.

For information about client support in general, see WebSphere MQ Clients.

Objects


|

||||

||||

WebSphere MQ applications in a client-server environmentWhen linked to a server, client WebSphere MQ applications can issue most MQIcalls in the same way as local applications. The client application issues anMQCONN call to connect to a specified queue manager. Any additional MQI callsthat specify the connection handle returned from the connect request are thenprocessed by this queue manager.

You must link your applications to the appropriate client libraries. See WebSphereMQ Clients for further information.

Extending queue manager facilitiesThe facilities provided by a queue manager can be extended by:v User exitsv Installable services

User exitsUser exits provide a mechanism for you to insert your own code into a queuemanager function. The user exits supported include:

Channel exitsThese exits change the way that channels operate. Channel exits aredescribed in WebSphere MQ Intercommunication.

Data conversion exitsThese exits create source code fragments that can be put into applicationprograms to convert data from one format to another. Data conversionexits are described in the WebSphere MQ Application Programming Guide.

The cluster workload exitThe function performed by this exit is defined by the provider of the exit.Call definition information is given in WebSphere MQ Queue ManagerClusters.

Installable servicesInstallable services are more extensive than exits in that they have formalizedinterfaces (an API) with multiple entry points.

An implementation of an installable service is called a service component. You canuse the components supplied with the WebSphere MQ product, or you can writeyour own component to perform the functions that you require.

Currently, the following installable services are provided:

Authorization serviceThe authorization service allows you to build your own security facility.

The default service component that implements the service is the ObjectAuthority Manager (OAM). By default, the OAM is active, and you do nothave to do anything to configure it. You can use the authorization serviceinterface to create other components to replace or augment the OAM. Formore information about the OAM, see Chapter 10, “WebSphere MQsecurity” on page 113.

Name serviceThe name service enables applications to share queues by identifyingremote queues as though they were local queues.

Clients and servers


A default service component that implements the name service is providedwith WebSphere MQ. It uses the Open Software Foundation (OSF)Distributed Computing Environment (DCE). You can also write your ownname service component. You might want to do this if you do not haveDCE installed, for example. By default, the name service is inactive.

API exitsAPI exits let you write code that changes the behavior of WebSphere MQAPI calls, such as MQPUT and MQGET, and then insert that codeimmediately before or immediately after those calls. The insertion isautomatic; the queue manager drives the exit code at the registered points.For more information about API exits, see Chapter 23, “API exits” onpage 419 and the WebSphere MQ Application Programming Guide.

See Part 7, “WebSphere MQ installable services and the API exit” on page 327 formore information about the installable services.

SecurityIn WebSphere MQ, there are three methods of providing security:v The Object Authority Manager (OAM) facilityv DCE securityv Channel security using Secure Sockets Layer (SSL)

Object Authority Manager (OAM) facilityAuthorization for using MQI calls, commands, and access to objects is provided bythe Object Authority Manager (OAM), which by default is enabled. Access toWebSphere MQ entities is controlled through WebSphere MQ user groups and theOAM. We provide a command line interface to enable administrators to grant orrevoke authorizations as required.

For more information about creating authorization service components, seeChapter 10, “WebSphere MQ security” on page 113.

DCE securityChannel exits that use the DCE Generic Security Service (GSS) are provided byWebSphere MQ. For more information, see WebSphere MQ Intercommunication.

Channel security using SSLThe Secure Sockets Layer (SSL) protocol provides industry-standard channelsecurity, with protection against eavesdropping, tampering, and impersonation.

SSL uses public key and symmetric techniques to provide message privacy andintegrity and mutual authentication.

For a comprehensive review of security in WebSphere MQ including detailedinformation on SSL, see WebSphere MQ Security. For an overview of SSL, includingpointers to the commands described in this book, see “Protecting channels withSSL” on page 129.

Transactional supportAn application program can group a set of updates into a unit of work. Theseupdates are usually logically related and must all be successful for data integrity tobe preserved. If one update succeeds while another fails, data integrity is lost.

Extending facilities


|||||||

||

|

|

||

||

||||

When a unit of work completes successfully, it is said to commit. Once committed,all updates made within that unit of work are made permanent and irreversible.However, if the unit of work fails, all updates are instead backed out. This process,where units of work are either committed or backed out with integrity, is knownas syncpoint coordination.

A local unit of work is one in which the only resources updated are those of theWebSphere MQ queue manager. Here syncpoint coordination is provided by thequeue manager itself using a single-phase commit process.

A global unit of work is one in which resources belonging to other resourcemanagers, such as XA-compliant databases, are also updated. Here, a two-phasecommit procedure must be used and the unit of work can be coordinated by thequeue manager itself, or externally by another XA-compliant transaction managersuch as IBM TXSeries®, or BEA Tuxedo.

For more information, see Chapter 11, “Transactional support” on page 139.

WebSphere MQ also provides support for the Microsoft Transaction Server (MTS).“Using the Microsoft Transaction Server (MTS)” on page 165 provides informationon how to set up WebSphere MQ to take advantage of MTS support.

Transactional support

Documents

System Administration Guide · 2018. 9. 27. · WebSphere MQ Script (MQSC) commands . . . 16 PCF commands .....16 Administration on WebSphere MQ for Windows . . 16 Using the WebSphere