WebSphere MQ

Application Programming Guide Version 6.0

SC34-6595-01

WebSphere MQ

Application Programming Guide Version 6.0

SC34-6595-01

Note! Before using this information and the product it supports, be sure to read the general information under Appendix G, Notices, on page 561.

Second edition (March 2006)

This edition applies to the following products: v IBM WebSphere MQ, Version 6.0 v IBM WebSphere for z/OS, Version 6.0and to all subsequent releases and modifications until otherwise indicated in new editions.

Copyright International Business Machines Corporation 1993, 2006. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

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

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

About this book . . . . . . . . . . . xv Who this book is for . . . . . . . . . . . xv What you need to know to understand this book . . xv How to use this book . . . . . . . . . . . xv

Appearance of text in this book . . . . . . xvi Terms used in this book . . . . . . . . . xvi

Summary of changes . . . . . . . . xvii Changes for this edition (SC34-6595-01) . . . . xvii

Part 1. Designing applications that use WebSphere MQ . . . . . . . . . 1

Chapter 1. Introduction to message queuing . . . . . . . . . . . . . . . 3 What is message queuing? . . . . . . . . . . 3 What is a message? . . . . . . . . . . . . 4

Message descriptor . . . . . . . . . . . 4 Message channel agent . . . . . . . . . . 4

What is a message queue? . . . . . . . . . . 4 What is a queue manager? . . . . . . . . . . 5 What is a cluster? . . . . . . . . . . . . . 5 What is a shared queue, a queue-sharing group, and intra-group queuing? . . . . . . . . . . . 6 What is a WebSphere MQ client? . . . . . . . 6 Main features of message queuing . . . . . . . 6

WebSphere MQ clients and servers . . . . . . 8 Benefits of message queuing to the application designer and developer . . . . . . . . . . . 8 What can you do with WebSphere MQ products? . . 9

WebSphere MQ for z/OS . . . . . . . . . 9 WebSphere MQ for non-z/OS platforms . . . . 10

Chapter 2. Overview of application design . . . . . . . . . . . . . . . 11 Planning your design . . . . . . . . . . . 11 Using WebSphere MQ objects . . . . . . . . 12 Designing your messages . . . . . . . . . . 13 WebSphere MQ techniques . . . . . . . . . 14

Waiting for messages . . . . . . . . . . 14 Correlating replies . . . . . . . . . . . 14 Setting and using context information . . . . 14 Starting WebSphere MQ programs automatically 15 Generating WebSphere MQ reports . . . . . 15 Clusters and message affinities . . . . . . . 15

Application programming . . . . . . . . . 16 Call interface . . . . . . . . . . . . . 16 Design for performance: hints and tips . . . . 16 Programming platforms . . . . . . . . . 17

Applications for more than one platform . . . 17 Testing WebSphere MQ applications . . . . . . 17

Chapter 3. WebSphere MQ messages 19 Message descriptor . . . . . . . . . . . . 20 Types of message . . . . . . . . . . . . 20

Datagrams . . . . . . . . . . . . . . 20 Request messages . . . . . . . . . . . 20 Reply messages . . . . . . . . . . . . 21 Report messages . . . . . . . . . . . . 21 Reports and segmented messages . . . . . . 23

Format of message control information and message data . . . . . . . . . . . . . . . . . 25

Format of message control information . . . . 25 Format of message data . . . . . . . . . 26 Application data conversion . . . . . . . . 27

Message priorities . . . . . . . . . . . . 28 Message groups . . . . . . . . . . . . . 28 Message persistence . . . . . . . . . . . 30 Selecting messages from queues . . . . . . . 30 Messages that fail to be delivered . . . . . . . 31 Messages that are backed out . . . . . . . . 31 Reply-to queue and queue manager . . . . . . 32 Message context . . . . . . . . . . . . . 32

Identity context . . . . . . . . . . . . 33 Origin context . . . . . . . . . . . . 33

Chapter 4. WebSphere MQ objects . . . 35 Queue managers . . . . . . . . . . . . 35

Attributes of queue managers . . . . . . . 36 Queue managers and workload management . . 36

Queue-sharing groups . . . . . . . . . . . 36 Queues . . . . . . . . . . . . . . . . 37

Types of queue . . . . . . . . . . . . 37 Attributes of queues . . . . . . . . . . 39 Remote queues . . . . . . . . . . . . 40 Alias queues . . . . . . . . . . . . . 40 Model queues . . . . . . . . . . . . 41 Dynamic queues . . . . . . . . . . . . 41 Transmission queues . . . . . . . . . . 43 Initiation queues . . . . . . . . . . . . 43 Dead-letter (undelivered message) queues . . . 44 System command queues . . . . . . . . . 44 System default queues . . . . . . . . . . 44

Namelists . . . . . . . . . . . . . . . 44 Process definitions . . . . . . . . . . . . 45 Authentication information objects . . . . . . 45 Channels . . . . . . . . . . . . . . . 45 Storage classes . . . . . . . . . . . . . 45 Listeners . . . . . . . . . . . . . . . 46 Services . . . . . . . . . . . . . . . 46 Rules for naming WebSphere MQ objects . . . . 47

Queue names . . . . . . . . . . . . . 47 Process definition, authentication information object, and namelist names . . . . . . . . 48

Copyright IBM Corp. 1993, 2006 iii

| | | |

Channel names . . . . . . . . . . . . 48 Reserved object names . . . . . . . . . . 48

Chapter 5. Handling program errors . . 49 Locally determined errors . . . . . . . . . 49

Failure of an MQI call . . . . . . . . . . 49 System interruptions . . . . . . . . . . 50 Messages containing incorrect data . . . . . 51

Using report messages for problem determination 51 Creating report messages . . . . . . . . . 52

Remotely determined errors . . . . . . . . . 52 Problems delivering a message . . . . . . . 53 Using the dead-letter (undelivered message) queue . . . . . . . . . . . . . . . 53

Part 2. Writing a WebSphere MQ application . . . . . . . . . . . . 57

Chapter 6. Introducing the Message Queue Interface . . . . . . . . . . . 61 What is in the MQI? . . . . . . . . . . . 61

Calls . . . . . . . . . . . . . . . . 62 Syncpoint calls . . . . . . . . . . . . 63 Data conversion . . . . . . . . . . . . 64 Structures . . . . . . . . . . . . . . 64 Elementary data types . . . . . . . . . . 64 WebSphere MQ data definitions . . . . . . 64 WebSphere MQ stub programs and library files 65

Parameters common to all the calls . . . . . . 69 Using connection and object handles . . . . . 69 Understanding return codes . . . . . . . . 69

Specifying buffers . . . . . . . . . . . . 70 Programming language considerations . . . . . 70

Coding in C . . . . . . . . . . . . . 71 Coding in COBOL . . . . . . . . . . . 73 Coding in System/390 assembler language . . . 74 Coding in RPG . . . . . . . . . . . . 76 Coding in PL/I . . . . . . . . . . . . 76 Coding in Visual Basic . . . . . . . . . . 77

z/OS batch considerations . . . . . . . . . 78 UNIX signal handling . . . . . . . . . . . 79

Unthreaded applications . . . . . . . . . 79 Threaded applications . . . . . . . . . . 79 Additional considerations . . . . . . . . 81

Chapter 7. Connecting to and disconnecting from a queue manager . 83 Connecting to a queue manager using the MQCONN call . . . . . . . . . . . . . 84

Scope of MQCONN or MQCONNX . . . . . 85 Connecting to a queue manager using the MQCONNX call . . . . . . . . . . . . . 85

Restrictions for trusted applications . . . . . 87 Shared (thread independent) connections with MQCONNX . . . . . . . . . . . . . 88 MQCONNX environment variable . . . . . . 89

Disconnecting programs from a queue manager using MQDISC . . . . . . . . . . . . . 90

When no MQDISC is issued . . . . . . . . 90

Authority checking . . . . . . . . . . . 90

Chapter 8. Opening and closing objects 91 Opening objects using the MQOPEN call . . . . 92

Scope of an object handle . . . . . . . . . 92 Identifying objects (the MQOD structure) . . . 92 Name resolution . . . . . . . . . . . . 93 Using the options of the MQOPEN call . . . . 95

Creating dynamic queues . . . . . . . . . . 98 Opening remote queues . . . . . . . . . . 99 Closing objects using the MQCLOSE call . . . . 99

Chapter 9. Putting messages on a queue . . . . . . . . . . . . . . . 101 Putting messages on a local queue using the MQPUT call . . . . . . . . . . . . . . 101

Specifying handles . . . . . . . . . . 102 Defining messages using the MQMD structure 102 Specifying options using the MQPMO structure 102 The data in your message . . . . . . . . 105

Putting messages on a remote queue . . . . . 106 Controlling context information . . . . . . . 106

Passing identity context . . . . . . . . . 106 Passing all context . . . . . . . . . . . 107 Setting identity context . . . . . . . . . 107 Setting all context . . . . . . . . . . . 107

Putting