Contents

Figures
Tables
About this book
Who this book is for
What you need to know to understand this book
How to use this book
Appearance of text in this book
Terms used in this book
Summary of changes
Changes for this edition (SC34-6595-00)
Designing applications that use WebSphere MQ
Introduction to message queuing
What is message queuing?
What is a message?
Message descriptor
Message channel agent
What is a message queue?
What is a queue manager?
What is a cluster?
What is a shared queue, a queue-sharing group, and intra-group queuing?
What is a WebSphere MQ client?
Main features of message queuing
WebSphere MQ clients and servers
Benefits of message queuing to the application designer and developer
What can you do with WebSphere MQ products?
WebSphere MQ for z/OS
WebSphere MQ for non-z/OS platforms
Overview of application design
Planning your design
Using WebSphere MQ objects
Designing your messages
WebSphere MQ techniques
Waiting for messages
Correlating replies
Setting and using context information
Starting WebSphere MQ programs automatically
Generating WebSphere MQ reports
Clusters and message affinities
Application programming
Call interface
Design for performance: hints and tips
Programming platforms
Applications for more than one platform
Testing WebSphere MQ applications
WebSphere MQ messages
Message descriptor
Types of message
Datagrams
Request messages
Reply messages
Report messages
Reports and segmented messages
Format of message control information and message data
Format of message control information
Format of message data
Application data conversion
Message priorities
Message groups
Message persistence
Selecting messages from queues
Messages that fail to be delivered
Messages that are backed out
Reply-to queue and queue manager
Message context
Identity context
Origin context
WebSphere MQ objects
Queue managers
Attributes of queue managers
Queue managers and workload management
Queue-sharing groups
Queues
Types of queue
Attributes of queues
Remote queues
Alias queues
Model queues
Dynamic queues
Transmission queues
Initiation queues
Dead-letter (undelivered message) queues
System command queues
System default queues
Namelists
Process definitions
Authentication information objects
Channels
Storage classes
Rules for naming WebSphere MQ objects
Queue names
Process definition, authentication information object, and namelist names
Channel names
Reserved object names
Handling program errors
Locally determined errors
Failure of an MQI call
System interruptions
Messages containing incorrect data
Using report messages for problem determination
Creating report messages
Remotely determined errors
Problems delivering a message
Using the dead-letter (undelivered message) queue
Writing a WebSphere MQ application
Introducing the Message Queue Interface
What is in the MQI?
Calls
Syncpoint calls
Data conversion
Structures
Elementary data types
WebSphere MQ data definitions
WebSphere MQ stub programs and library files
Parameters common to all the calls
Using connection and object handles
Understanding return codes
Specifying buffers
Programming language considerations
Coding in C
Coding in COBOL
Coding in System/390(R) assembler language
Coding in RPG
Coding in PL/I
Coding in Visual Basic
z/OS batch considerations
UNIX signal handling
Unthreaded applications
Threaded applications
Additional considerations
Connecting to and disconnecting from a queue manager
Connecting to a queue manager using the MQCONN call
Scope of MQCONN or MQCONNX
Connecting to a queue manager using the MQCONNX call
Restrictions for trusted applications
Shared (thread independent) connections with MQCONNX
MQCONNX environment variable
Disconnecting programs from a queue manager using MQDISC
When no MQDISC is issued
Authority checking
Opening and closing objects
Opening objects using the MQOPEN call
Scope of an object handle
Identifying objects (the MQOD structure)
Name resolution
Using the options of the MQOPEN call
Creating dynamic queues
Opening remote queues
Closing objects using the MQCLOSE call
Putting messages on a queue
Putting messages on a local queue using the MQPUT call
Specifying handles
Defining messages using the MQMD structure
Specifying options using the MQPMO structure
The data in your message
Putting messages on a remote queue
Controlling context information
Passing identity context
Passing all context
Setting identity context
Setting all context
Putting one message on a queue using the MQPUT1 call
Distribution lists
Opening distribution lists
Putting messages to a distribution list
Some cases where the put calls fail
Getting messages from a queue
Getting messages from a queue using the MQGET call
Specifying connection handles
Describing messages using the MQMD structure and the MQGET call
Specifying MQGET options using the MQGMO structure
Specifying the size of the buffer area
The order in which messages are retrieved from a queue
Priority
Logical and physical ordering
Getting a particular message
Type of index
Handling messages greater than 4 MB long
Increasing the maximum message length
Message segmentation
Reference messages
Waiting for messages
Signaling
To set a signal
When the message arrives
Skipping backout
Application data conversion
Conversion of EBCDIC newline characters
Browsing messages on a queue
The browse cursor
Browsing messages when the message length is unknown
Removing a message that you have browsed
Browsing messages in logical order
Browsing messages in groups
Some cases where the MQGET call fails
Writing data-conversion exits
Invoking the data-conversion exit
Data conversion on z/OS
Writing a data-conversion exit program
Skeleton source file
Convert characters call
Utility for creating conversion-exit code
Valid syntax
Writing a data-conversion exit program for WebSphere MQ for iSeries
Writing a data-conversion exit program for WebSphere MQ for z/OS
Writing a data-conversion exit for WebSphere MQ on UNIX systems
UNIX environment
Compiling data-conversion exits on UNIX and Linux
Writing a data-conversion exit for WebSphere MQ for Windows
Inquiring about and setting object attributes
Inquiring about the attributes of an object
Some cases where the MQINQ call fails
Setting queue attributes
Committing and backing out units of work
Syncpoint considerations in WebSphere MQ applications
Syncpoints in WebSphere MQ for z/OS applications
Syncpoints in CICS Transaction Server for OS/390 and CICS for MVS/ESA(TM) applications
Syncpoints in IMS applications
Syncpoints in z/OS batch applications
Syncpoints in CICS for AS/400 applications
Syncpoints in WebSphere MQ for Windows, WebSphere MQ for iSeries, and WebSphere MQ on UNIX systems
Local units of work
Global units of work
Interfaces to external syncpoint managers
Interfaces to the i5/OS external syncpoint manager
General XA support
WebSphere MQ XA support and Tuxedo
Starting WebSphere MQ applications using triggers
What is triggering?
Prerequisites for triggering
Conditions for a trigger event
Controlling trigger events
Example of the use of trigger type EVERY
Example of the use of trigger type FIRST
Example of the use of trigger type DEPTH
Special case of trigger type FIRST
Designing an application that uses triggered queues
Trigger messages and units of work
Getting messages from a triggered queue
Trigger monitors
Trigger monitors on z/OS
Trigger monitors on UNIX systems, i5/OS, and Windows systems
WebSphere MQ for iSeries trigger monitors
Properties of trigger messages
Persistence and priority of trigger messages
Queue manager restart and trigger messages
Trigger messages and changes to object attributes
Format of trigger messages
When triggering does not work
How CKTI detects errors
How CSQQTRMN detects errors
How RUNMQTRM detects errors
Using and writing API exits
Introducing API exits
Why use API exits
How you use API exits
What happens when an API exit runs?
Compiling API exits
On Solaris
On AIX
On HP-UX
On Linux(R)
On Windows systems
On i5/OS
Reference information
External control blocks
The exit chain area and exit chain area header (MQACH)
External constants
C language typedefs
The exit entry point registration call (MQXEP)
Invoking exit functions
General information on invoking exit functions
Using and writing applications on WebSphere MQ for z/OS
Environment-dependent WebSphere MQ for z/OS functions
Program debugging facilities
Syncpoint support
Recovery support
The WebSphere MQ for z/OS interface with the application environment
The batch adapter
RRS batch adapter
The CICS adapter
The IMS adapter
Writing z/OS(R) UNIX System Services applications
The API-crossing exit for z/OS
Using the API-crossing exit
Writing your own exit program
The sample API-crossing exit program, CSQCAPX
Preparing and using the API-crossing exit
WebSphere MQ Workflow
Application programming with shared queues
Serializing your applications
Applications that are not suitable for use with shared queues
Deciding whether to share non-application queues
Migrating your existing applications to use shared queues
Using and writing WebSphere(R) MQ-CICS bridge applications for z/OS
Distributed program link applications
Using CICS DPL programs with the bridge
Programming CICS DPL transactions in the distributed environment
Setting fields in the MQMD and MQCIH structures (DPL)
Managing MsgId and CorrelId in a unit of work (DPL)
3270 applications
Using CICS transactions with the bridge
Programming CICS transactions in the distributed environment
From 3270 legacy to 3270 bridge - an example
Setting fields in the MQMD and MQCIH structures (3270)
Managing MsgId and CorrelId in a unit of work (3270)
Information applicable to both DPL and 3270
Setting the open options and put message options for the bridge request queue
Error handling by the CICS bridge
Debugging CICS bridge applications
Application data structure terminology
IMS and IMS Bridge applications on WebSphere MQ for z/OS
Writing IMS applications using WebSphere MQ
Syncpoints in IMS applications
MQI calls in IMS applications
Writing WebSphere MQ-IMS bridge applications
How the WebSphere MQ-IMS bridge deals with messages
Writing your program
Object-oriented programming with WebSphere MQ
What is in the WebSphere MQ Object Model?
Classes
Object references
Return codes
Programming language considerations
Coding in C++
Coding in Java
Coding in ActiveX
Building a WebSphere MQ application
Building your application on AIX
Preparing C programs
Linking libraries
Preparing COBOL programs
Preparing COBOL programs using IBM(R) COBOL Set for AIX(R)
Preparing COBOL programs using Micro Focus COBOL
Preparing CICS programs
TXSeries CICS support
Building your application on HP-UX
Preparing C programs
Linking libraries
Preparing COBOL programs
Programs to run in the WebSphere MQ client environment
Preparing CICS programs
TXSeries CICS support
Building your application on Linux(R)
Preparing C programs
Linking libraries
Building your application on i5/OS
Preparing C programs
Preparing COBOL programs
Preparing CICS programs
Preparing RPG programs
SQL programming considerations
i5/OS programming considerations
QMQM activation group
Building your application on Solaris
Preparing C programs
Linking libraries
Preparing COBOL programs
Preparing CICS programs
TXSeries CICS support
Building your application on Windows systems
Preparing C programs
Preparing CICS and Transaction Server programs
Preparing COBOL programs
Preparing CICS and Transaction Server programs
Preparing Visual Basic programs
SSPI security exit
Introduction to security exits
Building your application on z/OS
Preparing your program to run
Building z/OS batch applications
Building CICS applications
Building IMS (BMP or MPP) applications
Building z/OS(R) UNIX System Services applications
Dynamically calling the WebSphere MQ stub
Debugging your programs
Debugging CICS programs
Debugging TSO programs
Using lightweight directory access protocol services with WebSphere MQ for Windows
What is a directory service?
What is LDAP?
Using LDAP with WebSphere MQ
LDAP sample program
Building the sample program
Configuring the directory
Configuring the IBM(R) eNetwork LDAP server
Configuring the Netscape directory server
Running the sample program
Program design
Sample WebSphere MQ programs
Sample programs (all platforms except z/OS)
Features demonstrated in the sample programs
Samples for Linux and UNIX systems
Samples for WebSphere MQ for Windows
Visual Basic samples for WebSphere MQ for Windows
Samples for WebSphere MQ for iSeries
Preparing and running the sample programs
i5/OS
UNIX systems
Windows systems
Running the sample programs
The Put sample programs
Running the amqsput and amqsputc samples
Running the amq0put sample
Running the AMQSPUT4 C sample
Running the AMQ0PUT4 COBOL sample
Design of the Put sample program
The Distribution List sample program
Running the Distribution List sample, amqsptl0
Design of the Distribution List sample
The Browse sample programs
UNIX(R) systems and Windows systems
i5/OS
Design of the Browse sample program
The Browser sample program
The Get sample programs
Running the amqsget and amqsgetc samples
Running the amq0get sample
Running the AMQSGET4 and the AMQ0GET4 samples
Design of the Get sample program
The Reference Message sample programs
Notes for i5/OS users
Running the Reference Message samples
Design of the Put Reference Message sample (amqsprma.c, AMQSPRM4)
Design of the Reference Message Exit sample (amqsxrma.c, AMQSXRM4)
Design of the Get Reference Message sample (amqsgrma.c, AMQSGRM4)
The Request sample programs
Running the amqsreq0.c, amqsreq, and amqsreqc samples
Running the amq0req0.cbl sample
Running the AMQSREQ4 sample
Running the AMQ0REQ4 sample
Running the Request sample using triggering
Design of the Request sample program
The Inquire sample programs
Design of the Inquire sample program
The Set sample programs
Design of the Set sample program
The Echo sample programs
Design of the Echo sample programs
The Data-Conversion sample program
Design of the data-conversion sample
The Triggering sample programs
Running the amqstrg0.c, amqstrg, and amqstrgc samples
Running the AMQSTRG4 sample
Design of the triggering sample
Running the AMQSERV4 sample
Design of the trigger server
Ending the triggering sample programs on i5/OS
Running the samples using remote queues
Database coordination samples
Creating the databases and tables
Precompiling, compiling, and linking the samples
Running the samples
The CICS transaction sample
TUXEDO samples
Building the server environment
Server sample program for TUXEDO
Put sample program for TUXEDO
Get sample for TUXEDO
Encina(R) sample program
Building the AMQSXAE0.C sample
Dead-letter queue handler sample
The Connect sample program
Running the amqscnxc sample
The API exit sample program
Configuring for the sample exit
Using the SSPI security exit on Windows systems
Object code
Source code
Sample programs for WebSphere MQ for z/OS
Features demonstrated in the sample applications
Put samples
Get samples
Browse sample
Print Message sample
Queue Attributes sample
Mail Manager sample
Credit Check sample
The Message Handler sample
Distributed queuing exit samples
Data-conversion exit samples
Preparing and running sample applications for the batch environment
Names of the sample batch applications
Preparing sample applications for the TSO environment
Names of the sample TSO applications
Preparing the sample applications for the CICS environment
QLOP abend
Names of the sample CICS applications
Preparing the sample application for the IMS environment
Names of the sample IMS application
The Put samples
Design of the Put sample
The Put samples for the batch environment
The Put samples for the CICS environment
The Get samples
Design of the Get sample
The Get samples for the CICS environment
The Browse sample
Design of the Browse sample
Language-dependent design considerations
The Print Message sample
Design of the sample
The Queue Attributes sample
Design of the sample
The Mail Manager sample
Preparing the sample
Running the sample
Design of the sample
The Credit Check sample
Preparing and running the Credit Check sample
Design of the sample
Design considerations
The Credit Check sample with multiple queue managers
The IMS extension to the Credit Check sample
The Message Handler sample
Preparing and running the sample
Using the sample
Design of the sample
Appendixes
Appendix A. C language examples
Connecting to a queue manager
Disconnecting from a queue manager
Creating a dynamic queue
Opening an existing queue
Closing a queue
Putting a message using MQPUT
Putting a message using MQPUT1
Getting a message
Getting a message using the wait option
Getting a message using signaling
Inquiring about the attributes of an object
Setting the attributes of a queue
Appendix B. COBOL examples
Connecting to a queue manager
Disconnecting from a queue manager
Creating a dynamic queue
Opening an existing queue
Closing a queue
Putting a message using MQPUT
Putting a message using MQPUT1
Getting a message
Getting a message using the wait option
Getting a message using signaling
Inquiring about the attributes of an object
Setting the attributes of a queue
Appendix C. System/390(R) assembler-language examples
Connecting to a queue manager
Disconnecting from a queue manager
Creating a dynamic queue
Opening an existing queue
Closing a queue
Putting a message using MQPUT
Putting a message using MQPUT1
Getting a message
Getting a message using the wait option
Getting a message using signaling
Inquiring about and setting the attributes of a queue
Appendix D. PL/I examples
Connecting to a queue manager
Disconnecting from a queue manager
Creating a dynamic queue
Opening an existing queue
Closing a queue
Putting a message using MQPUT
Putting a message using MQPUT1
Getting a message
Getting a message using the wait option
Getting a message using signaling
Inquiring about the attributes of an object
Setting the attributes of a queue
Appendix E. WebSphere MQ data definition files
C language include files
Visual Basic module files
COBOL copy files
System/390 assembler-language macros
PL/I include files
Appendix F. Coding standards on 64 bit platforms
Preferred data types
Standard data types
32-bit UNIX applications
64-bit UNIX applications
Windows(R) 64-bit applications
Appendix G. Notices
Programming interface information
Trademarks
Index