MQSeries® IBM

Intercommunication

SC33-1872-03
MQSeries® IBM

Intercommunication

SC33-1872-03
 Note!
Before using this information and the product it supports, be sure to read the general information under “Appendix E.
Notices” on page 641.

Fourth edition (March 2000)

This edition applies to the following products:
v MQSeries for AIX® V5.1
| v MQSeries for AS/400® V5.1
v MQSeries for AT&T GIS UNIX® V2.2
v MQSeries for Compaq (DIGITAL) OpenVMS, V2.2.1.1
| v MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX), V2.2.1
v MQSeries for HP-UX, V5.1
v MQSeries for OS/390® V2.1
v MQSeries for OS/2® Warp V5.1
v MQSeries for SINIX and DC/OSx, V2.2
v MQSeries for Sun Solaris, V5.1
| v MQSeries for Tandem NonStop Kernel, V2.2.0.1
v MQSeries for VSE/ESA™ V2.1
v MQSeries for Windows V2.0
v MQSeries for Windows V2.1
v MQSeries for Windows NT, V5.1
and to all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 1993, 2000 . All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
 Contents
Figures . . . . . . . . . . . . . . . xi Queue manager alias definitions . . . . . . . 26
Outbound messages - remapping the queue
Tables . . . . . . . . . . . . . . . xiii manager name . . . . . . . . . . . . 26
Outbound messages - altering or specifying the
transmission queue . . . . . . . . . . . 27
About this book . . . . . . . . . . . xv Inbound messages - determining the destination 27
Who this book is for . . . . . . . . . . . xv Reply-to queue alias definitions . . . . . . . 28
What you need to know to understand this book. . xv What is a reply-to queue alias definition? . . . 28
How to use this book . . . . . . . . . . . xvi Reply-to queue name . . . . . . . . . . 29
Appearance of text in this book . . . . . . xvi Networks . . . . . . . . . . . . . . . 29
Terms used in this book. . . . . . . . . xvii Channel and transmission queue names . . . . 29
Network planner . . . . . . . . . . . 31
Summary of changes . . . . . . . . xix
| Changes for this edition (SC33-1872-03) . . . . . xix
Changes for the previous edition (SC33-1872-02) xix
Part 2. How intercommunication
Changes for the second edition (SC33-1872-01) . . xx works . . . . . . . . . . . . . . . 33

Part 1. Introduction . . . . . . . . . 1 Chapter 4. MQSeries

distributed-messaging techniques . . . 35
Message flow control . . . . . . . . . . . 35
Chapter 1. Concepts of
Queue names in transmission header . . . . . 36
intercommunication . . . . . . . . . 3 How to create queue manager and reply-to
What is intercommunication? . . . . . . . . . 3 aliases . . . . . . . . . . . . . . . 36
How does distributed queuing work? . . . . . 3 Putting messages on remote queues . . . . . . 37
Distributed queuing components . . . . . . . 7 More about name resolution . . . . . . . . 38
Message channels. . . . . . . . . . . . 7 Choosing the transmission queue . . . . . . . 39
Message channel agents . . . . . . . . . 9 Receiving messages. . . . . . . . . . . . 40
Transmission queues . . . . . . . . . . 10 Receiving alias queue manager names . . . . 40
Channel initiators and listeners . . . . . . . 10 Passing messages through your system . . . . . 41
Channel-exit programs . . . . . . . . . 12 Method 1: Using the incoming location name . . 42
Dead-letter queues . . . . . . . . . . . . 13 Method 2: Using an alias for the queue manager 42
Remote queue definitions. . . . . . . . . . 14 Method 3: Selecting a transmission queue . . . 42
How to get to the remote queue manager . . . . 14 Using these methods . . . . . . . . . . 42
Multi-hopping . . . . . . . . . . . . 14 Separating message flows . . . . . . . . . 42
Sharing channels . . . . . . . . . . . 14 Concentrating messages to diverse locations . . . 44
Using different channels . . . . . . . . . 15 Diverting message flows to another destination . . 45
Using clustering . . . . . . . . . . . . 16 Sending messages to a distribution list . . . . . 46
Reply-to queue . . . . . . . . . . . . . 47
Chapter 2. Making your applications Reply-to queue alias example . . . . . . . 48
communicate . . . . . . . . . . . . 17 How the example works . . . . . . . . . 50
How to send a message to another queue manager 17 How the queue manager makes use of the
Defining the channels . . . . . . . . . . 18 reply-to queue alias. . . . . . . . . . . 51
Defining the queues . . . . . . . . . . 19 Reply-to queue alias walk-through . . . . . 51
Sending the messages . . . . . . . . . . 20 Networking considerations . . . . . . . . . 52
Starting the channel . . . . . . . . . . 20 Return routing . . . . . . . . . . . . . 53
Triggering channels. . . . . . . . . . . . 20 Managing queue name translations . . . . . . 53
Safety of messages . . . . . . . . . . . . 22 Message sequence numbering . . . . . . . . 54
Fast, nonpersistent messages . . . . . . . 22 Sequential retrieval of messages . . . . . . 55
Undelivered messages . . . . . . . . . . 23 Sequence of retrieval of fast, nonpersistent
messages . . . . . . . . . . . . . . 56
Chapter 3. More about Loopback testing . . . . . . . . . . . . 56
intercommunication . . . . . . . . . 25
Addressing information . . . . . . . . . . 25
Chapter 5. DQM implementation . . . . 57
What are aliases? . . . . . . . . . . . . 25 Functions of DQM . . . . . . . . . . . . 57
Queue name resolution . . . . . . . . . 26 Message sending and receiving . . . . . . . . 58

© Copyright IBM Corp. 1993, 2000 iii

 Channel parameters . . . . . . . . . . 59 Queue manager name (QMNAME) . . . . . 91
Channel status and sequence numbers . . . . 59 Receive exit name (RCVEXIT) . . . . . . . 91
Channel control function . . . . . . . . . . 59 Receive exit user data (RCVDATA) . . . . . 92
Preparing channels . . . . . . . . . . . 60 Security exit name (SCYEXIT) . . . . . . . 92
Channel states . . . . . . . . . . . . 62 Security exit user data (SCYDATA) . . . . . 93
Stopping and quiescing channels (not MQSeries Send exit name (SENDEXIT). . . . . . . . 93
for Windows). . . . . . . . . . . . . 67 Send exit user data (SENDDATA) . . . . . . 93
Stopping and quiescing channels (MQSeries for Sequence number wrap (SEQWRAP) . . . . . 93
Windows) . . . . . . . . . . . . . . 68 Sequential delivery . . . . . . . . . . . 93
Restarting stopped channels . . . . . . . . 69 Short retry count (SHORTRTY) . . . . . . . 93
In-doubt channels . . . . . . . . . . . 69 Short retry interval (SHORTTMR) . . . . . . 94
Problem determination . . . . . . . . . 71 Target system identifier . . . . . . . . . 94
What happens when a message cannot be Transaction identifier . . . . . . . . . . 94
delivered? . . . . . . . . . . . . . . . 71 Transmission queue name (XMITQ) . . . . . 94
Initialization and configuration files . . . . . . 73 Transport type (TRPTYPE) . . . . . . . . 95
OS/390 without CICS . . . . . . . . . . 73 User ID (USERID) . . . . . . . . . . . 95
OS/390 using CICS. . . . . . . . . . . 73
Windows NT . . . . . . . . . . . . . 73 Chapter 7. Example configuration
OS/2, Digital OpenVMS, Tandem NSK, OS/400 chapters in this book . . . . . . . . 97
and UNIX systems . . . . . . . . . . . 73
Network infrastructure . . . . . . . . . . 98
VSE/ESA . . . . . . . . . . . . . . 75
Communications software . . . . . . . . . 98
Data conversion . . . . . . . . . . . . . 75
How to use the communication examples . . . . 99
Writing your own message channel agents . . . . 75
IT responsibilities . . . . . . . . . . . 100

Chapter 6. Channel attributes . . . . . 77

Channel attributes in alphabetical order . . . . . 77 Part 3. DQM in MQSeries for OS/2
Alter date (ALTDATE) . . . . . . . . . . 78 Warp, Windows NT, Digital
Alter time (ALTTIME) . . . . . . . . . . 78 OpenVMS, Tandem NSK, and UNIX
Auto start (AUTOSTART). . . . . . . . . 78
Batch interval (BATCHINT) . . . . . . . . 79
systems . . . . . . . . . . . . . 101
Batch size (BATCHSZ) . . . . . . . . . . 79
Channel name (CHANNEL) . . . . . . . . 80 Chapter 8. Monitoring and controlling
Channel type (CHLTYPE) . . . . . . . . 81 channels on distributed platforms . . 105
CICS profile name . . . . . . . . . . . 81 The DQM channel control function . . . . . . 105
Cluster (CLUSTER) . . . . . . . . . . . 81 Functions available . . . . . . . . . . . 106
Cluster namelist (CLUSNL) . . . . . . . . 82 Getting started with objects. . . . . . . . . 108
Connection name (CONNAME) . . . . . . 82 Creating objects . . . . . . . . . . . 108
Convert message (CONVERT) . . . . . . . 83 Creating default objects . . . . . . . . . 108
Description (DESCR) . . . . . . . . . . 84 Creating a channel . . . . . . . . . . 109
Disconnect interval (DISCINT) . . . . . . . 84 Displaying a channel . . . . . . . . . . 110
Heartbeat interval (HBINT) . . . . . . . . 85 Displaying channel status . . . . . . . . 110
Long retry count (LONGRTY) . . . . . . . 85 Starting a channel . . . . . . . . . . . 110
Long retry interval (LONGTMR) . . . . . . 85 Renaming a channel . . . . . . . . . . 111
LU 6.2 mode name (MODENAME) . . . . . 86 Channel attributes and channel types . . . . . 111
LU 6.2 transaction program name (TPNAME) . . 86 Channel functions . . . . . . . . . . . 112
Maximum message length (MAXMSGL) . . . . 87
Maximum transmission size . . . . . . . . 87 Chapter 9. Preparing MQSeries for
Message channel agent name (MCANAME) . . 87 distributed platforms . . . . . . . . 117
Message channel agent type (MCATYPE) . . . 88
Transmission queues and triggering . . . . . . 117
Message channel agent user identifier
Creating a transmission queue. . . . . . . 117
(MCAUSER) . . . . . . . . . . . . . 88
Triggering channels . . . . . . . . . . 117
Message exit name (MSGEXIT) . . . . . . . 88
Channel programs . . . . . . . . . . . . 119
Message exit user data (MSGDATA) . . . . . 89
Other things to consider . . . . . . . . . . 119
Message-retry exit name (MREXIT) . . . . . 89
Undelivered-message queue . . . . . . . 119
Message-retry exit user data (MRDATA) . . . . 89
Queues in use . . . . . . . . . . . . 120
Message retry count (MRRTY) . . . . . . . 89
Multiple message channels per transmission
Message retry interval (MRTMR) . . . . . . 89
queue . . . . . . . . . . . . . . . 120
Network-connection priority (NETPRTY) . . . 90
Security of MQSeries objects . . . . . . . 120
Nonpersistent message speed (NPMSPEED) . . 90
System extensions and user-exit programs . . . 121
Password (PASSWORD) . . . . . . . . . 90
PUT authority (PUTAUT). . . . . . . . . 90

iv MQSeries Intercommunication
 Running channels and listeners as trusted Configuring an invokable TP . . . . . . . 179
applications . . . . . . . . . . . . . 121 What next? . . . . . . . . . . . . . 181
What next? . . . . . . . . . . . . . . 122 Establishing a TCP connection. . . . . . . . 181
What next? . . . . . . . . . . . . . 181
Chapter 10. Setting up communication Establishing a NetBIOS connection . . . . . . 181
for OS/2 and Windows NT . . . . . . 123 Establishing an SPX connection . . . . . . . 182
IPX/SPX parameters . . . . . . . . . . 182
Deciding on a connection . . . . . . . . . 123
SPX addressing . . . . . . . . . . . . 183
Defining a TCP connection . . . . . . . . . 124
Receiving on SPX . . . . . . . . . . . 183
Sending end . . . . . . . . . . . . . 124
MQSeries for Windows NT configuration . . . . 184
Receiving on TCP . . . . . . . . . . . 124
Default configuration . . . . . . . . . . 184
Defining an LU 6.2 connection . . . . . . . 126
Basic configuration . . . . . . . . . . 184
Sending end for OS/2 . . . . . . . . . 127
Channel configuration . . . . . . . . . 185
Sending end for Windows NT . . . . . . . 127
Automatic startup . . . . . . . . . . . 189
Receiving on LU 6.2 . . . . . . . . . . 127
Running channels as processes or threads . . . 189
Defining a NetBIOS connection . . . . . . . 128
Defining the MQSeries local NetBIOS name . . 129
Establishing the queue manager NetBIOS Chapter 13. Setting up communication
session, command, and name limits . . . . . 130 in UNIX systems . . . . . . . . . . 191
Establishing the LAN adapter number . . . . 130 Deciding on a connection . . . . . . . . . 191
Initiating the connection . . . . . . . . . 130 Defining a TCP connection . . . . . . . . . 191
Target listener . . . . . . . . . . . . 131 Sending end . . . . . . . . . . . . . 191
Defining an SPX connection . . . . . . . . 131 Receiving on TCP . . . . . . . . . . . 192
Sending end . . . . . . . . . . . . . 131 Defining an LU 6.2 connection . . . . . . . 194
Receiving on SPX . . . . . . . . . . . 132 Sending end . . . . . . . . . . . . . 195
IPX/SPX parameters . . . . . . . . . . 133 Receiving on LU 6.2 . . . . . . . . . . 195

Chapter 11. Example configuration - Chapter 14. Example configuration -

IBM MQSeries for OS/2 Warp. . . . . 137 IBM MQSeries for AIX . . . . . . . . 197
Configuration parameters for an LU 6.2 connection 137 Configuration parameters for an LU 6.2 connection 197
Configuration worksheet . . . . . . . . 137 Configuration worksheet . . . . . . . . 197
Explanation of terms . . . . . . . . . . 140 Explanation of terms . . . . . . . . . . 200
Establishing an LU 6.2 connection . . . . . . 142 Establishing a session using Communications
Defining local node characteristics . . . . . 142 Server for AIX V5 . . . . . . . . . . . . 202
Connecting to a peer system . . . . . . . 150 Configuring your node . . . . . . . . . 202
Connecting to a host system . . . . . . . 153 Configuring connectivity to the network . . . 203
Verifying the configuration . . . . . . . . 157 Defining a local LU . . . . . . . . . . 205
What next? . . . . . . . . . . . . . 158 Defining a transaction program . . . . . . 206
Establishing a TCP connection. . . . . . . . 158 Establishing a TCP connection. . . . . . . . 209
What next? . . . . . . . . . . . . . 159 What next? . . . . . . . . . . . . . 209
Establishing a NetBIOS connection . . . . . . 160 Establishing a UDP connection . . . . . . . 209
Establishing an SPX connection . . . . . . . 160 What next? . . . . . . . . . . . . . 209
IPX/SPX parameters . . . . . . . . . . 160 MQSeries for AIX configuration . . . . . . . 209
SPX addressing . . . . . . . . . . . . 161 Basic configuration . . . . . . . . . . 210
Using the SPX KEEPALIVE option . . . . . 162 Channel configuration . . . . . . . . . 210
Receiving on SPX . . . . . . . . . . . 162
MQSeries for OS/2 Warp configuration. . . . . 162 Chapter 15. Example configuration -
Basic configuration . . . . . . . . . . 163 IBM MQSeries for DIGITAL UNIX
Channel configuration . . . . . . . . . 163
Running channels as processes or threads . . . 167
(Compaq Tru64 UNIX) . . . . . . . . 215
Establishing a TCP connection. . . . . . . . 215
What next? . . . . . . . . . . . . . 215
Chapter 12. Example configuration - | MQSeries for DIGITAL UNIX (Compaq Tru64
IBM MQSeries for Windows NT . . . . 169 | UNIX) configuration . . . . . . . . . . . 215
Configuration parameters for an LU 6.2 connection 169 | Basic configuration . . . . . . . . . . 216
Configuration worksheet . . . . . . . . 170 | Channel configuration . . . . . . . . . 216
Explanation of terms . . . . . . . . . . 172
Establishing an LU 6.2 connection . . . . . . 174 Chapter 16. Example configuration -
Configuring the local node . . . . . . . . 174
Adding a connection . . . . . . . . . . 176
IBM MQSeries for HP-UX . . . . . . 219
Adding a partner . . . . . . . . . . . 178 Configuration parameters for an LU 6.2 connection 219
Adding a CPI-C entry . . . . . . . . . 179 Configuration worksheet . . . . . . . . 219

Contents v
 Explanation of terms . . . . . . . . . . 222 Receiving channels using Cisco MultiNet for
Establishing a session using HP SNAplus2 . . . 223 OpenVMS . . . . . . . . . . . . . 279
SNAplus2 configuration . . . . . . . . . 223 Receiving channels using Attachmate PathWay
APPC configuration . . . . . . . . . . 227 for OpenVMS . . . . . . . . . . . . 280
HP-UX operation . . . . . . . . . . . 237 Receiving channels using Process Software
What next? . . . . . . . . . . . . . 237 Corporation TCPware . . . . . . . . . 280
Establishing a TCP connection. . . . . . . . 237 Defining an LU 6.2 connection . . . . . . . 281
What next? . . . . . . . . . . . . . 237 SNA configuration. . . . . . . . . . . 281
MQSeries for HP-UX configuration . . . . . . 238 Specifying SNA configuration parameters to
Basic configuration . . . . . . . . . . 238 MQSeries. . . . . . . . . . . . . . 283
Channel configuration . . . . . . . . . 238 Sample MQSeries configuration . . . . . . 284
Problem solving . . . . . . . . . . . 285
Chapter 17. Example configuration - Defining a DECnet Phase IV connection . . . . 285
IBM MQSeries for AT&T GIS UNIX Sending end . . . . . . . . . . . . . 286
Receiving on DECnet Phase IV . . . . . . 286
Version 2.2 . . . . . . . . . . . . 243 Defining a DECnet Phase V connection. . . . . 286
Configuration parameters for an LU 6.2 connection 243
Configuration worksheet . . . . . . . . 243
Explanation of terms . . . . . . . . . . 246
Chapter 20. Setting up communication
Establishing a connection using AT&T GIS SNA in Tandem NSK . . . . . . . . . . 289
Server . . . . . . . . . . . . . . . . 246 Deciding on a connection . . . . . . . . . 289
Defining local node characteristics . . . . . 247 SNA channels . . . . . . . . . . . . . 289
Connecting to a partner node . . . . . . . 249 LU 6.2 responder processes. . . . . . . . 291
Configuring a remote node . . . . . . . . 249 TCP channels . . . . . . . . . . . . . 291
What next? . . . . . . . . . . . . . 251 Communications examples . . . . . . . . . 292
Establishing a TCP connection. . . . . . . . 251 SNAX communications example . . . . . . 292
What next? . . . . . . . . . . . . . 251 ICE communications example . . . . . . . 299
MQSeries for AT&T GIS UNIX configuration . . . 251 TCP/IP communications example . . . . . 303
Basic configuration . . . . . . . . . . 252
Channel configuration . . . . . . . . . 252 Chapter 21. Message channel
planning example for distributed
Chapter 18. Example configuration - platforms . . . . . . . . . . . . . 305
IBM MQSeries for Sun Solaris . . . . 257 What the example shows . . . . . . . . . 305
Configuration parameters for an LU 6.2 connection 257 Queue manager QM1 example . . . . . . 307
Configuration worksheet . . . . . . . . 257 Queue manager QM2 example . . . . . . 308
Explanation of terms . . . . . . . . . . 260 Running the example. . . . . . . . . . . 309
Establishing a connection using SunLink Version Expanding this example . . . . . . . . . 309
9.1 . . . . . . . . . . . . . . . . . 261
SunLink 9.1 base configuration . . . . . . 261 Chapter 22. Example SINIX and
Configuring a PU 2.1 server . . . . . . . 262 DC/OSx configuration files. . . . . . 311
Adding a LAN connection . . . . . . . . 263
Configuration file on bight . . . . . . . . . 312
Configuring a connection to a remote PU . . . 264
Configuration file on forties . . . . . . . . 313
Configuring an independent LU . . . . . . 265
Working configuration files for Pyramid DC/OSx 313
Configuring a partner LU . . . . . . . . 267
Output of dbd command . . . . . . . . 314
Configuring the session mode . . . . . . . 268
Configuring a transaction program . . . . . 269
CPI-C side information . . . . . . . . . 270 Part 4. DQM in MQSeries for
What next? . . . . . . . . . . . . . 271 OS/390 . . . . . . . . . . . . . . 319
Establishing a TCP connection. . . . . . . . 271
What next? . . . . . . . . . . . . . 271
Chapter 23. Monitoring and
MQSeries for Sun Solaris configuration . . . . . 271
Basic configuration . . . . . . . . . . 272 controlling channels on OS/390 . . . 321
Channel configuration . . . . . . . . . 272 The DQM channel control function . . . . . . 321
Using the panels and the commands . . . . . 322
Using the initial panel . . . . . . . . . 322
Chapter 19. Setting up communication
Managing your channels . . . . . . . . . 324
in Digital OpenVMS systems . . . . . 277 Defining a channel . . . . . . . . . . 324
Deciding on a connection . . . . . . . . . 277 Altering a channel definition . . . . . . . 325
Defining a TCP connection . . . . . . . . . 278 Displaying a channel definition . . . . . . 325
Sending end . . . . . . . . . . . . . 278 Displaying information about DQM . . . . . 326
Receiving channels using Compaq (DIGITAL) Deleting a channel definition . . . . . . . 326
TCP/IP services (UCX) for OpenVMS . . . . 278

vi MQSeries Intercommunication
 Starting a channel initiator . . . . . . . . 327 Chapter 27. Preparing MQSeries for
Stopping a channel initiator . . . . . . . 328 OS/390 when using CICS . . . . . . 381
Starting a channel listener . . . . . . . . 329 Setting up CICS communication for MQSeries for
Stopping a channel listener . . . . . . . . 329 OS/390 . . . . . . . . . . . . . . . 381
Starting a channel . . . . . . . . . . . 330 Connecting CICS systems . . . . . . . . 381
Testing a channel . . . . . . . . . . . 331 Defining an LU 6.2 connection . . . . . . 382
Resetting message sequence numbers for a Installing the connection. . . . . . . . . 383
channel . . . . . . . . . . . . . . 332 Communications between CICS systems
Resolving in-doubt messages on a channel . . 333 attached to one queue manager . . . . . . 383
Stopping a channel . . . . . . . . . . 334 Defining DQM requirements to MQSeries . . . . 384
Displaying channel status . . . . . . . . 335 Defining MQSeries objects . . . . . . . . . 384
Displaying cluster channels. . . . . . . . 337 Multiple message channels per transmission
queue . . . . . . . . . . . . . . . 384
Chapter 24. Preparing MQSeries for Channel operation considerations . . . . . . 385
OS/390 . . . . . . . . . . . . . . 339
Setting up communication . . . . . . . . . 339 Chapter 28. Message channel
TCP setup . . . . . . . . . . . . . 339 planning example for OS/390 using
APPC/MVS setup . . . . . . . . . . . 341
CICS . . . . . . . . . . . . . . . 387
Defining DQM requirements to MQSeries . . . . 342
Defining MQSeries objects . . . . . . . . . 342
Synchronization queue . . . . . . . . . 343 Chapter 29. Example configuration -
Channel command queues . . . . . . . . 343 IBM MQSeries for OS/390 . . . . . . 395
Channel operation considerations . . . . . . 344 Configuration parameters for an LU 6.2 connection 395
OS/390 Automatic Restart Management (ARM) 344 Configuration worksheet . . . . . . . . 396
Explanation of terms . . . . . . . . . . 398
Chapter 25. Message channel Establishing an LU 6.2 connection . . . . . . 400
planning example for OS/390 . . . . 345 Defining yourself to the network . . . . . . 400
Defining a connection to a partner . . . . . 402
What the example shows . . . . . . . . . 345
What next? . . . . . . . . . . . . . 402
Queue manager QM1 example . . . . . . 346
Establishing an LU 6.2 connection using CICS . . 402
Queue manager QM2 example . . . . . . 347
Defining a connection . . . . . . . . . 402
Running the example. . . . . . . . . . . 349
Defining the sessions . . . . . . . . . . 403
Expanding this example . . . . . . . . . 349
Installing the new group definition . . . . . 404
What next? . . . . . . . . . . . . . 404
Chapter 26. Monitoring and Establishing a TCP connection. . . . . . . . 404
controlling channels in OS/390 with What next? . . . . . . . . . . . . . 405
CICS . . . . . . . . . . . . . . . 351 MQSeries for OS/390 configuration . . . . . . 405
The DQM channel control function . . . . . . 351 Channel configuration . . . . . . . . . 405
CICS regions . . . . . . . . . . . . 352 Defining a local queue . . . . . . . . . 409
Starting DQM panels . . . . . . . . . . 352 Defining a remote queue . . . . . . . . 412
The Message Channel List panel . . . . . . . 353 Defining a sender channel when not using CICS 413
Keyboard functions . . . . . . . . . . 353 Defining a receiver channel when not using
Selecting a channel . . . . . . . . . . 354 CICS . . . . . . . . . . . . . . . 415
Working with channels . . . . . . . . . 354 Defining a sender channel using CICS . . . . 417
Creating a channel . . . . . . . . . . 356 Defining a receiver channel using CICS . . . 418
Altering a channel. . . . . . . . . . . 356
Browsing a channel . . . . . . . . . . 356 Part 5. DQM in MQSeries for
Renaming a channel . . . . . . . . . . 357
Selected menu-bar choice . . . . . . . . 357 AS/400 . . . . . . . . . . . . . . 421
Edit menu-bar choice . . . . . . . . . . 367
View menu-bar choice . . . . . . . . . 371 Chapter 30. Monitoring and
Help menu-bar choice . . . . . . . . . 372 controlling channels in MQSeries for
The channel definition panels . . . . . . . . 372 AS/400 . . . . . . . . . . . . . . 423
Channel menu-bar choice . . . . . . . . 373 The DQM channel control function . . . . . . 423
Help menu-bar choice . . . . . . . . . 373 Operator commands . . . . . . . . . . . 424
Channel settings panel fields . . . . . . . . 374 Getting started . . . . . . . . . . . . . 426
Details of sender channel settings panel . . . 376 Creating objects . . . . . . . . . . . . 426
Details of receiver channel settings panel . . . 377 Creating a channel . . . . . . . . . . . 426
Details of server channel settings panel. . . . 378 | Starting a channel . . . . . . . . . . . . 429
Details of requester channel settings panel. . . 379 Selecting a channel . . . . . . . . . . . 430

Contents vii
Browsing a channel . . . . . . . . . . . 430 Chapter 34. Message channel
Renaming a channel . . . . . . . . . . . 432 planning example for OS/400 . . . . 477
Work with channel status . . . . . . . . . 432 What the example shows . . . . . . . . . 477
Work-with-channel choices . . . . . . . . . 434 Queue manager QM1 example . . . . . . 478
Panel choices . . . . . . . . . . . . . 435 Queue manager QM2 example . . . . . . 480
F6=Create . . . . . . . . . . . . . 435 Running the example. . . . . . . . . . . 482
2=Change . . . . . . . . . . . . . 436 Expanding this example . . . . . . . . . 482
3=Copy . . . . . . . . . . . . . . 436
4=Delete . . . . . . . . . . . . . . 437
5=Display . . . . . . . . . . . . . 437 Part 6. DQM in MQSeries for
8=Work with Status . . . . . . . . . . 437 VSE/ESA . . . . . . . . . . . . . 483
13=Ping . . . . . . . . . . . . . . 437
14=Start . . . . . . . . . . . . . . 437 Chapter 35. Example configuration -
15=End . . . . . . . . . . . . . . 438
16=Reset . . . . . . . . . . . . . . 439
MQSeries for VSE/ESA . . . . . . . 485
17=Resolve . . . . . . . . . . . . . 439 Configuration parameters for an LU 6.2 connection 485
Configuration worksheet . . . . . . . . 485
Explanation of terms . . . . . . . . . . 487
Chapter 31. Preparing MQSeries for Establishing an LU 6.2 connection . . . . . . 488
AS/400 . . . . . . . . . . . . . . 441 Defining a connection . . . . . . . . . 488
Creating a transmission queue. . . . . . . . 441 Defining a session . . . . . . . . . . . 488
Triggering channels . . . . . . . . . . . 443 Installing the new group definition . . . . . 489
Channel programs. . . . . . . . . . . . 445 What next? . . . . . . . . . . . . . 489
Channel states on OS/400 . . . . . . . . . 446 Establishing a TCP connection. . . . . . . . 490
Other things to consider . . . . . . . . . . 447 MQSeries for VSE/ESA configuration . . . . . 490
Undelivered-message queue . . . . . . . 447 Configuring channels. . . . . . . . . . 490
Queues in use . . . . . . . . . . . . 447 Defining a local queue . . . . . . . . . 493
Maximum number of channels . . . . . . 447 Defining a remote queue . . . . . . . . 495
Multiple message channels per transmission Defining a SNA LU 6.2 sender channel . . . . 497
queue . . . . . . . . . . . . . . . 447 Defining a SNA LU6.2 receiver channel. . . . 498
Security of MQSeries for AS/400 objects . . . 447 Defining a TCP/IP sender channel . . . . . 500
System extensions and user-exit programs . . . 448 Defining a TCP receiver channel . . . . . . 501

Chapter 32. Setting up communication Part 7. Further intercommunication

for MQSeries for AS/400 . . . . . . . 449
Deciding on a connection . . . . . . . . . 449
considerations . . . . . . . . . . 503
Defining a TCP connection . . . . . . . . . 449
Receiving on TCP . . . . . . . . . . . 450 Chapter 36. Channel-exit programs 505
Defining an LU 6.2 connection . . . . . . . 451 What are channel-exit programs? . . . . . . . 505
Initiating end (Sending) . . . . . . . . . 452 Processing overview . . . . . . . . . . 506
Initiated end (Receiver) . . . . . . . . . 455 Channel security exit programs . . . . . . 507
Channel send and receive exit programs . . . 512
Chapter 33. Example configuration - Channel message exit programs . . . . . . 514
Channel message retry exit program. . . . . 516
IBM MQSeries for AS/400 . . . . . . 459 Channel auto-definition exit program . . . . 516
Configuration parameters for an LU 6.2 connection 459 Transport-retry exit program . . . . . . . 517
Configuration worksheet . . . . . . . . 459 Writing and compiling channel-exit programs . . 518
Explanation of terms . . . . . . . . . . 462 MQSeries for OS/390 without CICS . . . . . 520
Establishing an LU 6.2 connection . . . . . . 464 MQSeries for OS/390 using CICS. . . . . . 521
Local node configuration . . . . . . . . 464 MQSeries for AS/400 . . . . . . . . . . 521
Connection to partner node . . . . . . . 465 MQSeries for OS/2 Warp . . . . . . . . 522
What next? . . . . . . . . . . . . . 469 Windows 3.1 client . . . . . . . . . . 524
Establishing a TCP connection. . . . . . . . 469 MQSeries for Windows NT server, MQSeries
Adding a TCP/IP interface . . . . . . . . 469 client for Windows NT, and MQSeries client for
Adding a TCP/IP loopback interface . . . . 469 Windows 95 and Windows 98 . . . . . . . 524
Adding a default route . . . . . . . . . 470 MQSeries for Windows . . . . . . . . . 526
What next? . . . . . . . . . . . . . 470 MQSeries for AIX . . . . . . . . . . . 526
MQSeries for AS/400 configuration . . . . . . 471 MQSeries for Compaq (DIGITAL) OpenVMS 528
Basic configuration . . . . . . . . . . 471 | MQSeries for DIGITAL UNIX (Compaq Tru64
Channel configuration . . . . . . . . . 471 | UNIX) . . . . . . . . . . . . . . . 529
Defining a queue . . . . . . . . . . . 475 MQSeries for HP-UX . . . . . . . . . . 530
Defining a channel . . . . . . . . . . 476

viii MQSeries Intercommunication

 MQSeries for AT&T GIS UNIX . . . . . . 531 C declaration . . . . . . . . . . . . 608
MQSeries for Sun Solaris . . . . . . . . 532 MQXWD - Exit wait descriptor structure . . . . 609
MQSeries for SINIX and DC/OSx . . . . . 532 Fields . . . . . . . . . . . . . . . 609
MQSeries for Tandem NonStop Kernel . . . . 533 C declaration . . . . . . . . . . . . 610
Supplied channel-exit programs using DCE System/390 assembler declaration . . . . . 610
security services . . . . . . . . . . . . 537
What do the DCE channel-exit programs do? 537 Chapter 38. Problem determination in
How do the DCE channel-exit programs work? 538 DQM . . . . . . . . . . . . . . . 611
How to use the DCE channel-exit programs . . 540
Error message from channel control . . . . . . 611
Ping . . . . . . . . . . . . . . . . 611
Chapter 37. Channel-exit calls and Dead-letter queue considerations . . . . . . . 612
data structures. . . . . . . . . . . 543 Validation checks . . . . . . . . . . . . 612
Data definition files . . . . . . . . . . . 544 In-doubt relationship . . . . . . . . . . . 613
MQ_CHANNEL_EXIT - Channel exit . . . . . 546 Channel startup negotiation errors . . . . . . 613
Syntax. . . . . . . . . . . . . . . 546 When a channel refuses to run . . . . . . . 613
Parameters . . . . . . . . . . . . . 546 Triggered channels . . . . . . . . . . 614
Usage notes . . . . . . . . . . . . . 548 Conversion failure. . . . . . . . . . . 615
C invocation. . . . . . . . . . . . . 549 Network problems . . . . . . . . . . 615
COBOL invocation . . . . . . . . . . 549 Dial-up problems . . . . . . . . . . . 615
PL/I invocation . . . . . . . . . . . 549 Retrying the link . . . . . . . . . . . . 615
RPG invocation (ILE) . . . . . . . . . . 549 Retry considerations . . . . . . . . . . 615
RPG invocation (OPM) . . . . . . . . . 550 Data structures . . . . . . . . . . . . . 616
System/390® assembler invocation . . . . . 550 User exit problems . . . . . . . . . . . 616
MQ_CHANNEL_AUTO_DEF_EXIT - Channel Disaster recovery . . . . . . . . . . . . 616
auto-definition exit . . . . . . . . . . . 551 Channel switching. . . . . . . . . . . . 617
Syntax. . . . . . . . . . . . . . . 551 Connection switching. . . . . . . . . . . 617
Parameters . . . . . . . . . . . . . 551 Client problems . . . . . . . . . . . . 617
Usage notes . . . . . . . . . . . . . 551 Terminating clients . . . . . . . . . . 617
C invocation. . . . . . . . . . . . . 552 Error logs . . . . . . . . . . . . . . 618
COBOL invocation . . . . . . . . . . 552 Error logs for OS/2 and Windows NT . . . . 618
RPG invocation (ILE) . . . . . . . . . . 552 Error logs on UNIX systems . . . . . . . 618
RPG invocation (OPM) . . . . . . . . . 552 Error logs on DOS, Windows 3.1, and Windows
System/390 assembler invocation. . . . . . 552 95 and Windows 98 clients . . . . . . . . 618
MQXWAIT - Wait . . . . . . . . . . . . 553 Error logs on OS/390. . . . . . . . . . 619
Syntax. . . . . . . . . . . . . . . 553 Error logs on MQSeries for Windows . . . . 619
Parameters . . . . . . . . . . . . . 553 Error logs on MQSeries for VSE/ESA . . . . 619
C invocation. . . . . . . . . . . . . 554 | Error logs on MQSeries for Tandem NSK . . . 619
System/390 assembler invocation. . . . . . 554
MQ_TRANSPORT_EXIT - Transport retry exit . . 555
Syntax. . . . . . . . . . . . . . . 555
Part 8. Appendixes . . . . . . . . 621
Parameters . . . . . . . . . . . . . 555
Usage notes . . . . . . . . . . . . . 555 Appendix A. Channel planning form 623
C invocation. . . . . . . . . . . . . 555 How to use the form . . . . . . . . . . . 623
MQCD - Channel data structure . . . . . . . 556
Fields . . . . . . . . . . . . . . . 558 Appendix B. Constants for channels
C declaration . . . . . . . . . . . . 580 and exits . . . . . . . . . . . . . 627
COBOL declaration . . . . . . . . . . 582 List of constants . . . . . . . . . . . . 627
PL/I declaration . . . . . . . . . . . 584 MQ_* (Lengths of character string and byte
ILE RPG declaration . . . . . . . . . . 585 fields) . . . . . . . . . . . . . . . 627
OPM RPG declaration . . . . . . . . . 587 MQCD_* (Channel definition structure length) 628
System/390 assembler declaration . . . . . 589 MQCD_* (Channel definition structure version) 628
MQCXP - Channel exit parameter structure . . . 591 MQCDC_* (Channel data conversion) . . . . 628
Fields . . . . . . . . . . . . . . . 591 MQCF_* (Channel capability flags) . . . . . 628
C declaration . . . . . . . . . . . . 601 MQCHT_* (Channel type) . . . . . . . . 628
COBOL declaration . . . . . . . . . . 601 MQCXP_* (Channel-exit parameter structure
PL/I declaration . . . . . . . . . . . 602 identifier). . . . . . . . . . . . . . 628
ILE RPG declaration . . . . . . . . . . 602 MQCXP_* (Channel-exit parameter structure
OPM RPG declaration . . . . . . . . . 603 version) . . . . . . . . . . . . . . 629
System/390 assembler declaration . . . . . 604 MQMCAT_* (MCA type) . . . . . . . . 629
MQTXP - Transport-exit data structure . . . . . 605 MQNPMS_* (Nonpersistent message speed) . . 629
Fields . . . . . . . . . . . . . . . 605

Contents ix
 MQPA_* (Put authority) . . . . . . . . . 629 Glossary of terms and abbreviations 645
MQSID_* (Security identifier) . . . . . . . 629
MQSIDT_* (Security identifier type) . . . . . 630 Bibliography . . . . . . . . . . . . 659
MQTXP_* (Transport retry exit structure
MQSeries cross-platform publications . . . . . 659
identifier). . . . . . . . . . . . . . 630
MQSeries platform-specific publications . . . . 661
MQTXP_* (Transport retry exit version) . . . 630
Softcopy books . . . . . . . . . . . . . 662
MQXCC_* (Exit response) . . . . . . . . 630
BookManager format . . . . . . . . . . 662
MQXPT_* (Transmission protocol type). . . . 630
HTML format . . . . . . . . . . . . 662
MQXR_* (Exit reason) . . . . . . . . . 630
Portable Document Format (PDF) . . . . . 662
MQXR2_* (Secondary exit response) . . . . . 630
PostScript format . . . . . . . . . . . 662
MQXT_* (Exit identifier). . . . . . . . . 631
Windows Help format . . . . . . . . . 662
MQXUA_* (Exit user area) . . . . . . . . 631
MQSeries information available on the Internet . . 662
| MQXWD_* (Exit wait descriptor structure
Related publications . . . . . . . . . . . 662
| identifier). . . . . . . . . . . . . . 631
Programming . . . . . . . . . . . . 662
| MQXWD_* (Exit wait descriptor version) . . . 631
OS/390 . . . . . . . . . . . . . . 662
CICS . . . . . . . . . . . . . . . 662
Appendix C. Queue name resolution 633 OS/400 . . . . . . . . . . . . . . 663
What is queue name resolution? . . . . . . . 635 Digital. . . . . . . . . . . . . . . 663
How queue name resolution works . . . . . 636 SNA . . . . . . . . . . . . . . . 663
SINIX . . . . . . . . . . . . . . . 663
Appendix D. Configuration file stanzas
for distributed queuing . . . . . . . 637 Index . . . . . . . . . . . . . . . 665

Appendix E. Notices . . . . . . . . 641 Sending your comments to IBM . . . 679

Programming interface information . . . . . . 642
Trademarks . . . . . . . . . . . . . . 643

x MQSeries Intercommunication
Figures
1. Overview of the components of distributed 43. Resetting channel sequence numbers 332
queuing . . . . . . . . . . . . . . 4 44. Resolving in-doubt messages . . . . . . 333
2. Sending messages . . . . . . . . . . . 5 45. Stopping a channel . . . . . . . . . 334
3. Sending messages in both directions . . . . 6 46. Listing channel connections . . . . . . . 336
4. A cluster of queue managers . . . . . . . 7 47. Displaying channel connections - first panel 337
5. A sender-receiver channel . . . . . . . . 8 48. Displaying channel connections - second
6. A cluster-sender channel . . . . . . . . 8 panel . . . . . . . . . . . . . . 337
7. A requester-server channel . . . . . . . . 9 49. Listing cluster channels . . . . . . . . 338
8. A requester-sender channel. . . . . . . . 9 50. The message channel example for MQSeries
9. Channel initiators and listeners . . . . . . 11 for OS/390 . . . . . . . . . . . . 345
10. Sequence in which channel exit programs are 51. Sample configuration of channel control and
called . . . . . . . . . . . . . . 13 MCA . . . . . . . . . . . . . . 352
11. Passing through intermediate queue managers 14 52. The Message Channel List panel . . . . . 353
12. Sharing a transmission queue . . . . . . 15 53. The Message Channel List panel pull-down
13. Using multiple channels . . . . . . . . 15 menus . . . . . . . . . . . . . . 355
14. The concepts of triggering . . . . . . . 21 54. The Channel pull-down menu . . . . . . 357
15. Queue manager alias . . . . . . . . . 27 55. Sender/server Stop action window . . . . 360
16. Reply-to queue alias used for changing reply 56. Requester/receiver Stop action window 361
location . . . . . . . . . . . . . . 28 57. The Reset Channel Sequence Number action
17. Network diagram showing all channels 30 window . . . . . . . . . . . . . 363
18. Network diagram showing QM-concentrators 32 58. The Resolve Channel action window 364
19. A remote queue definition is used to resolve a 59. An example of a sender channel Display
queue name to a transmission queue to an Channel Status window . . . . . . . . 365
adjacent queue manager . . . . . . . . 38 60. An example of a receiver channel Display
20. The remote queue definition allows a different Channel Status window . . . . . . . . 365
transmission queue to be used . . . . . . 39 61. The Ping action window . . . . . . . . 366
21. Receiving messages directly, and resolving 62. The Exit confirmation secondary window 367
alias queue manager name . . . . . . . 40 63. The Copy action window . . . . . . . 368
22. Three methods of passing messages through 64. The Create action window . . . . . . . 369
your system . . . . . . . . . . . . 41 65. Example of default values during Create for a
23. Separating messages flows . . . . . . . 43 channel . . . . . . . . . . . . . 369
24. Combining message flows on to a channel 44 66. The Delete action window . . . . . . . 370
25. Diverting message streams to another 67. The Find a Channel action window . . . . 370
destination . . . . . . . . . . . . . 45 68. The Include search criteria action window 371
26. Reply-to queue name substitution during PUT 69. The Help pull-down menu . . . . . . . 372
call . . . . . . . . . . . . . . . 47 70. The Help choice pull-down menu. . . . . 373
27. Reply-to queue alias example . . . . . . 49 71. The sender channel settings panel. . . . . 376
28. Distributed queue management model . . . 58 72. The sender channel settings panel - screen 2 376
29. Channel states . . . . . . . . . . . 62 73. The receiver channel settings panel . . . . 377
30. Flows between channel states . . . . . . 63 74. The receiver channel settings panel - screen 2 377
31. What happens when a message cannot be 75. The server channel settings panel . . . . . 378
delivered . . . . . . . . . . . . . 72 76. The server channel settings panel - screen 2 378
32. MQSeries channel to be set up in the example 77. The requester channel settings panel . . . . 379
configuration chapters in this book. . . . . 97 78. The requester channel settings panel - screen
33. Local LU window . . . . . . . . . . 205 2. . . . . . . . . . . . . . . . 379
34. Mode window . . . . . . . . . . . 206 79. CICS LU 6.2 connection definition . . . . 383
35. CPI-C side information file for SunLink 80. Connecting two queue managers in MQSeries
Version 9.0 . . . . . . . . . . . . 271 for OS/390 using CICS . . . . . . . . 387
36. The message channel example for OS/2, 81. Sender settings (1) . . . . . . . . . . 389
Windows NT, and UNIX systems . . . . . 306 82. Sender settings (2) . . . . . . . . . . 390
37. The operations and controls initial panel 322 83. Connection definition (1). . . . . . . . 390
38. Listing channels. . . . . . . . . . . 323 84. Connection definition (2). . . . . . . . 391
39. Starting a system function . . . . . . . 327 85. Connection definition (1). . . . . . . . 391
40. Stopping a function control . . . . . . . 328 86. Connection definition (2). . . . . . . . 392
41. Starting a channel . . . . . . . . . . 330 87. Receiver channel settings (1) . . . . . . 392
42. Testing a channel . . . . . . . . . . 331 88. Receiver channel settings (2) . . . . . . 393

© Copyright IBM Corp. 1993, 2000 xi

 89. Channel Initiator APPL definition . . . . . 401 122. Sample DEF file for a channel exit on OS/2 523
90. Channel Initiator initialization parameters 401 123. Sample make file for a channel exit on OS/2 523
91. Channel Initiator initialization parameters 405 124. Sample source code for a channel exit on
92. Create channel (1) . . . . . . . . . . 427 Windows 3.1 . . . . . . . . . . . . 524
93. Create channel (2) . . . . . . . . . . 428 125. Sample source code for a channel exit on
94. Create channel (3) . . . . . . . . . . 428 Windows NT, Windows 95, or Windows 98 . 525
95. Create channel (4) . . . . . . . . . . 429 126. Sample DEF file for Windows NT, Windows
96. Work with channels . . . . . . . . . 430 95, Windows 98, or Windows . . . . . . 526
97. Display a TCP/IP channel (1) . . . . . . 431 127. Sample source code for a channel exit on
98. Display a TCP/IP channel (2) . . . . . . 431 Windows . . . . . . . . . . . . . 526
99. Display a TCP/IP channel (3) . . . . . . 432 128. Sample source code for a channel exit on AIX 527
100. Channel status (1) . . . . . . . . . . 433 129. Sample compiler and loader commands for
101. Channel status (2) . . . . . . . . . . 433 channel exits on AIX . . . . . . . . . 527
102. Channel status (3) . . . . . . . . . . 434 130. Sample export file for AIX . . . . . . . 528
103. Create a queue (1) . . . . . . . . . . 441 131. Sample make file for AIX . . . . . . . 528
104. Create a queue (2) . . . . . . . . . . 442 132. Sample source code for a channel exit on
105. Create a queue (3) . . . . . . . . . . 442 Digital OVMS . . . . . . . . . . . 528
106. Create a queue (4) . . . . . . . . . . 443 | 133. Sample source code for a channel exit on
107. Create process (1) . . . . . . . . . . 444 | DIGITAL UNIX . . . . . . . . . . . 530
108. Create process (2) . . . . . . . . . . 445 | 134. Sample compiler and loader commands for
109. LU 6.2 communication setup panel - initiating | channel exits on DIGITAL UNIX . . . . . 530
end . . . . . . . . . . . . . . . 452 135. Sample source code for a channel exit on
110. LU 6.2 communication setup panel - initiated HP-UX. . . . . . . . . . . . . . 531
end . . . . . . . . . . . . . . . 455 136. Sample compiler and loader commands for
111. LU 6.2 communication setup panel - initiated channel exits on HP-UX . . . . . . . . 531
end . . . . . . . . . . . . . . . 456 137. Sample source code for a channel exit on
112. The message channel example for MQSeries AT&T GIS UNIX . . . . . . . . . . 531
for AS/400 . . . . . . . . . . . . 477 138. Sample compiler and loader commands for
113. Channel configuration panel . . . . . . 501 channel exits on AT&T GIS UNIX . . . . . 532
114. Security exit loop . . . . . . . . . . 506 139. Sample source code for a channel exit on Sun
115. Example of a send exit at the sender end of Solaris . . . . . . . . . . . . . . 532
message channel . . . . . . . . . . 506 140. Sample compiler and loader commands for
116. Example of a receive exit at the receiver end channel exits on Sun Solaris. . . . . . . 532
of message channel . . . . . . . . . 507 141. Sample source code for a channel exit on
117. Sender-initiated exchange with agreement 509 SINIX and DC/OSx . . . . . . . . . 533
118. Sender-initiated exchange with no agreement 510 142. Sample compiler and loader commands for
119. Receiver-initiated exchange with agreement 511 channel exits on SINIX and DC/OSx. . . . 533
120. Receiver-initiated exchange with no 143. Security exit flows . . . . . . . . . . 538
agreement. . . . . . . . . . . . . 511 144. Name resolution . . . . . . . . . . 633
121. Sample source code for a channel exit on 145. qm.ini stanzas for distributed queuing 638
OS/2 . . . . . . . . . . . . . . 522

xii MQSeries Intercommunication

 Tables
1. Example of channel names . . . . . . . 30 25. Configuration worksheet for AT&T GIS SNA
2. Three ways of using the remote queue Services . . . . . . . . . . . . . 243
definition object . . . . . . . . . . . 37 26. Configuration worksheet for MQSeries for
3. Reply-to queue alias . . . . . . . . . 51 AT&T GIS UNIX . . . . . . . . . . 253
4. Queue name resolution at queue manager 27. Configuration worksheet for SunLink Version
QMA . . . . . . . . . . . . . . 54 9.1 . . . . . . . . . . . . . . . 257
5. Queue name resolution at queue manager 28. Configuration worksheet for MQSeries for
QMB . . . . . . . . . . . . . . . 54 Sun Solaris . . . . . . . . . . . . 272
6. Reply-to queue name translation at queue 29. Channel tasks . . . . . . . . . . . 324
manager QMA . . . . . . . . . . . 54 30. Settings on the local OS/390 system for a
7. Functions available in OS/2, Windows NT, remote queue manager platform . . . . . 341
Digital OpenVMS, Tandem NSK, and UNIX 31. Program and transaction names . . . . . 351
systems . . . . . . . . . . . . . 106 32. Message Channel List menu-bar choices 354
8. Channel attributes for the channel types in 33. Menu-bar choices on channel panels . . . . 372
OS/2, Windows NT, Digital OpenVMS, 34. Channel attribute fields per channel type 374
Tandem NSK, and UNIX systems . . . . . 111 35. Settings for LU 6.2 TP name on the local
9. Channel programs for OS/2 and Windows OS/390 system for a remote queue manager
NT . . . . . . . . . . . . . . . 119 platform . . . . . . . . . . . . . 374
10. Channel programs for UNIX systems, Digital 36. Configuration worksheet for OS/390 using
OpenVMS, and Tandem NSK . . . . . . 119 LU 6.2 . . . . . . . . . . . . . . 396
11. Default outstanding connection requests on 37. Configuration worksheet for MQSeries for
OS/2 and Windows NT . . . . . . . . 125 OS/390 . . . . . . . . . . . . . 406
12. Settings on the local OS/2 or Windows NT 38. Channel attribute fields per message channel
system for a remote queue manager platform . 126 type. . . . . . . . . . . . . . . 435
13. Default outstanding connection requests on 39. Program and transaction names . . . . . 445
OS/2 and Windows NT . . . . . . . . 132 | 40. Channel states on OS/400 . . . . . . . 446
14. Configuration worksheet for Communications 41. Settings on the local OS/400 system for a
Manager/2 . . . . . . . . . . . . 138 remote queue manager platform . . . . . 451
15. Configuration worksheet for MQSeries for 42. Configuration worksheet for SNA on an
OS/2 Warp . . . . . . . . . . . . 164 AS/400 system . . . . . . . . . . . 460
16. Configuration worksheet for IBM 43. Configuration worksheet for MQSeries for
Communications Server for Windows NT . . 170 AS/400 . . . . . . . . . . . . . 472
17. Configuration worksheet for MQSeries for 44. Configuration worksheet for VSE/ESA using
Windows NT . . . . . . . . . . . 185 APPC . . . . . . . . . . . . . . 485
18. Default outstanding connection requests 193 45. Configuration worksheet for MQSeries for
19. Settings on the local UNIX system for a VSE/ESA . . . . . . . . . . . . . 490
remote queue manager platform . . . . . 194 46. Channel exits available for each channel type 505
20. Configuration worksheet for Communications 47. Identifying API calls . . . . . . . . . 514
Server for AIX . . . . . . . . . . . 197 48. Fields in MQCD . . . . . . . . . . 556
21. Configuration worksheet for MQSeries for 49. Fields in MQCXP . . . . . . . . . . 591
AIX . . . . . . . . . . . . . . . 211 50. Fields in MQTXP . . . . . . . . . . 605
| 22. Configuration worksheet for MQSeries for 51. Fields in MQXWD . . . . . . . . . . 609
| DIGITAL UNIX (Compaq Tru64 UNIX) . . . 216 52. Channel planning form . . . . . . . . 625
23. Configuration worksheet for HP SNAplus2 219 53. Channel planning form . . . . . . . . 626
24. Configuration worksheet for MQSeries for
HP-UX. . . . . . . . . . . . . . 239

© Copyright IBM Corp. 1993, 2000 xiii

xiv MQSeries Intercommunication
About this book
This book describes intercommunication between MQSeries products. It introduces
the concepts of intercommunication; transmission queues, message channel agent
programs, and communication links, that are brought together to form message
channels. It describes how geographically separated queue managers are linked
together by message channels to form a network of queue managers. It discusses
the distributed-queuing management (DQM) facility of IBM® MQSeries, which
provides the services that enable applications to communicate via queue managers.

DQM provides communications that conform to the MQSeries Message Channel

Protocol. Each MQSeries product has its own implementation of this specification,
and this book is concerned with these implementations.

Who this book is for

This book is for anyone needing a description of DQM. In addition, the following
readers are specifically addressed:
v Network planners responsible for designing the overall queue manager network.
v Local channel planners responsible for implementing the network plan on one
node.
v Application programmers responsible for designing applications that include
processes, queues, and channels, perhaps without the assistance of a systems
administrator.
v Systems administrators responsible for monitoring the local system, controlling
exception situations, and implementing some of the planning details.
v System programmers with responsibility for designing and programming the
user exits.

What you need to know to understand this book

To use and control DQM you need to have a good knowledge of MQSeries in
general. You also need to understand the MQSeries products for the specific
platforms you will be using, and the communications protocols that will be used
on those platforms.

© Copyright IBM Corp. 1993, 2000 xv

About this book

How to use this book

This book has the following parts:
“Part 1. Introduction” on page 1
Introduces the concepts of MQSeries intercommunication.
“Part 2. How intercommunication works” on page 33
Describes the functions performed by the distributed-queuing management
(DQM) facilities. Read this part to understand DQM’s role in the context of
MQSeries.
“Part 3. DQM in MQSeries for OS/2 Warp, Windows NT, Digital OpenVMS,
Tandem NSK, and UNIX systems” on page 101
Is specific to MQSeries products on distributed platforms. It helps you to
install and customize DQM on these platforms. It explains how to establish
message channels to other systems and how to manage and control them.
“Part 4. DQM in MQSeries for OS/390” on page 319
Is specific to MQSeries for OS/390. It helps you to install and customize
DQM. It explains how to establish message channels to other systems and
how to manage and control them.
“Part 5. DQM in MQSeries for AS/400” on page 421
Is specific to MQSeries for AS/400. It helps you to install and customize
DQM. It explains how to establish message channels to other systems and
how to manage and control them.
“Part 6. DQM in MQSeries for VSE/ESA” on page 483
Is specific to MQSeries for VSE/ESA. It contains an example of how to set
up communication to other systems.
“Part 7. Further intercommunication considerations” on page 503
Tells you about channel exit programs, which are an optional feature of
DQM that allow you to add your own facilities to distributed queuing. It
gives some guidance on the problems you may experience, how to
recognize these problems, and what to do about them.
The Appendixes
contain extra information that is pertinent to DQM:
Appendix A. Channel planning form gives an explanation of one suggested
method of planning and maintaining DQM objects and channels.
Appendix B. Constants for channels and exits gives the values of named
constants that apply to the channels and exits in the MQI that are
discussed in this book.
Appendix C. Queue name resolution provides a detailed description of
name resolution by queue managers. You need to understand this process
in order to take full advantage of DQM.
Appendix D. Configuration file stanzas for distributed queuing gives
information about the configuration file stanzas that relate to distributed
queuing.

Appearance of text in this book

This book uses the following type styles:
CompCode
Example of the name of a parameter of a call

xvi MQSeries Intercommunication

 About this book
Terms used in this book
In the body of this book, the following shortened names are used:
CICS® The CICS Transaction Server for OS/390 (CICS/Enterprise Systems
Architecture) product. (Note that, unlike other MQSeries books, this book
does not use the term generically to include other CICS products such as
CICS for VSE/ESA.)
OS/2 OS/2 Warp
OS/390
In general, function described in this book as supported by MQSeries for
OS/390 is also supported by MQSeries for MVS/ESA™.

The term “UNIX systems” is used to denote the following UNIX operating
systems:
v AIX
v AT&T GIS UNIX
| v Digital UNIX (Compaq Tru64 UNIX)
v HP-UX
v SINIX and DC/OSx
v Sun Solaris

Throughout this book, the name mqmtop has been used to represent the name of
the base directory where MQSeries is installed on UNIX systems.
v For AIX, the name of the actual directory is /usr/mqm
v For other UNIX systems, the name of the actual directory is /opt/mqm

There is a glossary and a bibliography at the back of the book.

About this book xvii

About this book

xviii MQSeries Intercommunication

 Summary of changes
This information describes changes to the MQSeries product and changes to this
edition of the MQSeries Intercommunication book.

Changes since the previous edition of the book are marked in the left-hand margin
| with vertical bars.
|
| Changes for this edition (SC33-1872-03)
| This edition of MQSeries Intercommunication includes:
| v Addition of support for MQSeries for AS/400 V5.1.
| v Addition of support for MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX),
| V2.2.1.
| v Addition of support for MQSeries for Tandem NonStop Kernel, V2.2.0.1.
|
Changes for the previous edition (SC33-1872-02)
The previous edition of MQSeries Intercommunication applies to the following
versions and releases of MQSeries products:
v MQSeries for AIX V5.1
v MQSeries for AS/400 V4R2M1
v MQSeries for HP-UX V5.1
v MQSeries for OS/2 Warp V5.1
v MQSeries for OS/390 V2.1
v MQSeries for Sun Solaris V5.1
v MQSeries for VSE/ESA V2.1
v MQSeries for Windows NT V5.1

Major new function supplied with each of these MQSeries products is summarized
below:
v Additional new function and changes in MQSeries for OS/390
– Automatic Restart Manager (ARM).
– TCP OpenEdition® sockets interface.
– Screens in “Chapter 23. Monitoring and controlling channels on OS/390” on
page 321.
v MQSeries queue manager clusters implemented on MQSeries for AIX, HP-UX,
OS/2 Warp, OS/390, Sun Solaris, and Windows NT.
v Using the TCP listener backlog option on UNIX systems.
v Additional new function in MQSeries for AIX, V5.1
– The UDP transport protocol is supported.
– Sybase databases can participate in global units of work.
– Multithreaded channels are supported.
– “Configuration parameters for an LU 6.2 connection” on page 197.
v Additional new function in MQSeries for HP-UX, V5.1
– MQSeries for HP-UX, V5.1 runs on both HP-UX V10.20 and HP-UX V11.0.
– Multithreaded channels are supported.
– Both HP-UX kernel threads and DCE threads are supported.

© Copyright IBM Corp. 1993, 2000 xix

Changes
v Additional new function in MQSeries for Sun Solaris, V5.1
– MQSeries for Sun Solaris, V5.1 runs on both Sun Solaris V2.6 and Sun Solaris
7.
– Sybase databases can participate in global units of work.
– Multithreaded channels are supported.
– “Establishing a connection using SunLink Version 9.1” on page 261.
v Windows NT registry—now used to hold all configuration and related data. The
contents of any configuration (.INI) files from previous MQSeries installations of
MQSeries for Windows NT products are migrated into the registry; the .INI files
are then deleted.
v “MQSeries for VSE/ESA configuration” on page 490.
v Transport-retry exit program for MQSeries for AIX V5.1 and MQSeries for
Windows V2.0.
v ADOPTNEWMCA, ADOPTNEWMCATIMEOUT, and ADOPTNEWMCACHECK
configuration stanzas.

Changes for the second edition (SC33-1872-01)

Major changes for the second edition include:
v Addition of support for MQSeries for AS/400 V4R2.
v Addition of support for MQSeries for Tandem NonStop Kernel, V2.2.
v Addition of an example LU 6.2 configuration using IBM Communications Server
for Windows NT.
v Technical improvements throughout the book.

xx MQSeries Intercommunication
Part 1. Introduction
Chapter 1. Concepts of intercommunication . . . 3 How to send a message to another queue manager 17
What is intercommunication? . . . . . . . . . 3 Defining the channels . . . . . . . . . . 18
How does distributed queuing work? . . . . . 3 Defining the queues . . . . . . . . . . 19
What do we call the components? . . . . . 4 Sending the messages . . . . . . . . . . 20
Components needed to send a message . . . 5 Starting the channel . . . . . . . . . . 20
Components needed to return a message . . . 5 Triggering channels. . . . . . . . . . . . 20
Cluster components . . . . . . . . . . 6 Safety of messages . . . . . . . . . . . . 22
Distributed queuing components . . . . . . . 7 Fast, nonpersistent messages . . . . . . . 22
Message channels. . . . . . . . . . . . 7 Undelivered messages . . . . . . . . . . 23
Sender-receiver channels . . . . . . . . 8
Server-receiver channel . . . . . . . . . 8 Chapter 3. More about intercommunication . . . 25
Cluster-sender channels. . . . . . . . . 8 Addressing information . . . . . . . . . . 25
Requester-server channel . . . . . . . . 9 What are aliases? . . . . . . . . . . . . 25
Requester-sender channel . . . . . . . . 9 Queue name resolution . . . . . . . . . 26
Cluster-receiver channels . . . . . . . . 9 Queue manager alias definitions . . . . . . . 26
Message channel agents . . . . . . . . . 9 Outbound messages - remapping the queue
Transmission queues . . . . . . . . . . 10 manager name . . . . . . . . . . . . 26
Channel initiators and listeners . . . . . . . 10 Outbound messages - altering or specifying the
Channel-exit programs . . . . . . . . . 12 transmission queue . . . . . . . . . . . 27
Dead-letter queues . . . . . . . . . . . . 13 Inbound messages - determining the destination 27
Remote queue definitions. . . . . . . . . . 14 Reply-to queue alias definitions . . . . . . . 28
How to get to the remote queue manager . . . . 14 What is a reply-to queue alias definition? . . . 28
Multi-hopping . . . . . . . . . . . . 14 Reply-to queue name . . . . . . . . . . 29
Sharing channels . . . . . . . . . . . 14 Networks . . . . . . . . . . . . . . . 29
Using different channels . . . . . . . . . 15 Channel and transmission queue names . . . . 29
Using clustering . . . . . . . . . . . . 16 Network planner . . . . . . . . . . . 31

Chapter 2. Making your applications

communicate . . . . . . . . . . . . . 17

This part of the book introduces MQSeries intercommunication. The description in

this part is general, and is not restricted to a particular platform or system.

Note: Some references are made to individual MQSeries products. Details are
given only for the products that this edition of the book applies to (see the
edition notice for information about which MQSeries products these are).

© Copyright IBM Corp. 1993, 2000 1

Introduction

2 MQSeries Intercommunication
Chapter 1. Concepts of intercommunication
This chapter introduces the concepts of intercommunication in MQSeries.
v The basic concepts of intercommunication are explained in “What is
intercommunication?”
v The objects that you need for intercommunication are described in “Distributed
queuing components” on page 7.

This chapter goes on to introduce:

v “Dead-letter queues” on page 13
v “Remote queue definitions” on page 14
v “How to get to the remote queue manager” on page 14

What is intercommunication?
In MQSeries, intercommunication means sending messages from one queue
manager to another. The receiving queue manager could be on the same machine
or another; nearby or on the other side of the world. It could be running on the
same platform as the local queue manager, or could be on any of the platforms
supported by MQSeries. This is called a distributed environment. MQSeries handles
communication in a distributed environment such as this using Distributed Queue
Management (DQM).

The local queue manager is sometimes called the source queue manager and the
remote queue manager is sometimes called the target queue manager or the partner
queue manager.

How does distributed queuing work?

Figure 1 on page 4 shows an overview of the components of distributed queuing.

© Copyright IBM Corp. 1993, 2000 3

What is intercommunication?

M QOPEN

QM1 QM2

M essage
QUEUE S to re
DEFNS

QUEUE
M essage DEFNS
S to re

Transport Service
M o v in g M o v in g
S e r v ic e S e r v ic e

Figure 1. Overview of the components of distributed queuing

1. An application uses the MQOPEN call to open a queue so that it can put
messages on it.
2. A queue manager has a definition for each of its queues, specifying information
such as the maximum number of messages allowed on the queue.
3. If the messages are destined for a queue on a remote system, the local queue
manager holds them in a message store until it is ready to forward them to the
remote queue manager. This can be transparent to the application.
4. Each queue manager contains communications software called the moving
service component; through this, the queue manager can communicate with
other queue managers.
5. The transport service is independent of the queue manager and can be any one
of the following (depending on the platform):
v Systems Network Architecture Advanced Program-to Program
Communication (SNA APPC)
v Transmission Control Protocol/Internet Protocol (TCP/IP)
v Network Basic Input/Output System (NetBIOS)
v Sequenced Packet Exchange (SPX)
v User-Datagram Protocol (UDP)

What do we call the components?

1. MQSeries applications put messages onto a local queue, that is, a queue on the
same queue manager.
2. A queue manager has a definition for each of its queues. It may also have
definitions for queues that are owned by other queue managers. These are
called remote queue definitions.
3. If the messages are destined for a remote queue manager, the local queue
manager stores them on a transmission queue until it is ready to send them to
the remote queue manager. A transmission queue is a special type of local
queue on which messages are stored until they can be successfully transmitted
and stored at the remote queue manager.
4. The software that handles the sending and receiving of messages is called the
Message Channel Agent (MCA).

4 MQSeries Intercommunication
 What is intercommunication?
5. Messages are transmitted between queue managers on a channel. A channel is a
one-way communication link between two queue managers. It can carry
messages destined for any number of queues at the remote queue manager.

Components needed to send a message

If a message is to be sent to a remote queue manager, the local queue manager
needs definitions for a transmission queue and a channel.

Each end of a channel has a separate definition, defining it, for example, as the
sending end or the receiving end. A simple channel consists of a sender channel
definition at the local queue manager and a receiver channel definition at the
remote queue manager. These two definitions must have the same name, and
together constitute one channel.

There is also a message channel agent (MCA) at each end of a channel.

Each queue manager should have a dead-letter queue. Messages are put on this
queue if, for some reason, they cannot be delivered to their destination.

Figure 2 shows the relationship between queue managers, transmission queues,

channels, and MCAs.

QM1 QM2

Dead Letter Queue Dead Letter Queue

Application Message Flow

MCA MCA

Transmission
Queue
Channel Application
Queues

Figure 2. Sending messages

Components needed to return a message

If your application requires messages to be returned from the remote queue
manager, you need to define another channel, to run in the opposite direction
between the queue managers, as shown in Figure 3 on page 6.

Chapter 1. Concepts of intercommunication 5

 What is intercommunication?

QM1 QM2

M e ss a g e F lo w
MCA MCA

Tra n s m is s io n A p p lic a tio n

Queue Queue
Channels

M e ss a g e F lo w
MCA MCA

A p p lic a tio n Tra n s m is s io n

Queue Queue

Figure 3. Sending messages in both directions

Cluster components
| An alternative to the traditional MQSeries network is the use of clusters. Clusters
| are supported on V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun
| Solaris, and Windows NT and MQSeries for OS/390 only.

A cluster is a network of queue managers that are logically associated in some

way. You can group queue managers in a cluster so that queue managers can make
the queues that they host available to every other queue manager in the cluster.
Assuming you have the necessary network infrastructure in place, any queue
manager can send a message to any other queue manager in the same cluster
without the need for explicit channel definitions, remote-queue definitions, or
transmission queues for each destination. Every queue manager in a cluster has a
single transmission queue that transmits messages to any other queue manager in
the cluster. Each queue manager needs to define only one cluster-receiver channel
and one cluster-sender channel.

Figure 4 on page 7 shows the components of a cluster called CLUSTER:

v CLUSTER contains three queue managers, QM1, QM2, and QM3.
v QM1 and QM2 host repositories of information about the queue managers and
queues in the cluster.
v QM2 and QM3 host some cluster queues, that is, queues that are accessible to
any other queue manager in the cluster.
v Each queue manager has a cluster-receiver channel called TO.qmgr on which it
can receive messages.
v Each queue manager also has a cluster-sender channel on which it can send
information to one of the repository queue managers.
v QM1 and QM3 send to the repository at QM2 and QM2 sends to the repository
at QM1.

6 MQSeries Intercommunication
 What is intercommunication?

CLUSTER

QM1 TO.QM1 QM2

TO.QM2

QM3

TO.QM3

Figure 4. A cluster of queue managers

As with distributed queuing, you use the MQPUT call to put a message to a queue
at any queue manager. You use the MQGET call to retrieve messages from a local
queue.

For further information about clusters, see the MQSeries Queue Manager Clusters
book.

Distributed queuing components

This section describes the components of distributed queuing. These are:
v Message channels
v Message channel agents
v Transmission queues
v Channel initiators and listeners
v Channel-exit programs

Message channels
Message channels are the channels that carry messages from one queue manager to
another.

Do not confuse message channels with MQI channels. There are two types of MQI
channel, server-connection and client-connection. These are discussed in the
MQSeries Clients book.

The definition of each end of a message channel can be one of the following types:
v Sender
v Receiver
v Server
v Requester
v Cluster sender
v Cluster receiver

Chapter 1. Concepts of intercommunication 7

Distributed queuing components
A message channel is defined using one of these types defined at one end, and a
compatible type at the other end. Possible combinations are:
v Sender-receiver
v Requester-server
v Requester-sender (callback)
v Server-receiver
v Cluster sender-cluster receiver

Sender-receiver channels
A sender in one system starts the channel so that it can send messages to the other
system. The sender requests the receiver at the other end of the channel to start.
The sender sends messages from its transmission queue to the receiver. The
receiver puts the messages on the destination queue.

QM1 QM2
S ess ion Initiation
SENDER RECEIVER

M ess ag e F low
MCA MCA

Tra n s m is s io n
Q ueue
C hannel A p p lic a tio n
Q ueues

Figure 5. A sender-receiver channel

Server-receiver channel
This is similar to sender-receiver but applies only to fully qualified servers, that is
server channels that have the connection name of the partner specified in the
channel definition. Channel startup must be initiated at the server end of the link.
The illustration of this is similar to the illustration in Figure 5.

Cluster-sender channels
In a cluster, each queue manager has a cluster-sender channel on which it can send
cluster information to one of the repository queue managers. Queue managers can
also send messages to other queue managers on cluster-sender channels.

QM1 QM2

TO.QM2
MCA MCA

Message
Flow Application
Queues
SYSTEM.
CLUSTER.
TRANSMIT.
QUEUE

Figure 6. A cluster-sender channel

8 MQSeries Intercommunication
 Distributed queuing components
Requester-server channel
A requester in one system starts the channel so that it can receive messages from
the other system. The requester requests the server at the other end of the channel
to start. The server sends messages to the requester from the transmission queue
defined in its channel definition.

A server channel can also initiate the communication and send messages to a
requester, but this applies only to fully qualified servers, that is server channels that
have the connection name of the partner specified in the channel definition. A fully
qualified server may either be started by a requester, or may initiate a
communication with a requester.

QM1 QM2

SERVER Session Initiation REQUESTER

Message Flow
MCA MCA

Transmission
Queue
Channel Application
Queues

Figure 7. A requester-server channel

Requester-sender channel
The requester starts the channel and the sender terminates the call. The sender
then restarts the communication according to information in its channel definition
(this is known as callback). It sends messages from the transmission queue to the
requester.

QM1 QM2
S ess ion Initi ati on

SENDER Callba ck REQUESTER

M ess ag e F low
MCA MCA

Tr a n s m i s s i o n

Q ueue

Application
Channel
Q ueues

Figure 8. A requester-sender channel

Cluster-receiver channels
In a cluster, each queue manager has a cluster-receiver channel on which it can
receive messages and information about the cluster. The illustration of this is
similar to the illustration in Figure 6 on page 8.

Message channel agents

A message channel agent (MCA) is a program that controls the sending and receiving
of messages. There is one message channel agent at each end of a channel. One

Chapter 1. Concepts of intercommunication 9

Distributed queuing components
MCA takes messages from the transmission queue and puts them on the
communication link. The other MCA receives messages and delivers them to the
remote queue manager.

A message channel agent is called a caller MCA if it initiated the communication or,
otherwise, is called a responder MCA. A caller MCA may be associated with a
sender, server (fully qualified), or requester channel. A responder MCA, may be
associated with any type of message channel.

Transmission queues
A transmission queue is a special type of local queue used to store messages
temporarily before they are transmitted by the MCA to the remote queue manager.
In a distributed-queuing environment, you need to define one transmission queue
for each sending MCA.

You specify the name of the transmission queue in a remote queue definition, (see
“Remote queue definitions” on page 14). If you do not specify the name, the queue
manager looks for a transmission queue with the same name as the remote queue
manager.

You can specify the name of a default transmission queue for the queue manager.
This is used if you do not specify the name of the transmission queue, and a
transmission queue with the same name as the remote queue manager does not
exist.

Channel initiators and listeners

A channel initiator acts as a trigger monitor for sender MCAs, because a transmission
queue may be defined as a triggered queue. When a message arrives on a
transmission queue that satisfies the triggering criteria for that queue, a message is
sent to the initiation queue, triggering the channel initiator to start the appropriate
sender MCA. You can also start server MCAs in this way if you specified the
connection name of the partner in the channel definition. This means that channels
can be started automatically, based upon messages arriving on the appropriate
transmission queue.

You need a channel listener program to start receiving (responder) MCAs.

Responder MCAs are started in response to a startup request from the sending
MCA; the channel listener detects incoming network requests and starts the
associated channel.

Figure 9 on page 11 shows how channel initiators and channel listeners are used.

10 MQSeries Intercommunication
 Distributed queuing components

SESSION
REQUEST
CHANNEL
LISTENER QM2
QM1
START

MCA MCA

Transmission
Queue
Channel

Initiation CHANNEL
Queue INITIATOR

Figure 9. Channel initiators and listeners

The implementation of channel initiators is platform specific.

| v On OS/390 without CICS, there is one channel initiator for each queue manager
| and it runs as a separate address space. You start it using the MQSeries
| command START CHINIT, which you would normally issue as part of your
| queue manager startup. It monitors the system-defined queue
| SYSTEM.CHANNEL.INITQ, which is the initiation queue for all the
| transmission queues.
| v On OS/390, if you are using CICS for distributed queuing, there is no channel
| initiator. To implement triggering, use the CICS trigger monitor transaction,
| CKTI, to monitor the initiation queue.
| v MQSeries for Windows does not support triggering and does not have channel
| initiators.
| v On other platforms, you can start as many channel initiators as you like,
| specifying a name for the initiation queue for each one. Normally you need only
| one initiator. V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun
| Solaris, and Windows NT allows you to start three, by default, but you can
| change this value. On these platforms that support clustering, when you start a
| queue manager, a channel initiator is automatically started too.

The channel initiator is also required for other functions, discussed later in this
book.

The implementation of channel listeners is platform specific.

v Use the channel listener programs provided by MQSeries if you are using native
OS/390 communications for distributed queuing, MQSeries for Compaq
(DIGITAL) OpenVMS, MQSeries for Tandem NonStop Kernel, or MQSeries for
Windows,
v If you are using CICS for distributed queuing on OS/390, you do not need a
channel listener because CICS provides this function.
v On OS/400, use the channel listener program provided by MQSeries if you are
using TCP/IP. If you are using SNA, you do not need a listener program. SNA
starts the channel by invoking the receiver program on the remote system.
v On OS/2 and Windows NT, you can use either the channel listener program
provided by MQSeries, or the facilities provided by the ‘operating system’ (for
example, Attach manager for LU 6.2 communications on OS/2). If performance
is important in your environment and if the environment is stable, you can
choose to run the MQSeries listener as a trusted application as described in

Chapter 1. Concepts of intercommunication 11

Distributed queuing components
“Running channels and listeners as trusted applications” on page 121. See the
MQSeries Application Programming Guide for information about trusted
applications.
v On UNIX systems, use the channel listener program provided by MQSeries or
the facilities provided by the ‘operating system’ (for example, inetd for TCP/IP
communications).

Channel-exit programs
If you want to do some additional processing (for example, encryption or data
compression) you can write your own channel-exit programs, or sometimes use
SupportPacs. The Transaction Processing SupportPacs library for MQSeries is
available on the Internet at: > >
http://www.ibm.com/software/ts/mqseries/txppacs/

MQSeries calls channel-exit programs at defined places in the processing carried

out by the MCA. There are six types of channel exit:
Security exit
Used for security checking.
Message exit
Used for operations on the message, for example, encryption prior to
transmission.
Send and receive exits
Used for operations on split messages, for example, data compression and
decompression.
Message-retry exit
Used when there is a problem putting the message to the destination
Channel auto-definition exit
Used to modify the supplied default definition for an automatically
defined receiver or server-connection channel.
Transport-retry exit
Used to suspend data being sent on a channel when communication is not
possible.

The sequence of processing is as follows:

1. The security exits are called after the initial data negotiation between both ends
of the channel. These must end successfully for the startup phase to complete
and to allow messages to be transferred.
2. The message exit is called by the sending MCA, and then the send exit is called
for each part of the message that is transmitted to the receiving MCA.
3. The receiving MCA calls the receive exit when it receives each part of the
message, and then calls the message exit when the whole message has been
received.

This is illustrated in Figure 10 on page 13.

12 MQSeries Intercommunication
 Distributed queuing components

QM1 QM2

MCA MCA

Transmission
Queue
SECURITY SECURITY Application
Queues

MESSAGE MESSAGE

SEND RECEIVE

Message Flow MESSAGE

RETRY
Channel

Figure 10. Sequence in which channel exit programs are called

The message-retry exit is used to determine how many times the receiving MCA will
attempt to put a message to the destination queue before taking alternative action.
This exit program is described in “MQ_CHANNEL_EXIT - Channel exit” on
page 546. It is not supported on MQSeries for Windows.

For more information about channel exits, see “Chapter 36. Channel-exit programs”
on page 505.

Dead-letter queues
The dead-letter queue (or undelivered-message queue) is the queue to which
messages are sent if they cannot be routed to their correct destination. Messages
are put on this queue when they cannot be put on the destination queue for some
reason (for example, because the queue does not exist, or because it is full).
Dead-letter queues are also used at the sending end of a channel, for
data-conversion errors.

We recommend that you define a dead-letter queue for each queue manager. If you
do not, and the MCA is unable to put a message, it is left on the transmission
queue and the channel is stopped.

Also, if fast, nonpersistent messages (see “Fast, nonpersistent messages” on

page 22) cannot be delivered and no DLQ exists on the target system, these
messages are discarded.

However, using dead-letter queues can affect the sequence in which messages are
delivered, and so you may choose not to use them.

Dead-letter queues are not supported on MQSeries for Windows.

Chapter 1. Concepts of intercommunication 13

Remote queue definitions

Remote queue definitions

Whereas applications can retrieve messages only from local queues, they can put
messages on local queues or remote queues. Therefore, as well as a definition for
each of its local queues, a queue manager may have remote queue definitions. These
are definitions for queues that are owned by another queue manager. The
advantage of remote queue definitions is that they enable an application to put a
message to a remote queue without having to specify the name of the remote
queue or the remote queue manager, or the name of the transmission queue. This
gives you location independence.

There are other uses for remote queue definitions, which will be described later.

How to get to the remote queue manager

You may not always have one channel between each source and target queue
manager. Consider these alternative possibilities.

Multi-hopping
If there is no direct communication link between the source queue manager and
the target queue manager, it is possible to pass through one or more intermediate
queue managers on the way to the target queue manager. This is known as a
multi-hop.

You need to define channels between all the queue managers, and transmission
queues on the intermediate queue managers. This is shown in Figure 11.

QM1 QM2 QM3

Message Flow Message Flow

MCA MCA MCA MCA

Transmission Transmission Application

Queue Queue Queue
Channels Channels

Message Flow Message Flow

MCA MCA MCA MCA

Application Transmission Transmission

Queue Queue Queue

Figure 11. Passing through intermediate queue managers

Sharing channels
As an application designer, you have the choice of 1) forcing your applications to
specify the remote queue manager name along with the queue name, or 2) creating
a remote queue definition for each remote queue to hold the remote queue manager
name, the queue name, and the name of the transmission queue. Either way, all
messages from all applications addressing queues at the same remote location have

14 MQSeries Intercommunication
 Getting to remote queue manager
their messages sent through the same transmission queue. This is shown in
Figure 12.

QM1 QM2

Dead Letter Queue

Remote queue
definitions
Message Flow
MCA MCA

Transmission
Queue
Channel Application
Queues

Figure 12. Sharing a transmission queue

Figure 12 illustrates that messages from multiple applications to multiple remote

queues can use the same channel.

Using different channels

If you have messages of different types to send between two queue managers, you
can define more than one channel between the two. There are times when you
need alternative channels, perhaps for security purposes, or to trade off delivery
speed against sheer bulk of message traffic.

To set up a second channel you need to define another channel and another
transmission queue, and create a remote queue definition specifying the location
and the transmission queue name. Your applications can then use either channel
but the messages will still be delivered to the same target queues. This is shown in
Figure 13.

QM1 QM2

Message Flow
MCA MCA

Transmission Application
Queue Queue
Channels

Message Flow
MCA MCA

Transmission Application
Queue Queue

Figure 13. Using multiple channels

When you use remote queue definitions to specify a transmission queue, your
applications must not specify the location (that is, the destination queue manager)
themselves. If they do, the queue manager will not make use of the remote queue
definitions. Remote queue definitions make the location of queues and the
transmission queue transparent to applications. Applications can put messages to a

Chapter 1. Concepts of intercommunication 15

Getting to remote queue manager
logical queue without knowing where the queue is located and you can alter the
physical queue without having to change your applications.

Using clustering
Every queue manager within a cluster defines a cluster-receiver channel and when
another queue manager wants to send a message to that queue manager, it defines
the corresponding cluster-sender channel automatically. For example, if there is
more that one instance of a queue in a cluster, the cluster-sender channel could be
defined to any of the queue managers that host the queue. MQSeries uses a
workload management algorithm that uses a round-robin routine to select the best
queue manager to route a message to. For more information about this, see the
MQSeries Queue Manager Clusters book.

16 MQSeries Intercommunication
Chapter 2. Making your applications communicate
This chapter provides more detailed information about intercommunication
between MQSeries products. Before reading this chapter it is helpful to have an
understanding of channels, queues, and the other concepts introduced in
“Chapter 1. Concepts of intercommunication” on page 3.

This chapter covers the following topics:

v “How to send a message to another queue manager”
v “Triggering channels” on page 20
v “Safety of messages” on page 22

How to send a message to another queue manager

This section describes the simplest way to send a message from one queue
manager to another.

Before you do this you need to do the following:

1. Check that your chosen communication protocol is available.
2. Start the queue managers.
3. Start the channel initiators.
4. Start the listeners.

On MQSeries for Windows, instead of steps 2, 3, and 4, you start a connection,

which includes a queue manager, channels, and a listener. See the MQSeries for
Windows User’s Guide for more information.

You also need to have the correct MQSeries security authorization (except on
MQSeries for Windows) to create the objects required.

To send messages from one queue manager to another:

v Define the following objects on the source queue manager:
– Sender channel
– Remote queue
– Initiation queue (required on OS/390, otherwise optional)
– Transmission queue
– Dead-letter queue (recommended)
– Process (required on OS/390, otherwise optional)
v Define the following objects on the target queue manager:
– Receiver channel
– Target queue
– Dead-letter queue (recommended)

You can use several different methods to define these objects, depending on your
MQSeries platform:
OS/390 or MVS/ESA
If you are using native OS/390 communications, you can use the
Operation and Control panels or information from the MQSeries Command
Reference book. If you are using CICS for distributed queuing, you must
use the supplied CICS application CKMC for channels.

© Copyright IBM Corp. 1993, 2000 17

 Sending messages
| OS/400®
| You can use the panel interface, the control language (CL) commands
| described in the MQSeries for AS/400 System Administration, MQSeries
| commands described in the MQSeries Command Reference book, or the
| programmable command format (PCF) commands described in the
| MQSeries Programmable System Management book.
MQSeries for Windows
You can use MQSC commands, PCF commands, or the MQSeries
properties dialog. Not all MQSC and PCF commands are supported; see
the MQSeries for Windows User’s Guide.

Note: On MQSeries for Windows there is no initiation queue, dead-letter

queue, or process.
OS/2, Windows NT, UNIX systems, and Digital OpenVMS
You can use the MQSeries commands described in the MQSeries Command
Reference book, or the PCF commands described in the MQSeries
Programmable System Management book. On Windows NT only, you can also
use the graphical user interfaces, the MQSeries explorer and the MQSeries
Web Administration.
Tandem NSK
You can use MQSC commands, PCF commands, or the Message Queue
Management facility. See the MQSeries for Tandem NonStop Kernel System
Management Guide for more information about the control commands and
the Message Queue Management facility.
VSE/ESA
You can use the panel interface as described in the MQSeries for VSE/ESA
System Management Guide.

The different methods are described in more detail in the platform-specific parts of
this book.

Defining the channels

To send messages from one queue manager to another, you need to define two
channels; one on the source queue manager and one on the target queue manager.
On the source queue manager
Define a channel with a channel type of SENDER. You need to specify the
following:
v The name of the transmission queue to be used (the XMITQ attribute).
v The connection name of the partner system (the CONNAME attribute).
| v The name of the communication protocol you are using (the TRPTYPE
| attribute). For V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp,
| Sun Solaris, and Windows NT, and MQSeries for Windows, you do not
| have to specify this. You can leave it to pick up the value from your
| default channel definition. On MQSeries for Windows the protocol must
| be TCP or UDP. On MQSeries for VSE/ESA, the protocol must be TCP
| or LU 6.2; you can choose T or L accordingly on the Maintain Channel
| Definition menu.

Details of all the channel attributes are given in “Chapter 6. Channel

attributes” on page 77.

18 MQSeries Intercommunication
 Sending messages
On the target queue manager
Define a channel with a channel type of RECEIVER, and the same name as
the sender channel.
Specify the name of the communication protocol you are using (the
TRPTYPE attribute). For V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2
Warp, Sun Solaris, and Windows NT, and MQSeries for Windows, you do
not have to specify this. You can leave it to pick up the value from your
default channel definition. On MQSeries for Windows the protocol must be
TCP. If you are using CICS to define a channel, you cannot specify
TRPTYPE. Instead you should accept the defaults provided. On MQSeries
for VSE/ESA, you can choose T (TCP) or U (UDP) on the Maintain
Channel Definition menu.
Note that other than on MQSeries for Windows, receiver channel
definitions can be generic. This means that if you have several queue
managers communicating with the same receiver, the sending channels can
all specify the same name for the receiver, and one receiver definition will
apply to them all.

When you have defined the channel, you can test it using the PING CHANNEL
command. This command (which is not supported on MQSeries for Windows)
sends a special message from the sender channel to the receiver channel and
checks that it is returned.

Defining the queues

To send messages from one queue manager to another, you need to define up to
six queues; four on the source queue manager and two on the target queue
| manager.
| On the source queue manager
| v Remote queue definition
| In this definition you specify the following:
| Remote queue manager name
| The name of the target queue manager.
| Remote queue name
| The name of the target queue on the target queue manager.
| Transmission queue name
| The name of the transmission queue. You do not have to specify
| this. If you do not, a transmission queue with the same name as
| the target queue manager is used, or, if this does not exist, the
| default transmission queue is used. You are advised to give the
| transmission queue the same name as the target queue manager
| so that the queue is found by default.
| v Initiation queue definition
| Not supported on MQSeries for Windows, required on OS/390, and is
| optional on other platforms. On OS/390 you must use the initiation
| queue called SYSTEM.CHANNEL.INITQ and you are recommended to
| do so on other platforms also.
| v Transmission queue definition
| A local queue with the USAGE attribute set to XMITQ. If you are using
| the MQSeries for AS/400 V5.1 native interface, the USAGE attribute is
| *TMQ.

Chapter 2. Making your applications communicate 19

 Sending messages
| v Dead-letter queue definition—recommended (not applicable to MQSeries
| for Windows)
| Define a dead-letter queue to which undelivered messages can be
| written.

| On OS/390 you should also define a process if you want your channels to
| be triggered automatically. (See “Triggering channels”.)
| On the target queue manager
| v Local queue definition
| The target queue. The name of this queue must be the same as that
| specified in the remote queue name field of the remote queue definition
| on the source queue manager.
| v Dead-letter queue definition—recommended (not applicable to MQSeries
| for Windows)
| Define a dead-letter queue to which undelivered messages can be
| written.

| Sending the messages

When you put messages on the remote queue defined at the source queue
manager, they are stored on the transmission queue until the channel is started.
When the channel has been started, the messages are sent to the target queue on
the remote queue manager.

Starting the channel

Start the channel on the sending queue manager using the START CHANNEL
command. When you start the sending channel, the receiving channel is started
automatically (by the listener) and the messages are sent to the target queue. Both
ends of the message channel must be running for messages to be transferred.

Because the two ends of the channel are on different queue managers, they could
have been defined with different attributes. To resolve any differences, there is an
initial data negotiation between the two ends when the channel starts. In general,
the two ends of the channel agree to operate with the attributes needing the fewer
resources, thus enabling larger systems to accommodate the lesser resources of
smaller systems at the other end of the message channel.

The sending MCA splits large messages before sending them across the channel.
They are reassembled at the remote queue manager. This is transparent to the user.

Triggering channels
This explanation is intended as an overview of triggering concepts. You can find a
complete description in the MQSeries Application Programming Guide.

| For platform-specific information see the following:

| v For OS/2, Windows NT, UNIX systems, Digital OpenVMS, and Tandem NSK,
| “Triggering channels” on page 117
| v For OS/390 without CICS, “Defining MQSeries objects” on page 342
| v For OS/390 using CICS, “How to trigger channels” on page 358
| v For OS/400, “Triggering channels” on page 443

Triggering is not supported on MQSeries for Windows.

20 MQSeries Intercommunication
 Triggering channels

Application Queue manager Application

Local program
Local or 1. 5. started by
Transmission queue trigger monitor
MCA
puts message or
message retrieved MCA started by
on queue 2. trigger message channel initiator

Initiation queue

3.
trigger Program
message
retrieved
Channel
initiator
(Long 4. Queue server started
running)

Figure 14. The concepts of triggering

The objects required for triggering are shown in Figure 14. It shows the following
sequence of events:
1. The local queue manager places a message from an application or from a
message channel agent (MCA) on the transmission queue.
2. When the triggering conditions are fulfilled, the local queue manager places a
trigger message on the initiation queue.
3. The long-running channel initiator program monitors the initiation queue, and
retrieves messages as they appear.
4. The trigger monitor processes the trigger messages according to information
contained in them. This information may include the channel name, in which
case a special type of trigger monitor called a channel initiator starts the
corresponding MCA.
5. The local application or the MCA, having been triggered, retrieves the
messages from the transmission queue.

To set up this scenario, you need to:

v Create the transmission queue with the name of the initiation queue (that is,
SYSTEM.CHANNEL.INITQ) in the corresponding attribute.
v Ensure that the initiation queue (SYSTEM.CHANNEL.INITQ) exists.
v Ensure that the channel initiator program is available and running. The trigger
monitor program must be provided with the name of the initiation queue in its
start command. On OS/390 without CICS, the name of the initiation queue is
fixed, so is not used on the start command.
| v Create the process definition for the triggering, if it does not exist, and ensure
| that its UserData field contains the name of the channel it serves. For V5.1 of
| MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT,
| the process definition is optional (it is not supported on MQSeries for
| VSE/ESA). Instead, you can specify the channel name in the TriggerData
| attribute of the transmission queue. V5.1 of MQSeries for AIX, AS/400, HP-UX,

Chapter 2. Making your applications communicate 21

 Triggering channels
| OS/2 Warp, Sun Solaris, and Windows NT allow the channel name to be
| specified as blank, in which case the first available channel definition with this
| transmission queue is used.
v Ensure that the transmission queue definition contains the name of the process
definition to serve it, (if applicable), the initiation queue name, and the
triggering characteristics you feel are most suitable. The trigger control attribute
allows triggering to be enabled, or not, as necessary.
Notes:
1. An initiation queue and trigger process can be used to trigger any number of
channels.
2. Any number of initiation queues and trigger processes can be defined.
3. A trigger type of FIRST is recommended, to avoid flooding the system with
channel starts.

Safety of messages
In addition to the usual recovery features of MQSeries, distributed queue
management ensures that messages are delivered properly by using a syncpoint
procedure coordinated between the two ends of the message channel. If this
procedure detects an error, it closes the channel to allow you to investigate the
problem, and keeps the messages safely in the transmission queue until the
channel is restarted.

The syncpoint procedure has an added benefit in that it attempts to recover an

in-doubt situation when the channel starts up. (In-doubt is the status of a unit of
recovery for which a syncpoint has been requested but the outcome of the request
is not yet known.) Also associated with this facility are the two functions:
1. Resolve with commit or backout
2. Reset the sequence number

The use of these functions occurs only in exceptional circumstances because the
channel recovers automatically in most cases.

Fast, nonpersistent messages

| In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT, MQSeries for OS/390 without CICS and MQSeries for Windows
| V2.1, the nonpersistent message speed (NPMSPEED) channel attribute can be used
| to specify that any nonpersistent messages on the channel are to be delivered
| quickly. For more information about this attribute, see “Nonpersistent message
| speed (NPMSPEED)” on page 90. If a channel terminates while fast, nonpersistent
| messages are in transit, the messages may be lost and it is up to the application to
| arrange for their recovery if required. Similarly, if the MQPUT command fails for
| any reason, the messages are lost.

Every effort is made to deliver fast, nonpersistent messages safely. Unless there is a
problem with the message, such as a data-conversion problem or a message-size
problem, the message is delivered. The safety of an individual message is not
affected by sequence-number problems or problems with other messages in the
same batch.

In MQSeries for Compaq (DIGITAL) OpenVMS fast messages are defined

differently. To enable fast messages on a channel, of type sender, server, receiver, or
requester, set the following definitions at both ends of the channel after the
CHLTYPE:

22 MQSeries Intercommunication
 Safety of messages
DESCR(‘>>> description’) +

Specifying >>> as the first characters in the channel description defines the channel
as fast for nonpersistent messages.

Note: If the other end of the channel does not support the option, the channel runs
at normal speed.

Undelivered messages
For information about what happens when a message cannot be delivered, see
“What happens when a message cannot be delivered?” on page 71.

Chapter 2. Making your applications communicate 23

Introduction

24 MQSeries Intercommunication
Chapter 3. More about intercommunication
This chapter mentions three aliases:
v Remote queue definition
v Queue manager alias definition
v Reply-to queue alias definition

These are all based on the remote queue definition object introduced in “Remote
queue definitions” on page 14.

This discussion does not apply to alias queues. These are described in the MQSeries
Application Programming Guide.

This chapter also discusses “Networks” on page 29.

Addressing information
In a single-queue-manager environment, the address of a destination queue is
established when an application opens a queue for putting messages to. Because
the destination queue is on the same queue manager, there is no need for any
addressing information.

In a distributed environment the queue manager needs to know not only the
destination queue name, but also the location of that queue (that is, the queue
manager name), and the route to that remote location (that is, the transmission
queue). When an application puts messages that are destined for a remote queue
manager, the local queue manager adds a transmission header to them before
placing them on the transmission queue. The transmission header contains the
name of the destination queue and queue manager, that is, the addressing
information. The receiving channel removes the transmission header and uses the
information in it to locate the destination queue.

You can avoid the need for your applications to specify the name of the destination
queue manager if you use a remote queue definition. This definition specifies the
name of the remote queue, the name of the remote queue manager to which
messages are destined, and the name of the transmission queue used to transport
the messages.

What are aliases?

Aliases are used to provide a quality of service for messages. The queue manager
alias enables a system administrator to alter the name of a target queue manager
without causing you to have to change your applications. It also enables the
system administrator to alter the route to a destination queue manager, or to set up
a route that involves passing through a number of other queue managers
(multi-hopping). The reply-to queue alias provides a quality of service for replies.

Queue manager aliases and reply-to queue aliases are created using a
remote-queue definition that has a blank RNAME. These definitions do not define
real queues; they are used by the queue manager to resolve physical queue names,
queue manager names, and transmission queues.

Alias definitions are characterized by having a blank RNAME.

© Copyright IBM Corp. 1993, 2000 25

 What are aliases?
Queue name resolution
Queue name resolution occurs at every queue manager each time a queue is
opened. Its purpose is to identify the target queue, the target queue manager
(which may be local), and the route to that queue manager (which may be null).
The resolved name has three parts: the queue manager name, the queue name,
and, if the queue manager is remote, the transmission queue.

When a remote queue definition exists, no alias definitions are referenced. The
queue name supplied by the application is resolved to the name of the destination
queue, the remote queue manager, and the transmission queue specified in the
remote queue definition. For more detailed information about queue name
resolution, see “Appendix C. Queue name resolution” on page 633.

If there is no remote queue definition and a queue manager name is specified, or

resolved by the name service, the queue manager looks to see if there is a queue
manager alias definition that matches the supplied queue manager name. If there
is, the information in it is used to resolve the queue manager name to the name of
the destination queue manager. The queue manager alias definition can also be
used to determine the transmission queue to the destination queue manager.

If the resolved queue name is not a local queue, both the queue manager name
and the queue name are included in the transmission header of each message put
by the application to the transmission queue.

The transmission queue used usually has the same name as the resolved queue
manager, although this may be changed by a remote queue definition or a queue
manager alias definition. If you have not defined a transmission queue with the
name of the resolved queue manager and there is no transmission queue defined
by the remote queue definitions or queue manager alias definitions, but you have
defined a default transmission queue, the default transmission queue is used.

Note: Names of queue managers running on OS/390 are limited to four

characters.

Queue manager alias definitions

Queue manager alias definitions apply when an application that opens a queue to
put a message, specifies the queue name and the queue manager name.

Queue manager alias definitions have three uses:

v When sending messages, remapping the queue manager name
v When sending messages, altering or specifying the transmission queue
v When receiving messages, determining whether the local queue manager is the
intended destination for those messages

Outbound messages - remapping the queue manager name

Queue manager alias definitions can be used to remap the queue manager name
specified in an MQOPEN call. For example, an MQOPEN call specifies a queue
name of THISQ and a queue manager name of YOURQM. At the local queue
manager there is a queue manager alias definition like this:
| DEFINE QREMOTE (YOURQM) RQMNAME(REALQM)

This shows that the real queue manager to be used, when an application puts
messages to queue manager YOURQM, is REALQM. If the local queue manager is
REALQM, it puts the messages to the queue THISQ, which is a local queue. If the

26 MQSeries Intercommunication
 Queue manager alias definitions
local queue manager is not called REALQM, it routes the message to a
transmission queue called REALQM. The queue manager changes the transmission
header to say REALQM instead of YOURQM.

Outbound messages - altering or specifying the transmission

queue
Figure 15 shows a scenario where messages arrive at queue manager ‘QM1’ with
transmission headers showing queue names at queue manager ‘QM3’. In this
scenario, ‘QM3’ is reachable by multi-hopping through ‘QM2’.

QM1 QM2

Channel in A Q ueue 'QM3'

Channel in B Q ueue 'QM2' Channel out 1 Q ueue 'QM3' Channel out 2

to

QM3

Adjacent Local system Adjacent system Remote

system system

Figure 15. Queue manager alias

All messages for ‘QM3’ are captured at ‘QM1’ with a queue manager alias. The
queue manager alias is named ‘QM3’ and contains the definition ‘QM3 via
transmission queue QM2’. The definition looks like this:
DEFINE QREMOTE (QM3) RNAME() RQMNAME(QM3) XMITQ(QM2)

The queue manager puts the messages on transmission queue ‘QM2’ but does not
make any alteration to the transmission queue header because the name of the
destination queue manager, ‘QM3’, does not alter.

All messages arriving at ‘QM1’ and showing a transmission header containing a

queue name at ‘QM2’ are also put on the ‘QM2’ transmission queue. In this way,
messages with different destinations are collected onto a common transmission
queue to an appropriate adjacent system, for onward transmission to their
destinations.

Inbound messages - determining the destination

A receiving MCA opens the queue referenced in the transmission header. If a
queue manager alias definition exists with the same name as the queue manager
referenced, then the queue manager name received in the transmission header is
replaced with the RQMNAME from that definition.

This has two uses:

v Directing messages to another queue manager
v Altering the queue manager name to be the same as the local queue manager

Chapter 3. More about intercommunication 27

Reply-to queue alias definitions

Reply-to queue alias definitions

When an application needs to reply to a message it may look at the data in message
descriptor of the message it received to find out the name of the queue to which it
should reply. It is up to the sending application to suggest where replies should be
sent and to attach this information to its messages. This has to be coordinated as
part of your application design.

What is a reply-to queue alias definition?

A reply-to queue alias definition specifies alternative names for the reply
information in the message descriptor. The advantage of this is that you can alter
the name of a queue or queue manager without having to alter your applications.
Queue name resolution takes place at the sending end, before the message is put to
a queue.

Note: This is an unusual use of queue-name resolution. It is the only situation in

which name resolution takes place at a time when a queue is not being
opened.

Normally an application specifies a reply-to queue and leaves the reply-to queue
manager name blank. The queue manager fills in its own name at put time. This
works well except when you want alternate channels to be used for replies. In this
situation, the queue manager names specified in transmission-queue headers do
not match “real” queue manager names but are re-specified using queue manager
alias definitions. In order to return replies along similar alternate routes, it is
necessary to map reply-to queue data as well, using reply-to queue alias
definitions.

Queue manager 'QM1' Queue manager 'QM2'

Application
Queue 'Inquiry'

Queue 'QM3_relief' Channel_out_1 Queue 'QM3_relief' Channel_out_2

Inquiring
Queue 'Reply_to'

Queue 'Answer'

Queue 'QM1_relief' Channel_in_1 Queue 'QM1_relief' Channel_in_2

Local system Adjacent system Remote system

Figure 16. Reply-to queue alias used for changing reply location

In the example in Figure 16:

1. The application puts a message using the MQPUT call and specifying the
following in the message descriptor:
ReplyToQ=‘Reply_to’
ReplyToQMgr=‘’

28 MQSeries Intercommunication
 Reply-to queue alias definitions
Note that ReplyToQMgr must be blank in order for the reply-to queue alias to
be used.
2. You create a reply-to queue alias definition called ‘Reply_to’, which contains
the name ‘Answer’, and the queue manager name ‘QM1_relief’.
DEFINE QREMOTE ('Reply_to') RNAME ('Answer')
RQMNAME ('QM1_relief')
3. The messages are sent with a message descriptor showing ReplyToQ=‘Answer’
and ReplyToQMgr=‘QM1_relief’.
4. The application specification must include the information that replies are to be
found in queue ‘Answer’ rather than ‘Reply_to’.

To prepare for the replies you have to create the parallel return channel. This
involves defining:
v At QM2, the transmission queue named ‘QM1_relief’
DEFINE QLOCAL ('QM1_relief') USAGE(XMITQ)
v At QM1, the queue manager alias queue ‘QM1_relief’
DEFINE QREMOTE ('QM1_relief') RNAME() RQMNAME(QM1)

This queue manager alias queue terminates the chain of parallel return channels
and captures the messages for QM1.

If you think you might want to do this at sometime in the future, arrange for your
applications to use the alias name from the start. For now this is a normal queue
alias to the reply-to queue, but later it can be changed to a queue manager alias.

Reply-to queue name

Care is needed with naming reply-to queues. The reason that an application puts a
reply-to queue name in the message is that it can specify the queue to which its
replies will be sent. But when you create a reply-to queue alias definition with this
name, you cannot have the actual reply-to queue (that is, a local queue definition)
with the same name. Therefore, the reply-to queue alias definition must contain a
new queue name as well as the queue manager name, and the application
specification must include the information that its replies will be found in this
other queue.

The applications now have to retrieve the messages from a different queue from
the one they named as the reply-to queue when they put the original message.

Networks
So far this book has covered creating channels between your system and any other
system with which you need to have communications, and creating multi-hop
channels to systems where you have no direct connections. The message channel
connections described in the scenarios are shown as a network diagram in
Figure 17 on page 30.

Channel and transmission queue names

You can give transmission queues any name you like, but to avoid confusion, you
can give them the same names as the destination queue manager names, or queue
manager alias names, as appropriate, to associate them with the route they use.
This gives a clear overview of parallel routes that you create through intermediate
(multi-hopped) queue managers.

Chapter 3. More about intercommunication 29

Networks
This is not quite so clear-cut for channel names. The channel names in Figure 17
for QM2, for example, must be different for incoming and outgoing channels. All
channel names may still contain their transmission queue names, but they must be
qualified to make them unique.

For example, at QM2, there is a QM3 channel coming from QM1, and a QM3
channel going to QM3. To make the names unique, the first one may be named
‘QM3_from_QM1’, and the second may be named ‘QM3_from_QM2’. In this way,
the channel names show the transmission queue name in the first part of the name,
and the direction and adjacent queue manager name in the second part of the
name.

A table of suggested channel names for Figure 17 is given in Table 1.

QM2

QM 2 fast

'Q M 1' 'Q M 2' 'Q M 3'

QM1 QM1

QM 1 fast

Q M 1 re lie f Q M 1 re lie f

QM 3 QM 3

Q M 3 re lie f Q M 3 re lie f

Figure 17. Network diagram showing all channels

Table 1. Example of channel names

Route name Queue managers Transmission queue name Suggested channel name
hosting channel
QM1 QM1 & QM2 QM1 (at QM2) QM1.from.QM2
QM1 QM2 & QM3 QM1 (at QM3) QM1.from.QM3
QM1_fast QM1 & QM2 QM1_fast (at QM2) QM1_fast.from.QM2
QM1_relief QM1 & QM2 QM1_relief (at QM2) QM1_relief.from.QM2
QM1_relief QM2 & QM3 QM1_relief (at QM3) QM1_relief.from.QM3
QM2 QM1 & QM2 QM2 (at QM1) QM2.from.QM1
QM2_fast QM1 & QM2 QM2_fast (at QM1) QM2_fast.from.QM1
QM3 QM1 & QM2 QM3 (at QM1) QM3.from.QM1
QM3 QM2 & QM3 QM3 (at QM2) QM3.from.QM2
QM3_relief QM1 & QM2 QM3_relief (at QM1) QM3_relief.from.QM1
QM3_relief QM2 & QM3 QM3_relief (at QM2) QM3_relief.from.QM2

Notes:
1. On MQSeries for OS/390, queue manager names are limited to 4 characters.

30 MQSeries Intercommunication
 Networks
2. You are strongly recommended to name all the channels in your network
uniquely. As shown in Table 1 on page 30, including the source and target
queue manager names in the channel name is a good way to do this.

Network planner
This chapter has discussed application designer, systems administrator, and
channel planner functions. Creating a network assumes that there is another,
higher level function of network planner whose plans are implemented by the other
members of the team.

If an application is used widely, it is more economical to think in terms of local

access sites for the concentration of message traffic, using wide-band links between
the local access sites, as shown in Figure 18.

In this example there are two main systems and a number of satellite systems (The
actual configuration would depend on business considerations.) There are two
concentrator queue managers located at convenient centers. Each QM-concentrator
has message channels to the local queue managers:
v QM-concentrator 1 has message channels to each of the three local queue
managers, QM1, QM2, and QM3. The applications using these queue managers
can communicate with each other through the QM-concentrators.
v QM-concentrator 2 has message channels to each of the three local queue
managers, QM4, QM5, and QM6. The applications using these queue managers
can communicate with each other through the QM-concentrators.
v The QM-concentrators have message channels between themselves thus allowing
any application at a queue manager to exchange messages with any other
application at another queue manager.

Chapter 3. More about intercommunication 31

Introduction

'Q M 2'

'Q M -
'Q M 1' C o nce ntra to r 'Q M 3'
1'

'Q M -
'Q M 4' C o nce ntra to r 'Q M 6'
2'

'Q M 5'

Figure 18. Network diagram showing QM-concentrators

32 MQSeries Intercommunication
Part 2. How intercommunication works
Chapter 4. MQSeries distributed-messaging Stopping and quiescing channels (not MQSeries
techniques . . . . . . . . . . . . . . 35 for Windows). . . . . . . . . . . . . 67
Message flow control . . . . . . . . . . . 35 Stopping and quiescing channels (MQSeries for
Queue names in transmission header . . . . . 36 Windows) . . . . . . . . . . . . . . 68
How to create queue manager and reply-to Restarting stopped channels . . . . . . . . 69
aliases . . . . . . . . . . . . . . . 36 In-doubt channels . . . . . . . . . . . 69
Putting messages on remote queues . . . . . . 37 Problem determination . . . . . . . . . 71
More about name resolution . . . . . . . . 38 Command validation . . . . . . . . . 71
Choosing the transmission queue . . . . . . . 39 Processing problems . . . . . . . . . 71
Receiving messages. . . . . . . . . . . . 40 Messages and codes . . . . . . . . . 71
Receiving alias queue manager names . . . . 40 What happens when a message cannot be
Passing messages through your system . . . . . 41 delivered? . . . . . . . . . . . . . . . 71
Method 1: Using the incoming location name . . 42 Initialization and configuration files . . . . . . 73
Method 2: Using an alias for the queue manager 42 OS/390 without CICS . . . . . . . . . . 73
Method 3: Selecting a transmission queue . . . 42 OS/390 using CICS. . . . . . . . . . . 73
Using these methods . . . . . . . . . . 42 Windows NT . . . . . . . . . . . . . 73
Separating message flows . . . . . . . . . 42 OS/2, Digital OpenVMS, Tandem NSK, OS/400
Concentrating messages to diverse locations . . . 44 and UNIX systems . . . . . . . . . . . 73
Diverting message flows to another destination . . 45 MQSeries configuration file . . . . . . . 74
Sending messages to a distribution list . . . . . 46 Queue manager configuration file . . . . . 74
Reply-to queue . . . . . . . . . . . . . 47 VSE/ESA . . . . . . . . . . . . . . 75
Reply-to queue alias example . . . . . . . 48 Data conversion . . . . . . . . . . . . . 75
Definitions used in this example at QM1 . . 49 Writing your own message channel agents . . . . 75
Definitions used in this example at QM2 . . 50
Put definition at QM1 . . . . . . . . . 50 Chapter 6. Channel attributes. . . . . . . . 77
Put definition at QM2 . . . . . . . . . 50 Channel attributes in alphabetical order . . . . . 77
How the example works . . . . . . . . . 50 Alter date (ALTDATE) . . . . . . . . . . 78
How the queue manager makes use of the Alter time (ALTTIME) . . . . . . . . . . 78
reply-to queue alias. . . . . . . . . . . 51 Auto start (AUTOSTART). . . . . . . . . 78
Reply-to queue alias walk-through . . . . . 51 Batch interval (BATCHINT) . . . . . . . . 79
Networking considerations . . . . . . . . . 52 Batch size (BATCHSZ) . . . . . . . . . . 79
Return routing . . . . . . . . . . . . . 53 Channel name (CHANNEL) . . . . . . . . 80
Managing queue name translations . . . . . . 53 Channel type (CHLTYPE) . . . . . . . . 81
Message sequence numbering . . . . . . . . 54 CICS profile name . . . . . . . . . . . 81
Sequential retrieval of messages . . . . . . 55 Cluster (CLUSTER) . . . . . . . . . . . 81
Sequence of retrieval of fast, nonpersistent Cluster namelist (CLUSNL) . . . . . . . . 82
messages . . . . . . . . . . . . . . 56 Connection name (CONNAME) . . . . . . 82
Loopback testing . . . . . . . . . . . . 56 Convert message (CONVERT) . . . . . . . 83
Description (DESCR) . . . . . . . . . . 84
Chapter 5. DQM implementation . . . . . . . 57 Disconnect interval (DISCINT) . . . . . . . 84
Functions of DQM . . . . . . . . . . . . 57 Heartbeat interval (HBINT) . . . . . . . . 85
Message sending and receiving . . . . . . . . 58 Long retry count (LONGRTY) . . . . . . . 85
Channel parameters . . . . . . . . . . 59 Long retry interval (LONGTMR) . . . . . . 85
Channel status and sequence numbers . . . . 59 LU 6.2 mode name (MODENAME) . . . . . 86
Channel control function . . . . . . . . . . 59 LU 6.2 transaction program name (TPNAME) . . 86
Preparing channels . . . . . . . . . . . 60 Maximum message length (MAXMSGL) . . . . 87
Auto-definition of channels . . . . . . . 60 Maximum transmission size . . . . . . . . 87
Defining other objects . . . . . . . . . 61 Message channel agent name (MCANAME) . . 87
Starting a channel (not MQSeries for Message channel agent type (MCATYPE) . . . 88
Windows) . . . . . . . . . . . . . 61 Message channel agent user identifier
Starting a channel on MQSeries for Windows 61 (MCAUSER) . . . . . . . . . . . . . 88
Channel states . . . . . . . . . . . . 62 Message exit name (MSGEXIT) . . . . . . . 88
Current and active . . . . . . . . . . 62 Message exit user data (MSGDATA) . . . . . 89
Channel errors . . . . . . . . . . . 65 Message-retry exit name (MREXIT) . . . . . 89
Checking that the other end of the channel is Message-retry exit user data (MRDATA) . . . . 89
still available . . . . . . . . . . . . 66 Message retry count (MRRTY) . . . . . . . 89

© Copyright IBM Corp. 1993, 2000 33

Intercommunication
Message retry interval (MRTMR) . . . . . . 89 Short retry interval (SHORTTMR) . . . . . . 94
Network-connection priority (NETPRTY) . . . 90 Target system identifier . . . . . . . . . 94
Nonpersistent message speed (NPMSPEED) . . 90 Transaction identifier . . . . . . . . . . 94
Password (PASSWORD) . . . . . . . . . 90 Transmission queue name (XMITQ) . . . . . 94
PUT authority (PUTAUT). . . . . . . . . 90 Transport type (TRPTYPE) . . . . . . . . 95
Queue manager name (QMNAME) . . . . . 91 User ID (USERID) . . . . . . . . . . . 95
Receive exit name (RCVEXIT) . . . . . . . 91
Receive exit user data (RCVDATA) . . . . . 92 Chapter 7. Example configuration chapters in
Security exit name (SCYEXIT) . . . . . . . 92 this book . . . . . . . . . . . . . . . 97
Security exit user data (SCYDATA) . . . . . 93 Network infrastructure . . . . . . . . . . 98
Send exit name (SENDEXIT). . . . . . . . 93 Communications software . . . . . . . . . 98
Send exit user data (SENDDATA) . . . . . . 93 How to use the communication examples . . . . 99
Sequence number wrap (SEQWRAP) . . . . . 93 IT responsibilities . . . . . . . . . . . 100
Sequential delivery . . . . . . . . . . . 93
Short retry count (SHORTRTY) . . . . . . . 93

This part of the book gives more details about how intercommunication works.
The description in this part is general, and is not restricted to a particular platform
or system.

34 MQSeries Intercommunication
 Chapter 4. MQSeries distributed-messaging techniques
This chapter describes techniques that are of use when planning channels. It
introduces the concept of message flow control and explains how this is arranged
in distributed queue management (DQM). It gives more detailed information about
the concepts introduced in the preceding chapters and starts to show how you
might use distributed queue management. This chapter covers the following topics:
v “Message flow control”
v “Putting messages on remote queues” on page 37
v “Choosing the transmission queue” on page 39
v “Receiving messages” on page 40
v “Passing messages through your system” on page 41
v “Separating message flows” on page 42
v “Concentrating messages to diverse locations” on page 44
v “Diverting message flows to another destination” on page 45
v “Sending messages to a distribution list” on page 46
v “Reply-to queue” on page 47
v “Networking considerations” on page 52
v “Return routing” on page 53
v “Managing queue name translations” on page 53
v “Message sequence numbering” on page 54
v “Loopback testing” on page 56

Message flow control

Message flow control is a task that involves the setting up and maintenance of
message routes between queue managers. This is very important for routes that
multi-hop through many queue managers.

You control message flow using a number of techniques that were introduced in
“Chapter 2. Making your applications communicate” on page 17. If your queue
manager is in a cluster, message flow is controlled using different techniques as
described in the MQSeries Queue Manager Clusters book.

This chapter describes how you use your system’s queues, alias queue definitions,
and message channels to achieve message flow control.

You make use of the following objects:

v Transmission queues
v Message channels
v Remote queue definition
v Queue manager alias definition
v Reply-to queue alias definition

| The queue manager and queue objects are described in the MQSeries System
| Administration book for MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT, in the MQSeries for AS/400 V5.1 System Administration book for
| MQSeries for AS/400, or in the MQSeries System Management Guide for your
| platform. Message channels are described in “Message channels” on page 7. The
| following techniques use these objects to create message flows in your system:
| v Putting messages to remote queues
| v Routing via particular transmission queues
| v Receiving messages

© Copyright IBM Corp. 1993, 2000 35

 Message flow control
| v Passing messages through your system
| v Separating message flows
| v Switching a message flow to another destination
| v Resolving the reply-to queue name to an alias name
|

Note
All the concepts described in this chapter are relevant for all nodes in a
network, and include sending and receiving ends of message channels. For
this reason, only one node is illustrated in most examples, except where the
example requires explicit cooperation by the administrator at the other end of
a message channel.

Before proceeding to the individual techniques it is useful to recap on the concepts

of name resolution and the three ways of using remote queue definitions. See
“Chapter 3. More about intercommunication” on page 25.

Queue names in transmission header

The queue name used by the application, the logical queue name, is resolved by
the queue manager to the destination queue name, that is, the physical queue
name. This destination queue name travels with the message in a separate data
area, the transmission header, until the destination queue has been reached after
which the transmission header is stripped off.

You will be changing the queue manager part of this queue name when you create
parallel classes of service. Remember to return the queue manager name to the
original name when the end of the class of service diversion has been reached.

How to create queue manager and reply-to aliases

As discussed above, the remote queue definition object is used in three different
ways. Table 2 on page 37 explains how to define each of the three ways:
v Using a remote queue definition to redefine a local queue name.
The application provides only the queue name when opening a queue, and this
queue name is the name of the remote queue definition.
The remote queue definition contains the names of the target queue and queue
manager, and optionally, the definition can contain the name of the transmission
queue to be used. If no transmission queue name is provided, the queue
manager uses the new queue manager name for the transmission queue name. If
a transmission queue of this name is not defined, but a default transmission
queue is defined, the default transmission queue is used.
v Using a remote queue definition to redefine a queue manager name.
The application, or channel program, provides a queue name together with the
remote queue manager name when opening the queue.
If you have provided a remote queue definition with the same name as the
queue manager name, and you have left the queue name in the definition blank,
then the queue manager will substitute the queue manager name in the open
call with the queue manager name in the definition.
In addition, the definition can contain the name of the transmission queue to be
used. If no transmission queue name is provided, the queue manager takes the
new queue manager name for the transmission queue name. If a transmission
queue of this name is not defined, but a default transmission queue is defined,
the default transmission queue is used.

36 MQSeries Intercommunication
 Message flow control
v Using a remote queue definition to redefine a reply-to queue name.
Each time an application puts a message to a queue, it may provide the name of
a reply-to queue for answer messages but with the queue manager name blank.
If you provide a remote queue definition with the same name as the reply-to
queue then the local queue manager replaces the reply-to queue name with the
queue name from your definition.
You may provide a queue manager name in the definition, but not a
transmission queue name.
Table 2. Three ways of using the remote queue definition object
Usage Queue manager Queue name Transmission
name queue name
1. Remote queue definition (on OPEN call)
Supplied in the call blank or local QM (*) required -
Supplied in the definition required required optional
2. Queue manager alias (on OPEN call)
Supplied in the call (*) required and required -
not local QM
Supplied in the definition required blank optional
3. Reply-to queue alias (on PUT call)
Supplied in the call blank (*) required -
Supplied in the definition optional optional blank
Note: (*) means that this name is the name of the definition object

For a formal description, see “Appendix C. Queue name resolution” on page 633.

Putting messages on remote queues

In a distributed-queuing environment, a transmission queue and channel are the
focal point for all messages to a location whether the messages originate from
applications in your local system, or arrive through channels from an adjacent
system. This is shown in Figure 19 on page 38 where an application is placing
messages on a logical queue named ‘QA_norm’. The name resolution uses the
remote queue definition ‘QA_norm’ to select the transmission queue ‘QMB’, and
adds a transmission header to the messages stating ‘QA_norm at QMB’.

Messages arriving from the adjacent system on ‘Channel_back’ have a transmission

header with the physical queue name ‘QA_norm at QMB’, for example. These
messages are placed unchanged on transmission queue QMB.

The channel moves the messages to an adjacent queue manager.

Chapter 4. MQSeries distributed-messaging techniques 37

Messages on remote queues

A d ja ce n t Lo cal syste m
syste m
A p p lic a tio n 'Q M A '

Q A n o rm a t Q M B v ia Q M B
QA norm
Queue 'Q A n o rm '

Channel back Queue 'Q M B ' Channel out

Q A n o rm a t Q M B
C h a n n e l to a d ja c e n t s y s te m

Figure 19. A remote queue definition is used to resolve a queue name to a transmission
queue to an adjacent queue manager. Note: The dashed outline represents a remote queue
definition. This is not a real queue, but a name alias that is controlled as though it were a
real queue.

Your part in this scenario is to:

v Define the message channel from the adjacent system
v Define the message channel to the adjacent system
v Create the transmission queue ‘QMB’
v Define the remote queue object ‘QA_norm’ to resolve the queue name used by
applications to the desired destination queue name, destination queue manager
name, and transmission queue name

In a clustering environment, you only need to define a cluster-receiver channel at

the local queue manager. You do not need to define a transmission queue or a
remote queue object. For information about this, see the MQSeries Queue Manager
Clusters book.

More about name resolution

The effect of the remote queue definition is to define a physical destination queue
name and queue manager name; these names are put in the transmission headers
of messages.

Incoming messages from an adjacent system have already had this type of name
resolution carried out by the original queue manager, and have the transmission
header showing the physical destination queue name and queue manager name.
These messages are unaffected by remote queue definitions.

38 MQSeries Intercommunication
 Choosing the transmission queue

Choosing the transmission queue

Adjacent Local system

system
Application 'QMA'

QA norm at
QMB priority via TXI
QA nor m
Queue 'Q A n o r m '

Queue 'TXI' Channel out

Channel to adjacent system

Figure 20. The remote queue definition allows a different transmission queue to be used

In a distributed-queuing environment, when you need to change a message flow

from one channel to another, use the same system configuration as shown in
Figure 19 on page 38. Figure 20 shows how you use the remote queue definition to
send messages over a different transmission queue, and therefore over a different
channel, to the same adjacent queue manager.

In Figure 20, you provide:

v The remote queue object ‘QA_norm’ to choose:
– Queue ‘QA_norm’ at the remote queue manager
– Transmission queue ‘TX1’
– Queue manager ‘QMB_priority’
v The transmission queue ‘TX1’. Specify this in the definition of the channel to the
adjacent system

Messages are placed on transmission queue ‘TX1’ with a transmission header

containing ‘QA_norm at QMB_priority’, and are sent over the channel to the
adjacent system.

The channel_back has been left out of this illustration because it would need a
queue manager alias; this is discussed in the following example.

In a clustering environment, you do not need to define a transmission queue or a

remote queue definition. For more information about this, see the MQSeries Queue
Manager Clusters book.

Chapter 4. MQSeries distributed-messaging techniques 39

Receiving messages

Receiving messages

A djacent Local system

system
A p p lica tio n 'Q M B '

Q A n o rm
Q ueue 'Q A norm '

C hannel back
Q A n o rm a t Q M B

C hannel back Q ueue 'Q M B p r io rity '

Q A n o rm a t
Q M B p rio rity Q M B p riority to Q M B

Figure 21. Receiving messages directly, and resolving alias queue manager name

As well as arranging for messages to be sent, you also arrange for messages to be
received from adjacent queue managers. Received messages contain the physical
name of the destination queue manager and queue in the transmission header.
They are treated exactly the same as messages from a local application that
specifies both queue manager name and queue name. Because of this, you need to
ensure that messages entering your system do not have an unintentional name
resolution carried out. See Figure 21 for this scenario.

For this scenario, you prepare:

v Message channels to receive messages from adjacent queue managers
v A queue manager alias definition to resolve an incoming message flow,
‘QMB_priority’, to the local queue manager name, ‘QMB’
v The local queue, ‘QA_norm’, if it does not already exist

Receiving alias queue manager names

The use of the queue manager alias definition in this illustration has not selected a
different destination queue manager. Messages passing through this local queue
manager and addressed to ‘QMB_priority’ are intended for queue manager ‘QMB’.
The alias queue manager name is used to create the separate message flow.

40 MQSeries Intercommunication
 Passing messages through system

Passing messages through your system

Adjacent Local system Adjacent

system system
'QMB'

Channel in Queue 'QMC' Channel out

Channel in Queue 'QMD norm'

Queue 'TX1' Channel out

Channel in Queue 'QMD PRIORITY'

Queue 'QMD fast' Channel out

Figure 22. Three methods of passing messages through your system

Following on from the technique shown in Figure 21 on page 40, where you saw
how an alias flow is captured, Figure 22 illustrates the ways networks are built up
by bringing together the techniques we have discussed.

The scenario shows a channel delivering three messages with different

destinations:
1. ‘QMB at QMC’
2. ‘QMB at QMD_norm’
3. ‘QMB at QMD_PRIORITY’

You need to pass the first message flow through your system unchanged; the
second message flow through a different transmission queue and channel, while
reverting the messages from the alias queue manager name ‘QMD_norm’ to the
physical location ‘QMD’; and the third message flow simply chooses a different
transmission queue without any other change.

In a clustering environment, all messages are passed through the cluster

transmission queue, SYSTEM.CLUSTER.TRANSMIT.QUEUE. This is illustrated in
Figure 4 on page 7.

The following methods describe techniques applicable to a distributed-queuing

environment:

Chapter 4. MQSeries distributed-messaging techniques 41

Passing messages through system
Method 1: Using the incoming location name
When you need to receive messages with a transmission header containing another
location name, the simplest preparation is to have a transmission queue with that
name, ‘QMC’ in this example, as a part of a channel to an adjacent queue manager.
The messages are delivered unchanged.

Method 2: Using an alias for the queue manager

The second method is to use the queue manager alias object definition, but specify
a new location name, ‘QMD’, as well as a particular transmission queue, ‘TX1’.
This action:
v Terminates the alias message flow set up by the queue manager name alias
‘QMD_norm’. That is the named class of service ‘QMD_norm’.
v Changes the transmission headers on these messages from ‘QMD_norm’ to
‘QMD’.

Method 3: Selecting a transmission queue

The third method is to have a queue manager alias object defined with the same
name as the destination location, ‘QMD_PRIORITY’, and use the definition to
select a particular transmission queue, ‘QMD_fast’, and therefore another channel.
The transmission headers on these messages remain unchanged.

Using these methods

For these scenarios, you prepare the:
v Input channel definitions
v Output channel definitions
v Transmission queues:
– QMC
– TX1
– QMD_fast
v Queue manager alias definitions:
– QMD_norm with ‘QMD_norm to QMD via TX1’
– QMD_PRIORITY with ‘QMD_PRIORITY to QMD_PRIORITY via QMD_fast’

Note
None of the message flows shown in the example changes the destination
queue. The queue manager name aliases simply provide separation of
message flows.

Separating message flows

In a distributed-queuing environment, the need to separate messages to the same
queue manager into different message flows can arise for a number of reasons. For
example:
v You may need to provide a separate flow for very large, large, medium, and
small messages. This also applies in a clustering environment and, in this case,
you may create clusters that overlap. There are a number of reasons you might
do this, for example:
– To allow different organizations to have their own administration.
– To allow independent applications to be administered separately.

42 MQSeries Intercommunication
 Separating message flows
– To create a class of service. For example you could have a cluster called
STAFF that is a subset of the cluster called STUDENTS. When you put a
message to a queue advertised in the STAFF cluster, a restricted channel is
used. When you put a message to a queue advertised in the STUDENTS
cluster, either a general channel or a restricted channel may be used.
– To create test and production environments.
v It may be necessary to route incoming messages via different paths from the
path of the locally generated messages.
v Your installation may require to schedule the movement of messages at certain
times (for example, overnight) and the messages then need to be stored in
reserved queues until scheduled.

Adjacent Local system Adjacent

system system
'QMB'

QB at QMC small
Channel back Queue 'QMC small'

Application
'QB small'
Queue 'QB small'

Queue 'TX small' Channel out

QB large
Queue 'QB large'

Queue 'TX large' Channel out

QB at QMC large
Channel back Queue 'QMC large'

Queue 'TX external' Channel out

Figure 23. Separating messages flows

In the example shown in Figure 23, the two incoming flows are to alias queue
manager names ‘QMC_small’ and ‘QMC_large’. You provide these flows with a
queue manager alias definition to capture these flows for the local queue manager.
You have an application addressing two remote queues and you need these
message flows to be kept separate. You provide two remote queue definitions that
specify the same location, ‘QMC’, but specify different transmission queues. This
keeps the flows separate, and nothing extra is needed at the far end as they have
the same destination queue manager name in the transmission headers. You
provide:
v The incoming channel definitions
v The two remote queue definitions QB_small and QB_large
v The two queue manager alias definitions QMC_small and QMC_large
v The three sending channel definitions
v Three transmission queues: TX_small, TX_large, and TX_external

Chapter 4. MQSeries distributed-messaging techniques 43

Separating message flows

Coordination with adjacent systems

When you use a queue manager alias to create a separate message flow, you
need to coordinate this activity with the system administrator at the remote
end of the message channel to ensure that the corresponding queue manager
alias is available there.

Concentrating messages to diverse locations

Adjacent Local system Adjacent

system system

'QMB'

QB at QME
Channel back Queue 'QME'

A pp li ca ti on

QA
Queue 'QA'

QB
Queue 'QB'

Channel out Queue 'T X1'

'QMC'

Local queue

Queue 'QA'

Channel back Queue 'QMD' Channel out QB at QMD

Queue 'QME' Channel out QB at QME

Figure 24. Combining message flows on to a channel

Figure 24 illustrates a distributed-queuing technique for concentrating messages

that are destined for various locations on to one channel. Two possible uses would
be:
v Concentrating message traffic through a gateway
v Using wide bandwidth highways between nodes

In this example, messages from different sources, local and adjacent, and having
different destination queues and queue managers, are flowed via transmission
queue ‘TX1’ to queue manager QMC. Queue manager QMC delivers the messages
according to the destinations, one set to a transmission queue ‘QMD’ for onward

44 MQSeries Intercommunication
 Concentrating messages
transmission to queue manager QMD, another set to a transmission queue ‘QME’
for onward transmission to queue manager QME, while other messages are put on
the local queue ‘QA’.

You provide:
v Channel definitions
v Transmission queue TX1
v Remote queue definitions:
– QA with ‘QA at QMC via TX1’
– QB with ‘QB at QMD via TX1’
v Queue manager alias definition:
– QME with ‘QME via TX1’

Your colleague controlling QMC provides:

v Receiving channel definition with the same channel name
v Transmission queue QMD with associated sending channel definition
v Transmission queue QME with associated sending channel definition

Diverting message flows to another destination

Adjacent Local system Adjacent system Adjacent system

system

'QMA' 'QMB' 'QMD'

Channel back Queue 'QMC'

QB at QMC Local queue

Queue 'QMB' Channel Queue 'QMD' Channel Queue ' Q B'

Figure 25. Diverting message streams to another destination

Figure 25 illustrates how you can redefine the destination of certain messages.
Incoming messages to QMA are destined for ‘QB at QMC’. They would normally
arrive at QMA and be placed on a transmission queue called QMC which would
have been part of a channel to QMC. QMA must divert the messages to QMD, but
is able to reach QMD only over QMB. This method is useful when you need to
move a service from one location to another, and allow subscribers to continue to
send messages on a temporary basis until they have adjusted to the new address.

The method of rerouting incoming messages destined for a certain queue manager
to a different queue manager uses:
v A queue manager alias to change the destination queue manager to another
queue manager, and to select a transmission queue to the adjacent system
v A transmission queue to serve the adjacent queue manager
v A transmission queue at the adjacent queue manager for onward routing to the
destination queue manager

You provide:
v Channel_back definition
v Queue manager alias object definition QMC with QB at QMD via QMB

Chapter 4. MQSeries distributed-messaging techniques 45

Diverting message flows
v Channel_out definition
v The associated transmission queue QMB

Your colleague who controls QMB provides:

v The corresponding channel_back definition
v The transmission queue, QMD
v The associated channel definition to QMD

You can use aliases within a clustering environment. For information about this,
see the MQSeries Queue Manager Clusters book.

Sending messages to a distribution list

In MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT,
an application can send a message to several destinations with a single MQPUT
call. This applies in both a distributed-queuing environment and a clustering
environment. You have to define the destinations in a distribution list, as described
in the MQSeries Application Programming Guide.

Not all queue managers support distribution lists. When an MCA establishes a
connection with a partner, it determines whether or not the partner supports
distribution lists and sets a flag on the transmission queue accordingly. If an
application tries to send a message that is destined for a distribution list but the
partner does not support distribution lists, the sending MCA intercepts the
message and puts it onto the transmission queue once for each intended
destination.

A receiving MCA ensures that messages sent to a distribution list are safely
received at all the intended destinations. If any destinations fail, the MCA
establishes which ones have failed so that it can generate exception reports for
them and can try to resend the messages to them.

46 MQSeries Intercommunication
 Reply-to queue

Reply-to queue

Local system Adjacent system

Application QMA QMB Application

'E' Queue 'QR' 'F'

QA at QMB
reply-to
QR QA at QMB
Queue 'QMB' Queue 'QA'

Queue 'QMA class1' Queue 'QMA class1'

QRR at
QMA class1

Queue 'QRR'

Figure 26. Reply-to queue name substitution during PUT call

A complete remote queue processing loop using a reply-to queue is shown in

Figure 26. This applies in both a distributed-queuing environment and a clustering
environment. The details are as shown in Table 6 on page 54.

The application opens QA at QMB and puts messages on that queue. The messages
are given a reply-to queue name of QR, without the queue manager name being
specified. Queue manager QMA finds the reply-to queue object QR and extracts
from it the alias name of QRR and the queue manager name QMA_class1. These
names are put into the reply-to fields of the messages.

Reply messages from applications at QMB are addressed to QRR at QMA_class1.

The queue manager alias name definition QMA_class1 is used by the queue
manager to flow the messages to itself, and to queue QRR.

This scenario depicts the way you give applications the facility to choose a class of
service for reply messages, the class being implemented by the transmission queue
QMA_class1 at QMB, together with the queue manager alias definition,
QMA_class1 at QMA. In this way, you can change an application’s reply-to queue
so that the flows are segregated without involving the application. That is, the
application always chooses QR for this particular class of service, and you have the
opportunity to change the class of service with the reply-to queue definition QR.

You create:
v Reply-to queue definition QR
v Transmission queue object QMB
v Channel_out definition
v Channel_back definition
v Queue manager alias definition QMA_class1
v Local queue object QRR, if it does not exist

Your colleague at the adjacent system creates the:

Chapter 4. MQSeries distributed-messaging techniques 47

Reply-to queue
v Receiving channel definition
v Transmission queue object QMA_class1
v Associated sending channel

Your application programs use:

v Reply-to queue name QR in put calls
v Queue name QRR in get calls

In this way, you may change the class of service as necessary, without involving
the application, by changing the reply-to alias ‘QR’, together with the transmission
queue ‘QMA_class1’ and queue manager alias ‘QMA_class1’.

If no reply-to alias object is found when the message is put on the queue, the local
queue manager name is inserted in the blank reply-to queue manager name field,
and the reply-to queue name remains unchanged.

Name resolution restriction

Because the name resolution has been carried out for the reply-to queue at
‘QMA’ when the original message was put, no further name resolution is
allowed at ‘QMB’, that is, the message is put with the physical name of the
reply-to queue by the replying application.

Note that the applications must be aware of the naming convention that the name
they use for the reply-to queue is different from the name of the actual queue
where the return messages are to be found.

For example, when two classes of service are provided for the use of applications
with reply-to queue alias names of ‘C1_alias’, and ‘C2_alias’, the applications use
these names as reply-to queue names in the message put calls, but the applications
will actually expect messages to appear in queues ‘C1’ and ‘C2’, respectively.

However, an application is able to make an inquiry call on the reply-to alias queue
to check for itself the name of the real queue it must use to get the reply messages.

Reply-to queue alias example

This example illustrates the use of a reply-to alias to select a different route
(transmission queue) for returned messages. The use of this facility requires the
reply-to queue name to be changed in cooperation with the applications.

As shown in Figure 27 on page 49, the return route must be available for the reply
messages, including the transmission queue, channel, and queue manager alias.

48 MQSeries Intercommunication
 Reply-to queue

'QM1' 'QM2'

Queue 'Inquiry'

Queue 'QM2' Channel out Queue 'Inquiry'

Queue 'Answer alias'

Q='Answer'
QM='QM1 relief'

Queue 'Answer'

Queue 'QM1 relief' Channel back Queue 'QM1 relief'

Figure 27. Reply-to queue alias example

This example is for requester applications at ‘QM1’ that send messages to server
applications at ‘QM2’. The servers’ messages are to be returned through an
alternative channel using transmission queue ‘QM1_relief’ (the default return
channel would be served with a transmission queue ‘QM1’).

The reply-to queue alias is a particular use of the remote queue definition named
‘Answer_alias’. Applications at QM1 include this name, ‘Answer_alias’, in the
reply-to field of all messages that they put on queue ‘Inquiry’.

Reply-to queue definition ‘Answer_alias’ is defined as ‘Answer at QM1_relief’.

Applications at QM1 expect their replies to appear in the local queue named
‘Answer’.

Server applications at QM2 use the reply-to field of received messages to obtain
the queue and queue manager names for the reply messages to the requester at
QM1.

Definitions used in this example at QM1

The system supervisor at QM1 must ensure that the reply-to queue ‘Answer’ is
created along with the other objects. The name of the queue manager alias, marked
with a ‘*’, must agree with the queue manager name in the reply-to queue alias
definition, also marked with an ‘*’.

Chapter 4. MQSeries distributed-messaging techniques 49

Reply-to queue
Object Definition
Local transmission queue QM2
Remote queue definition Object name Inquiry
Remote queue manager name QM2
Remote queue name Inquiry
Transmission queue name QM2 (DEFAULT)
Queue manager alias Object name QM1_relief *
Queue manager name QM1
Queue name (blank)
Reply-to queue alias Object name Answer_alias
Remote queue manager name QM1_relief *
Remote queue name Answer

Definitions used in this example at QM2

The system supervisor at QM2 must ensure that the local queue exists for the
incoming messages, and that the correctly named transmission queue is available
for the reply messages.

Object Definition
Local queue Inquiry
Transmission queue QM1_relief

Put definition at QM1

Applications fill the reply-to fields with the reply-to queue alias name, and leave
the queue manager name field blank.

Field Content
Queue name Inquiry
Queue manager name (blank)
Reply-to queue name Answer_alias
Reply-to queue manager (blank)

Put definition at QM2

Applications at QM2 retrieve the reply-to queue name and queue manager name
from the original message and use them when putting the reply message on the
reply-to queue.

Field Content
Queue name Answer
Queue manager name QM1_relief

How the example works

In this example, requester applications at QM1 always use ‘Answer_alias’ as their
reply-to queue in the relevant field of the put call, and they always retrieve their
messages from the queue named ‘Answer’.

The reply-to queue alias definitions are available for use by the QM1 system
supervisor to change the name of the reply-to queue ‘Answer’, and of the return
route ‘QM1_relief’.

Changing the queue name ‘Answer’ is normally not useful because the QM1
applications are expecting their answers in this queue. However, the QM1
supervisor is able to change the return route (class of service), as necessary.

50 MQSeries Intercommunication
 Reply-to queue
How the queue manager makes use of the reply-to queue alias
Queue manager QM1 retrieves the definitions from the reply-to queue alias when
the reply-to queue name, included in the put call by the application, is the same as
the reply-to queue alias, and the queue manager part is blank.

The queue manager replaces the reply-to queue name in the put call with the
queue name from the definition. It replaces the blank queue manager name in the
put call with the queue manager name from the definition.

These names are carried with the message in the message descriptor.
Table 3. Reply-to queue alias
Field name Put call Transmission header
Queue name Answer_alias Answer
Queue manager name (blank) QM1_relief

Reply-to queue alias walk-through

To complete this example, let us take a walk through the process, from an
application putting a message on a remote queue at queue manager ‘QM1’,
through to the same application removing the reply message from the alias
reply-to queue.
1. The application opens a queue named ‘Inquiry’, and puts messages to it. The
application sets the reply-to fields of the message descriptor to:

Reply-to queue name Answer_alias

Reply-to queue manager name (blank)

2. Queue manager ‘QM1’ responds to the blank queue manager name by

checking for a remote queue definition with the name ‘Answer_alias’. If none
is found, the queue manager places its own name, ‘QM1’, in the reply-to
queue manager field of the message descriptor.
3. If the queue manager finds a remote queue definition with the name
‘Answer_alias’, it extracts the queue name and queue manager names from
the definition (queue name=‘Answer’ and queue manager name=
‘QM1_relief’) and puts them into the reply-to fields of the message descriptor.
4. The queue manager ‘QM1’ uses the remote queue definition ‘Inquiry’ to
determine that the intended destination queue is at queue manager ‘QM2’,
and the message is placed on the transmission queue ‘QM2’. ‘QM2’ is the
default transmission queue name for messages destined for queues at queue
manager ‘QM2’.
5. When queue manager ‘QM1’ puts the message on the transmission queue, it
adds a transmission header to the message. This header contains the name of
the destination queue, ‘Inquiry’, and the destination queue manager, ‘QM2’.
6. The message arrives at queue manager ‘QM2’, and is placed on the ‘Inquiry’
local queue.
7. An application gets the message from this queue and processes the message.
The application prepares a reply message, and puts this reply message on the
reply-to queue name from the message descriptor of the original message.
This is:

Reply-to queue name Answer

Reply-to queue manager name QM1_relief

Chapter 4. MQSeries distributed-messaging techniques 51

Reply-to queue
8. Queue manager ‘QM2’ carries out the put command, and finding that the
queue manager name, ‘QM1_relief’, is a remote queue manager, it places the
message on the transmission queue with the same name, ‘QM1_relief’. The
message is given a transmission header containing the name of the destination
queue, ‘Answer’, and the destination queue manager, ‘QM1_relief’.
9. The message is transferred to queue manager ‘QM1’ where the queue
manager, recognizing that the queue manager name ‘QM1_relief’ is an alias,
extracts from the alias definition ‘QM1_relief’ the physical queue manager
name ‘QM1’.
10. Queue manager ‘QM1’ then puts the message on the queue name contained in
the transmission header, ‘Answer’.
11. The application extracts its reply message from the queue ‘Answer’.

Networking considerations
In a distributed-queuing environment, because message destinations are addressed
with just a queue name and a queue manager name, the following rules apply:
1. Where the queue manager name is given, and the name is different from the
local queue manager’s name:
v A transmission queue must be available with the same name, and this
transmission queue must be part of a message channel moving messages to
another queue manager, or
v A queue manager alias definition must exist to resolve the queue manager
name to the same, or another queue manager name, and optional
transmission queue, or
v If the transmission queue name cannot be resolved, and a default
transmission queue has been defined, the default transmission queue is used.
2. Where only the queue name is supplied, a queue of any type but with the same
name must be available on the local queue manager. This queue may be a
remote queue definition which resolves to: a transmission queue to an adjacent
queue manager, a queue manager name, and an optional transmission queue.

To see how this works in a clustering environment, see the MQSeries Queue
Manager Clusters book.

Consider the scenario of a message channel moving messages from one queue
manager to another in a distributed-queuing environment.

The messages being moved have originated from any other queue manager in the
network, and some messages may arrive that have an unknown queue manager
name as destination. This can occur when a queue manager name has changed or
has been removed from the system, for example.

The channel program recognizes this situation when it cannot find a transmission
queue for these messages, and places the messages on your undelivered-message
(dead-letter) queue. It is your responsibility to look for these messages and arrange
for them to be forwarded to the correct destination, or to return them to the
originator, where this can be ascertained.

Exception reports are generated in these circumstances, if report messages were

requested in the original message.

52 MQSeries Intercommunication
 Networking considerations

Name resolution convention

It is strongly recommended that name resolution that changes the identity of
the destination queue, (that is, logical to physical name changing), should
only occur once, and only at the originating queue manager.

Subsequent use of the various alias possibilities should be used only when
separating and combining message flows.

Return routing
Messages may contain a return address in the form of the name of a queue and
queue manager. This applies in both a distributed-queuing environment and a
clustering environment. This address is normally specified by the application that
creates the message, but may be modified by any application that subsequently
handles the message, including user exit applications.

Irrespective of the source of this address, any application handling the message
may choose to use this address for returning answer, status, or report messages to
the originating application.

The way these response messages is routed is not different from the way the
original message is routed. You need to be aware that the message flows you
create to other queue managers will need corresponding return flows.

Physical name conflicts

The destination reply-to queue name has been resolved to a physical queue
name at the original queue manager, and must not be resolved again at the
responding queue manager.

This is a likely possibility for name conflict problems that can only be
prevented by a network-wide agreement on physical and logical queue
names.

Managing queue name translations

This description is mainly provided for application designers and channel planners
concerned with an individual system that has message channels to adjacent
systems. It takes a local view of channel planning and control.

When you create a queue manager alias definition or a remote queue definition,
the name resolution is carried out for every message carrying that name, regardless
of the source of the message. To oversee this situation, which may involve large
numbers of queues in a queue manager network, you keep tables of:
v The names of source queues and of source queue managers with respect to
resolved queue names, resolved queue manager names, and resolved
transmission queue names, with method of resolution
v The names of source queues with respect to:
– Resolved destination queue names
– Resolved destination queue manager names
– Transmission queues
– Message channel names

Chapter 4. MQSeries distributed-messaging techniques 53

Managing queue name translations
– Adjacent system names
– Reply-to queue names

Note: The use of the term source in this context refers to the queue name or the
queue manager name provided by the application, or a channel program
when opening a queue for putting messages.

An example of each of these tables is shown in Table 4, Table 5, and Table 6.

The names in these tables are derived from the examples in this chapter, and this
table is not intended as a practical example of queue name resolution in one node.
Table 4. Queue name resolution at queue manager QMA
Source queue Source queue manager Resolved queue Resolved queue Resolved transmission Resolution type
specified when specified when queue is name manager name queue name
queue is opened opened
QA_norm - QA_norm QMB QMB Remote queue
(any) QMB - - QMB (none)
QA_norm - QA_norm QMB TX1 Remote queue
QB QMC QB QMD QMB Queue manager alias

Table 5. Queue name resolution at queue manager QMB

Source queue Source queue manager Resolved queue Resolved queue Resolved transmission Resolution type
specified when specified when queue is name manager name queue name
queue is opened opened
QA_norm - QA_norm QMB - (none)
QA_norm QMB QA_norm QMB - (none)
QA_norm QMB_PRIORITY QA_norm QMB - Queue manager alias
(any) QMC (any) QMC QMC (none)
(any) QMD_norm (any) QMD_norm TX1 Queue manager alias
(any) QMD_PRIORITY (any) QMD_PRIORITY QMD_fast Queue manager alias
(any) QMC_small (any) QMC_small TX_small Queue manager alias
(any) QMC_large (any) QMC_large TX_external Queue manager alias
QB_small QMC QB_small QMC TX_small Remote queue
QB_large QMC QB_large QMC TX_large Remote queue
(any) QME (any) QME TX1 Queue manager alias
QA QMC QA QMC TX1 Remote queue
QB QMD QB QMD TX1 Remote queue

Table 6. Reply-to queue name translation at queue manager QMA

Application design Reply-to alias definition

Local QMGR Queue name for messages Reply-to queue alias name Redefined to
QMA QRR QR QRR at QMA_class1

Message sequence numbering

The message sequence numbering function is useful in some environments,
especially when messages are to be guaranteed to be delivered, delivered without
duplication, and stored in the same order as they were taken from the transmission
queue. Each message sent using message sequencing is tagged with an individual
sequence number, which is increased by one for each message sent. The sequence
number is assigned by the sending channel. In some implementations, this
sequence number is then regarded as a permanent attribute of the message, and is
retained by the receiving channel; in other implementations, it is removed by the
receiving channel.

54 MQSeries Intercommunication
 Message sequence numbering
Cooperating channels must be capable of:
v Respecting the sequential delivery attribute in their channel definition record
v Identifying or assigning a sequence number for each message sent or received
v Recording the sequence number assigned to the last message committed, on
hardened media for use in recovery
v Recording the sequence numbers such that they can be read by status
commands for problem resolution
v Detecting out-of-sequence conditions, such as duplicate numbers or gaps, and
returning an appropriate error indication

Sequence numbering is incompatible with the use of multiple channels to serve

one transmission queue.

The sequence number of the last committed message or LUWID is recorded at the
receiving end of a channel. This number is used at the sending end when
sequential delivery of messages has been selected. It is also used during
resequencing, on startup and restarts, to ensure that both ends of the link agree on
which messages have been transferred successfully.

The number stored at the sending end is incremented by one before being used;
this means that the current sequence number is the number of the last message
sent, and the numbering is independent of the instance of the MCA.

Sequential retrieval of messages

If an application puts a sequence of messages to the same destination queue, those
messages can be retrieved in sequence by a single application with a sequence of
get operations, if, for local queuing, the following conditions are met:
v All of the put requests were done from the same application
v All of the put requests were either from the same unit of work, or all the put
requests were made outside of a unit of work
v The application getting the message does not deliberately change the order of
retrieval, for example by specifying a particular MsgId or CorrelId or by using
message priorities
v Only one application is doing get operations to retrieve the messages from the
destination queue, unless the applications doing the get operations ensure, for
example, by specifying a CorrelId, that a single application always gets all of
the messages in each sequence put by a sending application
v Only one channel is serving the transmission queue
v The messages are not nonpersistent messages on a fast channel

Note: Messages from other tasks and units of work may be interspersed with the
sequence, even where the sequence was put from within a single unit of
work.

The order is preserved for remote queuing, but only if the configuration is such
that there can be only one path for the messages in the sequence, from the
application making the put request, through its queue manager, through
intercommunication, to the destination queue manager and the target queue.

Note: Messages that are destined for remote queues can also become out of
sequence if one or more of them is put to a dead-letter queue (for example,
if a queue is temporarily full).

Chapter 4. MQSeries distributed-messaging techniques 55

Message sequence numbering
If there is a possibility that some messages may be sent via a different path, for
example because of reconfiguration, the order at the destination cannot be
guaranteed.

Sequence of retrieval of fast, nonpersistent messages

In MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, OS/390 without CICS, Sun
Solaris, Windows V2.1, and Windows NT, nonpersistent messages on a fast channel
may overtake persistent messages on the same channel and so arrive out of
sequence. The receiving MCA puts the nonpersistent messages on the destination
queue immediately and makes them visible. Persistent messages are not made
visible until the next syncpoint.

Loopback testing
Loopback testing is a technique on non-OS/390 platforms that allows you to test a
communications link without actually linking to another machine. You set up a
connection between two queue managers as though they are on separate machines,
but you test the connection by looping back to another process on the same
machine. This means that you can test your communications code without
requiring an active network.

The way you do this depends on which products and protocols you are using. For
example the command to allow TCP/IP loopback testing on OS/2 without a
network, is:
ifconfig lo ipaddress

On Windows NT, you can use the “loopback” adapter.

Refer to the documentation for the products you are using for more information.

56 MQSeries Intercommunication
Chapter 5. DQM implementation
This chapter describes the implementation of the concepts introduced in
“Chapter 2. Making your applications communicate” on page 17.

Distributed queue management (DQM):

v Enables you to define and control communication channels between queue
managers
v Provides you with a message channel service to move messages from a type of
local queue, known as a transmission queue, to communication links on a local
system, and from communication links to local queues at a destination queue
manager
v Provides you with facilities for monitoring the operation of channels and
diagnosing problems, using panels, commands, and programs

This chapter discusses:

v “Functions of DQM”
v “Message sending and receiving” on page 58
v “Channel control function” on page 59
v “What happens when a message cannot be delivered?” on page 71
v “Initialization and configuration files” on page 73
v “Data conversion” on page 75
v “Writing your own message channel agents” on page 75

Functions of DQM
Distributed queue management has these functions:
v Message sending and receiving
v Channel control
v Initialization file
v Data conversion
v Channel exits

Channel definitions associate channel names with transmission queues,

communication link identifiers, and channel attributes. These are kept in a channel
definition file (CDF), implemented in different ways on different platforms.
Message sending and receiving is controlled by programs known as message channel
agents (MCAs), which use the channel definitions to start up and control
communication.

The MCAs in turn are controlled by DQM itself. The structure is platform
dependent, but typically includes listeners and trigger monitors, together with
operator commands and panels.

A message channel is a one-way pipe for moving messages from one queue manager
to another. Thus a message channel has two end-points, represented by a pair of
MCAs. Each end-point has a definition of its end of the message channel. For
example, one end would define a sender, the other end a receiver.

© Copyright IBM Corp. 1993, 2000 57

Functions of DQM
For details of how to define channels, see:
v “Chapter 8. Monitoring and controlling channels on distributed platforms” on
page 105
v “Chapter 23. Monitoring and controlling channels on OS/390” on page 321
v “Chapter 26. Monitoring and controlling channels in OS/390 with CICS” on
page 351
v “Chapter 30. Monitoring and controlling channels in MQSeries for AS/400” on
page 423

For information about channel exits, see “Chapter 36. Channel-exit programs” on
page 505.

Message sending and receiving

Figure 28 shows the relationships between entities when messages are transmitted,
and shows the flow of control.

Operator
Synchronization
Information
File Channel definitions

Status C o mm a nd s

User Message Message User

Exits Channel C o mm a nd s Channel Control C o mm a nd s Channel Exits
Agent Function Agent
(MCA) (MCA)
Status Status

Channel Listener
SENDING Initiator RECEIVING

Messages Messages

Queue Transmission Queue Local

Queue Local
Tr i g g e r Queue Initiation
m essag e

Queue Local

Communications
Messages Network Messages

Messages

TO ADJACENT QUEUE MANAGER

Figure 28. Distributed queue management model

Notes:
1. There is one MCA per channel, depending on the platform. There may be one
or more channel control functions for a given queue manager.

58 MQSeries Intercommunication
 Message sending and receiving
2. The implementation of MCAs and channel control functions is highly platform
dependent; they may be programs or processes or threads, and they may be a
single entity or many comprising several independent or linked parts.
3. All components marked with a star can use the MQI.

Channel parameters
An MCA receives its parameters in one of several ways:
v If started by a command, the channel name is passed in a data area. The MCA
then reads the channel definition directly to obtain its attributes.
v For sender, and in some cases server channels, the MCA can be started
automatically by the queue manager trigger. The channel name is retrieved from
the trigger process definition, where applicable, and is passed to the MCA. The
remaining processing is the same as that described above.
v If started remotely by a sender, server, requester, or client-connection, the
channel name is passed in the initial data from the partner message channel
agent. The MCA reads the channel definition directly to obtain its attributes.

Certain attributes not defined in the channel definition are also negotiable:
Split messages
If one end does not support this, split messages will not be sent.
Conversion capability
If one end cannot perform the necessary code page conversion or numeric
encoding conversion when needed, the other end must handle it. If neither
end supports it, when needed, the channel cannot start.
Distribution list support
If one end does not support distribution lists, the partner MCA sets a flag
in its transmission queue so that it will know to intercept messages
intended for multiple destinations.

Channel status and sequence numbers

Message channel agent programs keep records of the current sequence number and
logical unit of work number for each channel, and of the general status of the
channel. Some platforms allow you to display this status information to help you
control channels.

Channel control function

The channel control function provides facilities for you to define, monitor, and
control channels. Commands are issued through panels, programs, or from a
command line to the channel control function. The panel interface also displays
channel status and channel definition data.

Note: For the channel control function on MQSeries for OS/2 Warp, Windows NT,
Windows V2.1, UNIX systems, Digital OpenVMS, and Tandem NSK, you
can use Programmable Command Formats or those MQSeries commands
(MQSC) and control commands that are detailed in “Chapter 8. Monitoring
and controlling channels on distributed platforms” on page 105.

The commands fall into the following groups:

v Channel administration
v Channel control
v Channel status monitoring

Chapter 5. DQM implementation 59

Channel control function
Channel administration commands deal with the definitions of the channels. They
enable you to:
v Create a channel definition
v Copy a channel definition
v Alter a channel definition
v Delete a channel definition

Channel control commands manage the operation of the channels. They enable you
to:
v Start a channel
v Stop a channel
v Re-synchronize with partner (in some implementations)
v Reset message sequence numbers
v Resolve an in-doubt batch of messages
v Ping; send a test communication across the channel (not on MQSeries for
Windows)

Channel monitoring displays the state of channels, for example:

v Current channel settings
v Whether the channel is active or inactive
v Whether the channel terminated in a synchronized state

Preparing channels
Before trying to start a message channel or MQI channel, you must make sure that
all the attributes of the local and remote channel definitions are correct and
compatible. “Chapter 6. Channel attributes” on page 77 describes the channel
definitions and attributes.

Although you set up explicit channel definitions, the channel negotiations carried
out when a channel starts up may override one or other of the values defined. This
is quite normal, and transparent, and has been arranged like this so that otherwise
incompatible definitions can work together.

Auto-definition of channels
In MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, Windows NT, and
OS/390 (cluster-receiver and cluster-sender channels only), if there is no
appropriate channel definition, then for a receiver or server-connection channel
that has auto-definition enabled, a definition is created automatically. The
definition is created using:
1. The appropriate model channel definition, SYSTEM.AUTO.RECEIVER or
SYSTEM.AUTO.SVRCONN. The model channel definitions for auto-definition
are the same as the system defaults, SYSTEM.DEF.RECEIVER and
SYSTEM.DEF.SVRCONN, except for the description field, which is
“Auto-defined by” followed by 49 blanks. The systems administrator can
choose to change any part of the supplied model channel definitions.
2. Information from the partner system. The partner’s values are used for the
channel name and the sequence number wrap value.
3. A channel exit program, which you can use to alter the values created by the
auto-definition. See “Channel auto-definition exit program” on page 516.

The description is then checked to determine whether it has been altered by an

auto-definition exit or because the model definition has been changed. If the first
44 characters are still “Auto-defined by” followed by 29 blanks, the queue manager
name is added. If the final 20 characters are still all blanks the local time and date
are added.

60 MQSeries Intercommunication
 Channel control function
Once the definition has been created and stored the channel start proceeds as
though the definition had always existed. The batch size, transmission size, and
message size are negotiated with the partner.

Defining other objects

Before a message channel can be started, both ends must be defined (or enabled
for auto-definition) at their respective queue managers. The transmission queue it
is to serve must be defined to the queue manager at the sending end, and the
communication link must be defined and available. In addition, it may be
necessary for you to prepare other MQSeries objects, such as remote queue
definitions, queue manager alias definitions, and reply-to queue alias definitions,
so as to implement the scenarios described in “Chapter 2. Making your
applications communicate” on page 17.

For information about MQI channels, see the MQSeries Clients book.

Starting a channel (not MQSeries for Windows)

A channel can be caused to start transmitting messages in one of four ways. It can
be:
v Started by an operator (not receiver or server-connection channels).
v Triggered from the transmission queue (sender, and possibly server channels
only). You will need to prepare the necessary objects for triggering channels.
v Started from an application program (not receiver or server-connection
channels).
v Started remotely from the network by a sender, requester, server, or
client-connection channel. Receiver, and possibly server and requester channel
transmissions, are started this way; so are server-connection channels. The
channels themselves must already be started (that is, enabled).

Note: Because a channel is ‘started’ it is not necessarily transmitting messages, but,

rather, it is ‘enabled’ to start transmitting when one of the four events
described above occurs. The enabling and disabling of a channel is achieved
using the START and STOP operator commands.

Starting a channel on MQSeries for Windows

On MQSeries for Windows you start channels in the following ways:
v Using the start connection function of the MQSeries for Windows properties
dialog. This function starts the components defined for the connection. The
components are a queue manager, and optionally, a channel group. The channel
group can contain the listener and up to eight channels. See the MQSeries for
Windows User’s Guide.
v Using the START CHANNEL MQSC command or, in Version 2.1, the START
CHANNEL PCF command. This command starts just the specified channel. The
queue manager must already be running.

Chapter 5. DQM implementation 61

Channel control function
Channel states
Figure 29 shows the hierarchy of all possible channel states, and Figure 30 on
page 63 shows the links between them. These apply to all types of message
channel. On MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, OS/390, Sun Solaris,
and Windows NT, these states apply also to server-connection channels.

Channel

Inactive Current

Stopped Starting Retrying Active

Initializing Binding Requesting Running Paused Stopping

Figure 29. Channel states

Current and active

The channel is “current” if it is in any state other than inactive. A current channel
is “active” unless it is in RETRYING, STOPPED, or STARTING state.

62 MQSeries Intercommunication
 Channel control function

INACTIVE
Start
channel

START command
or
TRIGGER
or
REMOTE INITIATION
STOPPED or
Disabled CHANNEL INITIATOR

INITIALIZING STARTING

RETRYING
Waiting until time
for next attempt One attempt to
establish session fails

BINDING
Establishing session and
initial data exchange

PAUSED Status
Waiting for OK REQUESTING
message-retry
interval

RUNNING
Transferring or ready
to transfer

Error or STOP request or

Retryable error, one disconnect interval expires
attempt failed, retry
count not exhausted

STOPPING
Check limits if
retrying
STOP command, Disconnect interval expires
non-retryable error
or retry limit reached

Figure 30. Flows between channel states

Notes:
| 1. When a channel is in one of the six states highlighted in Figure 30
| (INITIALIZING, BINDING, REQUESTING, RUNNING, PAUSED, or
| STOPPING), it is consuming resource and a process or thread is running; the

Chapter 5. DQM implementation 63

 Channel control function
| channel is active. (INITIALIZING occurs only on V5.1 of MQSeries for AIX,
| AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT. PAUSED does not
| occur on OS/390.)
2. When a channel is in STOPPED state, the session may be active because the
next state is not yet known.

| Specifying the maximum number of current channels: You can specify the
| maximum number of channels that can be current at one time. This is the number
| of channels that have entries in the channel status table, including channels that
| are retrying and channels that are disabled (that is, stopped). Specify this in the
| channel initiator parameter module for OS/390, the queue manager initialization
| file for OS/400, the queue manager configuration file for OS/2, Tandem NSK, and
| UNIX systems, or the registry for Windows NT. For more information about the
| values you set using the initialization or the configuration file see “Appendix D.
| Configuration file stanzas for distributed queuing” on page 637. For more
| information about specifying the maximum number of channels, see the MQSeries
| System Administration book for V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun
| Solaris, and Windows NT, the MQSeries for AS/400 V5.1 System Administration book
| for MQSeries for AS/400, or the MQSeries System Management Guide for your
| platform.
| Notes:
| 1. On MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, OS/390, Sun Solaris, and
| Windows NT, server-connection channels are included in this number.
| 2. A channel must be current before it can become active. If a channel is started,
| but cannot become current, the start fails.
| 3. If you are using CICS for distributed queuing on OS/390, you cannot specify
| the maximum number of channels.
| 4. MQSeries for Windows does not support the qm.ini file. The maximum number
| of current channels and the maximum number of active channels is eight.

| Specifying the maximum number of active channels: You can also specify the
maximum number of active channels (except on MQSeries for OS/390 using CICS
and MQSeries for Windows). You can do this to prevent your system being
overloaded by a large number of starting channels. If you use this method, you
should set the disconnect interval attribute to a low value to allow waiting
channels to start as soon as other channels terminate.

Each time a channel that is retrying attempts to establish connection with its
partner, it must become an active channel. If the attempt fails, it remains a current
channel that is not active, until it is time for the next attempt. The number of times
that a channel will retry, and how often, is determined by the retry count and retry
interval channel attributes. There are short and long values for both these
attributes. See “Chapter 6. Channel attributes” on page 77 for more information.

When a channel has to become an active channel (because a START command has
been issued, or because it has been triggered, or because it is time for another retry
attempt), but is unable to do so because the number of active channels is already
at the maximum value, the channel waits until one of the active slots is freed by
another channel instance ceasing to be active. If, however, a channel is starting
because it is being initiated remotely, and there are no active slots available for it at
that time, the remote initiation is rejected.

Whenever a channel, other than a requester channel, is attempting to become

active, it goes into the STARTING state. This is true even if there is an active slot

64 MQSeries Intercommunication
 Channel control function
immediately available, although in this case it will only be in STARTING state for
a very short time. However, if the channel has to wait for an active slot, it is in
STARTING state while it is waiting.

Requester channels do not go into STARTING state. If a requester channel cannot

start because the number of active channels is already at the limit, the channel
abends.

Whenever a channel, other than a requester channel, is unable to get an active slot,
and so waits for one, a message is written to the log or the OS/390 console, and an
event is generated. When a slot is subsequently freed and the channel is able to
acquire it, another message and event are generated. Neither of these events and
messages are generated if the channel is able to acquire a slot straightaway.

If a STOP CHANNEL command is issued while the channel is waiting to become

active, the channel goes to STOPPED state. A Channel-Stopped event is raised as
usual.

On MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, OS/390, Sun Solaris, and
Windows NT, server-connection channels are included in the maximum number of
active channels.

| For more information about specifying the maximum number of active channels,
| see the MQSeries System Administration book for V5.1 of MQSeries for AIX, HP-UX,
| OS/2 Warp, Sun Solaris, and Windows NT, the MQSeries for AS/400 V5.1 System
| Administration book for MQSeries for AS/400, the MQSeries for Windows User’s
| Guide, or the MQSeries System Management Guide for your platform.

Channel errors
Errors on channels cause the channel to stop further transmissions. If the channel
is a sender or server, it goes to RETRY state because it is possible that the problem
may clear itself. If it cannot go to RETRY state, the channel goes to STOPPED state.
For sending channels, the associated transmission queue is set to GET(DISABLED)
and triggering is turned off. (A STOP command takes the side that issued it to
STOPPED state; only expiry of the disconnect interval will make it end normally
and become inactive.) Channels that are in STOPPED state need operator
| intervention before they will restart (see “Restarting stopped channels” on page 69).

| Note: For Digital OpenVMS, OS/2 Warp, OS/400, UNIX systems, Tandem NSK,
| and Windows NT, in order for retry to be attempted a channel initiator must
| be running. On platforms other than V5.1 of MQSeries for AIX, AS/400,
| HP-UX, OS/2 Warp, Sun Solaris, and Windows NT, the channel initiator
| must be monitoring the initiation queue specified in the transmission queue
| that the channel is using. MQSeries for Windows does not have a channel
| initiator; restarts are controlled by the MQSeries properties daemon task
| running in the background.

| “Long retry count (LONGRTY)” on page 85 describes how retrying works. If the
error clears, the channel restarts automatically, and the transmission queue is
reenabled. If the retry limit is reached without the error clearing, the channel goes
to STOPPED state. A stopped channel must be restarted manually by the operator.
If the error is still present, it does not retry again. When it does start successfully,
the transmission queue is reenabled.

On MQSeries for AIX, HP-UX, OS/2 Warp, OS/390 without CICS, Sun Solaris, and
Windows NT, if the channel initiator or queue manager stops while a channel is in

Chapter 5. DQM implementation 65

Channel control function
RETRYING or STOPPED status, the channel status is remembered when the
channel initiator or queue manager is restarted.

On MQSeries for OS/2 Warp, Windows NT, OS/400, Tandem NSK, and UNIX
systems, if a channel is unable to put a message to the target queue because that
queue is full or put inhibited, the channel can retry the operation a number of
times (specified in the message-retry count attribute) at a given time interval
(specified in the message-retry interval attribute). Alternatively, you can write your
own message-retry exit that determines which circumstances cause a retry, and the
number of attempts made. The channel goes to PAUSED state while waiting for
the message-retry interval to finish.

See “Chapter 6. Channel attributes” on page 77 for information about the channel
attributes, and “Chapter 36. Channel-exit programs” on page 505 for information
about the message-retry exit.

Checking that the other end of the channel is still available

In MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, OS/390 without CICS, Sun
Solaris, and Windows NT, you can use the heartbeat-interval channel attribute to
specify that flows are to be passed from the sending MCA when there are no
messages on the transmission queue. This is described in “Heartbeat interval
(HBINT)” on page 85.

In MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, OS/390 without CICS, Sun
Solaris, VSE/ESA, and Windows NT, if you are using TCP as your transport
protocol, you can use the SO_KEEPALIVE option on the TCP/IP socket. If you
specify this option, TCP periodically checks that the other end of the connection is
still available, and if it is not, the channel is terminated.

In MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT,
if you are using TCP as your transport protocol, the receiving end of inactive
connections can also be closed if no data is received for a period of time. This
period of time is determined according to the HBINT (heartbeat interval) value.

The timeout value is set as follows:

1. For an initial number of flows, before any negotiation has taken place, the
timeout is twice the HBINT value from the channel definition.
2. When the channels have negotiated a HBINT value, the timeout is set to twice
this value.
Notes:
1. If either of the above values is zero, then there is no timeout.
2. For connections that do not support heartbeats, the HBINT value is negotiated
to zero in step 2 and hence there is no timeout, so we must use TCP/IP
KEEPALIVE.
3. For client connections, heartbeats are only flowed from the server when the
client issues an MQGET call with wait; none are flowed during other MQI calls.
Therefore, you are not recommended to set the heartbeat interval too small for
client channels. For example, if the heartbeat is set to ten seconds, an MQCMIT
call will fail (with MQRC_CONNECTION_BROKEN) if it takes longer than
twenty seconds to commit because no data will have been flowed during this
time. This can happen with large units of work. However, it should not happen
if appropriate values are chosen for the heartbeat interval because only MQGET
with wait should take significant periods of time.

66 MQSeries Intercommunication
 Channel control function
4. Aborting the connection after twice the heartbeat interval is valid because we
expect flows (data or heartbeat) at least every heartbeat interval. If the
heartbeat interval is set too small, however, problems can occur, especially if
channel exits are in use. For example, if the HBINT value is one second, and a
send or receive exit is used, the receiving end will only wait for two seconds
before aborting the channel. This may not be long enough if the sending MCA
spends a long time in the send exit, perhaps encrypting the message.
If you have unreliable channels that are suffering from TCP errors, use of
SO_KEEPALIVE will mean that your channels are more likely to recover.

You can specify time intervals to control the behavior of the SO_KEEPALIVE
option. When you change the time interval, only TCP/IP channels started after the
change are affected. The value that you choose for the time interval should be less
than the value of the disconnect interval for the channel.

For more information about using the SO_KEEPALIVE option on OS/390, see the
MQSeries for OS/390 System Management Guide. For other platforms, see the chapter
about setting up communications for your platform in this manual.

Stopping and quiescing channels (not MQSeries for Windows)

Message channels are designed to be long-running connections between queue
managers with orderly termination controlled only by the disconnect interval
channel attribute. This mechanism works well unless the operator needs to
terminate the channel before the disconnect time interval expires. This can occur in
the following situations:
v System quiesce
v Resource conservation
v Unilateral action at one end of a channel

In this case, an operator command is provided to allow you to stop the channel.
The command provided varies by platform, as follows:
For OS/390 without CICS:
The STOP CHANNEL MQSC command or the Stop a channel panel
For OS/390 using CICS:
The Stop option on the Message Channel List panel
For OS/2, Windows NT, Digital OpenVMS, Tandem NSK, and UNIX systems:
The STOP CHANNEL MQSC or PCF command
| For OS/400:
| ENDMQMCHL or the END option on the WRKMQMCHL panel
For VSE/ESA:
The CLOSE command from the MQMMSC panel or MQCL transaction
closes (rather than stops) the channel.

For all of these commands there is a FORCE and a QUIESCE option. The FORCE
option attempts to stop the channel immediately and may require the channel to
resynchronize when it restarts because the channel may be left in doubt. The
QUIESCE option attempts to end the current batch of messages and then terminate
the channel. Note that both of these options leave the channel in a STOPPED state,
requiring operator intervention to restart it.

Stopping the channel at the sending end is quite effective but does require operator
intervention to restart. At the receiving end of the channel, things are much more

Chapter 5. DQM implementation 67

Channel control function
difficult because the MCA is waiting for data from the sending side, and there is
no way to initiate an orderly termination of the channel from the receiving side; the
stop command is pending until the MCA returns from its wait for data.

Consequently there are three recommended ways of using channels, depending

upon the operational characteristics required:
v If you want your channels to be long running, you should note that there can be
orderly termination only from the sending end. When channels are interrupted,
that is, stopped, operator intervention (a START CHANNEL command) is
required in order to restart them.
v If you want your channels to be active only when there are messages for them
to transmit, you should set the disconnect interval to a fairly low value. Note
that the default setting is quite high and so is not recommended for channels
where this level of control is required. Because it is difficult to interrupt the
receiving channel, the most economical option is to have the channel
automatically disconnect and reconnect as the workload demands. For most
channels, the appropriate setting of the disconnect interval can be established
heuristically.
v For MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, OS/390 without CICS, Sun
Solaris, and Windows NT, you can use the heartbeat-interval attribute to cause
the sending MCA to send a heartbeat flow to the receiving MCA during periods
in which it has no messages to send. This releases the receiving MCA from its
wait state and gives it an opportunity to quiesce the channel without waiting for
the disconnect interval to expire. Give the heartbeat interval a lower value than
the value of the disconnect interval.
Notes:
1. It is particularly advisable to set the disconnect interval to a low value, or to
use heartbeats, for server channels. This is to allow for the case where the
requester channel ends abnormally (for example, because the channel was
canceled) when there are no messages for the server channel to send. In this
case, the server does not detect that the requester has ended (it will only do
this the next time it tries to send a message to the requester). While the
server is still running, it holds the transmission queue open for exclusive
input in order to get any more messages that may arrive on the queue. If an
attempt is made to restart the channel from the requester, the start request
receives an error because the server still has the transmission queue open for
exclusive input. It is necessary to stop the server channel, and then restart
the channel from the requester again.
2. On OS/390, without CICS, and on V5.1 of MQSeries for AIX, AS/400,
HP-UX, OS/2 Warp, Sun Solaris, and Windows NT, server-connection
channels can also be stopped like receiver channels.

Stopping and quiescing channels (MQSeries for Windows)

On MQSeries for Windows you can stop or quiesce channels in the following
ways:
v Using the stop connection function of the MQSeries for Windows properties
dialog. This function stops the queue manager and any channels. Channels are
forced to stop if necessary and may go into in-doubt status if a batch of
messages is currently in transit. Any fast, nonpersistent messages that are in
transit are lost.

68 MQSeries Intercommunication
 Channel control function
v Using the STOP CHANNEL MQSC command or, in Version 2.1, the STOP
CHANNEL PCF command. You can specify a FORCE or QUIESCE option on
this command. Using this command stops just the specified channel and leaves
the queue manager running.

Restarting stopped channels

When a channel goes into STOPPED state (either because you have stopped the
channel manually using one of the methods given in “Stopping and quiescing
channels (not MQSeries for Windows)” on page 67, or because of a channel error)
you have to restart the channel manually.

To do this, issue one of the following commands:

For MQSeries for OS/390 without CICS:
The START CHANNEL MQSC command or the Start a channel panel
For MQSeries for OS/390 using CICS:
The Start option on the Message Channel List panel
For MQSeries for OS/2 Warp, Windows NT, Digital OpenVMS, Tandem NSK,
and UNIX systems:
The START CHANNEL MQSC or PCF command
For MQSeries for AS/400:
The START command on the WRKMQMCHL panel, the STRMQMCHL
command, or the START CHANNEL MQSC or PCF command
For MQSeries for Windows:
The START CHANNEL MQSC command, in Version 2.1 the START
CHANNEL PCF command, or the start connection function of the
MQSeries properties dialog.
For MQSeries for VSE/ESA:
The OPEN command from the MQMMSC panel or MQCL transaction
opens (rather than restarts) the channel.

For sender or server channels, when the channel entered the STOPPED state, the
associated transmission queue was set to GET(DISABLED) and triggering was set
off. When the start request is received, these attributes are reset automatically. On
V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT, and
MQSeries for OS/390 without CICS, if the channel initiator or queue manager
stops while a channel is in RETRYING or STOPPED status, the channel status is
remembered when the channel initiator or queue manager is restarted. On other
platforms (apart from MQSeries for Windows), if the channel initiator or queue
manager is restarted the status is lost and you have to alter the queue attributes
manually to reenable triggering of the channel.

Note: If you are using CICS for distributed queuing on OS/390, these queue
attributes are not reset automatically; you always have to alter them
manually when you restart a channel.

In-doubt channels
Observe the distinction between a channel being in doubt, which means that it is
in doubt with its partner channel about which messages have been sent and
received, and the queue manager being in doubt about which messages should be
committed to a queue.

Chapter 5. DQM implementation 69

 Channel control function
Normally, all resolution of in-doubt situations on channels is handled
automatically. Even if communication is lost, leaving the channel in doubt with a
batch of messages at the sender whose receipt status is unknown, the situation will
be resolved when communications are reestablished. Sequence number and
LUWID records are kept for this purpose. (In fact, channels are only in doubt for
the short period at the end of a batch while LUWID information is exchanged, and
no more than one batch of messages can be in doubt for each channel.)

In exceptional circumstances it is possible to manually resynchronize the channel.

(In this case, the term manual may refer to operators or to programs that contain
MQSeries system management commands.) The manual resynchronization process
works as follows. MQSC commands are used in this description; you can use the
PCF equivalents instead.
1. On platforms other than MQSeries for Windows, use the DISPLAY CHSTATUS
command to find the last-committed logical unit of work ID (LUWID) for each
side of the channel. Do this using the following commands:
v For the in-doubt side of the channel:
DISPLAY CHSTATUS(name) SAVED CURLUWID

You can use the CONNAME and XMITQ parameters to further identify the
channel.
v For the receiving side of the channel:
DISPLAY CHSTATUS(name) SAVED LSTLUWID

You can use the CONNAME parameter to further identify the channel.

The commands are different because only one side (the sending side) of the
channel can be in doubt. The receiving side is never in doubt.

| On MQSeries for AS/400, the DISPLAY CHSTATUS command can be executed

| from a file using the STRMQMMQSC command. Alternatively, the Work with
| MQM Channel Status CL command, WRKMQMCHST, provides similar
| function.

On MQSeries for Windows, the DISPLAY CHSTATUS command is not

supported. Instead, use the Status button on the Components tab of the
MQSeries for Windows properties dialog.
2. If you find that the two LUWIDs are the same, the receiving side has
committed the unit of work that the sender considers to be in doubt. Therefore,
the sending side can remove the in-doubt messages from the transmission
queue and reenable it. This is done with the following channel RESOLVE
command:
RESOLVE CHANNEL(name) ACTION(COMMIT)
3. If you find that the two LUWIDs are different, the receiving side has not
committed the unit of work that the sender considers to be in doubt. On some
platforms you can find out how many messages are in doubt by displaying the
saved channel status. The sending side needs to retain the in-doubt messages
on the transmission queue and resend them. This is done with the following
channel RESOLVE command:
RESOLVE CHANNEL(name) ACTION(BACKOUT)

| On MQSeries for AS/400, the Resolve MQM Channel command,

| RSVMQMCHL, provides a similar function.

70 MQSeries Intercommunication
 Channel control function
Once this process is complete the channel will no longer be in doubt. This means
that, if required, the transmission queue can be used by another channel.

Problem determination
There are two distinct aspects to problem determination:
v Problems discovered when a command is being submitted
v Problems discovered during operation of the channels

Command validation
Commands and panel data must be free from errors before they are accepted for
processing. Any errors found by the validation are immediately notified to the user
by error messages.

Problem diagnosis begins with the interpretation of these error messages and
taking the recommended corrective action.

Processing problems
Problems found during normal operation of the channels are notified to the system
console or the system log or, for MQSeries for Windows, the channel log. Problem
diagnosis begins with the collection of all relevant information from the log, and
continues with analysis to identify the problem.

Confirmation and error messages are returned to the terminal that initiated the
commands, when possible.

Messages and codes

Where provided, the Messages and Codes manual of the particular platform can help
with the primary diagnosis of the problem.

What happens when a message cannot be delivered?

Figure 31 on page 72 shows the processing that occurs when an MCA is unable to
put a message to the destination queue. (Note that the options shown do not apply
on all platforms.)

Chapter 5. DQM implementation 71

Undelivered messages

MQPUT

QM1 Channels QM2

Me s s a g e F l o w Transient Failure
MCA MCA
Retry Exit
Transmission
Queue

RTS Application
Queue

2 3

Transmission
Queue Dead Letter
Queue

DLQ Handler

Figure 31. What happens when a message cannot be delivered

As shown in the figure, the MCA can do several things with a message that it
cannot deliver. The action taken is determined by options specified when the
channel is defined and on the MQPUT options for the message.
1. Message-retry
If the MCA is unable to put a message to the target queue for a reason that
could be transitory (for example, because the queue is full), the MCA has
the option to wait and retry the operation later. You can determine if the
MCA waits, for how long, and how many times it retries.
v You can specify a message-retry time and interval for MQPUT errors
when you define your channel. If the message cannot be put to the
destination queue because the queue is full, or is inhibited for puts, the
MCA retries the operation the number of times specified, at the time
interval specified.
v You can write your own message-retry exit. The exit enables you to
specify under what conditions you want the MCA to retry the MQPUT
or MQOPEN operation. Specify the name of the exit when you define
the channel.

Message-retry is not available on MQSeries for OS/390, MQSeries for

Windows, or MQSeries for VSE/ESA.
2. Return-to-sender
If message-retry was unsuccessful, or a different type of error was
encountered, the MCA can send the message back to the originator.
To enable this, you need to specify the following options in the message
descriptor when you put the message to the original queue:
v The MQRO_EXCEPTION_WITH_FULL_DATA report option

72 MQSeries Intercommunication
 Undelivered messages
v The MQRO_DISCARD_MSG report option
v The name of the reply-to queue and reply-to queue manager

If the MCA is unable to put the message to the destination queue, it

generates an exception report containing the original message, and puts it
on a transmission queue to be sent to the reply-to queue specified in the
original message. (If the reply-to queue is on the same queue manager as
the MCA, the message is put directly to that queue, not to a transmission
queue.)

| Return-to-sender is not available on OS/390 or VSE/ESA.

| 3. Dead-letter queue
| If a message cannot be delivered or returned, it is put on to the dead-letter
| queue. You can use the DLQ handler to process the message. This is
| described in theMQSeries System Administration book for V5.1 of MQSeries
| for AIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT, the MQSeries
| for AS/400 V5.1 System Administration book for MQSeries for OS/400, or in
| the MQSeries System Management Guide for your platform. (The DLQ
| handler is not supported on OS/390.)
If the dead-letter queue is not available, the sending MCA leaves the
message on the transmission queue, and the channel stops. On a fast
channel, nonpersistent messages that cannot be written to a dead-letter
queue are lost.
Dead-letter queues are not supported on MQSeries for Windows.

Initialization and configuration files

The handling of channel initialization data depends on your MQSeries platform.

OS/390 without CICS

In MQSeries for OS/390 without CICS, initialization and configuration information
is in the channel initiator parameter module CSQXPARM. You can also put
commands in the CSQINPX initialization input data set, which is processed every
time you start the channel initiator if you specify the optional DD statement
CSQINPX in the channel initiator started task procedure. See the MQSeries for
OS/390 System Management Guide for information about both of these.

OS/390 using CICS

In MQSeries for OS/390 using CICS there is no channel initiator.

Windows NT
On MQSeries for Windows NT, the registry file holds basic configuration
information about the MQSeries installation. That is, information relevant to all of
the queue managers on the MQSeries system and also information relating to
individual queue managers.

OS/2, Digital OpenVMS, Tandem NSK, OS/400 and UNIX

systems
On MQSeries for OS/2 Warp, MQSeries for Compaq (DIGITAL) OpenVMS,
MQSeries for Tandem NonStop Kernel, OS/400 and MQSeries on UNIX systems,
there are configuration files to hold basic configuration information about the
MQSeries installation.

Chapter 5. DQM implementation 73

 Initialization and configuration files
There are two configuration files: one applies to the machine, the other applies to
an individual queue manager.

MQSeries configuration file

| This holds information relevant to all of the queue managers on the MQSeries
| system. The file is called MQSINI on Tandem NSK and mqs.ini on other platforms.
| It is fully described in the MQSeries System Administration book for MQSeries for
| AIX, MQSeries for HP-UX, MQSeries for OS/2 Warp, and MQSeries for Sun
| Solaris, in the MQSeries for AS/400 V5.1 System Administration book for MQSeries
| for AS/400, or in the MQSeries System Management Guide for your platform.

Queue manager configuration file

The queue manager configuration file holds configuration information relating to
one particular queue manager. The file is called QMINI on Tandem NSK, and
qm.ini on other platforms.

It is created during queue manager creation and may hold configuration

information relevant to any aspect of the queue manager. Information held in the
file includes details of how the configuration of the log differs from the default in
MQSeries configuration file.

The queue manager configuration file is held in the root of the directory tree
occupied by the queue manager. On MQSeries for Windows NT, the qm.ini file is
held in the registry. For example, for the DefaultPath attributes, the queue manager
configuration files for a queue manager called QMNAME would be:

For OS/2:
c:\mqm\qmgrs\QMNAME\qm.ini

For UNIX systems:

/var/mqm/qmgrs/QMNAME/qm.ini

For Digital OpenVMS:

mqs_root:[mqm.qmgrs.QMNAME]qm.ini

For Tandem NSK:

The file is held in the subvolume of the queue manager. For example, the path and
name for a configuration file for a queue manager called QMNAME could be
$VOLUME.QMNAMED.QMINI.

An excerpt of a qm.ini file follows. It specifies that the TCP/IP listener is to listen
on port 2500, the maximum number of current channels is to be 200 and the
maximum number of active channels is to be 100.
TCP:
Port=2500
CHANNELS:
MaxChannels=200
MaxActiveChannels=100

| Note: For Tandem NSK, the format of the qm.ini file is slightly different. For more
| details about this, see the MQSeries for Tandem NonStop Kernel System
| Management Guide.

| For OS/400:
| /QIBM/UserData/mqm/qmgrs/QMNAME/qm.ini

74 MQSeries Intercommunication
 Initialization and configuration files
| For more information about qm.ini files see “Appendix D. Configuration file
stanzas for distributed queuing” on page 637. For more information about QMINI
files see the MQSeries for Tandem NonStop Kernel System Management Guide.

VSE/ESA
There is no qm.ini file on VSE/ESA. Instead, use the Configuration main menu on
the MQMMCFG panel to configure the queue manager.

Data conversion
An MQSeries message consists of two parts:
v Control information in a message descriptor
v Application data

Either of the two parts may require data conversion when sent between queues on
different queue managers. For information about data conversion, see the MQSeries
Application Programming Guide.

Writing your own message channel agents

MQSeries products other than MQSeries for Windows allow you to write your
own message channel agent (MCA) programs or to install one from an
independent software vendor. You might want to do this to make an MQSeries
product interoperate over your own, proprietary communications protocol or to
send messages over a protocol that MQSeries does not support. (You cannot write
your own MCA to interoperate with an MQSeries-supplied MCA at the other end.)

If you decide to use an MCA that was not supplied by MQSeries, you need to
consider the following.
Message sending and receiving
You need to write a sending application that gets messages from wherever
your application puts them, for example from a transmission queue (see
the MQSeries Application Programming Reference book), and sends them out
on a protocol with which you want to communicate. You also need to
write a receiving application that takes messages from this protocol and
puts them onto destination queues. The sending and receiving applications
use the message queue interface (MQI) calls, not any special interfaces.
You need to ensure that messages are delivered once and once only.
Syncpoint coordination can be used to help with this.
Channel control function
You need to provide your own administration functions to control
channels. You cannot use MQSeries channel administration functions either
for configuring (for example, the DEFINE CHANNEL command) or
monitoring (for example, DISPLAY CHSTATUS) your channels.
Initialization file
You need to provide your own initialization file, if you require one.
Application data conversion
You will probably want to allow for data conversion for messages you
send to a different system. If so, use the MQGMO_CONVERT option on
the MQGET call when retrieving messages from wherever your application
puts them, for example the transmission queue.

Chapter 5. DQM implementation 75

Writing message channel agents
User exits
Consider whether you need user exits. If so, you can use the same
interface definitions that MQSeries uses.
Triggering
If your application puts messages to a transmission queue, you can set up
the transmission queue attributes so that your sending MCA is triggered
when messages arrive on the queue.
Channel initiator
You may need to provide your own channel initiator.

76 MQSeries Intercommunication
Chapter 6. Channel attributes
The previous chapters have introduced the basic concepts of the product, the
business perspective basis of its design, its implementation, and the control
features.

This chapter describes the channel attributes held in the channel definitions. This is
product-sensitive programming interface information.

You choose the attributes of a channel to be optimal for a given set of

circumstances for each channel. However, when the channel is running, the actual
values may have changed during startup negotiations. See “Preparing channels” on
page 60.

Many attributes have default values, and you can use these for most channels.
However, in those circumstances where the defaults are not optimal, refer to this
chapter for guidance in selecting the correct values.

Note: In MQSeries for AS/400, most parameters can be specified as *SYSDFTCHL,

which means that the value is taken from the system default channel in
your system.

Channel attributes in alphabetical order

MQSeries for some platforms may not implement all the attributes shown in the
list. Exceptions and platform differences are mentioned in the individual attribute
descriptions, where relevant.

The keyword that you can specify in MQSC is shown in brackets for each attribute.
(Attributes that apply only to MQSeries for OS/390 with CICS do not have MQSC
keywords.)

The attributes are arranged in alphabetical order, as follows:

Attribute See page...

Auto start (AUTOSTART) 78

Alter date (ALTDATE) 78
Alter time (ALTTIME) 78
Batch interval (BATCHINT) 79
Batch size (BATCHSZ) 79
Channel name (CHANNEL) 80
Channel type (CHLTYPE) 81
CICS profile name 81
Cluster (CLUSTER) 81
Cluster namelist (CLUSNL) 82
Connection name (CONNAME) 82
Convert message (CONVERT) 83
Description (DESCR) 84
Disconnect interval (DISCINT) 84
Heartbeat interval (HBINT) 85
Long retry count (LONGRTY) 85
Long retry interval (LONGTMR) 85

© Copyright IBM Corp. 1993, 2000 77

 Channel attributes
Attribute See page...

LU 6.2 mode name (MODENAME) 86

LU 6.2 transaction program name (TPNAME) 86
Maximum message length (MAXMSGL) 87
Maximum transmission size 87
Message channel agent name (MCANAME) 87
Message channel agent type (MCATYPE) 88
Message channel agent user identifier (MCAUSER) 88
Message exit name (MSGEXIT) 88
Message exit user data (MSGDATA) 89
Message-retry exit name (MREXIT) 89
Message-retry exit user data (MRDATA) 89
Message retry count (MRRTY) 89
Message retry interval (MRTMR) 89
Nonpersistent message speed (NPMSPEED) 90
Network-connection priority (NETPRTY) 90
Password (PASSWORD) 90
PUT authority (PUTAUT) 90
Queue manager name (QMNAME) 91
Receive exit name (RCVEXIT) 91
Receive exit user data (RCVDATA) 92
Security exit name (SCYEXIT) 92
Security exit user data (SCYDATA) 93
Send exit name (SENDEXIT) 93
Send exit user data (SENDDATA) 93
Sequence number wrap (SEQWRAP) 93
Sequential delivery 93
Short retry count (SHORTRTY) 93
Short retry interval (SHORTTMR) 94
Target system identifier 94
Transmission queue name (XMITQ) 94
Transport type (TRPTYPE) 95
User ID (USERID) 95

Alter date (ALTDATE)

This is the date on which the definition was last altered, in the form yyyy-mm-dd.

| This parameter is supported on AIX, HP-UX, OS/2 Warp, OS/390, OS/400, Sun
| Solaris, and Windows NT only.

Alter time (ALTTIME)

This is the time at which the definition was last altered, in the form hh:mm:ss.

| This parameter is supported on AIX, HP-UX, OS/2 Warp, OS/390, OS/400, Sun
| Solaris, and Windows NT only.

Auto start (AUTOSTART)

In MQSeries for Tandem NonStop Kernel there is no SNA listener process. Each
channel initiated from a remote system must have its own, unique TP name on
which it can listen. Such channels must be defined to MQSC with the attribute
AUTOSTART(ENABLED) to ensure that there is an LU 6.2 responder process
listening on this TP name whenever the queue manager is started.

78 MQSeries Intercommunication
 Auto start (AUTOSTART)
SNA channels defined AUTOSTART(DISABLED) do not listen for incoming SNA
requests. LU 6.2 responder processes are not started for such channels.

Batch interval (BATCHINT)

| In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT, and MQSeries for OS/390 without CICS, you can specify a period of
| time, in milliseconds, during which the channel will keep a batch open even if
| there are no messages on the transmission queue. You can specify any number of
| milliseconds, from zero through 999 999 999. The default value is zero.

If you do not specify a batch interval, the batch closes when the number of
messages specified in BATCHSZ has been sent or when the transmission queue
becomes empty. On lightly loaded channels, where the transmission queue
frequently becomes empty the effective batch size may be much smaller than
BATCHSZ.

You can use the BATCHINT attribute to make your channels more efficient by
reducing the number of short batches. Be aware, however, that you may slow
down the response time, because batches will last longer and messages will remain
uncommitted for longer.

If you specify a BATCHINT, batches close only when one of the following
conditions is met:
v The number of messages specified in BATCHSZ have been sent.
v There are no more messages on the transmission queue and a time interval of
BATCHINT has elapsed while waiting for messages (since the first message of
the batch was retrieved).

Note: BATCHINT specifies the total amount of time that is spent waiting for
messages. It does not include the time spent retrieving messages that are
already available on the transmission queue, or the time spent transferring
messages.

This attribute applies only to sender, cluster-sender, server, and cluster-receiver

channels.

Batch size (BATCHSZ)

The batch size is the maximum number of messages to be sent before a syncpoint
is taken. The batch size does not affect the way the channel transfers messages;
messages are always transferred individually, but are committed or backed out as a
batch.

To improve performance, you can set a batch size to define the maximum number
of messages to be transferred between two syncpoints. The batch size to be used is
negotiated when a channel starts up, and the lower of the two channel definitions
is taken. On some implementations, the batch size is calculated from the lowest of
the two channel definitions and the two queue manager
MAXUMSGS/MAXSMSGS values. The actual size of a batch can be less than this;
for example, a batch completes when there are no messages left on the
transmission queue or the batch interval expires.

| A large value for the batch size increases throughput, but recovery times are
| increased because there are more messages to back out and resend. The default

Chapter 6. Channel attributes 79

 Batch size (BATCHSZ)
| BATCHSZ is 50, and you are advised to try that value first. You might choose a
| lower value for BATCHSZ if your communications are unreliable, making the need
| to recover more likely.

Syncpoint procedure needs a unique logical unit of work identifier to be

exchanged across the link every time a syncpoint is taken, to coordinate batch
commit procedures.

If the synchronized batch commit procedure is interrupted, an in-doubt situation

may arise. In-doubt situations are resolved automatically when a message channel
starts up. If this resolution is not successful, manual intervention may be necessary,
making use of the RESOLVE command.

Some considerations when choosing the number for batch size:

v If the number is too large, the amount of queue space taken up on both ends of
the link becomes excessive. Messages take up queue space when they are not
committed, and cannot be removed from queues until they are committed.
v If there is likely to be a steady flow of messages, you can improve the
performance of a channel by increasing the batch size. However, this has the
negative effect of increasing restart times, and very large batches may also affect
performance.
v If message flow characteristics indicate that messages arrive intermittently, a
batch size of 1 with a relatively large disconnect time interval may provide a
better performance.
| v The number may be in the range 1 through 9999. However, for data integrity
| reasons, channels connecting to any of the current platforms, as described in this
| book, should specify a batch size greater than 1. (A value of 1 is for use with
| Version 1 products, apart from MQSeries for MVS/ESA.)
| For OS/390 using CICS it must also be at least 3 less than the value set by the
| DEFINE MAXSMSGS command.
v Even though nonpersistent messages on a fast channel do not wait for a
syncpoint, they do contribute to the batch-size count.

Channel name (CHANNEL)

Specifies the name of the channel definition. The name can contain up to 20
characters, although as both ends of a message channel must have the same name,
and other implementations may have restrictions on the size, the actual number of
characters may have to be smaller.

Where possible, channel names should be unique to one channel between any two
queue managers in a network of interconnected queue managers.

The name must contain characters from the following list:

Alphabetic (A-Z, a-z; note that uppercase and lowercase are significant)
Numerics (0-9)
Period (.)
Forward slash (/)
Underscore (_)
Percentage sign (%)

80 MQSeries Intercommunication
 Channel name (CHANNEL)
Notes:
1. Embedded blanks are not allowed, and leading blanks are ignored.
2. On systems using EBCDIC Katakana, you cannot use lowercase characters.

Channel type (CHLTYPE)

Specifies the type of the channel being defined. The possible channel types are:
Message channel types:
v Sender
v Server (not MQSeries for VSE/ESA)
| v Cluster-sender (MQSeries for OS/390 without CICS, V5.1 of MQSeries
| for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT
| only)
v Receiver
v Requester (not MQSeries for VSE/ESA)
| v Cluster-receiver (MQSeries for OS/390 without CICS, V5.1 of MQSeries
| for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT
| only)
MQI channel types:
v Client-connection (MQSeries for OS/2 Warp, Windows NT, UNIX
systems, VSE/ESA, DOS, Windows 3.1, Windows 95, and Windows 98
only)

Note: Client-connection channels can also be defined on OS/390 for use

on other platforms.
v Server-connection (not MQSeries for OS/390 using CICS)

The two ends of a channel must have the same name and have compatible types:
v Sender with receiver
v Requester with server
v Requester with sender (for Call_back)
v Server with receiver (server is used as a sender)
v Client-connection with server-connection
v Cluster-sender with cluster-receiver

CICS profile name

This is for OS/390 using CICS only, to give extra definition for the session
characteristics of the connection when CICS performs a communication session
allocation, for example to select a particular COS.

The name must be known to CICS and be one to eight alphanumeric characters
long.

Cluster (CLUSTER)
The name of the cluster to which the channel belongs. The maximum length is 48
characters conforming to the rules for naming MQSeries objects.

This parameter is valid only for cluster-sender and cluster-receiver channels. Up to

one of the resultant values of CLUSTER or CLUSNL can be nonblank. If one of the
values is nonblank, the other must be blank.

| This parameter is supported on AIX, HP-UX, OS/2 Warp, OS/390 without CICS,
| OS/400, Sun Solaris, and Windows NT only.

Chapter 6. Channel attributes 81

 Cluster namelist (CLUSNL)
Cluster namelist (CLUSNL)
The name of the namelist that specifies a list of clusters to which the channel
belongs.

This parameter is valid only for cluster-sender and cluster-receiver channels. Up to

one of the resultant values of CLUSTER or CLUSNL can be nonblank. If one of the
values is nonblank, the other must be blank.

| This parameter is supported on AIX, HP-UX, OS/2 Warp, OS/390 without CICS,
| OS/400, Sun Solaris, and Windows NT only.

Connection name (CONNAME)

This is the communications connection identifier. It specifies the particular
communications link to be used by this channel.

This attribute is required for sender channels, requester channels, and

client-connection channels. It does not apply to receiver or server-connection
channel types.

It is optional for server channels, except on OS/390 using CICS where it is

required in the channel definition, but is ignored unless the server is initiating the
conversation.

For OS/390 using CICS this attribute names the CICS communication connection
identifier for the session to be used for this channel. The name is one to four
alphanumeric characters long.

Otherwise, the name is up to 48 characters for OS/390, 264 characters for other
platforms, and:
If the transport type is TCP
This is either the hostname or the network address of the remote machine.
For example, (MACH1.ABC.COM) or (19.22.11.162). It may include the port
number, for example (MACHINE(123)).
If the transport type is UDP
For MQSeries for AIX and MQSeries for Windows V2.0 only, UDP is an
alternative to TCP. As with TCP/IP, it is either the hostname or the
network address of the remote machine.
If the transport type is LU 6.2
| For Version 5.1 of MQSeries for OS/2, OS/400, Windows NT, and UNIX
| systems, give the fully-qualified name of the partner LU if the TPNAME
| and MODENAME are specified. For other versions or if the TPNAME and
| MODENAME are blank, give the CPI-C side information object name as
| described in the section in this book about setting up communication for
| your platform.
On OS/390 there are two forms in which to specify the value:
v Logical unit name
The logical unit information for the queue manager, comprising the
logical unit name, TP name, and optional mode name. This can be
specified in one of 3 forms:
luname, for example IGY12355
luname/TPname, for example IGY12345/APING
luname/TPname/modename, for example IGY12345/APINGD/#INTER

82 MQSeries Intercommunication
 Connection name (CONNAME)
For the first form, the TP name and mode name must be specified for
the TPNAME and MODENAME attributes; otherwise these attributes
must be blank.

Note: For client-connection channels, only the first form is allowed.

v Symbolic name
The symbolic destination name for the logical unit information for the
queue manager, as defined in the side information data set. The
TPNAME and MODENAME attributes must be blank.

Note: For cluster-receiver channels, the side information is on the other

queue managers in the cluster. Alternatively, in this case it can be
a name that a channel auto-definition exit can resolve into the
appropriate logical unit information for the local queue manager.

For Digital OpenVMS, specify the Gateway Node name, the Access Name
to the channel program, and the TPNAME used to invoke the remote
program. For example: CONNAME('SNAGWY.VMSREQUESTER(HOSTVR)').

For Tandem NonStop Kernel, the value depends on whether SNAX or ICE
is used; see “Chapter 20. Setting up communication in Tandem NSK” on
page 289.
If the transmission protocol is NetBIOS
This is the NetBIOS name defined on the remote machine.
If the transmission protocol is SPX
This is an SPX-style address consisting of a 4-byte network address, a
6-byte node address and a 2-byte socket number. Enter these in
hexadecimal, with the network and node addresses separated by a fullstop
and the socket number in brackets. For example:
CONNAME('0a0b0c0d.804abcde23a1(5e86)')

If the socket number is omitted, the default MQSeries SPX socket number
is used. The default is X'5E86'.

Note: The definition of transmission protocol is contained in “Transport type

(TRPTYPE)” on page 95.

Convert message (CONVERT)

Application message data is usually converted by the receiving application.
However, if the remote queue manager is on a platform that does not support data
conversion, use this channel attribute to specify that the message should be
converted into the format required by the receiving system before transmission.

This attribute applies only to sender, cluster-sender, server, and cluster-receiver

channels and does not apply to MQSeries for OS/390 with CICS or MQSeries for
Windows.

The possible values are ‘yes’ and ‘no’. If you specify ‘yes’, the application data in
the message is converted before sending if you have specified one of the
appropriate built-in format names (see the MQSeries Application Programming
Guide). If you specify ‘no’, the application data in the message is not converted
before sending.

Chapter 6. Channel attributes 83

 Description (DESCR)
Description (DESCR)
This contains up to 64 bytes of text that describes the channel definition.

Note: The maximum number of characters is reduced if the system is using a

double byte character set (DBCS).

Use characters from the character set identified by the coded character set
identifier (CCSID) for the queue manager to ensure that the text is translated
correctly if it is sent to another queue manager.

Disconnect interval (DISCINT)

This is a time-out attribute, specified in seconds, for the server, cluster-sender,
sender, and cluster-receiver channels. The interval is measured from the point at
which a batch ends, that is when the batch size is reached or when the batch
interval expires and the transmission queue becomes empty. If no messages arrive
on the transmission queue during the specified time interval, the channel closes
down. (The time is approximate.)

The close-down exchange of control data between the two ends of the channel
includes an indication of the reason for closing. This ensures that the
corresponding end of the channel remains available to start up again.

On all platforms except OS/390 with CICS, you can specify any number of seconds
from zero through 999 999 where a value of zero means no disconnect; wait
indefinitely.

In OS/390 using CICS, you can specify any number of seconds from zero through
9999 where a value of zero means disconnect as soon as the transmission queue is
empty.

Note: Performance is affected by the value specified for the disconnect interval.

| A very low value (a few seconds) may cause excessive overhead in

| constantly starting up the channel. A very large value (more than an hour)
| could mean that system resources are unnecessarily held up. For V5.1 of
| MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows
| NT and MQSeries for OS/390 without CICS, you can also specify a
| heartbeat interval, so that when there are no messages on the transmission
| queue, the sending MCA will send a heartbeat flow to the receiving MCA,
| thus giving the receiving MCA an opportunity to quiesce the channel
| without waiting for the disconnect interval to expire. For these two values to
| work together effectively, the heartbeat interval value must be significantly
| lower than the disconnect interval value.

A value for the disconnect interval of a few minutes is a reasonable value to

use. Change this value only if you understand the implications for
performance, and you need a different value for the requirements of the
traffic flowing down your channels.

For more information, see “Stopping and quiescing channels (not MQSeries
for Windows)” on page 67.

84 MQSeries Intercommunication
 Heartbeat interval (HBINT)
Heartbeat interval (HBINT)
| This attribute applies to V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp,
| Sun Solaris, and Windows NT and MQSeries for OS/390 without CICS. You can
| specify the approximate time between heartbeat flows that are to be passed from a
| sending MCA when there are no messages on the transmission queue. Heartbeat
| flows unblock the receiving MCA, which is waiting for messages to arrive or for
| the disconnect interval to expire. When the receiving MCA is unblocked it can
| disconnect the channel without waiting for the disconnect interval to expire.
| Heartbeat flows also free any storage buffers that have been allocated for large
| messages and close any queues that have been left open at the receiving end of the
| channel.

The value is in seconds and must be in the range 0 through 999 999. A value of
zero means that no heartbeat flows are to be sent. The default value is 300. To be
most useful, the value should be significantly less than the disconnect interval
value.

This attribute is valid for sender, cluster-sender, server, receiver, cluster-receiver,

and requester channels. Other than on OS/390 and OS/400, it also applies to
server-connection and client-connection channels. On these channels, heartbeats
flow when a server MCA has issued an MQGET command with the WAIT option
on behalf of a client application.

Long retry count (LONGRTY)

Specify the maximum number of times that the channel is to try allocating a
session to its partner. If the initial allocation attempt fails, the short retry count
number is decremented and the channel retries the remaining number of times. If
it still fails, it retries a long retry count number of times with an interval of
long retry interval between each try. If it is still unsuccessful, the channel closes
down. The channel must subsequently be restarted with a command (it is not
started automatically by the channel initiator).

(Retry is not attempted if the cause of failure is such that a retry is not likely to be
successful.)

If the channel initiator or queue manager stops while the channel is retrying, the
short retry count and long retry count are reset when the channel initiator or queue
manager is restarted.

The long retry count attribute is valid only for channel types of sender,
cluster-sender, server, and cluster-receiver. It is also valid for requester channels on
OS/390 if you are using CICS. It may be set from zero through 999 999 999. On
OS/390 using CICS, it may be set from zero through 999, and the long and short
retries have the same count.

Note: For OS/2, OS/400, UNIX systems, and Windows NT, in order for retry to be
attempted a channel initiator must be running. The channel initiator must be
monitoring the initiation queue specified in the transmission queue that the
channel is using.

Long retry interval (LONGTMR)

The approximate interval in seconds that the channel is to wait before retrying to
establish connection, during the long retry mode.

Chapter 6. Channel attributes 85

Long retry interval (LONGTMR)
The interval between retries may be extended if the channel has to wait to become
active.

The channel tries to connect long retry count number of times at this long
interval, after trying the short retry count number of times at the short retry
interval.

This is valid only for channel types of sender, cluster-sender, server, and
cluster-receiver. It is also valid for requester channels on OS/390 if you are using
CICS. It may be set from zero through 999 999. On OS/390 using CICS, it may be
set from zero through 999.

LU 6.2 mode name (MODENAME)

This is for use with LU 6.2 connections. It gives extra definition for the session
characteristics of the connection when a communication session allocation is
performed.

When using side information for SNA communications, the mode name is defined
in the CPI-C Communications Side Object or APPC side information and this
attribute should be left blank; otherwise, it should be set to the SNA mode name.

The name must be one to eight alphanumeric characters long.

It is not valid for receiver or server-connection channels.

LU 6.2 transaction program name (TPNAME)

This is for use with LU 6.2 connections. It is the name, or generic name, of the
transaction program (MCA) to be run at the far end of the link.

When using side information for SNA communications, the transaction program
name is defined in the CPI-C Communications Side Object or APPC side
information and this attribute should be left blank. Otherwise, this name is
required by sender channels and requester channels except on OS/390 using CICS
where it is required in the channel definition but is ignored unless the server is
initiating the conversation.

On platforms other then Tandem NSK, the name can be up to 64 characters long.
See “Chapter 20. Setting up communication in Tandem NSK” on page 289 for more
information about that platform.

If the remote system is MQSeries for OS/390 using CICS, the transaction is:
v CKRC when you are defining a sender channel, or a server channel that acts as
a sender
v CKSV when you are defining a requester channel of a requester-server pair
v CKRC when you are defining a requester channel of a requester-sender pair

On other platforms, this should be set to the SNA transaction program name,
unless the CONNAME contains a side-object name in which case it should be set
to blanks. The actual name is taken instead from the CPI-C Communications Side
Object, or the APPC side information data set.

This information is set in a different way on other platforms; see the section in this
book about setting up communication for your platform.

86 MQSeries Intercommunication
 Maximum message length (MAXMSGL)
Maximum message length (MAXMSGL)
Specifies the maximum length of a message that can be transmitted on the channel.

| On AIX, HP-UX, OS/2 Warp, OS/400, Sun Solaris, Windows NT, and VSE/ESA,
| specify a value greater than or equal to zero, and less than or equal to the
| maximum message length for the queue manager. See the MAXMSGL parameter of
| the MQSeries Command Reference book for more information. On other platforms,
| specify a value greater than or equal to zero, and less than or equal to 4 194 304
| bytes.

Because various implementations of MQSeries systems exist on different platforms,

the size available for message processing may be limited in some applications. This
number must reflect a size that your system can handle without stress. When a
channel starts up, the lower of the two numbers at each end of the channel is
taken.
Notes:
1. If splitting of messages is not supported at either end of a channel, the
maximum message size cannot be greater than the negotiated maximum
transmission size.
2. The IBM MQSeries products that this edition of the book applies to all support
message splitting. Other MQSeries products do not support message splitting.
3. For a comparison of the functions available, including the different maximum
message lengths available see the MQSeries Planning Guide and the MQSeries
Application Programming Guide.
4. You may use a maximum message size of 0 which will be taken to mean that
the size is to be set to the local queue manager maximum value.

Maximum transmission size

If you are using CICS for distributed queuing on OS/390, you can specify the
maximum transmission size, in bytes, that your channel is allowed to use when
transmitting a message, or part of a message. When a channel starts up, this value
is negotiated between the sending and receiving channels and the lower of the two
values is agreed. The maximum size is 32 000 bytes on TCP/IP, but the maximum
usable size is 32 000 bytes less the message descriptor. On VSE/ESA, the
maximum size is 64 000 bytes on SNA.

Use this facility to ensure that system resources are not exceeded by your channels.
Set this value in conjunction with the maximum message size, remembering to
allow for message descriptors. An error situation may be created if the message
size is allowed to exceed the transmission size, and message splitting is not
supported.
Notes:
1. If channel startup negotiation results in a size less than the minimum required
for the local channel program, no messages can be transferred.
2. The IBM MQSeries products that this edition of the book applies to all support
message splitting. Other MQSeries products do not support message splitting.

Message channel agent name (MCANAME)

This attribute is reserved and should not be used.

Chapter 6. Channel attributes 87

 MCA type (MCATYPE)
Message channel agent type (MCATYPE)
| For MQSeries for AIX, AS/400, Windows NT, HP-UX, OS/2, and Sun Solaris, this
| attribute may be specified as a ‘process’ or a ‘thread’. This parameter is valid for
| channel types of sender, cluster-sender (on V5.1 of MQSeries for AIX, AS/400,
| HP-UX, OS/2 Warp, Sun Solaris, and Windows NT only), server, requester, or
| cluster-receiver. On MQSeries for OS/390, it is supported only for channels with a
| channel type of cluster-receiver. The MCA type is used when the channel is started
| locally to determine how the channel is run.

| Advantages of running as a process include:

| v Isolation for each channel providing greater integrity
| v Job authority specific for each channel
| v Control over job scheduling

| Advantages of threads include:

| v Much reduced use of storage
| v Easier configuration by typing on the command line
| v Faster execution - it is quicker to start a thread than to instruct the operating
| system to start a process

| For channel types of sender, server, and requester, the default is ‘process’. For
| channel types of cluster-sender and cluster-receiver, the default is ‘thread’. These
| defaults can change during your installation.

| If you specify ‘process’ on the channel definition, a runmqchi process is started. If

| you specify ‘thread’, the MCA runs on a thread of the MQCHI process. On the
| machine that receives the inbound allocates, the MCA runs as a thread or process
| depending on whether you specify inetd or MQLSR.

Message channel agent user identifier (MCAUSER)

This is not valid for OS/390 using CICS; it is not valid for channels of
client-connection type.

This attribute is the user identifier (a string) to be used by the MCA for
authorization to access MQSeries resources, including (if PUT authority is DEF)
authorization to put the message to the destination queue for receiver or requester
channels.

On MQSeries for Windows NT, the user identifier may be domain-qualified by

using the format, user@domain, where the domain must be either the Windows NT
domain of the local system or a trusted domain.

If this attribute is blank, the MCA uses its default user identifier.

Message exit name (MSGEXIT)

| Specifies the name of the user exit program to be run by the channel message exit.
| In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT this can be a list of names of programs that are to be run in
| succession. Leave blank, if no channel message exit is in effect.

The format and maximum length of this attribute depend on the platform, as for
“Receive exit name (RCVEXIT)” on page 91.

88 MQSeries Intercommunication
 Message exit name (MSGEXIT)
The message exit is not supported on client-connection or server-connection
channels.

Message exit user data (MSGDATA)

Specifies user data that is passed to the channel message exits.

| In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT, you can run a sequence of message exits. The limitations on the user
| data length and an example of how to specify MSGDATA for more than one exit
| are as shown for RCVDATA. See “Receive exit user data (RCVDATA)” on page 92.

On other platforms the maximum length of the string is 32 characters.

Message-retry exit name (MREXIT)

Specifies the name of the user exit program to be run by the message-retry user
exit. Leave blank if no message-retry exit program is in effect.

The format and maximum length of the name depend on the platform, as for
“Receive exit name (RCVEXIT)” on page 91.

This parameter is only valid for receiver, cluster-receiver, and requester channels. It
is not supported on MQSeries for OS/390 or MQSeries for Windows.

Message-retry exit user data (MRDATA)

This is passed to the channel message-retry exit when it is called.

This parameter is only valid for receiver, cluster-receiver, and requester channels. It
is not supported on MQSeries for OS/390 or MQSeries for Windows.

Message retry count (MRRTY)

This is the number of times the channel will retry before it decides it cannot
deliver the message.

This attribute controls the action of the MCA only if the message-retry exit name is
blank. If the exit name is not blank, the value of MRRTY is passed to the exit for
the exit’s use, but the number of retries performed (if any) is controlled by the exit,
and not by this attribute.

The value must be in the range 0 to 999 999 999. A value of zero means that no
retries will be performed.

This parameter is only valid for receiver, cluster-receiver, and requester channels. It
is not supported on MQSeries for OS/390 or MQSeries for Windows.

Message retry interval (MRTMR)

This is the minimum interval of time that must pass before the channel can retry
the MQPUT operation. This time interval is in milliseconds.

This attribute controls the action of the MCA only if the message-retry exit name is
blank. If the exit name is not blank, the value of MRTMR is passed to the exit for
the exit’s use, but the retry interval is controlled by the exit, and not by this
attribute.

Chapter 6. Channel attributes 89

 Message retry interval (MRTMR)
The value must be in the range 0 to 999 999 999. A value of zero means that the
retry will be performed as soon as possible (provided that the value of MRRTY is
greater than zero).

This parameter is only valid for receiver, cluster-receiver, and requester channels. It
is not supported on MQSeries for OS/390 or MQSeries for Windows.

Network-connection priority (NETPRTY)

The priority for the network connection. Distributed queuing will choose the path
with the highest priority if there are multiple paths available. The value must be in
the range 0 through 9; 0 is the lowest priority.

This parameter is valid only for cluster-receiver channels.

| This parameter is valid only on AIX, HP-UX, OS/2 Warp, OS/390 without CICS,
| OS/400, Sun Solaris, and Windows NT.

Nonpersistent message speed (NPMSPEED)

| For V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT, MQSeries for OS/390 without CICS, and MQSeries for Windows
| V2.1, you can specify the speed at which nonpersistent messages are to be sent.
| You can specify either ‘normal’ or ‘fast’. The default is ‘fast’, which means that
| nonpersistent messages on a channel need not wait for a syncpoint before being
| made available for retrieval. The advantage of this is that nonpersistent messages
| become available for retrieval far more quickly. The disadvantage is that because
| they do not wait for a syncpoint, messages may be lost if there is a transmission
| failure or if the channel stops when the messages are in transit. See “Fast,
| nonpersistent messages” on page 22.

This attribute is valid for sender, cluster-sender, server, receiver, cluster-receiver,

and requester channels.

Password (PASSWORD)
You can specify a password of maximum length 12 characters, although only the
first 10 characters are used.

The password may be used by the MCA when attempting to initiate a secure LU
6.2 session with a remote MCA. It is valid for channel types of sender, server,
requester, or client-connection.

This does not apply to MQSeries for OS/390 except for client-connection channels,
and does not apply to MQSeries for Windows.

PUT authority (PUTAUT)

Use this field to choose the type of security processing to be carried out by the
MCA when executing 1) an MQPUT command to the destination queue (for
message channels) ,or 2) an MQI call (for MQI channels). (PUT security is not
supported on MQSeries for Windows.)

You can choose one of the following:

Process security, also called default authority (DEF)
Default user ID is used.

90 MQSeries Intercommunication
 PUT authority (PUTAUT)
On OS/390, this might involve using both the user ID received from the
network and that derived from MCAUSER.
| On other platforms, with Process security, you choose to have the queue
| security based on the user ID that the process is running under. If
| MCAUSER is not blank, the user ID has the value of MCAUSER;
| otherwise, the user ID is that of the process, or user, running the MCA at
| the receiving end of the message channel.
The queues are opened with this user ID, and the open option
MQOO_SET_ALL_CONTEXT.
Context security (CTX)
Alternate user ID is used from the context information associated with a
message.
On OS/390, this may involve also using either the user ID received from
the network, or the user ID derived from MCAUSER, or both.
The UserIdentifier in the message descriptor is moved into the
AlternateUserId field in the object descriptor. The queue is opened with
the open options MQOO_SET_ALL_CONTEXT and
MQOO_ALTERNATE_USER_AUTHORITY.
Only Message Channel Agent security (ONLYMCA)
This is supported on OS/390 only and is the same as process security but
any user ID received from the network is not used.
Alternate Message Channel Agent security (ALTMCA)
This is supported on OS/390 only and is the same as context security but
any user ID received from the network is not used.

This parameter is only valid for receiver, requester, cluster-receiver, and

server-connection channels. Context security and alternate message channel agent
security are not supported on server-connection channels.

| Further details about context fields and open options can be found in the MQSeries
| Application Programming Guide. Further details about security can be found in the
| MQSeries System Administration book for V5.1 of MQSeries for AIX, HP-UX, OS/2
| Warp, Sun Solaris, and Windows NT, the MQSeries for AS/400 V5.1 System
| Administration book for MQSeries for AS/400, the MQSeries for Windows User’s
| Guide, or in the MQSeries System Management Guide or MQSeries Administration
| Guide for your platform.

Queue manager name (QMNAME)

This applies to a channel of client-connection type only. It is the name of the queue
manager or queue manager group to which an MQSeries client application can
request connection.

Receive exit name (RCVEXIT)

| Specifies the name of the user exit program to be run by the channel receive user
| exit. In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT this can be a list of names of programs that are to be run in
| succession. Leave blank, if no channel receive user exit is in effect.

The format and maximum length of this attribute depend on the platform:
v On OS/390 it is a load module name, maximum length 8 characters, except for
client-connection channels where the maximum length is 128 characters.
v On OS/400 it is of the form:

Chapter 6. Channel attributes 91

 Receive exit name (RCVEXIT)
libname/progname

when specified in CL commands.

When specified in MQSeries Commands (MQSC) it has the form:

progname libname

where progname occupies the first 10 characters, and libname the second 10
characters (both blank-padded to the right if necessary). The maximum length of
the string is 20 characters.
v On OS/2 and Windows it is of the form:
dllname(functionname)

where dllname is specified without the suffix “.DLL”. The maximum length of
the string is 40 characters.
v On UNIX systems, Digital OpenVMS, and Tandem NSK it is of the form:
libraryname(functionname)

The maximum length of the string is 40 characters.

| In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT you can specify a list of receive, send, or message exit program
| names. The names should be separated by a comma, a space, or both. For example:
| RCVEXIT(exit1 exit2)
| MSGEXIT(exit1,exit2)
| SENDEXIT(exit1, exit2)

| In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT the total length of the string of exit names and strings of user data
| for a particular type of exit is limited to 500 characters. In MQSeries for AS/400
| you can list up to 10 exit names.

Receive exit user data (RCVDATA)

Specifies user data that is passed to the receive exit.

| In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT, you can run a sequence of receive exits. The string of user data for a
| series of exits should be separated by a comma, spaces, or both. For example:
| RCVDATA(exit1_data exit2_data)
| MSGDATA(exit1_data,exit2_data)
| SENDDATA(exit1_data, exit2_data)

| In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT the length of the string of exit names and strings of user data is
| limited to 500 characters. In MQSeries for AS/400 you can specify up to 10 exit
| names and the length of user data for each is limited to 32 characters.

On other platforms the maximum length of the string is 32 characters.

Security exit name (SCYEXIT)

Specifies the name of the exit program to be run by the channel security exit.
Leave blank if no channel security exit is in effect.

92 MQSeries Intercommunication
 Security exit name (SCYEXIT)
The format and maximum length of the name depend on the platform, as for
“Receive exit name (RCVEXIT)” on page 91.

Security exit user data (SCYDATA)

Specifies user data that is passed to the security exit. The maximum length is 32
characters.

Send exit name (SENDEXIT)

| Specifies the name of the exit program to be run by the channel send exit. In V5.1
| of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT
| this can be a list of names of programs that are to be run in sequence. Leave blank
| if no channel send exit is in effect.

The format and maximum length of this attribute depend on the platform, as for
“Receive exit name (RCVEXIT)” on page 91.

Send exit user data (SENDDATA)

Specifies user data that is passed to the send exit.

| In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT, you can run a sequence of send exits. The limitations on the user
| data length and an example of how to specify SENDDATA for more than one exit,
| are as shown for RCVDATA. See “Receive exit user data (RCVDATA)” on page 92.

On other platforms the maximum length of the string is 32 characters.

Sequence number wrap (SEQWRAP)

This is the highest number the message sequence number reaches before it restarts
at 1. In OS/390 using CICS, this number is of interest only when sequential
delivery of messages is selected. It is not valid for channel types of
client-connection or server-connection.

The value of the number should be high enough to avoid a number being reissued
while it is still being used by an earlier message. The two ends of a channel must
have the same sequence number wrap value when a channel starts up; otherwise,
an error occurs.

The value may be set from 100 through 999 999 999 (1 through 9 999 999 for
OS/390 using CICS).

Sequential delivery
This applies only to OS/390 using CICS. Set this to ‘YES’ when using sequential
numbering of messages. If one side of the channel requests this facility, it must be
accepted by the other side.

There could be a performance penalty associated with the use of this option.

For other platforms, the MCA always uses message sequence numbering.

Short retry count (SHORTRTY)

Specify the maximum number of times that the channel is to try allocating a
session to its partner. If the initial allocation attempt fails, the short retry count is
decremented and the channel retries the remaining number of times with an

Chapter 6. Channel attributes 93

Short retry count (SHORTRTY)
interval, defined in the short retry interval attribute, between each attempt. If it
still fails, it retries long retry count number of times with an interval of
long retry interval between each attempt. If it is still unsuccessful, the channel
terminates.

(Retry is not attempted if the cause of failure is such that a retry is not likely to be
successful.)

If the channel initiator or queue manager stops while the channel is retrying, the
short retry count and long retry count are reset when the channel initiator or queue
manager is restarted.

The short retry count attribute is valid only for channel types of sender,
cluster-sender, server, and cluster-receiver. It is also valid for requester channels on
OS/390 if you are using CICS. It may be set from zero through 999 999 999 (1
through 999 for OS/390 using CICS, and the long and short retries have the same
count).

Note: For MQSeries for OS/2 Warp, OS/400, UNIX systems, and Windows NT, in
order for retry to be attempted a channel initiator must be running. The
channel initiator must be monitoring the initiation queue specified in the
transmission queue that the channel in using.

Short retry interval (SHORTTMR)

Specify the approximate interval in seconds that the channel is to wait before
retrying to establish connection, during the short retry mode.

The interval between retries may be extended if the channel has to wait to become
active.

This attribute is valid only for channel types of sender, cluster-sender, server, and
cluster-receiver. It is also valid for requester channels on OS/390 if you are using
CICS. It may be set from zero through 999 999. (0 through 999 for OS/390 using
CICS).

Target system identifier

This is for OS/390 using CICS only. It identifies the particular CICS system where
the sending or requesting channel transaction is to run.

The default is blank, which means the CICS system where you are logged on. The
name may be one through four alphanumeric characters.

Transaction identifier
This only applies to OS/390 using CICS.

The name of the local CICS transaction that you want to start. If you do not
specify a value, the name of the supplied transaction for the channel type is used.

Transmission queue name (XMITQ)

The name of the transmission queue from which messages are retrieved. This is
required for channels of type sender or server, it is not valid for other channel
types.

94 MQSeries Intercommunication
 Transmission queue name (XMITQ)
Provide the name of the transmission queue to be associated with this sender or
server channel, that corresponds to the queue manager at the far side of the
channel. The transmission queue may be given the same name as the queue
manager at the remote end.

Transport type (TRPTYPE)

This does not apply to OS/390 using CICS.

The possible values are:

LU62 LU 6.2
TCP TCP/IP (1)
UDP UDP (2)
NETBIOS NetBIOS (3)
SPX SPX (3)
Notes:
1. MQSeries for Windows Version 2.1 supports TCP only.
2. UDP is supported on MQSeries for AIX and MQSeries for Windows Version 2.0 only.
3. For use on OS/2 and Windows NT. Can also be used on OS/390 for defining
client-connection channels for use on OS/2 and Windows NT.

User ID (USERID)
| On V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT, you can specify a task user identifier of 20 characters. On other
| platforms, you can specify a task user identifier of maximum length 12 characters,
| although only the first 10 characters are used.

The user ID may be used by the MCA when attempting to initiate a secure SNA
session with a remote MCA. It is valid for channel types of sender, server,
requester, or client-connection.

This does not apply to MQSeries for OS/390 except for client-connection channels.

Chapter 6. Channel attributes 95

Intercommunication

96 MQSeries Intercommunication
Chapter 7. Example configuration chapters in this book
Throughout the following parts of the book, there is a series of chapters containing
examples of how to configure the various platforms to communicate with each
other. These chapters describe tasks performed to establish a working MQSeries
network. The tasks were to establish MQSeries sender and receiver channels to
enable bi-directional message flow between the platforms over all supported
protocols.

Figure 32 is a conceptual representation of a single channel and the MQSeries

objects associated with it.

MQPUT MQGET

Ap pl1 Appl2
Sender
ch anne l

Remote
queue

Transmission L oc a l
queue queue

Queue manager 1 Queue manager 2

Figure 32. MQSeries channel to be set up in the example configuration chapters in this book

This is a simple example, intended to introduce only the basic elements of the
MQSeries network. It does not demonstrate the use of triggering which is
described in “Triggering channels” on page 20.

The objects in this network are:

v A remote queue
v A transmission queue
v A local queue
v A sender channel

Appl1 and Appl2 are both application programs; Appl1 is putting messages and
Appl2 is receiving them.

Appl1 puts messages to a remote queue. The definition for this remote queue
specifies the name of a target queue manager, a local queue on that queue
manager, and a transmission queue on this the local queue manager.

When the queue manager receives the request from Appl1 to put a message to the
remote queue, it looks at the queue definition and sees that the destination is
remote. It therefore puts the message straight onto the transmission queue

© Copyright IBM Corp. 1993, 2000 97

 Example configurations
specified in the definition. The message remains on the transmission queue until
the channel becomes available, which may happen immediately.

A sender channel has in its definition a reference to one, and one only,
transmission queue. When a channel is started, and at other times during its
normal operation, it will look at this transmission queue and send any messages
on it to the target system. The message has in its transmission header details of the
destination queue and queue manager.

The intercommunication examples in the following chapters describe in detail the

creation of each of the objects described above, for a variety of platform
combinations.

On the target queue manager, definitions are required for the local queue and the
receiver side of the channel. These objects operate independently of each other and
so can be created in any sequence.

On the local queue manager, definitions are required for the remote queue, the
transmission queue, and the sender side of the channel. Since both the remote
queue definition and the channel definition refer to the transmission queue name,
it is advisable to create the transmission queue first.

Network infrastructure
The configuration examples assume that all the systems are connected to a Token
Ring network with the exception of OS/390 and VSE/ESA, which communicate
via a 3745 (or equivalent) that is attached to the Token Ring, and Sun Solaris,
which is on an adjacent local area network (LAN) also attached to the 3745.

It is also assumed that, for SNA, all the required definitions in VTAM® and
network control program (NCP) are in place and activated for the LAN-attached
platforms to communicate over the wide area network (WAN).

Similarly, for TCP, it is assumed that nameserver function is available, either via a
domain nameserver or via locally held tables (for example a host file).

Communications software
Working configurations are given in the following chapters for the following
network software products:
v SNA
– Communications Manager/2 Version 1.11
– Communications Server for Windows NT, Version 5.0
– AIX Communications Server, V5.0
– Hewlett-Packard SNAplus2
– AT&T GIS SNA Services Version 2.06 or later
| – OS/400 Version 4 Release 4
– SunLink Peer-to-Peer Version 9.1
– OS/390 Version 2 Release 4
– CICS/VSE® Version 2 Release 1

98 MQSeries Intercommunication
 Communications software
v TCP
– TCP for OS/2 Version 2
– Microsoft Windows NT Version 4 or later
– AIX Version 4 Release 1.4
– HP-UX Version 10.2 or later
– AT&T GIS UNIX Release 2.03.01
– Sun Solaris Release 2.4
| – OS/400 Version 4 Release 4
– TCP for OS/390
| – Digital UNIX Version 4.0 or later
v NetBIOS
v SPX
v UDP

How to use the communication examples

The following chapters contain example configurations:
v “Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp” on
page 137
v “Chapter 12. Example configuration - IBM MQSeries for Windows NT” on
page 169
v “Chapter 14. Example configuration - IBM MQSeries for AIX” on page 197
v “Chapter 15. Example configuration - IBM MQSeries for DIGITAL UNIX
(Compaq Tru64 UNIX)” on page 215
v “Chapter 16. Example configuration - IBM MQSeries for HP-UX” on page 219
v “Chapter 17. Example configuration - IBM MQSeries for AT&T GIS UNIX
Version 2.2” on page 243
v “Chapter 18. Example configuration - IBM MQSeries for Sun Solaris” on
page 257
v “Chapter 29. Example configuration - IBM MQSeries for OS/390” on page 395
v “Chapter 33. Example configuration - IBM MQSeries for AS/400” on page 459
v “Chapter 35. Example configuration - MQSeries for VSE/ESA” on page 485

The information in the example-configuration chapters describes the tasks that

were carried out on a single platform, to set up communication to another of the
platforms, and then describes the MQSeries tasks to establish a working channel to
that platform. Wherever possible, the intention is to make the information as
generic as possible. Thus, to connect any two MQSeries queue managers on
different platforms, you should need to refer to only the relevant two chapters.
Any deviations or special cases are highlighted as such. Of course, you can also
connect two queue managers running on the same platform (on different machines
or on the same machine). In this case, all the information can be derived from the
one chapter.

The examples only cover how to set up communications where clustering is not
being used. For information about setting up communications while using
clustering, see the MQSeries Queue Manager Clusters book. The communications’
configuration values given here still apply.

Each chapter contains a worksheet in which you can find the parameters used in
the example configurations. There is a short description of each parameter and
some guidance on where to find the equivalent values in your system. When you
have a set of values of your own, record these in the spaces on the worksheet. As
you proceed through the chapter, you will find cross-references to these values as
you need them.

Chapter 7. Example configuration chapters in this book 99

Using communication examples
Notes:
1. Example queue manager names usually reflect the platform that the queue
manager runs on, but MVS is used for both OS/390 and MVS/ESA, which are
essentially the same.
2. The sequence number wrap value for sender definitions defaults to 999999999
for Version 2 MQSeries products.
3. For connections to MQSeries for OS/390 the examples, in general, cover only
connection without using CICS. See “Chapter 27. Preparing MQSeries for
OS/390 when using CICS” on page 381 for information about connecting using
CICS.

IT responsibilities
Because the IT infrastructure can vary greatly between organizations, it is difficult
to indicate who, within an organization, controls and maintains the information
required to complete each parameter value. To understand the terminology used in
the following chapters, consider the following guidelines as a starting point.
v System administrator is used to describe the person (or group of people) who
installs and configures the software for a specific platform.
v Network administrator is used to describe the person who controls LAN
connectivity, LAN address assignments, network naming conventions, and so on.
This person may be in a separate group or may be part of the system
administration group.
In most OS/390 installations, there is a group responsible for updating the
ACF/VTAM®, ACF/NCP, and TCP/IP software to support the network
configuration. The people in this group should be the main source of
information needed when connecting any MQSeries platform to MQSeries for
OS/390. They may also influence or mandate network naming conventions on
LANs and you should verify their span of control before creating your
definitions.
v A specific type of administrator, for example CICS administrator is indicated in
cases where we can more clearly describe the responsibilities of the person.

The example-configuration chapters do not attempt to indicate who is responsible

for and able to set each parameter. In general, several different people may be
involved.

100 MQSeries Intercommunication

 Part 3. DQM in MQSeries for OS/2 Warp, Windows NT, Digital
OpenVMS, Tandem NSK, and UNIX systems
Chapter 8. Monitoring and controlling channels Running channels and listeners as trusted
on distributed platforms . . . . . . . . . 105 applications . . . . . . . . . . . . . 121
The DQM channel control function . . . . . . 105 What next? . . . . . . . . . . . . . . 122
Functions available . . . . . . . . . . . 106
Getting started with objects. . . . . . . . . 108 Chapter 10. Setting up communication for OS/2
Creating objects . . . . . . . . . . . 108 and Windows NT . . . . . . . . . . . 123
Creating default objects . . . . . . . . . 108 Deciding on a connection . . . . . . . . . 123
How are default objects created? . . . . . 109 Defining a TCP connection . . . . . . . . . 124
Changing the default objects . . . . . . 109 Sending end . . . . . . . . . . . . . 124
Creating a channel . . . . . . . . . . 109 Receiving on TCP . . . . . . . . . . . 124
Create channel example . . . . . . . . 109 Using the TCP/IP listener . . . . . . . 124
Displaying a channel . . . . . . . . . . 110 Using the TCP listener backlog option . . . 125
Display channel examples . . . . . . . 110 Using the MQSeries listener . . . . . . 125
Displaying channel status . . . . . . . . 110 Using the TCP/IP SO_KEEPALIVE option 126
Display channel status examples . . . . . 110 Defining an LU 6.2 connection . . . . . . . 126
Starting a channel . . . . . . . . . . . 110 Sending end for OS/2 . . . . . . . . . 127
Renaming a channel . . . . . . . . . . 111 Sending end for Windows NT . . . . . . . 127
Channel attributes and channel types . . . . . 111 Receiving on LU 6.2 . . . . . . . . . . 127
Channel functions . . . . . . . . . . . 112 Using the RUNMQLSR command . . . . 127
Create . . . . . . . . . . . . . . 113 Using Communications Manager/2 on OS/2 128
Change . . . . . . . . . . . . . 113 Using Microsoft SNA Server on Windows NT 128
Delete . . . . . . . . . . . . . . 113 Defining a NetBIOS connection . . . . . . . 128
Display . . . . . . . . . . . . . 113 Defining the MQSeries local NetBIOS name . . 129
Display Status . . . . . . . . . . . 113 Establishing the queue manager NetBIOS
Ping . . . . . . . . . . . . . . 113 session, command, and name limits . . . . . 130
Start . . . . . . . . . . . . . . 114 Establishing the LAN adapter number . . . . 130
Stop . . . . . . . . . . . . . . 115 Initiating the connection . . . . . . . . . 130
Reset . . . . . . . . . . . . . . 116 Target listener . . . . . . . . . . . . 131
Resolve . . . . . . . . . . . . . 116 Defining an SPX connection . . . . . . . . 131
Sending end . . . . . . . . . . . . . 131
Chapter 9. Preparing MQSeries for distributed Using the SPX KEEPALIVE option (OS/2
platforms . . . . . . . . . . . . . . 117 only) . . . . . . . . . . . . . . 132
Transmission queues and triggering . . . . . . 117 Receiving on SPX . . . . . . . . . . . 132
Creating a transmission queue. . . . . . . 117 Using the TCP listener backlog option . . . 132
Triggering channels . . . . . . . . . . 117 Using the MQSeries listener . . . . . . 133
Example definitions for triggering . . . . 118 IPX/SPX parameters . . . . . . . . . . 133
Examples for V5.1 of MQSeries for AIX, OS/2 . . . . . . . . . . . . . . 134
HP-UX, OS/2 Warp, Sun Solaris, and DOS and Windows 3.1 client . . . . . . 134
Windows NT . . . . . . . . . . . 118 Windows NT . . . . . . . . . . . 135
Starting the channel initiator . . . . . . 118 Windows 95 and Windows 98 . . . . . . 135
| Stopping the channel initiator . . . . . . 118
Channel programs . . . . . . . . . . . . 119 Chapter 11. Example configuration - IBM
Other things to consider . . . . . . . . . . 119 MQSeries for OS/2 Warp . . . . . . . . . 137
Undelivered-message queue . . . . . . . 119 Configuration parameters for an LU 6.2 connection 137
Queues in use . . . . . . . . . . . . 120 Configuration worksheet . . . . . . . . 137
Multiple message channels per transmission Explanation of terms . . . . . . . . . . 140
queue . . . . . . . . . . . . . . . 120 Establishing an LU 6.2 connection . . . . . . 142
Security of MQSeries objects . . . . . . . 120 Defining local node characteristics . . . . . 142
On UNIX systems, Digital OpenVMS, and Configuring a DLC . . . . . . . . . 144
Tandem NSK . . . . . . . . . . . 120 Configuring the local node . . . . . . . 145
On Windows NT . . . . . . . . . . 121 Adding a local LU. . . . . . . . . . 147
User IDs across systems . . . . . . . . 121 Adding a transaction program definition . . 147
User IDs on OS/2 . . . . . . . . . . 121 Configuring a mode . . . . . . . . . 148
System extensions and user-exit programs . . . 121 Connecting to a peer system . . . . . . . 150

© Copyright IBM Corp. 1993, 2000 101

DQM in distributed platforms
Adding a peer connection . . . . . . . 150 Basic configuration . . . . . . . . . . 184
Defining a partner LU . . . . . . . . 151 Channel configuration . . . . . . . . . 185
Connecting to a host system . . . . . . . 153 MQSeries for Windows NT sender-channel
Adding a host connection . . . . . . . 154 definitions using SNA . . . . . . . . 187
Defining a partner LU . . . . . . . . 155 MQSeries for Windows NT receiver-channel
Verifying the configuration . . . . . . . . 157 definitions using SNA . . . . . . . . 187
What next? . . . . . . . . . . . . . 158 MQSeries for Windows NT sender-channel
Establishing a TCP connection. . . . . . . . 158 definitions using TCP/IP . . . . . . . 188
What next? . . . . . . . . . . . . . 159 MQSeries for Windows NT receiver-channel
Establishing a NetBIOS connection . . . . . . 160 definitions using TCP . . . . . . . . 188
Establishing an SPX connection . . . . . . . 160 MQSeries for Windows NT sender-channel
IPX/SPX parameters . . . . . . . . . . 160 definitions using NetBIOS . . . . . . . 188
IPX . . . . . . . . . . . . . . . 161 MQSeries for Windows NT receiver-channel
SPX . . . . . . . . . . . . . . 161 definitions using NetBIOS . . . . . . . 188
SPX addressing . . . . . . . . . . . . 161 MQSeries for Windows NT sender-channel
Using the SPX KEEPALIVE option . . . . . 162 definitions using SPX. . . . . . . . . 188
Receiving on SPX . . . . . . . . . . . 162 MQSeries for Windows NT receiver-channel
Using the MQSeries listener . . . . . . 162 definitions using SPX. . . . . . . . . 189
MQSeries for OS/2 Warp configuration. . . . . 162 Automatic startup . . . . . . . . . . . 189
Basic configuration . . . . . . . . . . 163 Running channels as processes or threads . . . 189
Channel configuration . . . . . . . . . 163
MQSeries for OS/2 Warp sender-channel Chapter 13. Setting up communication in UNIX
definitions using SNA . . . . . . . . 166 systems . . . . . . . . . . . . . . . 191
MQSeries for OS/2 Warp receiver-channel Deciding on a connection . . . . . . . . .191
definitions using SNA . . . . . . . . 166 Defining a TCP connection . . . . . . . . .191
MQSeries for OS/2 Warp sender-channel Sending end . . . . . . . . . . . . .191
definitions using TCP . . . . . . . . 166 Receiving on TCP . . . . . . . . . . .192
MQSeries for OS/2 Warp receiver-channel Using the TCP/IP listener . . . . . . .192
definitions using TCP/IP . . . . . . . 166 Using the TCP listener backlog option . . .193
MQSeries for OS/2 Warp sender-channel Using the MQSeries listener . . . . . .193
definitions using NetBIOS . . . . . . . 167 Using the TCP/IP SO_KEEPALIVE option 194
MQSeries for OS/2 Warp receiver-channel Defining an LU 6.2 connection . . . . . . . 194
definitions using NetBIOS . . . . . . . 167 Sending end . . . . . . . . . . . . . 195
MQSeries for OS/2 Warp sender-channel Receiving on LU 6.2 . . . . . . . . . . 195
definitions using IPX/SPX . . . . . . . 167
MQSeries for OS/2 Warp receiver-channel Chapter 14. Example configuration - IBM
definitions using IPX/SPX . . . . . . . 167 MQSeries for AIX . . . . . . . . . . . 197
Running channels as processes or threads . . . 167 Configuration parameters for an LU 6.2 connection 197
Configuration worksheet . . . . . . . . 197
Chapter 12. Example configuration - IBM Explanation of terms . . . . . . . . . . 200
MQSeries for Windows NT . . . . . . . . 169 Establishing a session using Communications
Configuration parameters for an LU 6.2 connection 169 Server for AIX V5 . . . . . . . . . . . . 202
Configuration worksheet . . . . . . . . 170 Configuring your node . . . . . . . . . 202
Explanation of terms . . . . . . . . . . 172 Configuring connectivity to the network . . . 203
Establishing an LU 6.2 connection . . . . . . 174 Defining a local LU . . . . . . . . . . 205
Configuring the local node . . . . . . . . 174 Defining a transaction program . . . . . . 206
Adding a connection . . . . . . . . . . 176 Establishing a TCP connection. . . . . . . . 209
Adding a partner . . . . . . . . . . . 178 What next? . . . . . . . . . . . . . 209
Adding a CPI-C entry . . . . . . . . . 179 Establishing a UDP connection . . . . . . . 209
Configuring an invokable TP . . . . . . . 179 What next? . . . . . . . . . . . . . 209
What next? . . . . . . . . . . . . . 181 MQSeries for AIX configuration . . . . . . . 209
Establishing a TCP connection. . . . . . . . 181 Basic configuration . . . . . . . . . . 210
What next? . . . . . . . . . . . . . 181 Channel configuration . . . . . . . . . 210
Establishing a NetBIOS connection . . . . . . 181 MQSeries for AIX sender-channel definitions
Establishing an SPX connection . . . . . . . 182 using SNA . . . . . . . . . . . . 213
IPX/SPX parameters . . . . . . . . . . 182 MQSeries for AIX receiver-channel
SPX addressing . . . . . . . . . . . . 183 definitions using SNA . . . . . . . . 213
Receiving on SPX . . . . . . . . . . . 183 MQSeries for AIX TPN setup . . . . . . 213
Using the MQSeries listener . . . . . . 183 MQSeries for AIX sender-channel definitions
MQSeries for Windows NT configuration . . . . 184 using TCP . . . . . . . . . . . . 213
Default configuration . . . . . . . . . . 184

102 MQSeries Intercommunication

 DQM in distributed platforms
MQSeries for AIX receiver-channel Chapter 17. Example configuration - IBM
definitions using TCP . . . . . . . . 214 MQSeries for AT&T GIS UNIX Version 2.2 . . . 243
MQSeries for AIX sender-channel definitions Configuration parameters for an LU 6.2 connection 243
using UDP . . . . . . . . . . . . 214 Configuration worksheet . . . . . . . . 243
MQSeries for AIX receiver-channel Explanation of terms . . . . . . . . . . 246
definitions using UDP . . . . . . . . 214 Establishing a connection using AT&T GIS SNA
Server . . . . . . . . . . . . . . . . 246
Chapter 15. Example configuration - IBM Defining local node characteristics . . . . . 247
MQSeries for DIGITAL UNIX (Compaq Tru64 Configuring the SNA subsystem . . . . . 247
UNIX) . . . . . . . . . . . . . . . . 215 Defining a mode . . . . . . . . . . 248
Establishing a TCP connection. . . . . . . . 215 Defining a local Transaction Program . . . 248
What next? . . . . . . . . . . . . . 215 Connecting to a partner node . . . . . . . 249
| MQSeries for DIGITAL UNIX (Compaq Tru64 Configuring a remote node . . . . . . . . 249
| UNIX) configuration . . . . . . . . . . . 215 Defining a partner LU . . . . . . . . 250
| Basic configuration . . . . . . . . . . 216 Adding a CPI-C Side Entry. . . . . . . 250
| Channel configuration . . . . . . . . . 216 What next? . . . . . . . . . . . . . 251
| MQSeries for DIGITAL UNIX (Compaq Tru64 Establishing a TCP connection. . . . . . . . 251
| UNIX) sender-channel definitions using What next? . . . . . . . . . . . . . 251
| TCP/IP . . . . . . . . . . . . . 218 MQSeries for AT&T GIS UNIX configuration . . . 251
| MQSeries for DIGITAL UNIX (Compaq Tru64 Basic configuration . . . . . . . . . . 252
| UNIX) receiver-channel definitions using Channel configuration . . . . . . . . . 252
| TCP/IP . . . . . . . . . . . . . 218 MQSeries for AT&T GIS UNIX
sender-channel definitions using SNA . . . 255
Chapter 16. Example configuration - IBM MQSeries for AT&T GIS UNIX
MQSeries for HP-UX . . . . . . . . . . 219 receiver-channel definitions using SNA . . . 255
Configuration parameters for an LU 6.2 connection 219 MQSeries for AT&T GIS UNIX
Configuration worksheet . . . . . . . . 219 sender-channel definitions using TCP . . . 255
Explanation of terms . . . . . . . . . . 222 MQSeries for AT&T GIS UNIX
Establishing a session using HP SNAplus2 . . . 223 receiver-channel definitions using TCP/IP . . 255
SNAplus2 configuration . . . . . . . . . 223
Defining a local node. . . . . . . . . 225 Chapter 18. Example configuration - IBM
Adding a Token Ring Port . . . . . . . 225 MQSeries for Sun Solaris. . . . . . . . . 257
Defining a local LU . . . . . . . . . 226 Configuration parameters for an LU 6.2 connection 257
APPC configuration . . . . . . . . . . 227 Configuration worksheet . . . . . . . . 257
Defining a remote node . . . . . . . . 227 Explanation of terms . . . . . . . . . . 260
Defining a partner LU . . . . . . . . 228 Establishing a connection using SunLink Version
Defining a link station . . . . . . . . 229 9.1 . . . . . . . . . . . . . . . . . 261
Defining a mode . . . . . . . . . . 231 SunLink 9.1 base configuration . . . . . . 261
Adding CPI-C information . . . . . . . 233 Configuring a PU 2.1 server . . . . . . . 262
Adding a TP definition using HP SNAplus2 Adding a LAN connection . . . . . . . . 263
Release 5 . . . . . . . . . . . . . 235 Configuring a connection to a remote PU . . . 264
Adding a TP definition using HP SNAplus2 Configuring an independent LU . . . . . . 265
Release 6 . . . . . . . . . . . . . 235 Configuring a partner LU . . . . . . . . 267
HP-UX operation . . . . . . . . . . . 237 Configuring the session mode . . . . . . . 268
What next? . . . . . . . . . . . . . 237 Configuring a transaction program . . . . . 269
Establishing a TCP connection. . . . . . . . 237 Invokable TP path . . . . . . . . . . 270
What next? . . . . . . . . . . . . . 237 CPI-C side information . . . . . . . . . 270
MQSeries for HP-UX configuration . . . . . . 238 What next? . . . . . . . . . . . . . 271
Basic configuration . . . . . . . . . . 238 Establishing a TCP connection. . . . . . . . 271
Channel configuration . . . . . . . . . 238 What next? . . . . . . . . . . . . . 271
MQSeries for HP-UX sender-channel MQSeries for Sun Solaris configuration . . . . . 271
definitions using SNA . . . . . . . . 241 Basic configuration . . . . . . . . . . 272
MQSeries for HP-UX receiver-channel Channel configuration . . . . . . . . . 272
definitions using SNA . . . . . . . . 241 MQSeries for Sun Solaris sender-channel
MQSeries for HP-UX invokable TP setup . . 241 definitions using SNA . . . . . . . . 275
MQSeries for HP-UX sender-channel MQSeries for Sun Solaris receiver-channel
definitions using TCP . . . . . . . . 241 definitions using SNA . . . . . . . . 275
MQSeries for HP-UX receiver-channel MQSeries for Sun Solaris sender-channel
definitions using TCP/IP . . . . . . . 242 definitions using TCP . . . . . . . . 275
MQSeries for Sun Solaris receiver-channel
definitions using TCP/IP . . . . . . . 275

Part 3. DQM in MQSeries for OS/2 Warp, Windows NT, Digital OpenVMS, Tandem NSK, and UNIX systems 103
 DQM in distributed platforms
Chapter 19. Setting up communication in Digital SNA channels . . . . . . . . . . . . . 289
OpenVMS systems . . . . . . . . . . . 277 LU 6.2 responder processes. . . . . . . . 291
Deciding on a connection . . . . . . . . . 277 TCP channels . . . . . . . . . . . . . 291
Defining a TCP connection . . . . . . . . . 278 Communications examples . . . . . . . . . 292
Sending end . . . . . . . . . . . . . 278 SNAX communications example . . . . . . 292
Receiving channels using Compaq (DIGITAL) SCF SNA line configuration file . . . . . 292
TCP/IP services (UCX) for OpenVMS . . . . 278 SYSGEN parameters . . . . . . . . . 294
Using the TCP/IP SO_KEEPALIVE option 279 SNAX/APC process configuration . . . . 295
Receiving channels using Cisco MultiNet for Channel definitions . . . . . . . . . 299
OpenVMS . . . . . . . . . . . . . 279 ICE communications example . . . . . . . 299
Receiving channels using Attachmate PathWay Configuring the ICE process . . . . . . 299
for OpenVMS . . . . . . . . . . . . 280 Defining the line and APC information . . . 300
Receiving channels using Process Software Channel definitions for ICE. . . . . . . 303
Corporation TCPware . . . . . . . . . 280 TCP/IP communications example . . . . . 303
Defining an LU 6.2 connection . . . . . . . 281 TCPConfig stanza in QMINI . . . . . . 303
SNA configuration. . . . . . . . . . . 281 Defining a TCP sender channel . . . . . 303
Defining access names . . . . . . . . 282 Defining a TCP receiver channel . . . . . 304
Specifying SNA configuration parameters to Defining a TCP/IP sender channel on the
MQSeries. . . . . . . . . . . . . . 283 remote system . . . . . . . . . . . 304
Passing parameters to sender and requester
channel pairs . . . . . . . . . . . 283 Chapter 21. Message channel planning example
Running senders and requesters . . . . . 283 for distributed platforms . . . . . . . . . 305
Passing parameters to servers and receivers 283 What the example shows . . . . . . . . . 305
Running servers and receivers . . . . . . 284 Queue manager QM1 example . . . . . . 307
Ending the SNA Listener process . . . . . 284 Queue manager QM2 example . . . . . . 308
Sample MQSeries configuration . . . . . . 284 Running the example. . . . . . . . . . . 309
Problem solving . . . . . . . . . . . 285 Expanding this example . . . . . . . . . 309
Defining a DECnet Phase IV connection . . . . 285
Sending end . . . . . . . . . . . . . 286 Chapter 22. Example SINIX and DC/OSx
Receiving on DECnet Phase IV . . . . . . 286 configuration files . . . . . . . . . . . 311
Defining a DECnet Phase V connection. . . . . 286 Configuration file on bight . . . . . . . . . 312
Configuration file on forties . . . . . . . . 313
Chapter 20. Setting up communication in Working configuration files for Pyramid DC/OSx 313
Tandem NSK . . . . . . . . . . . . . 289 Output of dbd command . . . . . . . . 314
Deciding on a connection . . . . . . . . . 289

| This part of the book describes the MQSeries distributed queue management
| function for MQSeries for OS/2 Warp, Windows NT, Digital OpenVMS, Tandem
| NSK, and UNIX systems. The information given may not all apply to MQSeries for
| Windows. You should refer to theMQSeries for Windows User’s Guidefor information
| about that product. For information about the MQSeries distributed queue
| management function for MQSeries for OS/390, see“Part 4. DQM in MQSeries for
| OS/390” on page 319. For information about the MQSeries distributed queue
| management function for MQSeries for AS/400, see“Part 5. DQM in MQSeries for
| AS/400” on page 421.

104 MQSeries Intercommunication

Chapter 8. Monitoring and controlling channels on distributed
platforms
For DQM you need to create, monitor, and control the channels to remote queue
managers. You can use the following types of command to do this:
The MQSeries commands (MQSC)
You can use the MQSC as single commands in an MQSC session in OS/2,
Windows NT, Digital OpenVMS, Tandem NSK, and UNIX systems. To
issue more complicated, or multiple, commands the MQSC can be built
into a file that you then run from the command line. For full details see the
MQSeries Command Reference book. This chapter gives some simple
examples of using MQSC for distributed queuing.
Control commands
You can also issue control commands at the command line for some of these
functions. Reference material for these commands is contained in the
MQSeries System Administration book for V5.1 of MQSeries for AIX, HP-UX,
OS/2 Warp, Sun Solaris, and Windows NT, or in the MQSeries System
Management Guide for your platform.
Programmable command format commands
See the MQSeries Programmable System Management book for information
about using these commands.
Message Queue Management facility
On Tandem NSK, you can use the Message Management facility. See the
MQSeries for Tandem NonStop Kernel System Management Guide for
information about this facility.
IBM MQSeries Explorer
On Windows NT, you can use an MMC snap-in called the MQSeries
Explorer. This provides a graphical administration interface to perform
administrative tasks as an alternative to using control commands or MQSC
commands.

Each queue manager has a DQM component for controlling interconnections to

compatible remote queue managers.

For a list of the functions available to you when setting up and controlling
message channels, using the two types of commands, see Table 7 on page 106.

The DQM channel control function

The channel control function provides the interface and function for administration
and control of message channels between systems.

It consists of commands, programs, a file for the channel definitions, and a storage
area for synchronization information. The following is a brief description of the
components.
v The channel commands are a subset of the MQSeries Commands (MQSC).
v You use MQSC and the control commands to:
– Create, copy, display, change, and delete channel definitions

© Copyright IBM Corp. 1993, 2000 105

 Channel control function
– Start and stop channels, ping, reset channel sequence numbers, and resolve
in-doubt messages when links cannot be re-established
– Display status information about channels
v The channel definition file (CDF), amqrfcda.dat:
– Is indexed on channel name
– Holds channel definitions
v A storage area holds sequence numbers and logical unit of work (LUW) identifiers.
These are used for channel synchronization purposes.

Functions available
Table 7 shows the full list of MQSeries functions that you may need when setting
up and controlling channels. The channel functions are explained in this chapter.

| For more details of the control commands that you issue at the command line, see
| the MQSeries System Administration book for V5.1 of MQSeries for AIX, HP-UX,
| OS/2 Warp, Sun Solaris, and Windows NT, or the MQSeries System Management
| Guide for your platform.

The MQSC commands are fully described in the MQSeries Command Reference book.
Table 7. Functions available in OS/2, Windows NT, Digital OpenVMS, Tandem NSK, and UNIX systems
Function Control MQSC MQSeries MQSeries Service
commands Explorer snap-in
equivalent? equivalent?
Queue manager functions
Change queue manager ALTER QMGR Yes No
Create queue manager crtmqm Yes Yes
Delete queue manager dltmqm Yes Yes
Display queue manager DISPLAY QMGR Yes No
End queue manager endmqm Yes Yes
Ping queue manager PING QMGR No No
Start queue manager strmqm Yes Yes
Add a queue manager to Windows No Yes
NT Service Control Manager
Command server functions
Display command server dspmqcsv No Yes
End command server endmqcsv No Yes
Start command server strmqcsv No Yes
Queue functions
Change queue ALTER QALIAS Yes No
ALTER QLOCAL
ALTER QMODEL
ALTER
QREMOTE
Clear queue CLEAR QLOCAL Yes No
CLEAR QUEUE

106 MQSeries Intercommunication

 Functions available
Table 7. Functions available in OS/2, Windows NT, Digital OpenVMS, Tandem NSK, and UNIX systems (continued)
Function Control MQSC MQSeries MQSeries Service
commands Explorer snap-in
equivalent? equivalent?
Create queue DEFINE QALIAS Yes No
DEFINE QLOCAL
DEFINE
QMODEL
DEFINE
QREMOTE
Delete queue DELETE QALIAS Yes No
DELETE
QLOCAL
DELETE
QMODEL
DELETE
QREMOTE
Display queue DISPLAY QUEUE Yes No
Process functions
Change process ALTER PROCESS Yes No
Create process DEFINE Yes No
PROCESS
Delete process DELETE Yes No
PROCESS
Display process DISPLAY Yes No
PROCESS
Channel functions
Change channel ALTER Yes No
CHANNEL
Create channel DEFINE Yes No
CHANNEL
Delete channel DELETE Yes No
CHANNEL
Display channel DISPLAY Yes No
CHANNEL
Display channel status DISPLAY Yes No
CHSTATUS
End channel STOP CHANNEL Yes Yes
Ping channel PING CHANNEL Yes No
Reset channel RESET Yes No
CHANNEL
Resolve channel RESOLVE Yes No
CHANNEL
Run channel runmqchl START Yes Yes
CHANNEL
Run channel initiator runmqchi START CHINIT No Yes
(not Tandem
NSK)

Chapter 8. Monitoring and controlling channels on distributed platforms 107

Functions available
Table 7. Functions available in OS/2, Windows NT, Digital OpenVMS, Tandem NSK, and UNIX systems (continued)
Function Control MQSC MQSeries MQSeries Service
commands Explorer snap-in
equivalent? equivalent?
Run listener runmqlsr (not START LISTENER No Yes
AT&T GIS UNIX (not Tandem
and Digital UNIX) NSK)
End listener endmqlsr (OS/2, No Yes
Windows NT,
AIX, HP-UX, Sun
Solaris, and SINIX
and DC/OSx
only)

Getting started with objects

Use the MQSeries commands (MQSC) or the MQSeries Explorer on Windows NT
to:
1. Define message channels and associated objects
2. Monitor and control message channels

The objects you may need to define are:

v Transmission queues
v Remote queue definitions
v Queue manager alias definitions
v Reply-to queue alias definitions
v Reply-to local queues
v Processes for triggering (MCAs)
v Message channel definitions

Channels must be completely defined, and their associated objects must exist and
be available for use, before a channel can be started. This chapter shows you how
to do this.

In addition, the particular communication link for each channel must be defined
and available before a channel can be run. For a description of how LU 6.2,
TCP/IP, NetBIOS, SPX, and DECnet links are defined, see the particular
communication guide for your installation. See also the example configuration
chapters in this book.

Creating objects
Use MQSC to create the queue and alias objects: transmission queues, remote
queue definitions, queue manager alias definitions, reply-to queue alias definitions,
and reply-to local queues.

Also create the definitions of processes for triggering (MCAs) in a similar way.

For an example showing how to create all the required objects see “Chapter 21.
Message channel planning example for distributed platforms” on page 305.

Creating default objects

In V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT,
default objects are created automatically when a queue manager is created. These
objects are queues, channels, a process definition, and administration queues. They

108 MQSeries Intercommunication

 Getting started
correspond to the objects that are created when you run the amqscoma.tst sample
command file on earlier releases of these products and on other MQSeries
products.

How are default objects created?

When you use the CRTMQM command to create a queue manager, the command
also initiates a program to create a set of default objects.
1. Each default object is created in turn. The program keeps a count of how many
objects are successfully defined, how many already existed and were replaced,
and how many unsuccessful attempts there were.
2. The program displays the results to you and if any errors occurred, directs you
to the appropriate error log for details.

When the program has finished running, you can use the STRMQM command to
start the queue manager.

| See the MQSeries System Administration book for information about the CRTMQM
| and STRMQM commands and a list of default objects.

Changing the default objects

Once the default objects have been created, you can replace them at any time by
running the STRMQM command with the -c option. When you specify the -c
option, the queue manager is started temporarily while the objects are created and
is then shut down again. You must use the STRMQM command again, without the
-c option, if you want to start the queue manager.

If you wish to make any changes to the default objects, you can create your own
version of the old amqscoma.tst file and edit it.

Creating a channel
To create a new channel you have to create two channel definitions, one at each
end of the connection. You create the first channel definition at the first queue
manager. Then you create the second channel definition at the second queue
manager, on the other end of the link.

Both ends must be defined using the same channel name. The two ends must have
compatible channel types, for example: Sender and Receiver.

To create a channel definition for one end of the link use the MQSC command
DEFINE CHANNEL. Include the name of the channel, the channel type for this
end of the connection, a connection name, a description (if required), the name of
the transmission queue (if required), and the transmission protocol. Also include
any other attributes that you want to be different from the system default values
for the required channel type, using the information you have gathered previously.

You are provided with help in deciding on the values of the channel attributes in
“Chapter 6. Channel attributes” on page 77.

Note: You are very strongly recommended to name all the channels in your
network uniquely. Including the source and target queue manager names in
the channel name is a good way to do this.

Create channel example

DEFINE CHANNEL(QM1.TO.QM2) CHLTYPE(SDR) +
DESCR('Sender channel to QM2') +
CONNAME(QM2) TRPTYPE(TCP) XMITQ(QM2) CONVERT(YES)

Chapter 8. Monitoring and controlling channels on distributed platforms 109

Getting started
In all the examples of MQSC the command is shown as it would appear in a file of
commands, and as it would be typed in OS/2, Windows NT, UNIX systems,
Digital OpenVMS, or Tandem NSK. The two methods look identical, except that to
issue a command interactively, you must first start an MQSC session. Type
runmqsc, for the default queue manager, or runmqsc qmname where QMNAME is the
name of the required queue manager. Then type any number of commands, as
shown in the examples.

For portability, you should restrict the line length of your commands to 72
characters. Use a concatenation character as shown to continue over more than one
line. On Tandem NSK use Ctrl-y to end the input at the command line, or enter
exit or quit. On OS/2, Windows NT, or Digital OpenVMS use Ctrl-z. On UNIX
systems, use Ctrl-d. Alternatively, on V5.1 of MQSeries for AIX, HP-UX, OS/2
Warp, Sun Solaris, and Windows NT, use the end command.

Displaying a channel
Use the MQSC command DISPLAY CHANNEL, specifying the channel name, the
channel type (optional), and the attributes you want to see, or specifying that all
attributes are to be displayed. In V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp,
Sun Solaris, and Windows NT the ALL parameter of the DISPLAY CHANNEL
command is assumed by default if no specific attributes are requested and the
channel name specified is not generic.

The attributes are described in “Chapter 6. Channel attributes” on page 77.

Display channel examples

DISPLAY CHANNEL(QM1.TO.QM2) TRPTYPE,CONVERT

DISPLAY CHANNEL(QM1.TO.*) TRPTYPE,CONVERT

DISPLAY CHANNEL(*) TRPTYPE,CONVERT

DISPLAY CHANNEL(QM1.TO.QMR34) ALL

Displaying channel status

Use the MQSC command DISPLAY CHSTATUS, specifying the channel name and
whether you want the current status of channels or the status of saved
information.

Display channel status examples

DISPLAY CHSTATUS(*) CURRENT

DISPLAY CHSTATUS(QM1.TO.*) SAVED

Note that the saved status does not apply until at least one batch of messages has
been transmitted on the channel. In V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp,
Sun Solaris, and Windows NT status is also saved when a channel is stopped
(using the STOP CHL command) and when the queue manager is ended.

Starting a channel
For applications to be able to exchange messages you must start a listener program
for inbound connections (or, in the case of UNIX systems, create a listener
attachment). In OS/2, Windows NT, and Tandem NSK, use the runmqlsr command
to start the MQSeries listener process. Any inbound requests for channel

110 MQSeries Intercommunication

 Getting started
attachment start MCAs as threads of this listener process. In Digital OpenVMS,
each receiver or server channel requires a listener process that then starts a channel
process.
runmqlsr -t tcp -m QM2

For outbound connections you must start the channel in one of the following three
ways:
1. Use the MQSC command START CHANNEL, specifying the channel name, to
start the channel as a process or a thread, depending on the MCATYPE
parameter. (If channels are started as threads, they are threads of a channel
initiator, which must have been started previously using the runmqchi
command.)
START CHANNEL(QM1.TO.QM2)
2. Use the control command runmqchl to start the channel as a process.
runmqchl -c QM1.TO.QM2 -m QM1
3. Use the channel initiator to trigger the channel.

Renaming a channel
To rename a message channel, use MQSC to carry out the following steps:
1. Use STOP CHANNEL to stop the channel.
2. Use DEFINE CHANNEL to create a duplicate channel definition with the new
name.
3. Use DISPLAY CHANNEL to check that it has been created correctly.
4. Use DELETE CHANNEL to delete the original channel definition.

If you decide to rename a message channel, remember that a channel has two
channel definitions, one at each end. Make sure you rename the channel at both
ends at the same time.

Channel attributes and channel types

| The channel attributes for each type of channel are shown in Table 8. The channel
| attributes are described in detail in “Chapter 6. Channel attributes” on page 77.
| Client-connection channels and server-connection channels are described in the
| MQSeries Clients book.
Table 8. Channel attributes for the channel types in OS/2, Windows NT, Digital OpenVMS, Tandem NSK, and UNIX
systems
Attribute field SDR SVR RCVR RQSTR CLNT- SVR- CLUS- CLUS-
CONN CONN SDR RCVR
Batch interval U U U U
Batch size U U U U U U
Channel name U U U U U U U U
Cluster U U
Cluster namelist U U
Channel type U U U U U U U U
Connection name U U U U U U
Convert message U U U U
Description U U U U U U U U
Disconnect interval U U U U
Heartbeat interval U U U U U U U U

Chapter 8. Monitoring and controlling channels on distributed platforms 111

Channel attributes and types
Table 8. Channel attributes for the channel types in OS/2, Windows NT, Digital OpenVMS, Tandem NSK, and UNIX
systems (continued)
Attribute field SDR SVR RCVR RQSTR CLNT- SVR- CLUS- CLUS-
CONN CONN SDR RCVR
Long retry count U U U U
Long retry interval U U U U
LU 6.2 Transaction U U U U U U
program name
Maximum message U U U U U U
length
Message channel agent U U U U U U
type
Message channel agent U U U U U U U U
user
Message exit name U U U U U U
Message exit user data U U U U U U
Message-retry exit U U U U
name
Message-retry exit user U U U U
data
Message retry count U U U U
Message retry interval U U U U
Mode name U U U U U U
Network-connection U U
priority
Nonpersistent message U U U U U U
speed
Password U U U U U
PUT authority U U U
Queue manager name U
Receive exit U U U U U U U U
Receive exit user data U U U U U U U U
Security exit U U U U U U U U
Security exit user data U U U U U U U U
Send exit U U U U U U U
Send exit user data U U U U U U U U
Sequence number wrap U U U U U U
Short retry interval U U U U
Short retry count U U U U
Transport type U U U U U U
Transmission queue U U
User ID U U U U U

Channel functions
The channel functions available are shown in Table 7 on page 106. Here some more
detail is given about the channel functions.

112 MQSeries Intercommunication

 Channel functions
Create
You can create a new channel definition using the default values supplied by
MQSeries, specifying the name of the channel, the type of channel you are
creating, the communication method to be used, the transmission queue name and
the connection name.

The channel name must be the same at both ends of the channel, and unique
within the network. However, you should restrict the characters used to those that
are valid for MQSeries object names.

Change
Use the MQSC command ALTER CHANNEL to change an existing channel
definition, except for the channel name, or channel type.

Delete
Use the MQSC command DELETE CHANNEL to delete a named channel.

Display
Use the MQSC command DISPLAY CHANNEL to display the current definition
for the channel.

Display Status
The MQSC command DISPLAY CHSTATUS displays the status of a channel
whether the channel is active or inactive. It applies to all message channels. It does
not apply to MQI channels other than server-connection channels on V5.1 of
MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT. See
“Displaying channel status” on page 110.

Information displayed includes:

v Channel name
v Communication connection name
v In-doubt status of channel (where appropriate)
v Last sequence number
v Transmission queue name (where appropriate)
v The in-doubt identifier (where appropriate)
v The last committed sequence number
v Logical unit of work identifier
v Process ID
v Thread ID (OS/2 and Windows NT only)

Ping
Use the MQSC command PING CHANNEL to exchange a fixed data message with
the remote end. This gives some confidence to the system supervisor that the link
is available and functioning.

Ping does not involve the use of transmission queues and target queues. It uses
channel definitions, the related communication link, and the network setup. It can
only be used if the channel is not currently active.

It is available from sender and server channels only. The corresponding channel is
started at the far side of the link, and performs the startup parameter negotiation.
Errors are notified normally.

The result of the message exchange is presented as Ping complete or an error

message.

Chapter 8. Monitoring and controlling channels on distributed platforms 113

 Channel functions
Ping with LU 6.2: When Ping is invoked, by default no USERID or password
flows to the receiving end. If USERID and password are required, they can be
created at the initiating end in the channel definition. If a password is entered into
the channel definition, it is encrypted by MQSeries before being saved. It is then
decrypted before flowing across the conversation.

Start
Use the MQSC command START CHANNEL for sender, server, and requester
channels. It should not be necessary where a channel has been set up with queue
manager triggering.

Also use the START CHANNEL command for receiver channels that have a
disabled status, and on V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris,
and Windows NT, for server-connection channels that have a disabled status.
Starting a receiver or server-connection channel that is in disabled status resets the
channel and allows it to be started from the remote channel.

When started, the sending MCA reads the channel definition file and opens the
transmission queue. A channel start-up sequence is executed, which remotely starts
the corresponding MCA of the receiver or server channel. When they have been
started, the sender and server processes await messages arriving on the
transmission queue and transmit them as they arrive.

When you use triggering or run channels as threads, you will need to start the
channel initiator to monitor the initiation queue. Use the runmqchi command for
this.

However, TCP and LU 6.2 do provide other capabilities:

v For TCP on OS/2, Digital OpenVMS, and UNIX systems, inetd (or an equivalent
TCP/IP service on OpenVMS) can be configured to start a channel. This will be
started as a separate process.
v For LU 6.2 in OS/2, using Communications Manager/2 it is possible to
configure the Attach Manager to start a channel. This will be started as a
separate process.
v For LU 6.2 in UNIX systems, configure your SNA product to start the LU 6.2
responder process.
v For LU 6.2 in Windows NT, using SNA Server you can use TpStart (a utility
provided with SNA Server) to start a channel. This will be started as a separate
process.
v For LU 6.2 in Digital OpenVMS systems, use the runmqlsr command to start the
LU 6.2 responder process.
| v For LU 6.2 in Tandem NSK, the strmqm command normally starts the LU 6.2
| responder process if your channel is defined AUTOSTART (ENABLED). To start
| the process manually, use the runmqsc or runmqchl command.

Use of the Start option always causes the channel to re-synchronize, where
necessary.

For the start to succeed:

v Channel definitions, local and remote, must exist. If there is no appropriate
channel definition for a receiver or server-connection channel, a default one is
created automatically if the channel is auto-defined. See “Channel
auto-definition exit program” on page 516.
v Transmission queue must exist, and have no other channels using it.

114 MQSeries Intercommunication

 Channel functions
v MCAs, local and remote, must exist.
v Communication link must be available.
v Queue managers must be running, local and remote.
v Message channel must not be already running.

A message is returned to the screen confirming that the request to start a channel
has been accepted. For confirmation that the start command has succeeded, check
the error log, or use DISPLAY CHSTATUS. The error logs are:
OS/2 and Windows NT
\mqm\qmgrs\qmname\errors\AMQERR01.LOG (for each queue manager called
qmname)
\mqm\qmgrs\@SYSTEM\errors\AMQERR01.LOG (for general errors)

Note: On Windows NT, you still also get a message in the Windows NT
application event log.
Digital OpenVMS
MQS_ROOT:[MQM.QMGRS.QMNAME.ERRORS]AMQERR01.LOG (for each queue
manager called qmname)
MQS_ROOT:[MQM.QMGRS.$SYSTEM.ERRORS]AMQERR01.LOG (for general errors)
Tandem NSK
The location of the error logs depends on whether the queue manager
name is known and whether the error is associated with a client.
v If the queue manager name is known and the queue manager is
available:
<QMVOL>.<SUBVOL>L.MQERRLG1
v If the queue manager is not available:
<MQSVOL>.ZMQSSYS.MQERRLG1
UNIX systems
/var/mqm/qmgrs/qmname/errors/AMQERR01.LOG (for each queue manager
called qmname)
/var/mqm/qmgrs/@SYSTEM/errors/AMQERR01.LOG (for general errors)

Stop
Use the MQSC command STOP CHANNEL to request the channel to stop activity.
Any channel type is disabled by this command. The channel will not start a new
batch of messages until the operator starts the channel again. (For information
about restarting stopped channels, see “Restarting stopped channels” on page 69.)

You can select the type of stop you require:

Stop quiesce example:

STOP CHANNEL(QM1.TO.QM2) MODE(QUIESCE)

This command requests the channel to close down in an orderly way. The current
batch of messages is completed and the syncpoint procedure is carried out with
the other end of the channel.

Note: If the channel is idle this command will not terminate a receiving channel.

Stop force example:

STOP CHANNEL(QM1.TO.QM2) MODE(FORCE)

Chapter 8. Monitoring and controlling channels on distributed platforms 115

Channel functions
Normally, this option should not be used. It terminates the channel process or
thread. The channel does not complete processing the current batch of messages,
and can, therefore, leave the channel in doubt. In general, it is recommended that
operators use the quiesce stop option.

Reset
Use the MQSC command RESET CHANNEL to change the message sequence
number. This command is available for any message channel, but not for MQI
channels (client-connection or server-connection). The first message starts the new
sequence the next time the channel is started.

If the command is issued on a sender or server channel, it informs the other side
of the change when the channel is restarted.

Resolve
Use the MQSC command RESOLVE CHANNEL when messages are held in-doubt
by a sender or server, for example because one end of the link has terminated, and
there is no prospect of it recovering. The RESOLVE CHANNEL command accepts
one of two parameters: BACKOUT or COMMIT. Backout restores messages to the
transmission queue, while Commit discards them.

The channel program does not try to establish a session with a partner. Instead, it
determines the logical unit of work identifier (LUWID) which represents the
in-doubt messages. It then issues, as requested, either:
v BACKOUT to restore the messages to the transmission queue; or
v COMMIT to delete the messages from the transmission queue.

For the resolution to succeed:

v The channel must be inactive
v The channel must be in doubt
v The channel type must be sender or server
v A local channel definition must exist
v The local queue manager must be running

116 MQSeries Intercommunication

 Chapter 9. Preparing MQSeries for distributed platforms
This chapter describes the MQSeries preparations required before DQM can be
used in OS/2, Windows NT, Digital OpenVMS, Tandem NSK, and UNIX systems.
It includes “Transmission queues and triggering” and “Channel programs” on
page 119.

Transmission queues and triggering

Before a channel (other than a requester channel) can be started, the transmission
queue must be defined as described in this chapter, and must be included in the
message channel definition.

In addition, where needed, the triggering arrangement must be prepared with the
definition of the necessary processes and queues.

Creating a transmission queue

Define a local queue with the USAGE attribute set to XMITQ for each sending
message channel. If you want to make use of a specific transmission queue in your
remote queue definitions, create a remote queue as shown below.

To create a transmission queue, use the MQSeries Commands (MQSC), as shown

in the following examples:
Create transmission queue example
DEFINE QLOCAL(QM2) DESCR('Transmission queue to QM2') USAGE(XMITQ)
Create remote queue example
DEFINE QREMOTE(PAYROLL) DESCR('Remote queue for QM2') +
XMITQ(QM2) RNAME(PAYROLL) RQMNAME(QM2)

The recommended name for the transmission queue is the queue manager name
on the remote system, as shown in the examples above.

Triggering channels
An overview of triggering is given in “Triggering channels” on page 20, while it is
described in depth in the MQSeries Application Programming Guide. This description
provides you with information specific to MQSeries for OS/2 Warp, Windows NT,
Digital OpenVMS, Tandem NSK, and UNIX systems.

You can create a process definition in MQSeries, defining processes to be triggered.

Use the MQSC command DEFINE PROCESS to create a process definition naming
the process to be triggered when messages arrive on a transmission queue. The
USERDATA attribute of the process definition should contain the name of the
channel being served by the transmission queue.

| Alternatively, for V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT, you can eliminate the need for a process definition by specifying the
| channel name in the TRIGGERDATA attribute of the transmission queue.

If you do not specify a channel name, the channel initiator searches the channel
definition files until it finds a channel that is associated with the named
transmission queue.

© Copyright IBM Corp. 1993, 2000 117

 Transmission queues and triggering
Example definitions for triggering
Define the local queue (Q3), specifying that trigger messages are to be written to
the default initiation queue SYSTEM.CHANNEL.INITQ, to trigger the application
(process P1) that starts channel (QM3.TO.QM4):
DEFINE QLOCAL(QM4) TRIGGER INITQ(SYSTEM.CHANNEL.INITQ) PROCESS(P1) USAGE (XMITQ)

Define the application (process P1) to be started:

DEFINE PROCESS(P1) USERDATA(QM3.TO.QM4)

Examples for V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun
Solaris, and Windows NT
Define the local queue (Q3), specifying that trigger messages are to be written to
the initiation queue (IQ) to trigger the application that starts channel
(QM3.TO.QM4):
DEFINE QLOCAL(QM4) TRIGGER INITQ(SYSTEM.CHANNEL.INITQ) USAGE (XMITQ)

Starting the channel initiator

| Triggering is implemented using the channel initiator process. On MQSeries for
| AT&T, Digital OpenVMS, SINIX and DC/OSx, and Tandem NSK, this process is
| started with the run channel initiator command, runmqchi, or (on distributed
| platforms except Tandem NSK) with the MQSC command START CHINIT. For
| example, to use the runmqchi command to start the default initiation queue for
| the default queue manager, enter:
| runmqchi

| Whichever command you use, specify the name of the initiation queue on the
| command, unless you are using the default initiation queue. For example, to use
| the runmqchi command to start queue IQ for the default queue manager, enter:
| runmqchi -q IQ

| To use the START CHINIT command (not on Tandem NSK), enter:

START CHINIT INITQ(IQ)

| Note: Tandem NSK also allows control of the channel initiator from the PATHWAY
| environment. This is the recommended method. For more information about
| this, see the MQSeries for Tandem NonStop Kernel System Management Guide.

| In V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT, a
| channel initiator is started automatically and the number of channel initiators that
| you can start is limited. The default limit is 3. You can change this using
| MAXINITIATORS in the qm.ini file for AIX, HP-UX, OS/2 Warp, and Sun Solaris,
| and in the registry for Windows NT.

| See the MQSeries System Administration book for V5.1 of MQSeries for AIX, HP-UX,
| OS/2 Warp, Sun Solaris, and Windows NT, or the MQSeries System Management
| Guide for your platform, for details of the run channel initiator command, and the
| other control commands.

| Stopping the channel initiator

| The default channel initiator is started automatically when you start a queue
| manager. Similarly, it is stopped automatically when a queue manager is stopped.

| However, if you need to stop a channel initiator but not the queue manager, you
| should inhibit the queue that the initiator queue is reading from. To do this, you
| disable the GET attribute of the initiation queue. To restart the channel initiator,
| simply use the runmqchi command.

118 MQSeries Intercommunication

 Transmission queues and triggering
| The consequences of stopping a channel initiator are:
| v If you stop the only channel initiator running, no channels that you have
| attempted to start will be retried.
| v If you have more than one channel initiator running, channels that have a
| transmission queue configured with this initiation queue are not automatically
| started. However, those channels configured for connection retries will continue
| to be retried.
|
Channel programs
There are different types of channel programs (MCAs) available for use at the
channels. The names are shown in the following tables.
Table 9. Channel programs for OS/2 and Windows NT
Program name Direction of connection Communication
RUNMQLSR Inbound Any
ENDMQLSR Any
AMQCRS6A Inbound LU 6.2
AMQCRSTA Inbound TCP
RUNMQCHL Outbound Any
RUNMQCHI Outbound Any

Table 10. Channel programs for UNIX systems, Digital OpenVMS, and Tandem NSK
Program name Direction of connection Communication
amqcrs6a (MQLU6RES on Inbound LU 6.2
Tandem NSK only)
amqcrsta (MQTCPRES (on Inbound TCP and DECnet for Digital
Tandem NSK only) OpenVMS
runmqchl Outbound TCP for UNIX systems
runmqlsr Inbound LU 6.2 for Digital OpenVMS
and Tandem NSK and TCP
for UNIX systems
runmqchi Outbound Any

RUNMQLSR (Run MQSeries listener), ENDMQLSR (End MQSeries listener), and

RUNMQCHL (Run MQSeries channel) are control commands that you can enter at
the command line. AMQCRS6A and AMQCRSTA are programs that, if you are
using SNA, you define as transaction programs, or, if you are using TCP, you
define in the INETD.LST file for OS/2 or Windows NT or the inetd.conf file for
UNIX systems. Examples of the use of these channel programs are given in the
following chapters.

Other things to consider

Here are some other topics that you should consider when preparing MQSeries for
distributed queue management.

Undelivered-message queue
| A DLQ handler is provided with MQSeries for OS/2 Warp and Windows NT, and
| with MQSeries on UNIX systems, Digital OpenVMS, and Tandem NSK. See the

Chapter 9. Preparing MQSeries for distributed platforms 119

 Other things to consider
| MQSeries System Administration book for V5.1 of MQSeries for AIX, HP-UX, OS/2
| Warp, Sun Solaris, and Windows NT, or the MQSeries System Management Guide for
| your platform, for information about this.

Queues in use
MCAs for receiver channels may keep the destination queues open even when
messages are not being transmitted; this results in the queues appearing to be “in
use”.

Multiple message channels per transmission queue

It is possible to define more than one channel per transmission queue, but only
one of these channels can be active at any one time. This is recommended for the
provision of alternative routes between queue managers for traffic balancing and
link failure corrective action.

Security of MQSeries objects

This section deals with remote messaging aspects of security.

You need to provide users with authority to make use of the MQSeries facilities,
and this is organized according to actions to be taken with respect to objects and
definitions. For example:
v Queue managers can be started and stopped by authorized users
v Applications need to connect to the queue manager, and have authority to make
use of queues
v Message channels need to be created and controlled by authorized users
v Objects are kept in libraries, and access to these libraries may be restricted

The message channel agent at a remote site needs to check that the message being
delivered originated from a user with authority to do so at this remote site. In
addition, as MCAs can be started remotely, it may be necessary to verify that the
remote processes trying to start your MCAs are authorized to do so. There are
three possible ways for you to deal with this:
1. Specify PUTAUT=CTX in the channel definition to indicate that messages must
contain acceptable context authority, otherwise they will be discarded.
2. Implement user exit security checking to ensure that the corresponding message
channel is authorized. The security of the installation hosting the corresponding
channel ensures that all users are properly authorized, so that you do not need
to check individual messages.
3. Implement user exit message processing to ensure that individual messages are
vetted for authorization.

On UNIX systems, Digital OpenVMS, and Tandem NSK

Administration users must be part of the mqm group on your system (including
root) if this ID is going to use MQSeries administration commands. In Digital
OpenVMS, the user must hold the mqm identifier.

You should always run amqcrsta as the “mqm” user ID.

User IDs on UNIX systems, Digital OpenVMS: In Digital OpenVMS, all user IDs
are displayed in uppercase. The queue manager converts all uppercase or mixed
case user identifiers into lowercase, before inserting them into the context part of a
message, or checking their authorization. All authorizations should therefore be
based only on lowercase identifiers.

120 MQSeries Intercommunication

 Other things to consider
On Windows NT
Administration users must be part of both the mqm group and the administrators
group on your Windows NT system if this ID is going to use MQSeries
administration commands.

User IDs on Windows NT systems: On Windows NT, if there is no message exit

installed, the queue manager converts any uppercase or mixed case user identifiers
into lowercase, before inserting them into the context part of a message, or
checking their authorization. All authorizations should therefore be based only on
lowercase identifiers.

User IDs across systems

Platforms other than Windows NT and UNIX systems use uppercase characters for
user IDs. To allow Windows NT and UNIX systems to use lowercase user IDs, the
following conversions are carried out by the message channel agent (MCA) on
these platforms:
At the sending end
The alpha characters in all user IDs are converted to uppercase, if there is
no message exit installed.
At the receiving end
The alpha characters in all user IDs are converted to lowercase, if there is
no message exit installed.

Note that the automatic conversions are not carried out if you provide a message
exit on UNIX systems and Windows NT for any other reason.

User IDs on OS/2

The user identifier service enables queue managers running under OS/2 to obtain
a user-defined user ID. This is described in the MQSeries Programmable System
Management book.

System extensions and user-exit programs

A facility is provided in the channel definition to allow extra programs to be run at
defined times during the processing of messages. These programs are not supplied
with MQSeries, but may be provided by each installation according to local
requirements.

In order to run, these user-exit programs must have predefined names and be
available on call to the channel programs. The names of the user-exit programs are
included in the message channel definitions.

There is a defined control block interface for handing over control to these
programs, and for handling the return of control from these programs.

The precise places where these programs are called, and details of control blocks
and names, are to be found in “Part 7. Further intercommunication considerations”
on page 503.

Running channels and listeners as trusted applications

If performance is an important consideration in your environment and your
environment is stable, you can choose to run your channels and listeners as
trusted, that is, using the fastpath binding. There are two factors that influence
whether or not channels and listeners run as trusted.

Chapter 9. Preparing MQSeries for distributed platforms 121

Other things to consider
v The environment variable MQ_CONNECT_TYPE=FASTPATH or
MQ_CONNECT_TYPE=STANDARD. This is case sensitive. If you specify a
value that is not valid it is ignored.
v MQIBindType in the Channels stanza of the qm.ini or registry file. You can set
this to FASTPATH or STANDARD and it is not case sensitive. The default is
STANDARD.

You can use MQIBindType in association with the environment variable to achieve
the desired affect as follows:

MQIBindType Environment variable Result

STANDARD UNDEFINED STANDARD
FASTPATH UNDEFINED FASTPATH
STANDARD STANDARD STANDARD
FASTPATH STANDARD STANDARD
STANDARD FASTPATH STANDARD
FASTPATH FASTPATH FASTPATH

In summary, there are only two ways of actually making channels and listeners
run as trusted:
1. By specifying MQIBindType=FASTPATH in qm.ini or registry and not
specifying the environment variable.
2. By specifying MQIBindType=FASTPATH in qm.ini or registry and setting the
environment variable to FASTPATH.

You are recommended to run channels and listeners as trusted only in a stable
environment in which you are not, for example, testing applications or user exits
that may abend or need to be cancelled. An errant application could compromise
the integrity of your queue manager. However, if your environment is stable and if
performance is an important issue, you may choose to run channels and listeners
as trusted.

Note: If you are using MQSeries for Compaq (DIGITAL) OpenVMS the option on
the MQ_CONNECT_TYPE is FAST, not FASTPATH.

What next?
When you have made the preparations described in this chapter you are ready to
set up communications. Proceed to one of the following chapters, depending on
what platform you are using:
v “Chapter 10. Setting up communication for OS/2 and Windows NT” on
page 123
v “Chapter 13. Setting up communication in UNIX systems” on page 191
v “Chapter 19. Setting up communication in Digital OpenVMS systems” on
page 277
v “Chapter 20. Setting up communication in Tandem NSK” on page 289

122 MQSeries Intercommunication

Chapter 10. Setting up communication for OS/2 and
Windows NT
DQM is a remote queuing facility for MQSeries. It provides channel control
programs for the queue manager which form the interface to communication links,
controllable by the system operator. The channel definitions held by
distributed-queuing management use these connections.

When a distributed-queuing management channel is started, it tries to use the

connection specified in the channel definition. For this to succeed, it is necessary
for the connection to be defined and available. This chapter explains how to do
this. You may also find it helpful to refer to “Chapter 11. Example configuration -
IBM MQSeries for OS/2 Warp” on page 137 or “Chapter 12. Example configuration
- IBM MQSeries for Windows NT” on page 169.

For UNIX systems see “Chapter 13. Setting up communication in UNIX systems”
on page 191. For Digital OpenVMS, see “Chapter 19. Setting up communication in
Digital OpenVMS systems” on page 277.

Deciding on a connection
There are four forms of communication for MQSeries for OS/2 Warp and
Windows NT:
v TCP
v LU 6.2
v NetBIOS
v SPX

Each channel definition must specify only one protocol as the Transmission
protocol (Transport Type) attribute. One or more protocols may be used by a queue
manager.

For MQSeries clients, it may be useful to have alternative channels using different
transmission protocols. See the MQSeries Clients book.

© Copyright IBM Corp. 1993, 2000 123

Defining a TCP connection

Defining a TCP connection

The channel definition at the sending end specifies the address of the target. A
listener program must be run at the receiving end.

Sending end
Specify the host name, or the TCP address of the target machine, in the Connection
name field of the channel definition. The port to connect to will default to 1414.
Port number 1414 is assigned by the Internet Assigned Numbers Authority to
MQSeries.

To use a port number other than the default, change the connection name field
thus:
Connection Name OS2ROG3(1822)

where 1822 is the port required. (This must be the port that the listener at the
receiving end is listening on.)

You can change the default port number by specifying it in the queue manager
configuration file (qm.ini) for MQSeries for OS/2 Warp and the registry for
MQSeries for Windows NT:
TCP:
Port=1822

For more information about the values you set using qm.ini, see “Appendix D.
Configuration file stanzas for distributed queuing” on page 637.

Receiving on TCP
Receiving channel programs are started in response to a startup request from the
sending channel. To do this, a listener program has to be started to detect incoming
network requests and start the associated channel.

You should use either the TCP/IP listener (INETD) (not for Windows NT) or the
MQSeries listener.

Using the TCP/IP listener

To use INETD to start channels on OS/2, two files must be configured:
1. Add a line in the TCPIP\ETC\SERVICES file:
MQSeries 1414/tcp

where 1414 is the port number required for MQSeries. You can change this but
it must match the port number specified at the sending end.
2. Add a line to the TCPIP\ETC\INETD.LST file:
MQSeries tcp C:\MQM\BIN\AMQCRSTA [-m QMName]

The last part in square brackets is optional and is not required for the default
queue manager. If your MQSeries for OS/2 Warp is installed on a different
drive, replace the C: above with the correct drive letter.

It is possible to have more than one queue manager on the machine. You must add
a line to each of the two files, as above, for each of the queue managers. For
example:
MQSeries2 1822/tcp

124 MQSeries Intercommunication

 Defining a TCP connection
Now stop, and then start the inetd program, before continuing.

Using the TCP listener backlog option

When receiving on TCP, a maximum number of outstanding connection requests is
set. This can be considered a backlog of requests waiting on the TCP port for the
listener to accept the request. The default listener backlog values are shown in
Table 11.
Table 11. Default outstanding connection requests on OS/2 and Windows NT
Platform Default listener backlog value
OS/2 Warp 10
Windows NT Server 100
Windows NT Workstation 5

If the backlog reaches the values shown in Table 11, the TCP/IP connection is
rejected and the channel will not be able to start.

For MCA channels, this results in the channel going into a RETRY state and
retrying the connection at a later time.

For client connections, the client receives an MQRC_Q_MGR_NOT_AVAILABLE

reason code from MQCONN and should retry the connection at a later time.

However, to avoid this error, you can add an entry in the qm.ini file or in the
registry for Windows NT:
TCP:
ListenerBacklog = n

This overrides the default maximum number of outstanding requests (see Table 11)
for the TCP/IP listener.

Note: Some operating systems support a larger value than the default. If necessary,
this can be used to avoid reaching the connection limit.

To run the listener with the backlog option switched on, use the RUNMQLSR -B
command. For information about the RUNMQLSR command, see the MQSeries System
Administration book.

Using the MQSeries listener

To run the Listener supplied with MQSeries, that starts new channels as threads,
use the RUNMQLSR command. For example:
RUNMQLSR -t tcp [-m QMNAME] [-p 1822]

The square brackets indicate optional parameters; QMNAME is not required for the
default queue manager, and the port number is not required if you are using the
default (1414).

For the best performance, run the MQSeries listener as a trusted application as
described in “Running channels and listeners as trusted applications” on page 121.
See the MQSeries Application Programming Guide for information about trusted
applications.

You can stop all MQSeries listeners running on a queue manager that is inactive,
using the command:

Chapter 10. Setting up communication for OS/2 and Windows NT 125

Defining a TCP connection
ENDMQLSR [-m QMNAME]

If you do not specify a queue manager name, the default queue manager is
assumed.

Using the TCP/IP SO_KEEPALIVE option

If you want to use the SO_KEEPALIVE option (as discussed in “Checking that the
other end of the channel is still available” on page 66) you need to add the
following entry to your queue manager configuration file (qm.ini):
TCP:
KeepAlive=yes

If you are using OS/2, you must then issue the following command:
inetcfg keepalive=value

where value is the time interval in minutes.

On Windows NT, the TCP configuration registry value for KeepAliveTime controls
the interval that elapses before the connection will be checked. The default is two
hours. For information about changing this value, see the Microsoft article TCP/IP
and NBT Configuration Parameters for Windows NT 3.5 (PSS ID number Q120642).

Defining an LU 6.2 connection

SNA must be configured so that an LU 6.2 conversation can be established
between the two machines. Then proceed as follows.

See the Multiplatform APPC Configuration Guide for OS/2 examples, and the
following table for information.
Table 12. Settings on the local OS/2 or Windows NT system for a remote queue manager
platform
Remote platform TPNAME TPPATH
OS/390 or The same as in the corresponding -
MVS/ESA side information on the remote
without CICS queue manager.
OS/390 or CKRC (sender) CKSV (requester) -
MVS/ESA using CKRC (server)
CICS
OS/400 The same as the compare value in -
the routing entry on the OS/400
system.
OS/2 As specified in the OS/2 Run <drive>:\mqm\bin\amqcrs6a
Listener command, or defaulted
from the OS/2 queue manager
configuration file.
UNIX systems The same as in the corresponding mqmtop/bin/amqcrs6a
side information on the remote
queue manager.
Windows NT As specified in the Windows NT <drive>:\mqm\bin\amqcrs6a
Run Listener command, or the
invokable Transaction Program
that was defined using TpSetup on
Windows NT.

126 MQSeries Intercommunication

 Defining an LU 6.2 connection
If you have more than one queue manager on the same machine, ensure that the
TPnames in the channel definitions are unique.

Sending end for OS/2

Establish a valid session between the two machines. The local LU that MQSeries
uses is decided in the following order:
1. Specify the LU that will be used. In the queue manager configuration file
(qm.ini), under the LU 6.2 section add the line:
LOCALLU = Your_LU_Name

For more information about the values you set using qm.ini, see “Appendix D.
Configuration file stanzas for distributed queuing” on page 637.
2. Specify the environment variable:
APPNLLU = Your_LU_Name
3. If this has not been specified, your default LU will be used.

When you define an MQSeries channel that will use the LU 6.2 connection, the
Connection name (CONNAME) channel attribute specifies the fully-qualified name
of the partner LU. as defined in the local Communications Manager/2 profile.

SECURITY PROGRAM is always used when MQSeries attempts to establish an

SNA session.

Sending end for Windows NT

Create a CPI-C side object (symbolic destination) from the administration
application of the LU 6.2 product you are using, and enter this name in the
Connection name field in the channel definition. Also create an LU 6.2 link to the
partner.

In the CPI-C side object enter the partner LU Name at the receiving machine, the
TP Name and the Mode Name. For example:
Partner LU Name OS2ROG2
Partner TP Name recv
Mode Name #INTER

Receiving on LU 6.2
Receiving channel programs are started in response to a startup request from the
sending channel. To do this, a listener program has to be started to detect incoming
network requests and start the associated channel. You start this listener program
with the RUNMQLSR command, giving the TpName to listen on. Alternatively,
you can use Attach Manager in Communications Manager/2 for OS/2, or TpStart
under SNA Server for Windows NT.

Using the RUNMQLSR command

Example of the command to start the listener:
RUNMQLSR -t LU62 -n RECV [-m QMNAME]

where RECV is the TpName that is specified at the other (sending) end as the
“TpName to start on the remote side”. The last part in square brackets is optional
and is not required for the default queue manager.

It is possible to have more than one queue manager running on one machine. You
must assign a different TpName to each queue manager, and then start a listener
program for each one. For example:

Chapter 10. Setting up communication for OS/2 and Windows NT 127

Defining an LU 6.2 connection
RUNMQLSR -t LU62 -m QM1 -n TpName1
RUNMQLSR -t LU62 -m QM2 -n TpName2

For the best performance, run the MQSeries listener as a trusted application as
described in “Running channels and listeners as trusted applications” on page 121.
See the MQSeries Application Programming Guide for information about trusted
applications.

You can stop all MQSeries listeners running on a queue manager that is inactive,
using the command:
ENDMQLSR [-m QMNAME]

If you do not specify a queue manager name, the default queue manager is
assumed.

Using Communications Manager/2 on OS/2

If you are going to use Attach Manager in Communications Manager/2 to start the
listener program, you must specify the Program parameter string or parm_string in
addition to the TPNAME and TPPATH.

You can do this using the panel configuration in Communications Manager/2 or,
alternatively, you can edit your NDF file directly (see the heading “Define
Transaction Programs” in the Multiplatform APPC Configuration Guide).

Panel configuration: These are the entries required on the TP definition panel:
Transaction Program (TP) name : AMQCRS6A
OS/2 program path and file name: c:\mqm\bin\amqcrs6a.exe
Program parameter string : -n AMQCRS6A

NDF file configuration: Your node definitions file (.ndf) must contain a define_tp
command. The following example shows what must be included:
define_tp
tp_name(AMQCRS6A)
filespec(c:\mqm\bin\amqcrs6a.exe)
parm_string(-n AMQCRS6A -m QM1)

Using Microsoft SNA Server on Windows NT

You can use TpSetup (from the SNA Server SDK) to define an invokable TP that
then drives amqcrs6a.exe, or you can set various registry values manually. The
parameters that should be passed to amqcrs6a.exe are:
-m QM -n TpName

where QM is the Queue Manager name and TpName is the TP Name. See the
Microsoft SNA Server APPC Programmers Guide or the Microsoft SNA Server CPI-C
Programmers Guide for more information.

Defining a NetBIOS connection

MQSeries uses three types of NetBIOS resource when establishing a NetBIOS
connection to another MQSeries product: sessions, commands, and names. Each of
these resources has a limit, which is established either by default or by choice
during the installation of NetBIOS.

Each running channel, regardless of type, uses one NetBIOS session and one
NetBIOS command. The IBM NetBIOS implementation allows multiple processes
to use the same local NetBIOS name. Therefore, only one NetBIOS name needs to
be available for use by MQSeries. Other vendors’ implementations, for example

128 MQSeries Intercommunication

 Defining a NetBIOS connection
Novell’s NetBIOS emulation, require a different local name per process. Verify your
requirements from the documentation for the NetBIOS product you are using.

In all cases, ensure that sufficient resources of each type are already available, or
increase the maximums specified in the configuration. Any changes to the values
will require a system restart.

During system startup, the NetBIOS device driver displays the number of sessions,
commands, and names available for use by applications. These resources are
available to any NetBIOS-based application that is running on the same system.
Therefore, it is possible for other applications to consume these resources before
MQSeries needs to acquire them. Your LAN network administrator should be able
to clarify this for you.

Defining the MQSeries local NetBIOS name

The local NetBIOS name used by MQSeries channel processes can be specified in
three ways. In order of precedence they are:
1. The value specified in the -l parameter of the RUNMQLSR command, for
example:
RUNMQLSR -t NETBIOS -l my_station
2. The MQNAME environment variable whose value is established by the
command:
SET MQNAME=my_station

You can set the MQNAME value for each process. Alternatively, you may set it
at a system level — in the CONFIG.SYS file on OS/2 or in the Windows NT
registry.

If you are using a NetBIOS implementation that requires unique names, you
must issue a SET MQNAME command in each window in which an MQSeries
process is started. The MQNAME value is arbitrary but it must be unique for
each process.
3. The NETBIOS stanza in the queue manager configuration file qm.ini or in the
Windows NT registry. For example:
NETBIOS:

LocalName=my_station
Notes:
1. Due to the variations in implementation of the NetBIOS products supported,
you are advised to make each NetBIOS name unique in the network. If you do
not, unpredictable results may occur. If you have problems establishing a
NetBIOS channel and there are error messages in the queue-manager error log
showing a NetBIOS return code of X'15', review your use of NetBIOS names.
2. On Windows NT you cannot use your machine name as the NetBIOS name
because Windows NT already uses it.
3. Sender channel initiation requires that a NetBIOS name be specified either via
the MQNAME environment variable or the LocalName in the qm.ini file or in
the Windows NT registry.

Chapter 10. Setting up communication for OS/2 and Windows NT 129

Defining a NetBIOS connection
Establishing the queue manager NetBIOS session, command,
and name limits
The queue manager limits for NetBIOS sessions, commands, and names can be
specified in two ways. In order of precedence they are:
1. The values specified in the RUNMQLSR command:
-s Sessions
-e Names
-o Commands

If the -m operand is not specified in the command, the values will apply only
to the default queue manager.
2. The NETBIOS stanza in the queue manager configuration file qm.ini or in the
Windows NT registry. For example:
NETBIOS:

NumSess=Qmgr_max_sess
NumCmds=Qmgr_max_cmds
NumNames=Qmgr_max_names

Establishing the LAN adapter number

For channels to work successfully across NetBIOS, the adapter support at each end
must be compatible. MQSeries allows you to control the choice of adapter number
(lana) by using the AdapterNum value in the NETBIOS stanza of your qm.ini file
or the Windows NT registry and by specifying the -a parameter on the runmqlsr
command.

The default LAN adapter number used by MQSeries for NetBIOS connections is 0.
Verify the adapter number being used on your system as follows:

On OS/2 the adapter number used by NetBIOS on your system can be viewed in
the PROTOCOL.INI file or the LANTRAN.LOG file found in the \IBMCOM
directory.

On Windows NT view the information displayed in the NetBIOS Interface pop-up

window. This is accessible by selecting the Network option, which is one of many
options displayed when opening the Control icon from the Main Window.
Windows NT can assign multiple ‘logical’ adapter numbers to one physical LAN
adapter. The installation default for ‘logical’ adapter number 0 is NetBIOS running
over a TCP network, not a Token-Ring network. This is not necessary for
MQSeries. You should select logical adapter number 1, which is native NetBIOS.
MQSeries for Windows NT uses the ‘logical’ adapter number for communication.

Specify the correct value in the NETBIOS stanza of the queue manager
configuration file, qm.ini, or the Windows NT registry:
NETBIOS:
AdapterNum=n

where n is the correct LAN adapter number for this system.

Initiating the connection

To initiate the connection, follow these steps at the sending end:
1. Define the NetBIOS station name using the MQNAME or LocalName value as
described above.

130 MQSeries Intercommunication

 Defining a NetBIOS connection
2. Verify the LAN adapter number being used on your system and specify the
correct file using the AdapterNum as described above.
3. In the ConnectionName field of the channel definition, specify the NetBIOS
name being used by the target listener program. On Windows NT, NetBIOS
channels must be run as threads. Do this by specifying MCATYPE(THREAD) in
the channel definition.
DEFINE CHANNEL (chname) CHLTYPE(SDR) +
TRPTYPE(NETBIOS) +
CONNAME(your_station) +
XMITQ(xmitq) +
MCATYPE(THREAD) +
REPLACE

Target listener
At the receiving end, follow these steps:
1. Define the NetBIOS station name using the MQNAME or LocalName value as
described above.
2. Verify the LAN adapter number being used on your system and specify the
correct file using the AdapterNum as described above.
3. Define the receiver channel:
DEFINE CHANNEL (chname) CHLTYPE(RCVR) +
TRPTYPE(NETBIOS) +
REPLACE
4. Start the MQSeries listener program to establish the station and make it
possible to contact it. For example:
RUNMQLSR -t NETBIOS -l your_station [-m qmgr]

This command establishes your_station as a NetBIOS station waiting to be

contacted. The NetBIOS station name must be unique throughout your
NetBIOS network.

For the best performance, run the MQSeries listener as a trusted application as
described in “Running channels and listeners as trusted applications” on page 121.
See the MQSeries Application Programming Guide for information about trusted
applications.

You can stop all MQSeries listeners running on a queue manager that is inactive,
using the command:
ENDMQLSR [-m QMNAME]

If you do not specify a queue manager name, the default queue manager is
assumed.

Defining an SPX connection

The channel definition at the sending end specifies the address of the target. A
listener program must be run at the receiving end.

Sending end
If the target machine is remote, specify the SPX address of the target machine in
the Connection name field of the channel definition.

The SPX address is specified in the following form:

network.node(socket)

Chapter 10. Setting up communication for OS/2 and Windows NT 131

Defining an SPX connection
where:
network
Is the 4-byte network address of the network on which the remote machine
resides,
node Is the 6-byte node address, which is the LAN address of the LAN adapter
in the remote machine
socket Is the 2-byte socket number on which the remote machine will listen.

If the local and remote machines are on the same network then the network
address need not be specified. If the remote end is listening on the default socket
(5E86) then the socket need not be specified.

An example of a fully specified SPX address specified in the CONNAME

parameter of an MQSC command is:
CONNAME('00000001.08005A7161E5(5E87)')

In the default case, where the machines are both on the same network, this
becomes:
CONNAME(08005A7161E5)

The default socket number may be changed by specifying it in the queue manager
configuration file (qm.ini) or the Windows NT registry:
SPX:
Socket=5E87

For more information about the values you set using qm.ini or the Windows NT
registry, see “Appendix D. Configuration file stanzas for distributed queuing” on
page 637.

Using the SPX KEEPALIVE option (OS/2 only)

If you want to use the KEEPALIVE option (as discussed in “Checking that the
other end of the channel is still available” on page 66) you need to add the
following entry to your queue manager configuration file (qm.ini):
SPX:
KeepAlive=yes

You can use the timeouts described in “IPX/SPX parameters” on page 133 to adjust
the behavior of KEEPALIVE.

Receiving on SPX
Receiving channel programs are started in response to a startup request from the
sending channel. To do this, a listener program has to be started to detect incoming
network requests and start the associated channel.

You should use the MQSeries listener.

Using the TCP listener backlog option

When receiving on TCP/IP, a maximum number of outstanding connection
requests is set. This can be considered a backlog of requests waiting on the TCP/IP
port for the listener to accept the request. The default listener backlog values are
shown in Table 13.
Table 13. Default outstanding connection requests on OS/2 and Windows NT
Platform Default listener backlog value
OS/2 Warp 10

132 MQSeries Intercommunication

 Defining an SPX connection
Table 13. Default outstanding connection requests on OS/2 and Windows NT (continued)
Platform Default listener backlog value
Windows NT Server 100
Windows NT Workstation 5

If the backlog reaches the values in Table 13 on page 132, the reason code,
MQRC_Q_MGR_NOT_AVAILABLE is received when trying to connect to the
queue manager using MQCONN or MQCONNX. If this happens, it is possible to
try to connect again.

However, to avoid this error, you can add an entry in the qm.ini file or in the
registry for Windows NT:
TCP:
ListenerBacklog = n

This overrides the default maximum number of outstanding requests (see Table 13
on page 132) for the TCP/IP listener.

Note: Some operating systems support a larger value than the default. If necessary,
this can be used to avoid reaching the connection limit.

To run the listener with the backlog option switched on, use the RUNMQLSR -B
command. For information about the RUNMQLSR command, see the MQSeries System
Administration book.

Using the MQSeries listener

To run the Listener supplied with MQSeries, that starts new channels as threads,
use the RUNMQLSR command. For example:
RUNMQLSR -t spx [-m QMNAME] [-x 5E87]

The square brackets indicate optional parameters; QMNAME is not required for the
default queue manager, and the socket number is not required if you are using the
default (5E86).

For the best performance, run the MQSeries listener as a trusted application as
described in “Running channels and listeners as trusted applications” on page 121.
See the MQSeries Application Programming Guide for information about trusted
applications.

You can stop all MQSeries listeners running on a queue manager that is inactive,
using the command:
ENDMQLSR [-m QMNAME]

If you do not specify a queue manager name, the default queue manager is
assumed.

IPX/SPX parameters
In most cases the default settings for the IPX/SPX parameters will suit your needs.
However, you may need to modify some of them in your environment to tune its
use for MQSeries. The actual parameters and the method of changing them varies
according to the platform and provider of SPX communications support. The
following sections describe some of these parameters, particularly those that may
influence the operation of MQSeries channels and client connections.

Chapter 10. Setting up communication for OS/2 and Windows NT 133

Defining an SPX connection
OS/2
Please refer to the Novell Client for OS/2 documentation for full details of the use
and setting of NET.CFG parameters.

The following IPX/SPX parameters can be added to the Novell NET.CFG file, and
can affect MQSeries SPX channels and client connections.

IPX:
sockets (range = 9 - 128, default 64)
This specifies the total number of IPX sockets available. MQSeries channels
use this resource, so depending on the number of channels and the
requirements of other IPX/SPX applications, you may need to increase this
value.

SPX:
sessions (default 16)
This specifies the total number of simultaneous SPX connections. Each
MQSeries channel or client connection uses one session. You may need to
increase this value depending on the number of MQSeries channels or
client connections you need to run.
retry count (default = 12)
This controls the number of times an SPX session will resend
unacknowledged packets. MQSeries does not override this value.
verify timeout, listen timeout, and abort timeout (milliseconds)
These timeouts adjust the ‘Keepalive’ behavior. If an SPX sending end does
not receive anything within the ‘verify timeout’ period, it sends a packet to
the receiving end. It then waits for the duration of the ‘listen timeout’ for a
response. If it still does not receive a response, it sends another packet and
expects a response within the ‘abort timeout’ period.

DOS and Windows 3.1 client

Please refer to the Novell Client for DOS and MS Windows documentation for full
details of the use and setting of NET.CFG parameters.

The following IPX/SPX parameters can be added to the Novell NET.CFG file, and
can affect MQSeries SPX channels and client connections.

IPX:
sockets (default = 20)
This specifies the total number of IPX sockets available. MQSeries channels
use this resource, so depending on the number of channels and the
requirements of other IPX/SPX applications, you may need to increase this
value.
retry count
This controls the number of times unacknowledged packets will be resent.
MQSeries does not override this value.

SPX:
connections (default 15)
This specifies the total number of simultaneous SPX connections. Each
MQSeries channel or client connection uses one session. You may need to
increase this value depending on the number of MQSeries channels or
client connections you need to run.

134 MQSeries Intercommunication

 Defining an SPX connection
Windows NT
Please refer to the Microsoft documentation for full details of the use and setting of
the NWLink IPX and SPX parameters. The IPX/SPX parameters are in the
following paths in the registry:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Service\NWLinkSPX\Parameters
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Service\NWLinkIPX\Parameters

Windows 95 and Windows 98

Please refer to the Microsoft documentation for full details of the use and setting of
the IPX and SPX parameters. You access them by selecting Network option in the
control panel, then double-clicking on IPX/SPX Compatible Transport.

Chapter 10. Setting up communication for OS/2 and Windows NT 135

DQM in distributed platforms

136 MQSeries Intercommunication

 Chapter 11. Example configuration - IBM MQSeries for OS/2
Warp
This chapter gives an example of how to set up communication links from
MQSeries for OS/2 Warp to MQSeries products on the following platforms:
v Windows NT
v AIX
| v Digital UNIX
v HP-UX
v AT&T GIS UNIX1
v Sun Solaris
| v OS/400
v OS/390 or MVS/ESA without CICS
v VSE/ESA

First it describes the parameters needed for an LU 6.2 connection, then it guides
you through the following tasks:
v “Establishing an LU 6.2 connection” on page 142
v “Establishing a TCP connection” on page 158
v “Establishing a NetBIOS connection” on page 160
v “Establishing an SPX connection” on page 160

Once the connection is established, you need to define some channels to complete
the configuration. This is described in “MQSeries for OS/2 Warp configuration” on
page 162.

See “Chapter 7. Example configuration chapters in this book” on page 97 for

background information about this chapter and how to use it.

Configuration parameters for an LU 6.2 connection

Table 14 on page 138 presents a worksheet listing all the parameters needed to set
up communication from OS/2 to one of the other MQSeries platforms. The
worksheet shows examples of the parameters, which have been tested in a
working environment, and leaves space for you to fill in your own values. An
explanation of the parameter names follows the worksheet. Use the worksheet in
this chapter in conjunction with the worksheet in the chapter for the platform to
which you are connecting.

This chapter shows how to use the values on the worksheet for:
v “Defining local node characteristics” on page 142
v “Connecting to a peer system” on page 150
v “Connecting to a host system” on page 153
v “Verifying the configuration” on page 157

Configuration worksheet
Use the following worksheet to record the values you will use for this
configuration. Where numbers appear in the Reference column they indicate that
the value must match that in the appropriate worksheet elsewhere in this book.

1. This platform has become NCR UNIX SVR4 MP-RAS, R3.0

© Copyright IBM Corp. 1993, 2000 137

OS/2 and LU 6.2
The examples that follow in this chapter refer back to the values in the ID column
of this table. The entries in the Parameter Name column are explained in
“Explanation of terms” on page 140.
Table 14. Configuration worksheet for Communications Manager/2
ID Parameter Name Reference Example Used User Value
Definition for local node
«1¬ Configuration name EXAMPLE
«2¬ Network ID NETID
«3¬ Local node name OS2PU
«4¬ Local node ID (hex) 05D 12345
«5¬ Local node alias name OS2PU
«6¬ LU name (local) OS2LU
«7¬ Alias (for local LU name) OS2QMGR
«8¬ Local transaction program (TP) name MQSERIES
«9¬ OS/2 program path and file name c:\mqm\bin\amqcrs6a.exe
«10¬ LAN adapter address 10005AFC5D83
Connection to a Windows NT system

The values in this section of the table must match those used in Table 16 on page 170, as indicated.
«11¬ Link name WINNT
«12¬ LAN destination address (hex) «9¬ 08005AA5FAB9
«13¬ Partner network ID «2¬ NETID
«14¬ Partner node name «3¬ WINNTCP
«15¬ LU name «5¬ WINNTLU
«16¬ Alias (for remote LU name) NTQMGR
«17¬ Mode «17¬ #INTER
«18¬ Remote transaction program name «7¬ MQSERIES
Connection to an AIX system

The values in this section of the table must match those used in Table 20 on page 197, as indicated.
«11¬ Link name RS6000
«12¬ LAN destination address (hex) «8¬ 123456789012
«13¬ Partner network ID «1¬ NETID
«14¬ Partner node name «2¬ AIXPU
«15¬ LU name «4¬ AIXLU
«16¬ Alias (for remote LU name) AIXQMGR
«17¬ Mode «17¬ #INTER
«18¬ Remote transaction program name «6¬ MQSERIES
Connection to an HP-UX system

The values in this section of the table must match those used in Table 23 on page 219, as indicated.
«11¬ Link name HPUX
«12¬ LAN destination address (hex) «8¬ 100090DC2C7C
«13¬ Partner network ID «4¬ NETID
«14¬ Partner node name «2¬ HPUXPU
«15¬ LU name «5¬ HPUXLU
«16¬ Alias (for remote LU name) HPUXQMGR
«17¬ Mode «6¬ #INTER
«18¬ Remote transaction program name «7¬ MQSERIES

138 MQSeries Intercommunication

 OS/2 and LU 6.2
Table 14. Configuration worksheet for Communications Manager/2 (continued)
ID Parameter Name Reference Example Used User Value
Connection to an AT&T GIS UNIX system

The values in this section of the table must match those used in Table 25 on page 243, as indicated.
«11¬ Link name GIS
«12¬ LAN destination address (hex) «8¬ 10007038E86B
«13¬ Partner network ID «2¬ NETID
«14¬ Partner node name «3¬ GISPU
«15¬ LU name «4¬ GISLU
«16¬ Alias (for remote LU name) GISQMGR
«17¬ Mode «15¬ #INTER
«18¬ Remote transaction program name «5¬ MQSERIES
Connection to a Sun Solaris system

The values in this section of the table must match those used in Table 27 on page 257, as indicated.
«11¬ Link name SOLARIS
«12¬ LAN destination address (hex) «5¬ 08002071CC8A
«13¬ Partner network ID «2¬ NETID
«14¬ Partner node name «3¬ SOLARPU
«15¬ LU name «7¬ SOLARLU
«16¬ Alias (for remote LU name) SOLQMGR
«17¬ Mode «17¬ #INTER
«18¬ Remote transaction program name «8¬ MQSERIES
Connection to an AS/400 system

The values in this section of the table must match those used in Table 42 on page 460, as indicated.
«11¬ Link name AS400
«12¬ LAN destination address (hex) «4¬ 10005A5962EF
«13¬ Partner network ID «1¬ NETID
«14¬ Partner node name «2¬ AS400PU
«15¬ LU name «3¬ AS400LU
«16¬ Alias (for remote LU name) AS4QMGR
«17¬ Mode «17¬ #INTER
«18¬ Remote transaction program name «8¬ MQSERIES
Connection to an OS/390 or MVS/ESA system without CICS

The values in this section of the table must match those used in Table 36 on page 396, as indicated.
«11¬ Link name HOST0001
«12¬ LAN destination address (hex) «8¬ 400074511092
«13¬ Partner network ID «2¬ NETID
«14¬ Partner node name «3¬ MVSPU
«15¬ LU name «4¬ MVSLU
«16¬ Alias (for remote LU name) MVSQMGR
«17¬ Mode «10¬ #INTER
«18¬ Remote transaction program name «7¬ MQSERIES
Connection to a VSE/ESA system

The values in this section of the table must match those used in Table 44 on page 485, as indicated.
«11¬ Link name HOST0001

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 139
OS/2 and LU 6.2
Table 14. Configuration worksheet for Communications Manager/2 (continued)
ID Parameter Name Reference Example Used User Value
«12¬ LAN destination address (hex) «5¬ 400074511092
«13¬ Partner network ID «1¬ NETID
«14¬ Partner node name «2¬ VSEPU
«15¬ LU name «3¬ VSELU
«16¬ Alias (for remote LU name) VSEQMGR
«17¬ Mode #INTER
«18¬ Remote transaction program name «4¬ MQ01 MQ01

Explanation of terms
«1¬ Configuration name
This is the name of the OS/2 file that will hold the configuration.
If you are adding to or modifying an existing configuration it will be the
name previously specified.
If you are creating a new configuration then you can specify any
8-character name that obeys the normal rules for file naming.
«2¬ Network ID
This is the unique ID of the network to which you are connected. It is an
alphanumeric value and can be 1-8 characters long. The network ID works
with the local node name to uniquely identify a system. Your network
administrator will tell you the value.
«3¬ Local node name
This is the unique Control Point name for this workstation. Your network
administrator will assign this to you.
«4¬ Local node ID (hex)
This is a unique identifier for this workstation. On other platforms it is
often referred to as the exchange ID (XID). Your network administrator will
assign this to you.
«5¬ Local node alias name
This is the name by which your local node will be known within this
workstation. This value is not used elsewhere, but it is recommended that
it be the same as «3¬, the local node name.
«6¬ LU name (local)
An LU manages the exchange of data between systems. The local LU name
is the name of the LU on your system. Your network administrator will
assign this to you.
«7¬ Alias (for local LU name)
The name by which your local LU will be known to your applications. You
choose this name yourself. It can be 1-8 characters long. This value is used
during MQSeries configuration, when entries are added to the qm.ini file.
«8¬ Local transaction program (TP) name
MQSeries applications trying to converse with this workstation will specify
a symbolic name for the program to be run at the receiving end. This will
have been defined on the channel definition at the sender. The TP name is
also used during MQSeries configuration, when entries are added to the
qm.ini file. For simplicity, wherever possible use a transaction program

140 MQSeries Intercommunication

 OS/2 and LU 6.2
name of MQSERIES, or in the case of a connection to VSE/ESA, where the
length is limited to 4 bytes, use MQTP.
See Table 12 on page 126 for more information.
«9¬ OS/2 program path and file name
This is the path and name of the actual program to be run when a
conversation has been initiated with this workstation. The example shown
on the worksheet assumes that MQSeries is installed in the default
directory, c:\mqm. The configuration pairs this name with the symbolic
name «8¬.
«10¬ LAN adapter address
This is the address of your token-ring card. When using the default
address, the exact value can be found in the LANTRAN.LOG file found in
the \IBMCOM directory.
For example:
Adapter 0 is using node address 10005AFC5D83
«11¬ Link name
This is a meaningful symbolic name by which the connection to a partner
node is known. It is used only inside Communications Manager/2 setup
and is specified by you. It can be 1-8 characters in length.
«16¬ Alias (for remote LU name)
This is a value known only on this workstation and is used to represent
the fully qualified partner LU name. You supply the value.
«17¬ Mode
This is the name given to the set of parameters that control the APPC
conversation. This name must be defined at each point in the network
between the local and partner LUs. Your network administrator will assign
this to you.

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 141
Using Communications Manager/2

Establishing an LU 6.2 connection

This section describes how to establish an LU 6.2 connection using
Communications Manager/2 Version 1.11. You may use any of the supported LU
6.2 products for this platform. The panels would look different from those shown
but most of their content would be similar.

Defining local node characteristics

To set up the local node you need to perform these tasks:
1. Configure a DLC.
2. Configure the local node.
3. Add a local LU.
4. Add a transaction program definition.
5. Configure a mode.

To define the local node characteristics:

1. Start the Communications Manager/2 Installation and Setup program by
typing CMSETUP on an OS/2 command line, and pressing Enter.

2. Press OK to continue.

3. Press Setup to create or modify a configuration.

142 MQSeries Intercommunication

 Using Communications Manager/2

4. Specify a name (up to 8-characters) for a new configuration file «1¬, or select
the one that you wish to update. The following examples guide you through
the creation of a new configuration file. Treat them as a guide if you are
modifying an existing configuration.

5. Press Yes.

6. Press Yes.
In this example we set up connections using APPC over Token-ring. The
following screen appears in two stages. When you first see it, highlight the line:
APPC APIs through Token-ring

The complete screen appears as shown below.

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 143
Using Communications Manager/2

7. Press Configure....

Configuring a DLC

1. Complete the values for Network ID («2¬) and Local node name («3¬).
a.
b. Select End node - no network node server.
c. Click on Advanced.

d. Select DLC - Token-ring or other LAN types and press Configure....

144 MQSeries Intercommunication

 Using Communications Manager/2

e. Enter the value for C&SM LAN ID. This should be the same value as the
Network ID entered earlier («2¬).
f. Leave the remaining default values and press OK.

Configuring the local node

1. Select SNA local node characteristics and press Configure....

2. Complete the value for Local node ID (hex) («4¬) using the values in your
configuration worksheet.

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 145
Using Communications Manager/2
3. Press Options...

4. Complete the value for Local node alias name («5¬) and press OK.

5. Press OK.

6. Select SNA features and press Configure....

146 MQSeries Intercommunication

 Using Communications Manager/2
Adding a local LU

1. Select Local LUs and press Create....

2. Complete the fields LU name («6¬) and Alias («7¬).

3. Press OK.

Adding a transaction program definition

1. Select Transaction program definitions and press Create....

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 147
Using Communications Manager/2

2. Complete the values for Transaction program (TP) name («8¬) and OS/2
program path and file name («9¬). If you are going to use Attach Manager to
start the listener program, specify the Program parameter string, for example
-m OS2 -n MQSERIES.
3. Press Continue....

4. Specify that the program is to be run in the Background and that it is to be

Non-queued, Attach Manager started.
5. Press OK.

Configuring a mode

1. Select Modes and #INTER and press Change....

148 MQSeries Intercommunication

 Using Communications Manager/2

2. Ensure that the default values match those shown above and press Cancel.

3. Press Close to close the SNA Features List window.

Local configuration is complete.

The following sections describe how to create connections to other nodes.

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 149
Using Communications Manager/2
Connecting to a peer system
To set up a connection to a peer system the steps are:
1. Adding a peer connection
2. Defining a partner LU

Start from the Communications Manager Profile List panel.

Select SNA connections and press Configure....

Adding a peer connection

1. Select To peer node and press Create....

150 MQSeries Intercommunication

 Using Communications Manager/2
2. Select Token-ring or other LAN types and press Continue....

3. Specify a Link name («11¬) and check Activate at startup.

4. Complete the fields LAN destination address (hex) («12¬), Partner network ID
(«13¬), and Partner node name («14¬).

5. Press Define Partner LUs....

Defining a partner LU

1. Complete the fields Network ID («13¬), LU name («15¬), and Alias («16¬).
2. Press Add.

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 151
Using Communications Manager/2

3. Press OK.

4. Press OK.

5. Press Close.

152 MQSeries Intercommunication

 Using Communications Manager/2

If you have connections to make to other platforms repeat this section as

appropriate.

If you have made all the connections you require proceed to “Verifying the
configuration” on page 157 to complete Communications Manager/2 configuration.

Connecting to a host system

To set up a connection to a host system, for example OS/390 or VSE/ESA, the
steps are:
1. Adding a host connection
2. Defining a partner LU

Start from the Communications Manager Profile List panel.

Select SNA connections and press Configure....

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 153
Using Communications Manager/2
Adding a host connection

1. Select To host and press Create....

2. Select Token-ring or other LAN types and press Continue....

3. Specify a Link name («11¬) and check Activate at startup.

4. Complete the fields LAN destination address (hex) («12¬), Partner network ID
(«13¬), and Partner node name («14¬).

154 MQSeries Intercommunication

 Using Communications Manager/2

5. Press Define Partner LUs....

Defining a partner LU

1. Complete the fields Network ID («13¬), LU name («15¬), and Alias («16¬).
2. Press Add

3. Press OK.

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 155
Using Communications Manager/2

4. Press OK.

5. Press Close.

If you have connections to make to other platforms, proceed to the appropriate

section.

If you have made all the connections you require proceed to “Verifying the
configuration” on page 157 to complete Communications Manager/2 configuration.

156 MQSeries Intercommunication

 Using Communications Manager/2
Verifying the configuration

1. Press Close to close the Communications Manager Profile List panel.

2. Press Close.

3. Press Yes.

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 157
Using Communications Manager/2

4. Press OK.

5. Press Close.

What next?
The LU 6.2 connection is now established. You are ready to complete the
configuration. Go to “MQSeries for OS/2 Warp configuration” on page 162.

Establishing a TCP connection

1. From your desktop, open the TCP Icon View.

The icons you see may vary from those shown above, depending on how you
have installed the product.
2. Start the TCP Configuration program.
3. On the Network page, ensure that the IP Address and Subnet Mask fields
have been completed.
4. Select the Autostart tab.

158 MQSeries Intercommunication

 OS/2 and TCP

5. Ensure that inetd is selected.

6. Select the Hostnames tab.
7. Ensure that This machine’s hostname, Local domain name, and Nameserver
address have been completed.
8. Close the configuration notebook.

Note: You may see a panel warning that the inetd superserver has been
selected without selecting servers. Press No to indicate that you do not
wish to correct this.

9. Press Save to save the changes made.

10. Verify that the \MPTN\ETC\SERVICES file, which is located on the drive
where you installed IBM Multi-Protocol Transport Services (MPTS), contains
the following line:
MQSeries 1414/tcp # MQSeries Chan'l Listener

If this line is not present, add it.

11. Verify that the file \MPTN\ETC\INETD.LST, located on the same drive
contains the following line:
MQSeries tcp c:\mqm\bin\amqcrsta [-m QMName]

If this line is not present, add it. Note that this assumes you have installed
MQSeries on the default drive and in the default directories.
12. (Re)start the inetd superserver, either by rebooting OS/2 or by stopping any
existing inetd superserver and then entering start inetd on the command
line.

What next?
The TCP connection is now established. You are ready to complete the
configuration. Go to “MQSeries for OS/2 Warp configuration” on page 162.

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 159
OS/2 and NetBIOS

Establishing a NetBIOS connection

A NetBIOS connection is initiated from a queue manager that uses the
ConnectionName parameter on its channel definition to connect to a target listener.
To set up a NetBIOS connection, follow these steps:
1. At each end of the channel specify the local NetBIOS name to be used by the
MQSeries channel processes, in the queue manager configuration file qm.ini or
in the registry for Windows NT. For example, the NETBIOS stanza in qm.ini at
the sending end might look like this:
NETBIOS:
LocalName=O2NETB1

and at the receiving end:

NETBIOS:
LocalName=O2NETB2
2. At each end of the channel, look at the LANTRAN.LOG file in the \IBMCOM
directory to see what LAN adapter number is used by NetBIOS on your
system. If it is not 0, which MQSeries uses by default, specify the correct value
in the NETBIOS stanza of the qm.ini file or of the registry for Windows NT. For
example:
NETBIOS:
AdapterNum=1
3. At the sending end, define a channel specifying the NetBIOS name being used
at the other end of the channel. For example:
DEFINE CHANNEL (OS2.WINNT.NET) CHLTYPE(SDR) +
TRPTYPE(NETBIOS) +
CONNAME(O2NETB2) +
XMITQ(WINNT) +
REPLACE
4. At the receiving end, define the corresponding receiver channel. For example:
DEFINE CHANNEL (OS2.WINNT.NET) CHLTYPE(RCVR) +
TRPTYPE(NETBIOS) +
REPLACE
5. At the receiving end, start the MQSeries listener:
runmqlsr -t netbios

Optionally you may specify values for the queue manager name, NetBIOS local
name, number of sessions, number of names, and number of commands. See
“Defining a NetBIOS connection” on page 128 for more information about
setting up NetBIOS connections.

Establishing an SPX connection

This section discusses the following topics:
v IPX/SPX parameters
v SPX addressing
v Using the SPX KEEPALIVE option
v Receiving on SPX

IPX/SPX parameters
In most cases the default settings for the IPX/SPX parameters will suit your needs.
However, you may need to modify some of them in your environment to tune its
use for MQSeries. The actual parameters and the method of changing them varies
according to the platform and provider of SPX communications support. The

160 MQSeries Intercommunication

 OS/2 and SPX
following sections describe some of these parameters, particularly those that may
influence the operation of MQSeries channels and client connections.

Please refer to the Novell Client for OS/2 documentation for full details of the use
and setting of NET.CFG parameters.

The following IPX/SPX parameters can be added to the Novell NET.CFG file, and
can affect MQSeries SPX channels and client connections.

IPX
sockets (range = 9 - 128, default 64)
This specifies the total number of IPX sockets available. MQSeries channels
use this resource, so depending on the number of channels and the
requirements of other IPX/SPX applications, you may need to increase this
value.

SPX
sessions (default 16)
This specifies the total number of simultaneous SPX connections. Each
MQSeries channel or client connection uses one session. You may need to
increase this value depending on the number of MQSeries channels or
client connections you need to run.
retry count (default = 12)
This controls the number of times an SPX session will resend
unacknowledged packets. MQSeries does not override this value.
verify timeout, listen timeout, and abort timeout (milliseconds)
These timeouts adjust the ‘Keepalive’ behavior. If an SPX sending end does
not receive anything within the ‘verify timeout’ period, it sends a packet to
the receiving end. It then waits for the duration of the ‘listen timeout’ for a
response. If it still does not receive a response, it sends another packet and
expects a response within the ‘abort timeout’ period.

SPX addressing
MQSeries uses the SPX address of each machine to establish connectivity. The SPX
address is specified in the following form:
network.node(socket)

where
network
Is the 4-byte network address of the network on which the remote machine
resides,
node Is the 6-byte node address, which is the LAN address of the LAN adapter
in the remote machine
socket Is the 2-byte socket number on which the remote machine will listen.

The default socket number used by MQSeries is 5E86. You can change the default
socket number by specifying it in the queue manager configuration file qm.ini or
the Windows NT registry. If you have taken the default options for installation, the
qm.ini file for queue manager OS2 is found in c:\mqm\qmgs\os2. The lines in
qm.ini might read:
SPX:
SOCKET=n

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 161
OS/2 and SPX
For more information about values you can set in qm.ini, see “Appendix D.
Configuration file stanzas for distributed queuing” on page 637.

The SPX address is later specified in the CONNAME parameter of the sender
channel definition. If the MQSeries systems being connected reside on the same
network, the network address need not be specified. Similarly, if the remote system
is listening on the default socket number (5E86), it need not be specified. A fully
qualified SPX address in the CONNAME parameter would be:
CONNAME('network.node(socket)')

but if the systems reside on the same network and the default socket number is
used, the parameter would be:
CONNAME(node)

A detailed example of the channel configuration parameters is given in “MQSeries

for OS/2 Warp configuration”.

Using the SPX KEEPALIVE option

If you want to use the KEEPALIVE option you need to add the following entry to
your queue manager configuration file (qm.ini) or the Windows NT registry:
SPX:
KeepAlive=yes

You can use the timeout parameters described above to adjust the behavior of
KEEPALIVE.

Receiving on SPX
Receiving channel programs are started in response to a startup request from the
sending channel. To do this, a listener program has to be started to detect incoming
network requests and start the associated channel.

You should use the MQSeries listener.

Using the MQSeries listener

To run the Listener supplied with MQSeries, that starts new channels as threads,
use the RUNMQLSR command. For example:
RUNMQLSR -t spx

Optionally you may specify the queue manager name or the socket number if you
are not using the defaults.

MQSeries for OS/2 Warp configuration

Notes:
1. You can use the sample program AMQSBCG to display, to the stdout spool, the
contents and headers of all the messages in a queue. For example:
AMQSBCG q_name qmgr_name

displays the contents of the queue q_name defined in queue manager qmgr_name.
2. The MQSeries command used to start the TCP listener is:
runmqlsr -t tcp

The listener enables receiver channels to start automatically in response to a

start request from an inbound sender channel.

162 MQSeries Intercommunication

 OS/2 configuration
3. You can start any channel from the command prompt using the command
runmqchl -c channel.name
4. Error logs can be found in the directories \mqm\qmgrs\qmgrname\errors,
\mqm\qmgrs\@system\errors, and \mqm\errors. In all cases, the most recent
messages are at the end of amqerr01.log.
5. When you are using the command interpreter runmqsc to enter administration
commands, a + at the end of a line indicates that the next line is a continuation.
Ensure that there is a space between the last parameter and the continuation
character.

Basic configuration
1. Create the queue manager from the OS/2 command line using the command:
crtmqm -u dlqname -q os2

where:
os2 Is the name of the queue manager
-q Indicates that this is to become the default queue manager
-u dlqname
Specifies the name of the undeliverable message queue

This command creates a queue manager and a set of default objects, and sets
the DEADQ attribute of the queue manager.
2. For SNA channels add an LU 6.2 stanza to the queue manager’s qm.ini file:
LU62:
TPName=MQSERIES «8¬
LocalLU=OS2QMGR «7¬

If you have taken the default options for installation, the qm.ini file for queue
manager os2 is found in c:\mqm\qmgrs\os2.
3. Start the queue manager from the OS/2 command line using the command:
strmqm os2

where os2 is the name given to the queue manager when it was created.

Channel configuration
The following sections detail the configuration to be performed on the OS/2 queue
manager to implement the channel described in Figure 32 on page 97. In each case
the MQSC command is shown.

Examples are given for connecting MQSeries for OS/2 Warp and MQSeries for
Windows NT. If you wish connect to another MQSeries product use the
appropriate set of values from the table in place of those for Windows NT.

Note: The words in bold are user-specified and reflect the names of MQSeries
objects used throughout these examples. If you change the names used here,
ensure that you also change the other references made to these objects
throughout this book. All others are keywords and should be entered as
shown.

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 163
 OS/2 configuration
Table 15. Configuration worksheet for MQSeries for OS/2 Warp
Parameter Name Reference Example Used User Value
Definition for local node
«A¬ Queue Manager Name OS2
«B¬ Local queue name OS2.LOCALQ
Connection to MQSeries for Windows NT

The values in this section of the table must match those used in Table 17 on page 185, as indicated.
«C¬ Remote queue manager name «A¬ WINNT
«D¬ Remote queue name WINNT.REMOTEQ
«E¬ Queue name at remote system «B¬ WINNT.LOCALQ
«F¬ Transmission queue name WINNT
«G¬ Sender (SNA) channel name OS2.WINNT.SNA
«H¬ Sender (TCP/IP) channel name OS2.WINNT.TCP
«I¬ Receiver (SNA) channel name «G¬ WINNT.OS2.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ WINNT.OS2.TCP
«K¬ Sender (NetBIOS) channel name OS2.WINNT.NET
«L¬ Sender (SPX) channel name OS2.WINNT.SPX
«M¬ Receiver (NetBIOS) channel name «K¬ WINNT.OS2.NET
«N¬ Receiver (SPX) channel name «L¬ WINNT.OS2.SPX
Connection to MQSeries for AIX

The values in this section of the table must match those used in Table 21 on page 211, as indicated.
«C¬ Remote queue manager name «A¬ AIX
«D¬ Remote queue name AIX.REMOTEQ
«E¬ Queue name at remote system «B¬ AIX.LOCALQ
«F¬ Transmission queue name AIX
«G¬ Sender (SNA) channel name OS2.AIX.SNA
«H¬ Sender (TCP/IP) channel name OS2.AIX.TCP
«I¬ Receiver (SNA) channel name «G¬ AIX.OS2.SNA
«J¬ Receiver (TCP) channel name «H¬ AIX.OS2.TCP
| Connection to MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| The values in this section of the table must match those used in Table 22 on page 216, as indicated.
| «C¬ Remote queue manager name «A¬ DECUX
| «D¬ Remote queue name DECUX.REMOTEQ
| «E¬ Queue name at remote system «B¬ DECUX.LOCALQ
| «F¬ Transmission queue name DECUX
| «H¬ Sender (TCP) channel name DECUX.OS2.TCP
| «J¬ Receiver (TCP) channel name «H¬ OS2.DECUX.TCP
Connection to MQSeries for HP-UX

The values in this section of the table must match those used in Table 24 on page 239, as indicated.
«C¬ Remote queue manager name «A¬ HPUX
«D¬ Remote queue name HPUX.REMOTEQ
«E¬ Queue name at remote system «B¬ HPUX.LOCALQ
«F¬ Transmission queue name HPUX
«G¬ Sender (SNA) channel name OS2.HPUX.SNA
«H¬ Sender (TCP) channel name OS2.HPUX.TCP
«I¬ Receiver (SNA) channel name «G¬ HPUX.OS2.SNA

164 MQSeries Intercommunication

 OS/2 configuration
Table 15. Configuration worksheet for MQSeries for OS/2 Warp (continued)
Parameter Name Reference Example Used User Value
«J¬ Receiver (TCP) channel name «H¬ HPUX.OS2.TCP
Connection to MQSeries for AT&T GIS UNIX

The values in this section of the table must match those used in Table 26 on page 253, as indicated.
«C¬ Remote queue manager name «A¬ GIS
«D¬ Remote queue name GIS.REMOTEQ
«E¬ Queue name at remote system «B¬ GIS.LOCALQ
«F¬ Transmission queue name GIS
«G¬ Sender (SNA) channel name OS2.GIS.SNA
«H¬ Sender (TCP) channel name OS2.GIS.TCP
«I¬ Receiver (SNA) channel name «G¬ GIS.OS2.SNA
«J¬ Receiver (TCP) channel name «H¬ GIS.OS2.TCP
Connection to MQSeries for Sun Solaris

The values in this section of the table must match those used in Table 28 on page 272, as indicated.
«C¬ Remote queue manager name SOLARIS
«D¬ Remote queue name SOLARIS.REMOTEQ
«E¬ Queue name at remote system «B¬ SOLARIS.LOCALQ
«F¬ Transmission queue name SOLARIS
«G¬ Sender (SNA) channel name OS2.SOLARIS.SNA
«H¬ Sender (TCP/IP) channel name OS2.SOLARIS.TCP
«I¬ Receiver (SNA) channel name «G¬ SOLARIS.OS2.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ SOLARIS.OS2.TCP
| Connection to MQSeries for AS/400

| The values in this section of the table must match those used in Table 43 on page 472, as indicated.
| «C¬ Remote queue manager name AS400
| «D¬ Remote queue name AS400.REMOTEQ
| «E¬ Queue name at remote system «B¬ AS400.LOCALQ
| «F¬ Transmission queue name AS400
| «G¬ Sender (SNA) channel name OS2.AS400.SNA
| «H¬ Sender (TCP/IP) channel name OS2.AS400.TCP
| «I¬ Receiver (SNA) channel name «G¬ AS400.OS2.SNA
| «J¬ Receiver (TCP) channel name «H¬ AS400.OS2.TCP
Connection to MQSeries for OS/390 or MVS/ESA without CICS

The values in this section of the table must match those used in Table 37 on page 406, as indicated.
«C¬ Remote queue manager name MVS
«D¬ Remote queue name MVS.REMOTEQ
«E¬ Queue name at remote system «B¬ MVS.LOCALQ
«F¬ Transmission queue name MVS
«G¬ Sender (SNA) channel name OS2.MVS.SNA
«H¬ Sender (TCP) channel name OS2.MVS.TCP
«I¬ Receiver (SNA) channel name «G¬ MVS.OS2.SNA
«J¬ Receiver (TCP) channel name «H¬ MVS.OS2.TCP
Connection to MQSeries for VSE/ESA

The values in this section of the table must match those used in Table 45 on page 490, as indicated.

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 165
OS/2 configuration
Table 15. Configuration worksheet for MQSeries for OS/2 Warp (continued)
Parameter Name Reference Example Used User Value
«C¬ Remote queue manager name VSE
«D¬ Remote queue name VSE.REMOTEQ
«E¬ Queue name at remote system «B¬ VSE.LOCALQ
«F¬ Transmission queue name VSE
«G¬ Sender channel name OS2.VSE.SNA
«I¬ Receiver channel name «G¬ VSE.OS2.SNA

MQSeries for OS/2 Warp sender-channel definitions using SNA

def ql (WINNT) «F¬
usage(xmitq) +
replace

def qr (WINNT.REMOTEQ) + «D¬

rname(WINNT.LOCALQ) + «E¬
rqmname(WINNT) + «C¬
xmitq(WINNT) + «F¬
replace

def chl (OS2.WINNT.SNA) chltype(sdr) + «G¬

trptype(lu62) +
conname('NETID.WINNTLU') + «13¬.«15¬
xmitq(WINNT) + «F¬
modename('#INTER') + «17¬
tpname('MQSERIES') + «18¬
replace

MQSeries for OS/2 Warp receiver-channel definitions using SNA

def ql (OS2.LOCALQ) replace «B¬

def chl (WINNT.OS2.SNA) chltype(rcvr) + «I¬

trptype(lu62) +
replace

MQSeries for OS/2 Warp sender-channel definitions using TCP

def ql (WINNT) + «F¬
usage(xmitq) +
replace

def qr (WINNT.REMOTEQ) + «D¬

rname(WINNT.LOCALQ) + «E¬
rqmname(WINNT) + «C¬
xmitq(WINNT) + «F¬
replace

def chl (OS2.WINNT.TCP) chltype(sdr) + «H¬

trptype(tcp) +
conname(remote_tcpip_hostname) +
xmitq(WINNT) + «F¬
replace

MQSeries for OS/2 Warp receiver-channel definitions using

TCP/IP
def ql (OS2.LOCALQ) replace «B¬

def chl (WINNT.OS2.TCP) chltype(rcvr) + «J¬

trptype(tcp) +
replace

166 MQSeries Intercommunication

 OS/2 configuration
MQSeries for OS/2 Warp sender-channel definitions using
NetBIOS
def ql (WINNT) + «F¬
usage(xmitq) +
replace

def qr (WINNT.REMOTEQ) + «D¬

rname(WINNT.LOCALQ) + «E¬
rqmname(WINNT) + «C¬
xmitq(WINNT) + «F¬
replace

def chl (OS2.WINNT.NET) chltype(sdr) + «K¬

trptype(netbios) +
conname(remote NetBIOS name) +
xmitq(WINNT) + «F¬
replace

MQSeries for OS/2 Warp receiver-channel definitions using

NetBIOS
def ql (OS2.LOCALQ) replace «B¬

def chl (WINNT.OS2.NET) chltype(rcvr) + «M¬

trptype(netbios) +
replace

MQSeries for OS/2 Warp sender-channel definitions using

IPX/SPX
def ql (WINNT) + «F¬
usage(xmitq) +
replace

def qr (WINNT.REMOTEQ) + «D¬

rname(WINNT.LOCALQ) + «E¬
rqmname(WINNT) + «C¬
xmitq(WINNT) + «F¬
replace

def chl (OS2.WINNT.SPX) chltype(sdr) + «L¬

trptype(spx) +
conname('network.node(socket)') +
xmitq(WINNT) + «F¬
replace

MQSeries for OS/2 Warp receiver-channel definitions using

IPX/SPX
def ql (OS2.LOCALQ) replace «B¬

def chl (WINNT.OS2.SPX) chltype(rcvr) + «N¬

trptype(spx) +
replace

Running channels as processes or threads

MQSeries for OS/2 Warp provides the flexibility to run sender channels as OS/2
processes or OS/2 threads. This is specified in the MCATYPE parameter on the
sender channel definition. Each installation should select the type appropriate for
their application and configuration. Factors affecting this choice are discussed
below.

Most installations will select to run their sender channels as threads, because the
virtual and real memory required to support a large number of concurrent channel
connections will be reduced. When the MQSeries listener process (started via the

Chapter 11. Example configuration - IBM MQSeries for OS/2 Warp 167
OS/2 configuration
RUNMQLSR command) exhausts the available private memory needed, an
additional listener process will need to be started to support more channel
connections. When each channel runs as a process, additional processes are
automatically started, avoiding the out-of-memory condition.

If all channels are run as threads under one MQSeries listener, a failure of the
listener for any reason will cause all channel connections to be temporarily lost.
This can be prevented by balancing the threaded channel connections across two or
more listener processes, thus enabling other connections to keep running. If each
sender channel is run as a separate process, the failure of the listener for that
process will affect only that specific channel connection.

A NetBIOS connection needs a separate process for the Message Channel Agent.
Therefore, before you can issue a START CHANNEL command, you must start the
channel initiator, or you may start a channel using the RUNMQCHL command.

168 MQSeries Intercommunication

 Chapter 12. Example configuration - IBM MQSeries for
Windows NT
This chapter gives an example of how to set up communication links from
MQSeries for Windows NT to MQSeries products on the following platforms:
v OS/2
v AIX
| v Digital UNIX
v HP-UX
v AT&T GIS UNIX2
v Sun Solaris
| v OS/400
v OS/390 or MVS/ESA without CICS
v VSE/ESA

This chapter first describes the parameters needed for an LU 6.2 connection, then it
guides you through the following tasks:
v “Establishing an LU 6.2 connection” on page 174
v “Establishing a TCP connection” on page 181
v “Establishing a NetBIOS connection” on page 181
v “Establishing an SPX connection” on page 182

Once the connection is established, you need to define some channels to complete
the configuration. This is described in “MQSeries for Windows NT configuration”
on page 184.

See “Chapter 7. Example configuration chapters in this book” on page 97 for

background information about this chapter and how to use it.

Configuration parameters for an LU 6.2 connection

Table 16 on page 170 presents a worksheet listing all the parameters needed to set
up communication from Windows NT to one of the other MQSeries platforms. The
worksheet shows examples of the parameters, which have been tested in a
working environment, and leaves space for you to fill in your own values. An
explanation of the parameter names follows the worksheet. Use the worksheet in
this chapter in conjunction with the worksheet in the chapter for the platform to
which you are connecting.

The steps required to set up an LU 6.2 connection are described, with numbered
cross references to the parameters on the worksheet. These steps are:
v “Configuring the local node” on page 174
v “Adding a connection” on page 176
v “Adding a partner” on page 178
v “Adding a CPI-C entry” on page 179
v “Configuring an invokable TP” on page 179

2. This platform has become NCR UNIX SVR4 MP-RAS, R3.0

© Copyright IBM Corp. 1993, 2000 169

Windows NT and LU 6.2
Configuration worksheet
Use this worksheet to record the values you use for your configuration. Where
numbers appear in the Reference column they indicate that the value must match
that in the appropriate worksheet elsewhere in this book. The examples that follow
in this chapter refer back to the values in the ID column. The entries in the
Parameter Name column are explained in “Explanation of terms” on page 172.
Table 16. Configuration worksheet for IBM Communications Server for Windows NT
ID Parameter Name Reference Example Used User Value
Definition for local node
«1¬ Configuration name NTCONFIG
«2¬ Network Name NETID
«3¬ Control Point Name WINNTCP
«4¬ Local Node ID (hex) 05D 30F65
«5¬ LU Name (local) WINNTLU
«6¬ LU Alias (local) NTQMGR
«7¬ TP Name MQSERIES
«8¬ Command line c:\mqm\bin\amqcrs6a.exe
«9¬ LAN adapter address 08005AA5FAB9
Connection to an OS/2 system

The values in this section of the table must match those used in Table 14 on page 138, as indicated.
«10¬ Connection OS2
«11¬ Remote Network Address «10¬ 10005AFC5D83
«12¬ Network Name «2¬ NETID
«13¬ Control Point Name «3¬ OS2PU
«14¬ Remote Node ID «4¬ 05D 12345
«15¬ LU Alias (remote) OS2QMGR
«16¬ LU Name «6¬ OS2LU
«17¬ Mode «17¬ #INTER
«18¬ CPI-C Name OS2CPIC
«19¬ Partner TP Name «8¬ MQSERIES
Connection to an AIX system

The values in this section of the table must match those used in Table 20 on page 197, as indicated.
«10¬ Connection AIX
«11¬ Remote Network Address «8¬ 123456789012
«12¬ Network Name «1¬ NETID
«13¬ Control Point Name «2¬ AIXPU
«14¬ Remote Node ID «3¬ 071 23456
«15¬ LU Alias (remote) AIXQMGR
«16¬ LU Name «4¬ AIXLU
«17¬ Mode «14¬ #INTER
«18¬ CPI-C Name AIXCPIC
«19¬ Partner TP Name «6¬ MQSERIES
Connection to an HP-UX system

The values in this section of the table must match those used in Table 23 on page 219, as indicated.
«10¬ Connection HPUX
«11¬ Remote Network Address «8¬ 100090DC2C7C

170 MQSeries Intercommunication

 Windows NT and LU 6.2
Table 16. Configuration worksheet for IBM Communications Server for Windows NT (continued)
ID Parameter Name Reference Example Used User Value
«12¬ Network Name «4¬ NETID
«13¬ Control Point Name «2¬ HPUXPU
«14¬ Remote Node ID «3¬ 05D 54321
«15¬ LU Alias (remote) HPUXQMGR
«16¬ LU Name «5¬ HPUXLU
«17¬ Mode «17¬ #INTER
«18¬ CPI-C Name HPUXCPIC
«19¬ Partner TP Name «7¬ MQSERIES
Connection to an AT&T GIS UNIX system

The values in this section of the table must match those used in Table 25 on page 243, as indicated.
«10¬ Connection GIS
«11¬ Remote Network Address «8¬ 10007038E86B
«12¬ Network Name «2¬ NETID
«13¬ Control Point Name «3¬ GISPU
«14¬ Remote Node ID «9¬ 03E 00018
«15¬ LU Alias (remote) GISQMGR
«16¬ LU Name «4¬ GISLU
«17¬ Mode «15¬ #INTER
«18¬ CPI-C Name GISCPIC
«19¬ Partner TP Name «5¬ MQSERIES
Connection to a Sun Solaris system

The values in this section of the table must match those used in Table 27 on page 257, as indicated.
«10¬ Connection SOLARIS
«11¬ Remote Network Address «5¬ 08002071CC8A
«12¬ Network Name «2¬ NETID
«13¬ Control Point Name «3¬ SOLARPU
«14¬ Remote Node ID «6¬ 05D 310D6
«15¬ LU Alias (remote) SOLARQMGR
«16¬ LU Name «7¬ SOLARLU
«17¬ Mode «17¬ #INTER
«18¬ CPI-C Name SOLCPIC
«19¬ Partner TP Name «8¬ MQSERIES
Connection to an AS/400 system

The values in this section of the table must match those used in Table 42 on page 460, as indicated.
«10¬ Connection AS400
«11¬ Remote Network Address «4¬ 10005A5962EF
«12¬ Network Name «1¬ NETID
«13¬ Control Point Name «2¬ AS400PU
«14¬ Remote Node ID
«15¬ LU Alias (remote) AS400QMGR
«16¬ LU Name «3¬ AS400LU
«17¬ Mode «17¬ #INTER
«18¬ CPI-C Name AS4CPIC
«19¬ Partner TP Name «8¬ MQSERIES

Chapter 12. Example configuration - IBM MQSeries for Windows NT 171

Windows NT and LU 6.2
Table 16. Configuration worksheet for IBM Communications Server for Windows NT (continued)
ID Parameter Name Reference Example Used User Value
Connection to an OS/390 or MVS/ESA system without CICS

The values in this section of the table must match those used in Table 36 on page 396, as indicated.
«10¬ Connection MVS
«11¬ Remote Network Address «8¬ 400074511092
«12¬ Network Name «2¬ NETID
«13¬ Control Point Name «3¬ MVSPU
«14¬ Remote Node ID
«15¬ LU Alias (remote) MVSQMGR
«16¬ LU Name «4¬ MVSLU
«17¬ Mode «10¬ #INTER
«18¬ CPI-C Name MVSCPIC
«19¬ Partner TP Name «7¬ MQSERIES
Connection to a VSE/ESA system

The values in this section of the table must match those used in Table 44 on page 485, as indicated.
«10¬ Connection MVS
«11¬ Remote Network Address «5¬ 400074511092
«12¬ Network Name «1¬ NETID
«13¬ Control Point Name «2¬ VSEPU
«14¬ Remote Node ID
«15¬ LU Alias (remote) VSEQMGR
«16¬ LU Name «3¬ VSELU
«17¬ Mode #INTER
«18¬ CPI-C Name VSECPIC
«19¬ Partner TP Name «4¬ MQ01 MQ01

Explanation of terms
«1¬ Configuration Name
This is the name of the file in which the Communications Server
configuration is saved.
«2¬ Network Name
This is the unique ID of the network to which you are connected. It is an
alphanumeric value and can be 1-8 characters long. The network name
works with the Control Point Name to uniquely identify a system. Your
network administrator will tell you the value.
«3¬ Control Point Name
In Advanced Peer-to-Peer® Networking (APPN)®, a control point is
responsible for managing a node and its resources. A control point is also a
logical unit (LU). The Control Point Name is the name of the LU and is
assigned to your system by the network administrator.
«4¬ Local Node ID (hex)
Some SNA products require partner systems to specify a node identifier
that uniquely identifies their workstation. The two systems exchange this
node identifier in a message unit called the exchange identifier (XID). Your
network administrator will assign this ID for you.

172 MQSeries Intercommunication

 Windows NT and LU 6.2
«5¬ LU Name (local)
A logical unit (LU) is software that serves as an interface or translator
between a transaction program and the network. An LU manages the
exchange of data between transaction programs. The local LU Name is the
name of the LU on your workstation. Your network administrator will
assign this to you.
«6¬ LU Alias (local)
The name by which your local LU will be known to your applications. You
choose this name yourself. It can be 1-8 characters long.
«7¬ TP Name
MQSeries applications trying to converse with your workstation specify a
symbolic name for the program that is to start running. This will have
been defined on the channel definition at the sender. For simplicity,
wherever possible use a transaction program name of MQSERIES, or in the
case of a connection to VSE/ESA, where the length is limited to 4 bytes,
use MQTP.
See Table 12 on page 126 for more information.
«8¬ Command line
This is the path and name of the actual program to be run when a
conversation has been initiated with your workstation. The example shown
on the worksheet assumes that MQSeries is installed in the default
directory, c:\mqm. The configuration pairs this name with the symbolic
name «7¬ when you use TPSETUP (which is part of the SNA Server
software developers kit).
«9¬ LAN adapter address
This is the address of your token-ring card. To discover this type net
config server at a command prompt. The address appears in the output.
For example:
Server is active on 08005AA5FAB9
«10¬ Connection
This is a meaningful symbolic name by which the connection to a partner
node is known. It is used only within SNA Server administration and is
specified by you.
«15¬ LU Alias (remote)
This is a value known only in this server and is used to represent the fully
qualified partner LU name. You supply the value.
«17¬ Mode
This is the name given to the set of parameters that control the APPC
conversation. An entry with this name and a similar set of parameters
must be defined at each partner system. Your network administrator will
tell you this name.
«18¬ CPI-C Name
This is the name given to a locally held definition of a partner application.
You supply the name and it must be unique within this server. The name
is specified in the CONNAME attribute of the MQSeries sender channel
definition.

Chapter 12. Example configuration - IBM MQSeries for Windows NT 173

Using IBM Communications Server

Establishing an LU 6.2 connection

This section describes how to establish an LU 6.2 connection using IBM
Communications Server for Windows NT, Version 5.0. You may use any of the
supported LU 6.2 products for this platform. The panels of other products will not
be identical to those shown here, but most of their content will be similar.

Configuring the local node

To configure the local node, follow these steps:
1. From the Scenarios pull-down of the Communications Server SNA Node
Configuration window, select the CPI-C, APPC or 5250 Emulation scenario.

The CPI-C, APPC or 5250 Emulation scenario window is displayed.

2. Click on Configure Node, then click on New. The Define the Node property
sheet is displayed.

174 MQSeries Intercommunication

 Using IBM Communications Server

3. In the Fully qualified CP name field on the Basic page, enter the unique ID of
the network to which you are connected («2¬) and the control point name («3¬).
Click on OK to continue.
4. From the SNA Node Configuration window, click on Configure Local LU 6.2,
then click on New. The Define a Local LU 6.2 window is displayed.

Chapter 12. Example configuration - IBM MQSeries for Windows NT 175

Using IBM Communications Server
5. In the Local LU name field on the Basic page, enter the name of the LU on
your workstation («5¬). In the Local LU alias field, enter the name by which
your local LU will be known to your applications («6¬). Click on OK to
continue.

Adding a connection
To add a connection, follow these steps:
1. From the SNA Node Configuration window, select Configure Devices, select
LAN as the DLC type, then click on New. The Define a LAN Device property
sheet is displayed.

2. If you have the LLC2 protocol installed with Communications Server for
Windows NT, the Adapter number list box lists the available LAN adapters.
See the help file INLLC40.HLP (Windows NT 4.0) or INLLC35.HLP (Windows
NT 3.51) in the Communications Server installation directory for LLC2
installation instructions.
3. The default values displayed on the Define a LAN Device Basic page may be
accepted. Click on OK to continue.
4. From the SNA Node Configuration window, select Configure Connections,
select LAN as the DLC type, then click on New. The Define a LAN Connection
property sheet is displayed.

176 MQSeries Intercommunication

 Using IBM Communications Server

5. In the Destination address field on the Basic page, enter the LAN address of
the system to which you are connecting («11¬). Select the Advanced page.

6. In the Block ID field on the Advanced page, enter the local node ID (hex)
(«4¬). Select the Security page.

Chapter 12. Example configuration - IBM MQSeries for Windows NT 177

Using IBM Communications Server

7. In the Adjacent CP name field on the Security page, enter the network name
and control point name of the remote node («12¬ and «13¬). In the Adjacent CP
type field, enter APPN Node. You do not need to complete the Adjacent node ID
field for a peer-to-peer connection. Click on OK to continue. Take note of the
default link name used to identify this new definition (for example, LINK0000).

Adding a partner
To add a partner LU definition, follow these steps:
1. From the SNA Node Configuration window, select Configure Partner LU 6.2,
then click on New. The Define a Partner LU 6.2 property sheet is displayed.

2. In the Partner LU name field on the Basic page, enter the network name («12¬)
and LU name of the remote system («16¬). In the Partner LU alias field, enter
the remote LU alias («15¬). In the Fully qualified CP name fields, enter the
network name and control point name of the remote system («12¬ and «13¬).
Click on OK to continue.

178 MQSeries Intercommunication

 Using IBM Communications Server
Adding a CPI-C entry
To add a CPI-C Side information entry, follow these steps:
1. From the SNA Node Configuration window, select Configure CPI-C Side
Information, then click on New. The Define a CPI-C Side Information property
sheet is displayed.

2. In the Symbolic destination name field of the Basic page, enter the CPI-C
name («18¬). In the Mode name field, enter the mode value («17¬). Enter either
a fully qualified partner LU name («12¬.«16¬) or a partner LU alias («15¬)
depending on what you choose in the CPI-C Side Information property sheet.
In the TP name field, enter the partner TP name («19¬). Click on OK to
continue.

Configuring an invokable TP
To add a Transaction Program (TP) definition, follow these steps:
1. From the SNA Node Configuration window, select Configure Transaction
Programs, then click on New. The Define a Transaction Program property sheet
is displayed.

Chapter 12. Example configuration - IBM MQSeries for Windows NT 179

Using IBM Communications Server

2. In the TP name field on the Basic page, enter the transaction program name
(«7¬). In the Complete pathname field, enter the actual path and name of the
the program that will be run when a conversation is initiated with your
workstation («8¬). When you are happy with the settings, click on OK to
continue.
3. In order to be able to stop the MQSeries Transaction Program, you need to start
it in one of the following ways:
a. Check Service TP on the Basic page. This starts the TP programs at
Windows NT startup and will run the programs under the system user ID.
b. Check Dynamically loaded on the Advanced page. This dynamically loads
and starts the programs as and when incoming SNA conversation requests
arrive. It will run the programs under the same user ID as the rest of
MQSeries.

Note: To use dynamic loading, it is necessary to vary the user ID under

which the MQSeries SNA Transaction program runs. To do this, set
the Attach Manager to run under the desired user context by
modifying the startup parameters within the Control Panel in the
Services applet for the AppnNode service.
c. Issue the MQSeries command, runmqlsr, to run the channel listener process.

Communications Server has a tuning parameter called the Receive_Allocate

timeout parameter that is set in the Transaction Program. The default value of this
parameter is 3600 and this indicates that the listener will only remain active for
3600 seconds, that is, 1 hour. You can make your listener run for longer than this
by increasing the value of the Receive_Allocate timeout parameter. You can also
make it run ‘forever’ by specifying zero.

180 MQSeries Intercommunication

 Using IBM Communications Server
What next?
The SNA configuration task is complete. From the File pull-down, select Save and
specify a file name under which to save your SNA configuration information, for
example, NTCONFIG («1¬). When prompted, select this configuration as the
default.

From the SNA Node Operations application, start the node by clicking the Start
node button on the toolbar. Specify the file name of the configuration you just
saved. (It should appear in the file-name box by default, because you identified it
as your default configuration.) When the node startup is complete, ensure that
your link to the remote node has been established by selecting the Connections
button on the toolbar, then find the link name you configured (for example,
LINK0000). The link should be active if the remote node is active waiting for the
link to be established.

A complementary SNA setup process is required on the node to which you are
connecting before you can attempt MQSeries server-to-server message
transmissions.

The LU 6.2 connection is now established. You are ready to complete the
configuration. Go to “MQSeries for Windows NT configuration” on page 184.

Establishing a TCP connection

The TCP stack that is shipped with Windows NT does not include an inet daemon
or equivalent.

The MQSeries command used to start a TCP listener is:

runmqlsr -t tcp

The listener must be started explicitly before any channels are started.

What next?
When the TCP/IP connection is established, you are ready to complete the
configuration. Go to “MQSeries for Windows NT configuration” on page 184.

Establishing a NetBIOS connection

A NetBIOS connection is initiated from a queue manager that uses the
ConnectionName parameter on its channel definition to connect to a target listener.
To set up a NetBIOS connection, follow these steps:
1. At each end of the channel specify the local NetBIOS name to be used by the
MQSeries channel processes, in the Windows NT registry or in the queue
manager configuration file qm.ini. For example, the NETBIOS stanza in the
Windows NT registry at the sending end might look like this:
NETBIOS:
LocalName=WNTNETB1

and at the receiving end:

NETBIOS:
LocalName=WNTNETB2

Each MQSeries process must use a different local NetBIOS name. Do not use
your machine name as the NetBIOS name because Windows NT already uses it.

Chapter 12. Example configuration - IBM MQSeries for Windows NT 181

Windows NT and NetBIOS
2. At each end of the channel, verify the LAN adapter number being used on
your system. The MQSeries for Windows NT default for logical adapter
number 0 is NetBIOS running over a TCP/IP network. To use native NetBIOS
you need to select logical adapter number 1. See “Establishing the LAN adapter
number” on page 130.
Specify the correct LAN adapter number in the NETBIOS stanza of the the
Windows NT registry. For example:
NETBIOS:
AdapterNum=1
3. So that sender channel initiation will work, specify the local NetBIOS name via
the MQNAME environment variable:
SET MQNAME=WNTNETB1I

This name must be unique.

4. At the sending end, define a channel specifying the NetBIOS name being used
at the other end of the channel. For example:
DEFINE CHANNEL (WINNT.OS2.NET) CHLTYPE(SDR) +
TRPTYPE(NETBIOS) +
CONNAME(WNTNETB2) +
XMITQ(OS2) +
MCATYPE(THREAD) +
REPLACE

You must specify the option MCATYPE(THREAD) because, on Windows NT, sender
channels must be run as threads.
5. At the receiving end, define the corresponding receiver channel. For example:
DEFINE CHANNEL (WINNT.OS2.NET) CHLTYPE(RCVR) +
TRPTYPE(NETBIOS) +
REPLACE
6. Start the channel initiator because each new channel is started as a thread
rather than as a new process.
runmqchi
7. At the receiving end, start the MQSeries listener:
runmqlsr -t netbios

Optionally you may specify values for the queue manager name, NetBIOS local
name, number of sessions, number of names, and number of commands. See
“Defining a NetBIOS connection” on page 128 for more information about
setting up NetBIOS connections.

Establishing an SPX connection

This section discusses the following topics:
v IPX/SPX parameters
v SPX addressing
v Receiving on SPX

IPX/SPX parameters
Please refer to the Microsoft documentation for full details of the use and setting of
the NWLink IPX and SPX parameters. The IPX/SPX parameters are in the
following paths in the registry:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Service\NWLinkSPX\Parameters
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Service\NWLinkIPX\Parameters

182 MQSeries Intercommunication

 Windows NT and SPX
SPX addressing
MQSeries uses the SPX address of each machine to establish connectivity. The SPX
address is specified in the following form:
network.node(socket)

where
network
Is the 4-byte network address of the network on which the remote machine
resides,
node Is the 6-byte node address, which is the LAN address of the LAN adapter
in the remote machine
socket Is the 2-byte socket number on which the remote machine will listen.

The default socket number used by MQSeries is 5E86. You can change the default
socket number by specifying it in the the Windows NT registry or in the queue
manager configuration file qm.ini. If you have taken the default options for
installation, the qm.ini file for queue manager OS2 is found in c:\mqm\qmgs\os2.
The lines in the Windows NT registry might read:
SPX:
SOCKET=n

For more information about values you can set in qm.ini, see “Appendix D.
Configuration file stanzas for distributed queuing” on page 637.

The SPX address is later specified in the CONNAME parameter of the sender
channel definition. If the MQSeries systems being connected reside on the same
network, the network address need not be specified. Similarly, if the remote system
is listening on the default socket number (5E86), it need not be specified. A fully
qualified SPX address in the CONNAME parameter would be:
CONNAME('network.node(socket)')

but if the systems reside on the same network and the default socket number is
used, the parameter would be:
CONNAME(node)

A detailed example of the channel configuration parameters is given in “MQSeries

for Windows NT configuration” on page 184.

Receiving on SPX
Receiving channel programs are started in response to a startup request from the
sending channel. To do this, a listener program has to be started to detect incoming
network requests and start the associated channel.

You should use the MQSeries listener.

Using the MQSeries listener

To run the Listener supplied with MQSeries, that starts new channels as threads,
use the RUNMQLSR command. For example:
RUNMQLSR -t spx

Optionally you may specify the queue manager name or the socket number if you
are not using the defaults.

Chapter 12. Example configuration - IBM MQSeries for Windows NT 183

Windows NT configuration

MQSeries for Windows NT configuration

Notes:
1. You can use the sample program, AMQSBCG, to display the contents and
headers of all the messages in a queue. For example:
AMQSBCG q_name qmgr_name

displays the contents of the queue q_name defined in queue manager qmgr_name.

Alternatively, you can use the message browser in the MQSeries Explorer.
2. The MQSeries command used to start the TCP/IP listener is:
runmqlsr -t tcp

The listener enables receiver channels to start automatically in response to a

start request from an inbound sender channel.
3. You can start any channel from the command prompt using the command
runmqchl -c channel.name
4. Error logs can be found in the directories \mqm\qmgrs\qmgrname\errors and
\mqm\qmgrs\@system\errors. In both cases, the most recent messages are at
the end of amqerr01.log.
5. When you are using the command interpreter runmqsc to enter administration
commands, a + at the end of a line indicates that the next line is a continuation.
Ensure that there is a space between the last parameter and the continuation
character.

Default configuration
You can create a default configuration by using either the First Steps application or
the MQSeries Postcard application to guide you through the process. For
information about this, see the MQSeries System Administration book.

Basic configuration
You can create and start a queue manager from the MQSeries Explorer or from the
command prompt.

If you choose the command prompt:

1. Create the queue manager using the command:
crtmqm -u dlqname -q winnt

where:
winnt Is the name of the queue manager
-q Indicates that this is to become the default queue manager
-u dlqname
Specifies the name of the undeliverable message queue

This command creates a queue manager and a set of default objects.

2. Start the queue manager using the command:
strmqm winnt

where winnt is the name given to the queue manager when it was created.

184 MQSeries Intercommunication

 Windows NT configuration
Channel configuration
The following sections detail the configuration to be performed on the Windows
NT queue manager to implement the channel described in Figure 32 on page 97.

In each case the MQSC command is shown. Either start runmqsc from a command
prompt and enter each command in turn, or build the commands into a command
file.

Examples are given for connecting MQSeries for Windows NT and MQSeries for
OS/2 Warp. If you wish to connect to another MQSeries product use the
appropriate set of values from the table in place of those for OS/2.

Note: The words in bold are user-specified and reflect the names of MQSeries
objects used throughout these examples. If you change the names used here,
ensure that you also change the other references made to these objects
throughout this book. All others are keywords and should be entered as
shown.
Table 17. Configuration worksheet for MQSeries for Windows NT
Parameter Name Reference Example Used User Value
Definition for local node
«A¬ Queue Manager Name WINNT
«B¬ Local queue name WINNT.LOCALQ
Connection to MQSeries for OS/2 Warp

The values in this section of the table must match those used in Table 15 on page 164, as indicated.
«C¬ Remote queue manager name «A¬ OS2
«D¬ Remote queue name OS2.REMOTEQ
«E¬ Queue name at remote system «B¬ OS2.LOCALQ
«F¬ Transmission queue name OS2
«G¬ Sender (SNA) channel name WINNT.OS2.SNA
«H¬ Sender (TCP/IP) channel name WINNT.OS2.TCP
«I¬ Receiver (SNA) channel name «G¬ OS2.WINNT.SNA
«J¬ Receiver (TCP) channel name «H¬ OS2.WINNT.TCP
«K¬ Sender (NetBIOS) channel name WINNT.OS2.NET
«L¬ Sender (SPX) channel name WINNT.OS2.SPX
«M¬ Receiver (NetBIOS) channel name «K¬ OS2.WINNT.NET
«N¬ Receiver (SPX) channel name «L¬ OS2.WINNT.SPX
Connection to MQSeries for AIX

The values in this section of the table must match those used in Table 21 on page 211, as indicated.
«C¬ Remote queue manager name «A¬ AIX
«D¬ Remote queue name AIX.REMOTEQ
«E¬ Queue name at remote system «B¬ AIX.LOCALQ
«F¬ Transmission queue name AIX
«G¬ Sender (SNA) channel name WINNT.AIX.SNA
«H¬ Sender (TCP) channel name WINNT.AIX.TCP
«I¬ Receiver (SNA) channel name «G¬ AIX.WINNT.SNA
«J¬ Receiver (TCP) channel name «H¬ AIX.WINNT.TCP
| Connection to MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| The values in this section of the table must match those used in Table 22 on page 216, as indicated.

Chapter 12. Example configuration - IBM MQSeries for Windows NT 185

 Windows NT configuration
Table 17. Configuration worksheet for MQSeries for Windows NT (continued)
Parameter Name Reference Example Used User Value
| «C¬ Remote queue manager name «A¬ DECUX
| «D¬ Remote queue name DECUX.REMOTEQ
| «E¬ Queue name at remote system «B¬ DECUX.LOCALQ
| «F¬ Transmission queue name DECUX
| «H¬ Sender (TCP) channel name DECUX.WINNT.TCP
| «J¬ Receiver (TCP) channel name «H¬ WINNT.DECUX.TCP
Connection to MQSeries for HP-UX

The values in this section of the table must match those used in Table 24 on page 239, as indicated.
«C¬ Remote queue manager name «A¬ HPUX
«D¬ Remote queue name HPUX.REMOTEQ
«E¬ Queue name at remote system «B¬ HPUX.LOCALQ
«F¬ Transmission queue name HPUX
«G¬ Sender (SNA) channel name WINNT.HPUX.SNA
«H¬ Sender (TCP) channel name WINNT.HPUX.TCP
«I¬ Receiver (SNA) channel name «G¬ HPUX.WINNT.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ HPUX.WINNT.TCP
Connection to MQSeries for AT&T GIS UNIX

The values in this section of the table must match those used in Table 26 on page 253, as indicated.
«C¬ Remote queue manager name «A¬ GIS
«D¬ Remote queue name GIS.REMOTEQ
«E¬ Queue name at remote system «B¬ GIS.LOCALQ
«F¬ Transmission queue name GIS
«G¬ Sender (SNA) channel name WINNT.GIS.SNA
«H¬ Sender (TCP/IP) channel name WINNT.GIS.TCP
«I¬ Receiver (SNA) channel name «G¬ GIS.WINNT.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ GIS.WINNT.TCP
Connection to MQSeries for Sun Solaris

The values in this section of the table must match those used in Table 28 on page 272, as indicated.
«C¬ Remote queue manager name SOLARIS
«D¬ Remote queue name SOLARIS.REMOTEQ
«E¬ Queue name at remote system «B¬ SOLARIS.LOCALQ
«F¬ Transmission queue name SOLARIS
«G¬ Sender (SNA) channel name WINNT.SOLARIS.SNA
«H¬ Sender (TCP) channel name WINNT.SOLARIS.TCP
«I¬ Receiver (SNA) channel name «G¬ SOLARIS.WINNT.SNA
«J¬ Receiver (TCP) channel name «H¬ SOLARIS.WINNT.TCP
| Connection to MQSeries for AS/400

| The values in this section of the table must match those used in Table 43 on page 472, as indicated.
| «C¬ Remote queue manager name AS400
| «D¬ Remote queue name AS400.REMOTEQ
| «E¬ Queue name at remote system «B¬ AS400.LOCALQ
| «F¬ Transmission queue name AS400
| «G¬ Sender (SNA) channel name WINNT.AS400.SNA
| «H¬ Sender (TCP) channel name WINNT.AS400.TCP

186 MQSeries Intercommunication

 Windows NT configuration
Table 17. Configuration worksheet for MQSeries for Windows NT (continued)
Parameter Name Reference Example Used User Value
| «I¬ Receiver (SNA) channel name «G¬ AS400.WINNT.SNA
| «J¬ Receiver (TCP) channel name «H¬ AS400.WINNT.TCP
Connection to MQSeries for OS/390 or MVS/ESA without CICS

The values in this section of the table must match those used in Table 37 on page 406, as indicated.
«C¬ Remote queue manager name MVS
«D¬ Remote queue name MVS.REMOTEQ
«E¬ Queue name at remote system «B¬ MVS.LOCALQ
«F¬ Transmission queue name MVS
«G¬ Sender (SNA) channel name WINNT.MVS.SNA
«H¬ Sender (TCP) channel name WINNT.MVS.TCP
«I¬ Receiver (SNA) channel name «G¬ MVS.WINNT.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ MVS.WINNT.TCP
Connection to MQSeries for VSE/ESA

The values in this section of the table must match those used in Table 45 on page 490, as indicated.
«C¬ Remote queue manager name VSE
«D¬ Remote queue name VSE.REMOTEQ
«E¬ Queue name at remote system «B¬ VSE.LOCALQ
«F¬ Transmission queue name VSE
«G¬ Sender channel name WINNT.VSE.SNA
«I¬ Receiver channel name «G¬ VSE.WINNT.SNA

MQSeries for Windows NT sender-channel definitions using SNA

def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (WINNT.OS2.SNA) chltype(sdr) + «G¬

trptype(lu62) +
conname(OS2CPIC) + «18¬
xmitq(OS2) + «F¬
replace

MQSeries for Windows NT receiver-channel definitions using

SNA
def ql (WINNT.LOCALQ) replace «B¬

def chl (OS2.WINNT.SNA) chltype(rcvr) + «I¬

trptype(lu62) +
replace

Chapter 12. Example configuration - IBM MQSeries for Windows NT 187

Windows NT configuration
MQSeries for Windows NT sender-channel definitions using
TCP/IP
def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (WINNT.OS2.TCP) chltype(sdr) + «H¬

trptype(tcp) +
conname(remote_tcpip_hostname) +
xmitq(OS2) + «F¬
replace

MQSeries for Windows NT receiver-channel definitions using

TCP
def ql (WINNT.LOCALQ) replace «B¬

def chl (OS2.WINNT.TCP) chltype(rcvr) + «J¬

trptype(tcp) +
replace

MQSeries for Windows NT sender-channel definitions using

NetBIOS
def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (WINNT.OS2.NET) chltype(sdr) + «K¬

trptype(netbios) +
conname(remote_system_NetBIOS_name) +
xmitq(OS2) + «F¬
replace

MQSeries for Windows NT receiver-channel definitions using

NetBIOS
def ql (WINNT.LOCALQ) replace «B¬

def chl (OS2.WINNT.NET) chltype(rcvr) + «M¬

trptype(tcp) +
replace

MQSeries for Windows NT sender-channel definitions using SPX

def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (WINNT.OS2.SPX) chltype(sdr) + «L¬

188 MQSeries Intercommunication

 Windows NT configuration
trptype(spx) +
conname('network.node(socket)') +
xmitq(OS2) + «F¬
replace

MQSeries for Windows NT receiver-channel definitions using

SPX
def ql (WINNT.LOCALQ) replace «B¬

def chl (OS2.WINNT.SPX) chltype(rcvr) + «N¬

trptype(tcp) +
replace

Automatic startup
MQSeries for Windows NT allows you to automate the startup of a queue manager
and its channel initiator, channels, listeners, and command servers. Use the IBM
MQSeries Services snap-in to define the services for the queue manager. When you
have successfully completed testing of your communications setup, set the relevant
services to automatic within the snap-in. This file can be read by the supplied
MQSeries service when the system is started.

For more information about this, see the MQSeries System Administration book.

Running channels as processes or threads

MQSeries for Windows NT provides the flexibility to run sender channels as
Windows NT processes or Windows NT threads. This is specified in the MCATYPE
parameter on the sender channel definition. Each installation should select the type
appropriate for their application and configuration. Factors affecting this choice are
discussed below.

Most installations will select to run their sender channels as threads, because the
virtual and real memory required to support a large number of concurrent channel
connections will be reduced. When the MQSeries listener process (started via the
RUNMQLSR command) exhausts the available private memory needed, an
additional listener process will need to be started to support more channel
connections. When each channel runs as a process, additional processes are
automatically started, avoiding the out-of-memory condition.

If all channels are run as threads under one MQSeries listener, a failure of the
listener for any reason will cause all channel connections to be temporarily lost.
This can be prevented by balancing the threaded channel connections across two or
more listener processes, thus enabling other connections to keep running. If each
sender channel is run as a separate process, the failure of the listener for that
process will affect only that specific channel connection.

A NetBIOS connection needs a separate process for the Message Channel Agent.
Therefore, before you can issue a START CHANNEL command, you must start the
channel initiator, or you may start a channel using the RUNMQCHL command.

Chapter 12. Example configuration - IBM MQSeries for Windows NT 189

DQM in distributed platforms

190 MQSeries Intercommunication

 Chapter 13. Setting up communication in UNIX systems
DQM is a remote queuing facility for MQSeries. It provides channel control
programs for the queue manager which form the interface to communication links,
controllable by the system operator. The channel definitions held by
distributed-queuing management use these connections.

When a distributed-queuing management channel is started, it tries to use the

connection specified in the channel definition. For this to succeed, it is necessary
for the connection to be defined and available. This chapter explains how to do
this. You may also find it helpful to refer to the following chapters:
v “Chapter 14. Example configuration - IBM MQSeries for AIX” on page 197
| v “Chapter 15. Example configuration - IBM MQSeries for DIGITAL UNIX
| (Compaq Tru64 UNIX)” on page 215
v “Chapter 16. Example configuration - IBM MQSeries for HP-UX” on page 219
v “Chapter 17. Example configuration - IBM MQSeries for AT&T GIS UNIX
Version 2.2” on page 243
v “Chapter 18. Example configuration - IBM MQSeries for Sun Solaris” on
page 257

For OS/2 and Windows NT, see “Chapter 10. Setting up communication for OS/2
and Windows NT” on page 123. For Digital OpenVMS, see “Chapter 19. Setting up
communication in Digital OpenVMS systems” on page 277. For Tandem NSK, see
“Chapter 20. Setting up communication in Tandem NSK” on page 289.

Deciding on a connection
There are three forms of communication for MQSeries on UNIX systems:
v TCP
v LU 6.2
v UDP (MQSeries for AIX only)

Each channel definition must specify one only as the transmission protocol
(Transport Type) attribute. One or more protocols may be used by a queue
manager.

For MQSeries clients, it may be useful to have alternative channels using different
transmission protocols. See the MQSeries Clients book.

Defining a TCP connection

The channel definition at the sending end specifies the address of the target. The
inetd daemon is configured for the connection at the receiving end.

Sending end
Specify the host name, or the TCP address of the target machine, in the Connection
Name field of the channel definition. The port to connect to will default to 1414.
Port number 1414 is assigned by the Internet Assigned Numbers Authority to
MQSeries.

© Copyright IBM Corp. 1993, 2000 191

 Defining a TCP connection
To use a port number other than the default, change the connection name field
thus:
Connection Name REMHOST(1822)

where REMHOST is the hostname of the remote machine and 1822 is the port number
required. (This must be the port that the listener at the receiving end is listening
on.)

Alternatively you can change the port number by specifying it in the queue
manager configuration file (qm.ini):
TCP:
Port=1822

For more information about the values you set using QM.INI, see “Appendix D.
Configuration file stanzas for distributed queuing” on page 637.

Receiving on TCP
You should use either the TCP/IP listener (INETD) or the MQSeries listener.

Using the TCP/IP listener

To use INETD to start channels on UNIX, two files must be configured:
1. Add a line in the /etc/services file:
MQSeries 1414/tcp

where 1414 is the port number required by MQSeries.

Note: To edit the /etc/services file, you must be logged in as a superuser or

root. You can change this, but it must match the port number specified at
the sending end.
2. Add a line in the inetd.conf file to call the program amqcrsta:
MQSeries stream tcp nowait mqm /mqmtop/bin/amqcrsta amqcrsta
[-m Queue_Man_Name]

The updates are active after inetd has reread the configuration files. To do this,
issue the following commands from the root user ID:
v On AIX:
refresh -s inetd
v On HP-UX:
inetd -c
v On other UNIX systems:
kill -1 <process number>
| When the listener program started by INETD inherits the locale from INETD, it is
| possible that the MQMDE will not be honored and will be placed on the queue as
| message data. To ensure that the MQMDE is honored (merged), you must set the
| locale correctly. The locale set by INETD may not match that chosen for other
| locales used by MQSeries processes. To set the locale:
| 1. Create a shell script which sets the locale environment variables LANG,
| LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME, and
| LC_MESSAGES to the locale used for other MQSeries process.
| 2. In the same shell script, call the listener program.
| 3. Modify the inetd.conf file to call your shell script in place of the listener
| program.

192 MQSeries Intercommunication

 Defining a TCP connection
It is possible to have more than one queue manager on the server machine. You
must add a line to each of the two files, as above, for each of the queue managers.
For example:
MQSeries1 1414/tcp
MQSeries2 1822/tcp
MQSeries2 stream tcp nowait mqm /mqmtop/bin/amqcrsta amqcrsta -m QM2

This avoids error messages being generated if there is a limitation on the number
of outstanding connection requests queued at a single TCP port. For information
about the number of outstanding connection requests, see “Using the TCP listener
backlog option”.

Using the TCP listener backlog option

When receiving on TCP, a maximum number of outstanding connection requests is
set. This can be considered a backlog of requests waiting on the TCP port for the
listener to accept the request. The default listener backlog values are shown in
Table 18.
Table 18. Default outstanding connection requests
Platform Default listener backlog value
AIX V4.2 or later 100
AIX V4.1 10
HP-UX 20
Sun Solaris 100
All others 5

If the backlog reaches the values shown in Table 18, the TCP/IP connection is
rejected and the channel will not be able to start.

For MCA channels, this results in the channel going into a RETRY state and
retrying the connection at a later time.

For client connections, the client receives an MQRC_Q_MGR_NOT_AVAILABLE

reason code from MQCONN and should retry the connection at a later time.

However, to avoid this error, you can add an entry in the qm.ini file:
TCP:
ListenerBacklog = n

This overrides the default maximum number of outstanding requests (see Table 18)
for the TCP/IP listener.

Note: Some operating systems support a larger value than the default. If necessary,
this can be used to avoid reaching the connection limit.

To run the listener with the backlog option switched on, use the RUNMQLSR -B
command. For information about the RUNMQLSR command, see the MQSeries System
Administration book.

Using the MQSeries listener

To run the listener supplied with MQSeries, which starts new channels as threads,
use the runmqlsr command. For example:
runmqlsr -t tcp [-m QMNAME] [-p 1822]

Chapter 13. Setting up communication in UNIX systems 193

Defining a TCP connection
The square brackets indicate optional parameters; QMNAME is not required for the
default queue manager, and the port number is not required if you are using the
default (1414).

For the best performance, run the MQSeries listener as a trusted application as
described in “Running channels and listeners as trusted applications” on page 121.
See the MQSeries Application Programming Guide for information about trusted
applications.

You can stop all MQSeries listeners running on a queue manager that is inactive,
using the command:
endmqlsr [-m QMNAME]

If you do not specify a queue manager name, the default queue manager is
assumed.

Using the TCP/IP SO_KEEPALIVE option

If you want to use the SO_KEEPALIVE option (as discussed in “Checking that the
other end of the channel is still available” on page 66) you must the add the
following entry to your queue manager configuration file (QM.INI) or the
Windows NT registry:
TCP:
KeepAlive=yes

On some UNIX systems, you can define how long TCP waits before checking that
the connection is still available, and how frequently it retries the connection if the
first check fails. This is either a kernel tunable parameter, or can be entered at the
command line. See the documentation for your UNIX system for more information.

On MQSeries for SINIX and DC/OSx you can set the TCP keepalive parameters by
using the idtune and idbuild commands to modify the TCP_KEEPCNT and
TCP_KEEPINT values for the kernel configuration. The default configuration is to
retry 7 times at 7200 second (2 hourly) intervals.

Defining an LU 6.2 connection

SNA must be configured so that an LU 6.2 conversation can be established
between the two machines.

See the Multiplatform APPC Configuration Guide and the following table for
information.
Table 19. Settings on the local UNIX system for a remote queue manager platform
Remote platform TPNAME TPPATH
OS/390 or The same as the corresponding -
MVS/ESA TPName in the side information on
without CICS the remote queue manager.
OS/390 or CKRC (sender) CKSV (requester) -
MVS/ESA using CKRC (server)
CICS
OS/400 The same as the compare value in -
the routing entry on the OS/400
system.

194 MQSeries Intercommunication

 Defining an LU 6.2 connection
Table 19. Settings on the local UNIX system for a remote queue manager
platform (continued)
Remote platform TPNAME TPPATH
OS/2 As specified in the OS/2 Run <drive>:\mqm\bin\amqcrs6a
Listener command, or defaulted
from the OS/2 queue manager
configuration file.
UNIX systems The same as the corresponding mqmtop/bin/amqcrs6a
TPName in the side information on
the remote queue manager.
Windows NT As specified in the Windows NT <drive>:\mqm\bin\amqcrs6a
Run Listener command, or the
invokable Transaction Program
that was defined using TpSetup on
Windows NT.

If you have more than one queue manager on the same machine, ensure that the
TPnames in the channel definitions are unique.

Sending end
v On UNIX systems other than SINIX, and DC/OSx, create a CPI-C side object
(symbolic destination) and enter this name in the Connection name field in the
channel definition. Also create an LU 6.2 link to the partner.
In the CPI-C side object enter the partner LU name at the receiving machine, the
transaction program name and the mode name. For example:
Partner LU Name REMHOST
Remote TP Name recv
Service Transaction Program no
Mode Name #INTER

On HP-UX, use the APPCLLU environment variable to name the local LU that
the sender should use. On Sun Solaris, set the APPC_LOCAL_LU environment
variable to be the local LU name.

SECURITY PROGRAM is used, where supported by CPI-C, when MQSeries

attempts to establish an SNA session.
v On SINIX, create an XSYMDEST entry in SNA configuration file (the TRANSIT
KOGS file), for example:
XSYMDEST sendMP01,
RLU = forties,
MODE = MODE1,
TP = recvMP01,
TP-TYP = USER,
SEC-TYP = NONE

See the MQSeries for SINIX and DC/OSx System Management Guide for more
information about the TRANSIT KOGS file.
v On DC/OSx, create an entry in the /etc/opt/lu62/cpic_cfg file, for example:
sendMP01 <local LU name> <remote LU name> <mode name> <remote TP name>

Receiving on LU 6.2
v On UNIX systems other than SINIX, and DC/OSx, create a listening attachment
at the receiving end, an LU 6.2 logical connection profile, and a TPN profile.

Chapter 13. Setting up communication in UNIX systems 195

Defining an LU 6.2 connection
In the TPN profile, enter the full path to the executable and the Transaction
Program name:
Full path to TPN executable mqmtop/bin/amqcrs6a
Transaction Program name recv
User ID 0

On systems where you can set the User ID, you should specify a user who is a
member of the mqm group. On HP-UX, set the APPCTPN (transaction name)
and APPCLLU (local LU name) environment variables (you can use the
configuration panels for the invoked transaction program). On Sun Solaris, set
the APPC_LOCAL_LU environment variable to be the local LU name.

On Sun Solaris, amqcrs6a requires the option -n tp_name, where tp_name is the
TP name on the receiving end of the SNA connection. It is the value of the
tp_path variable in the SunLink configuration file.

You may need to use a queue manager other than the default queue manager. If
so, define a command file that calls:
amqcrs6a -m Queue_Man_Name

then call the command file. On AIX, this only applies up to version 3.2.5; for
later versions, use the TPN profile parameters as follows:
Use Command Line Parameters ? yes
Command Line Parameters -m Queue_Man_Name
v On SINIX, create an XTP entry in the SNA configuration file (the TRANSIT
KOGS file), for example:
XTP recvMP01,
UID = abcdefgh,
TYP = USER,
PATH = /home/abcdefgh/recvMP01.sh,
SECURE = NO

Where /home/abcdefgh/recvMP01.sh is a file that contains:

#!/bin/sh
#
# script to start the receiving side for the qmgr MP01
#
exec /opt/mqm/bin/amqcrs6a -m <queue manager>

See the MQSeries for SINIX and DC/OSx System Management Guide for more
information about the TRANSIT KOGS file.
v On DC/OSx, add a Transaction Program entry to the SNA configuration file,
including the following information:
TRANSACTION PROGRAM
transaction programname (ebcdic): recvMP04
transaction program execute name:
'home/abcdefgh/recvMP04.sh
tp is enabled
tp supports basic conversations
tp supports mapped conversations
tp supports confirm synchronization
tp supports no synchronization
no verification is required
number of pip fields required: 0
privilege mask (hex): 0
(no privileges)

196 MQSeries Intercommunication

 Chapter 14. Example configuration - IBM MQSeries for AIX
This chapter gives an example of how to set up communication links from
MQSeries for AIX to MQSeries products on the following platforms:
v OS/2
v Windows NT
| v Digital UNIX
v HP-UX
v AT&T GIS UNIX3
v Sun Solaris
| v OS/400
v OS/390 or MVS/ESA without CICS
v VSE/ESA

First it describes the parameters needed for an LU 6.2 connection, then it describes
“Establishing a TCP connection” on page 209 and “Establishing a UDP connection”
on page 209.

Once the connection is established, you need to define some channels to complete
the configuration. This is described in “MQSeries for AIX configuration” on
page 209.

See “Chapter 7. Example configuration chapters in this book” on page 97 for

background information about this chapter and how to use it.

Configuration parameters for an LU 6.2 connection

Table 20 presents a worksheet listing all the parameters needed to set up
communication from AIX to one of the other MQSeries platforms. The worksheet
shows examples of the parameters, which have been tested in a working
environment, and leaves space for you to fill in your own values. An explanation
of the parameter names follows the worksheet. Use the worksheet in this chapter
in conjunction with the worksheet in the chapter for the platform to which you are
connecting.

Configuration worksheet
Use the following worksheet to record the values you will use for this
configuration. Where numbers appear in the Reference column they indicate that
the value must match that in the appropriate worksheet elsewhere in this book.
The examples that follow in this chapter refer back to the values in the ID column
of this table. The entries in the Parameter Name column are explained in
“Explanation of terms” on page 200.
Table 20. Configuration worksheet for Communications Server for AIX
ID Parameter Name Reference Example User Value
Parameters for local node
«1¬ Network name NETID
«2¬ Control Point name AIXPU
«3¬ Node ID 07123456

3. This platform has become NCR UNIX SVR4 MP-RAS, R3.0

© Copyright IBM Corp. 1993, 2000 197

AIX and LU 6.2
Table 20. Configuration worksheet for Communications Server for AIX (continued)
ID Parameter Name Reference Example User Value
«4¬ Local LU name AIXLU
«5¬ Local LU alias AIXQMGR
«6¬ TP Name MQSERIES
«7¬ Full path to TP executable usr/lpp/mqm/bin/amqcrs6a
«8¬ Token-ring adapter address 123456789012
«9¬ Mode name #INTER
Connection to an OS/2 system

The values in this section of the table must match those used in Table 14 on page 138, as indicated.
«10¬ Network name «2¬ NETID
«11¬ Remote LU name «6¬ OS2LU
«12¬ Remote Transaction Program name «8¬ MQSERIES
«13¬ LU 6.2 CPI-C Side Information profile OS2CPIC
name
«14¬ Mode name «17¬ #INTER
«15¬ LAN destination address «10¬ 10005AFC5D83
«16¬ Token-Ring Link Station profile name OS2PRO
«17¬ CP name of adjacent node «3¬ OS2PU
«18¬ LU 6.2 partner location profile name OS2LOCPRO
Connection to a Windows NT system

The values in this section of the table must match those used in Table 16 on page 170, as indicated.
«10¬ Network name «2¬ NETID
«11¬ Remote LU name «5¬ WINNTLU
«12¬ Remote Transaction Program name «7¬ MQSERIES
«13¬ LU 6.2 CPI-C Side Information profile NTCPIC
name
«14¬ Mode name «17¬ #INTER
«15¬ LAN destination address «9¬ 08005AA5FAB9
«16¬ Token-Ring Link Station profile name NTPRO
«17¬ CP name of adjacent node «3¬ WINNTCP
«18¬ LU 6.2 partner LU profile name NTLUPRO
Connection to an HP-UX system

The values in this section of the table must match those used in Table 23 on page 219, as indicated.
«10¬ Network name «4¬ NETID
«11¬ Remote LU name «5¬ HPUXLU
«12¬ Remote Transaction Program name «7¬ MQSERIES
«13¬ LU 6.2 CPI-C Side Information profile HPUXCPIC
name
«14¬ Mode name «6¬ #INTER
«15¬ LAN destination address «8¬ 100090DC2C7C
«16¬ Token-Ring Link Station profile name HPUXPRO
«17¬ CP name of adjacent node «2¬ HPUXPU
«18¬ LU 6.2 partner LU profile name HPUXLUPRO
Connection to an AT&T GIS UNIX system

The values in this section of the table must match those used in Table 25 on page 243, as indicated.

198 MQSeries Intercommunication

 AIX and LU 6.2
Table 20. Configuration worksheet for Communications Server for AIX (continued)
ID Parameter Name Reference Example User Value
«10¬ Network name «2¬ NETID
«11¬ Remote LU name «4¬ GISLU
«12¬ Remote Transaction Program name «5¬ MQSERIES
«13¬ LU 6.2 CPI-C Side Information profile GISCPIC
name
«14¬ Mode name «7¬ #INTER
«15¬ LAN destination address «8¬ 10007038E86B
«16¬ Token-Ring Link Station profile name GISPRO
«17¬ CP name of adjacent node «3¬ GISPU
«18¬ LU 6.2 partner LU profile name GISLUPRO
Connection to a Sun Solaris system

The values in this section of the table must match those used in Table 27 on page 257, as indicated.
«10¬ Network name «2¬ NETID
«11¬ Remote LU name «7¬ SOLARLU
«12¬ Remote Transaction Program name «8¬ MQSERIES
«17¬ LU 6.2 CPI-C Side Information profile SOLCPIC
name
«14¬ Mode name «17¬ #INTER
«5¬ LAN destination address «5¬ 08002071CC8A
«16¬ Token-Ring Link Station profile name SOLPRO
«17¬ CP name of adjacent node «3¬ SOLARPU
«18¬ LU 6.2 partner LU profile name SOLLUPRO
Connection to an AS/400 system

The values in this section of the table must match those used in Table 42 on page 460, as indicated.
«10¬ Network name «1¬ NETID
«11¬ Remote LU name «3¬ AS400LU
«12¬ Remote Transaction Program name «8¬ MQSERIES
«13¬ LU 6.2 CPI-C Side Information profile AS4CPIC
name
«14¬ Mode name «17¬ #INTER
«15¬ LAN destination address «4¬ 10005A5962EF
«16¬ Token-Ring Link Station profile name AS4PRO
«17¬ CP name of adjacent node «2¬ AS400PU
«18¬ LU 6.2 partner LU profile name AS4LUPRO
Connection to an OS/390 or MVS/ESA system without CICS

The values in this section of the table must match those used in Table 36 on page 396, as indicated.
«10¬ Network name «2¬ NETID
«11¬ Remote LU name «3¬ MVSLU
«12¬ Remote Transaction Program name «7¬ MQSERIES
«13¬ LU 6.2 CPI-C Side Information profile MVSCPIC
name
«14¬ Mode name «10¬ #INTER
«15¬ LAN destination address «8¬ 400074511092
«16¬ Token-Ring Link Station profile name MVSPRO
«17¬ CP name of adjacent node «3¬ MVSPU

Chapter 14. Example configuration - IBM MQSeries for AIX 199

AIX and LU 6.2
Table 20. Configuration worksheet for Communications Server for AIX (continued)
ID Parameter Name Reference Example User Value
«18¬ LU 6.2 partner LU profile name MVSLUPRO
Connection to a VSE/ESA system

The values in this section of the table must match those used in Table 44 on page 485, as indicated.
«10¬ Network name «1¬ NETID
«11¬ Remote LU name «3¬ VSELU
«12¬ Remote Transaction Program name «4¬ MQ01
«13¬ LU 6.2 CPI-C Side Information profile VSECPIC
name
«14¬ Mode name #INTER
«15¬ LAN destination address «5¬ 400074511092
«16¬ Token-Ring Link Station profile name VSEPRO
«17¬ CP name of adjacent node «2¬ VSEPU
«18¬ LU 6.2 partner LU profile name VSELUPRO

Explanation of terms
«1¬Network name
This is the unique ID of the network to which you are connected. Your
network administrator will tell you this value.
«2¬ Control Point name
This is a unique control point name for this workstation. Your network
administrator will assign this to you.
«3¬ XID node ID
This is a unique identifier for this workstation. On other platforms it is
often referred to as the exchange ID (XID). Your network administrator will
assign this to you.
«4¬ Local LU name
A logical unit (LU) manages the exchange of data between systems. The
local LU name is the name of the LU on your system. Your network
administrator will assign this to you.
«5¬ Local LU alias
The local LU alias is the name by which your local LU is known to your
applications. You can choose this name yourself. It need be unique only on
this machine.
«6¬ TP Name
MQSeries applications trying to converse with this workstation will specify
a symbolic name for the program to be run at the receiving end. This will
have been defined on the channel definition at the sender. It is
recommended that when AIX is the receiver a Transaction Program Name
of MQSERIES is used, or in the case of a connection to VSE/ESA, where
the length is limited to 4 bytes, use MQTP.
See Table 19 on page 194 for more information.
«7¬ Full path to TP executable
This is the path and name of a shell script file that invokes the actual
program to be run when a conversation is initiated with this workstation.
You can choose the path and name of the script file. The contents of the
file are illustrated in “MQSeries for AIX TPN setup” on page 213.

200 MQSeries Intercommunication

 AIX and LU 6.2
«8¬ Token-ring adapter address
This is the 12-character hex address of the token-ring card. It can be found
by entering the AIX command:
lsfg -v -l tokn

where n is the number assigned to the token-ring adapter you are using.
The Network Address field of the Token-Ring section indicates the
adapter’s address.
«9¬ Mode name
This is the name of a configuration profile used by Communications Server
for AIX. The profile contains the set of parameters that control the APPC
conversation. The mode name specified in the profile will be assigned to
you by your network administrator. You supply the name to be used for
the profile.
«13¬ LU 6.2 CPI-C Side Information profile name
This is a name given to the Side Information profile defining a partner
node. You supply the name. It needs to be unique only on this machine.
You will later use the name in the MQSeries sender channel definition.
«16¬ Token-Ring Link Station profile name
This is the name of a configuration profile used by Communications Server
for AIX. You supply the name to be used for the profile. The link station
profile associates the link station with the SNA DLC profile, which has
been used to define the hardware adapter and link characteristics, and the
node control point.
«17¬ CP name of adjacent node
This is the unique control point name of the partner system which which
you are establishing communication. Your network administrator will
assign this to you.
«18¬ LU 6.2 partner LU profile name
This is the name of a configuration profile used by Communications Server
for AIX. You supply the name to be used for the profile. It needs to be
unique only on this machine. The profile defines parameters for
establishing a session with a specific partner LU. In some scenarios, this
profile may not be required but it is shown here to reduce the likelihood of
error. See the SNA Server for AIX Configuration Reference manual for details.

Chapter 14. Example configuration - IBM MQSeries for AIX 201

Using Communications Server for AIX

Establishing a session using Communications Server for AIX V5

Verify the level of Communications Server software you have installed by entering
the AIX command:
lslpp -h sna.rte

The level displayed in the response needs to be at least Version 5.0.

To update the SNA configuration profile, you need root authority. (Without root
authority you can display options and appear to modify them, but cannot actually
make any changes.) You can make configuration changes when SNA is either
active or inactive.

The configuration scenario that follows was accomplished using the graphical
interface.

Note: The setup used is APPN using independent LUs.

If you are an experienced user of AIX, you may choose to circumvent the panels
and use the command-line interface. Refer to the SNA Server for AIX Configuration
Reference manual to see the commands that correspond to the panels illustrated.

Throughout the following example, only the panels for profiles that must be added
or updated are shown.

Configuring your node

This configuration uses a token ring setup. To define the end node to connect to
the network node (assuming that a network node already exists), you need to:
1. Click on Services from the main menu on the main window.
2. Select Configuration node parameters ... from the drop-down list. A windows
entitled Node parameters appears:

3. Click on End node for APPN support.

4. In the SNA addressing box, enter a name and alias for the Control point. The
Control point name consists of a Network name («1¬) and a Control point
name («2¬).
5. Enter the Node ID («3¬) of your local machine.
6. Click on OK.
You have now configured your node to connect to the network node.

202 MQSeries Intercommunication

 Using Communications Server for AIX
Configuring connectivity to the network
1. Defining your port:
a. From the main menu of the main window, click on Services, Connectivity,
and New port ... A window entitled Add to machine name screen appears.
b. Select the default card for connecting to the network (Token ring card).
c. Click on OK. A window entitled Token ring SAP appears:

d. Enter a port name in the SNA port name box, for example, MQPORT.
e. Check Initially Active.
f. Click on OK.

Chapter 14. Example configuration - IBM MQSeries for AIX 203

Using Communications Server for AIX
2. Defining your connection to the network node:
a. From the main menu on the main window, click on Services, Connectivity,
and New link station ...
b. Click on OK to link your station to the chosen port (MQPORT). A window
entitled Token ring link station appears:

c. Enter a name for your link station («4¬), for example, NETNODE.
d. Enter the port name to which you want to connect the link station. In this
case, the port name would be MQPORT.
e. Check Any in the LU traffic box.
f. Define where the remote node is by entering the control point on the
network node in the Independent LU traffic box. The control point consists
of a Network name («10¬) and a CP name of adjacent node («17¬).

Note: The network node does not have to be on the remote system that you
are connecting to.
g. Ensure the Remote node type is Network node.
h. In the Contact information, enter the MAC address («15¬) of the token ring
card on the network node.

Note: The network node does not have to be on the remote system that you
are connecting to.

204 MQSeries Intercommunication

 Using Communications Server for AIX
i. Click on Advanced .... A window entitled Token ring parameters appears:

j. Check Remote node is network node server.

k. Click on OK. The Token ring link station window remains on the screen.
l. Click on OK on the Token ring link station window.

Defining a local LU
To define a local LU:
1. From the main menu on the main window, click on Services, APPC, and New
independent local LU .... A window entitled Local LU appears:

Figure 33. Local LU window

2. Enter an LU name («4¬) and alias («5¬).

3. Click on OK.
You have now set up a basic SNA system.

To define the mode controlling the SNA session limits:

1. From the main menu in the main window, click on Services, APPC, and Modes
.... A Modes window appears.

Chapter 14. Example configuration - IBM MQSeries for AIX 205

Using Communications Server for AIX
2. Select the New ... button. A window entitled Mode appears:

Figure 34. Mode window

3. Enter a Name («9¬) for your mode.

4. When you are happy with the session limits, click on OK. The Modes window
remains on the screen.
5. Click on Done in the Modes window.

Defining a transaction program

This section describes how to define a transaction program. To do this, use the
command line rather than the graphical interface.
1. Defining a transaction program for the receiver end of the channel:
a. Name your transaction program («6¬):
snaadmin define_tp, tp_name=MQSERIES

where MQSERIES can be any name that matches the name used on the CPI-C
side information at the sender end of the channel.
b. Define the program your transaction program (MQSERIES) relates to, that is,
the receiving MQSeries channel:
snaadmin define_tp_load_info,
tp_name=MQSERIES, userid=mqm, group=mqm,
type=NON-QUEUED, style=COMPATIBLE,
path=/usr/lpp/mqm/bin/amqcrs6a,
arguments=-m AIX -n MQSERIES

where AIX and MQSERIES can be upper or lower case but must be the same
throughout.

206 MQSeries Intercommunication

 Using Communications Server for AIX
c. View the definition you have just created through the graphical interface:
1) From the main window, click on Services, APPC, and Transaction
programs ... A window entitled TP invocation appears for you to view
your configuration:

2) Verify the Application TP («6¬).

3) Verify the Full path to TP executable («7¬).

Chapter 14. Example configuration - IBM MQSeries for AIX 207

Using Communications Server for AIX
2. Defining the CPI-C side information for the sender channel: You can define the
CPI-C side information for the sender channel using the graphical interface:
a. From the main menu on the main window, click on Services, APPC, and
CPI-C .... A CPI-C destination names window appears.
b. Click on the New ... button. A window entitled CPI-C destination appears:

This window lets you define the LU that you want to connect to and the
transaction program you want to start:
c. Enter a Name, («13¬). You must specify this name in the CONNAME
parameter of the channel.
d. Check Specify local LU alias and enter the LU alias value («5¬).
e. In the Partner LU and mode box, check Use PLU full name and enter the
name of the remote machine to which you are connecting. This consists of a
Network name («10¬) and a Remote LU name («11¬).
f. Enter the Mode («14¬).

To start the transaction program on the remote machine:

a. Check Application TP in the Partner TP box.
b. Enter the name of the transaction program («12¬).
c. Click on OK.

208 MQSeries Intercommunication

 AIX and TCP

Establishing a TCP connection

1. Edit the file /etc/services.

Note: To edit the /etc/services file, you must be logged in as a superuser or

root. If you do not have the following line in that file, add it as shown:
MQSeries 1414/tcp # MQSeries channel listener
2. Edit the file /etc/inetd.conf. If you do not have the following line in that file,
add it as shown:
MQSeries stream tcp nowait root /usr/mqm/bin/amqcrsta amqcrsta
[-m queue.manager.name]
3. Enter the command refresh -s inetd.

What next?
The connection is now established. You are ready to complete the configuration.
Go to “MQSeries for AIX configuration”.

Establishing a UDP connection

To establish a UDP connection, ensure a listener is started by issuing the following
MQSC command:
runmqlsr -m QMgrName -t UDP -p 1414
Notes:
1. You cannot start a listener channel on AIX using the START LISTENER MQSC
command.
2. Using the runmqlsr command implies that you must not add entries to the
/etc/services and /etc/inetd.conf file for UDP on MQSeries for AIX.

What next?
The connection is now established. You are ready to complete the configuration.
Go to “MQSeries for AIX configuration”.

MQSeries for AIX configuration

Notes:
1. Before beginning the installation process ensure that you have first created the
mqm user and group, and set the password.
2. If installation fails as a result of insufficient space in the file system you can
increase the size as follows, using the command smit C sna. (Use df to display
the current status of the file system. This will indicate the logical volume that is
full.)
-- Physical and Logical Storage
-- File Systems
-- Add / Change / Show / Delete File Systems
-- Journaled File Systems
-- Change/Show Characteristics of a Journaled File System
3. Start any channel using the command:
runmqchl -c channel.name
4. Sample programs are installed in /usr/mqm/samp.
5. Error logs are stored in /var/mqm/qmgrs/qmgrname/errors.
6. You can start an AIX trace of the MQSeries components using the command:
trace -a -j30D,30E -o trace.file

Chapter 14. Example configuration - IBM MQSeries for AIX 209

AIX configuration
You can stop AIX trace by entering:
trcstop

Format the trace report using the command:

trcrpt -t /usr/mqm/samp/amqtrc.fmt trace.file > trace.report
7. When you are using the command interpreter runmqsc to enter administration
commands, a + at the end of a line indicates that the next line is a continuation.
Ensure that there is a space between the last parameter and the continuation
character.

Basic configuration
1. Create the queue manager from the AIX command line using the command:
crtmqm -u dlqname -q aix

where:
aix Is the name of the queue manager
-q Indicates that this is to become the default queue manager
-u dlqname
Specifies the name of the undeliverable message queue

This command creates a queue manager and a set of default objects.

2. Start the queue manager from the AIX command line using the command:
strmqm aix

where aix is the name given to the queue manager when it was created.
3. Start runmqsc from the AIX command line and use it to create the
undeliverable message queue by entering the command:
def ql (dlqname)

where dlqname is the name given to the undeliverable message queue when the
queue manager was created.

Channel configuration
The following section details the configuration to be performed on the AIX queue
manager to implement the channel described in Figure 32 on page 97.

In each case the MQSC command is shown. Either start runmqsc from an AIX
command line and enter each command in turn, or build the commands into a
command file.

Examples are given for connecting MQSeries for AIX and MQSeries for OS/2
Warp. If you wish to connect to another MQSeries product use the appropriate set
of values from the table in place of those for OS/2.

Note: The words in bold are user-specified and reflect the names of MQSeries
objects used throughout these examples. If you change the names used here,
ensure that you also change the other references made to these objects
throughout this book. All others are keywords and should be entered as
shown.

210 MQSeries Intercommunication

 AIX configuration
Table 21. Configuration worksheet for MQSeries for AIX
ID Parameter Name Reference Example Used User Value
Definition for local node
«A¬ Queue Manager Name AIX
«B¬ Local queue name AIX.LOCALQ
Connection to MQSeries for OS/2 Warp

The values in this section of the table must match those used in Table 15 on page 164, as indicated.
«C¬ Remote queue manager name «A¬ OS2
«D¬ Remote queue name OS2.REMOTEQ
«E¬ Queue name at remote system «B¬ OS2.LOCALQ
«F¬ Transmission queue name OS2
«G¬ Sender (SNA) channel name AIX.OS2.SNA
«H¬ Sender (TCP/IP) channel name AIX.OS2.TCP
«I¬ Receiver (SNA) channel name «G¬ OS2.AIX.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ OS2.AIX.TCP
Connection to MQSeries for Windows NT

The values in this section of the table must match those used in Table 17 on page 185, as indicated.
«C¬ Remote queue manager name «A¬ WINNT
«D¬ Remote queue name WINNT.REMOTEQ
«E¬ Queue name at remote system «B¬ WINNT.LOCALQ
«F¬ Transmission queue name WINNT
«G¬ Sender (SNA) channel name AIX.WINNT.SNA
«H¬ Sender (TCP/IP) channel name AIX.WINNT.TCP
«I¬ Receiver (SNA) channel name «G¬ WINNT.AIX.SNA
«J¬ Receiver (TCP) channel name «H¬ WINNT.AIX.TCP
| Connection to MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| The values in this section of the table must match those used in Table 22 on page 216, as indicated.
| «C¬ Remote queue manager name «A¬ DECUX
| «D¬ Remote queue name DECUX.REMOTEQ
| «E¬ Queue name at remote system «B¬ DECUX.LOCALQ
| «F¬ Transmission queue name DECUX
| «H¬ Sender (TCP) channel name DECUX.AIX.TCP
| «J¬ Receiver (TCP) channel name «H¬ AIX.DECUX.TCP
Connection to MQSeries for HP-UX

The values in this section of the table must match those used in Table 24 on page 239, as indicated.
«C¬ Remote queue manager name «A¬ HPUX
«D¬ Remote queue name HPUX.REMOTEQ
«E¬ Queue name at remote system «B¬ HPUX.LOCALQ
«F¬ Transmission queue name HPUX
«G¬ Sender (SNA) channel name AIX.HPUX.SNA
«H¬ Sender (TCP) channel name AIX.HPUX.TCP
«I¬ Receiver (SNA) channel name «G¬ HPUX.AIX.SNA
«J¬ Receiver (TCP) channel name «H¬ HPUX.AIX.TCP
Connection to MQSeries for AT&T GIS UNIX

The values in this section of the table must match those used in Table 26 on page 253, as indicated.

Chapter 14. Example configuration - IBM MQSeries for AIX 211

 AIX configuration
Table 21. Configuration worksheet for MQSeries for AIX (continued)
ID Parameter Name Reference Example Used User Value
«C¬ Remote queue manager name «A¬ GIS
«D¬ Remote queue name GIS.REMOTEQ
«E¬ Queue name at remote system «B¬ GIS.LOCALQ
«F¬ Transmission queue name GIS
«G¬ Sender (SNA) channel name AIX.GIS.SNA
«H¬ Sender (TCP) channel name AIX.GIS.TCP
«I¬ Receiver (SNA) channel name «G¬ GIS.AIX.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ GIS.AIX.TCP
Connection to MQSeries for Sun Solaris

The values in this section of the table must match those used in Table 28 on page 272, as indicated.
«C¬ Remote queue manager name SOLARIS
«D¬ Remote queue name SOLARIS.REMOTEQ
«E¬ Queue name at remote system «B¬ SOLARIS.LOCALQ
«F¬ Transmission queue name SOLARIS
«G¬ Sender (SNA) channel name AIX.SOLARIS.SNA
«H¬ Sender (TCP/IP) channel name AIX.SOLARIS.TCP
«I¬ Receiver (SNA) channel name «G¬ SOLARIS.AIX.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ SOLARIS.AIX.TCP
| Connection to MQSeries for AS/400

| The values in this section of the table must match those used in Table 43 on page 472, as indicated.
| «C¬ Remote queue manager name AS400
| «D¬ Remote queue name AS400.REMOTEQ
| «E¬ Queue name at remote system «B¬ AS400.LOCALQ
| «F¬ Transmission queue name AS400
| «G¬ Sender (SNA) channel name AIX.AS400.SNA
| «H¬ Sender (TCP) channel name AIX.AS400.TCP
| «I¬ Receiver (SNA) channel name «G¬ AS400.AIX.SNA
| «J¬ Receiver (TCP) channel name «H¬ AS400.AIX.TCP
Connection to MQSeries for OS/390 or MVS/ESA without CICS

The values in this section of the table must match those used in Table 37 on page 406, as indicated.
«C¬ Remote queue manager name MVS
«D¬ Remote queue name MVS.REMOTEQ
«E¬ Queue name at remote system «B¬ MVS.LOCALQ
«F¬ Transmission queue name MVS
«G¬ Sender (SNA) channel name AIX.MVS.SNA
«H¬ Sender (TCP) channel name AIX.MVS.TCP
«I¬ Receiver (SNA) channel name «G¬ MVS.AIX.SNA
«J¬ Receiver (TCP) channel name «H¬ MVS.AIX.TCP
Connection to MQSeries for VSE/ESA

The values in this section of the table must match those used in Table 45 on page 490, as indicated.
«C¬ Remote queue manager name VSE
«D¬ Remote queue name VSE.REMOTEQ
«E¬ Queue name at remote system «B¬ VSE.LOCALQ
«F¬ Transmission queue name VSE

212 MQSeries Intercommunication

 AIX configuration
Table 21. Configuration worksheet for MQSeries for AIX (continued)
ID Parameter Name Reference Example Used User Value
«G¬ Sender channel name AIX.VSE.SNA
«I¬ Receiver channel name «G¬ VSE.AIX.SNA

MQSeries for AIX sender-channel definitions using SNA

def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (AIX.OS2.SNA) chltype(sdr) + «G¬

trptype(lu62) +
conname('OS2CPIC') + «17¬
xmitq(OS2) + «F¬
replace

MQSeries for AIX receiver-channel definitions using SNA

def ql (AIX.LOCALQ) replace «B¬

def chl (OS2.AIX.SNA) chltype(rcvr) + «I¬

trptype(lu62) +
replace

MQSeries for AIX TPN setup

During the AIX Communications Server configuration process, an LU 6.2 TPN
profile was created, which contained the full path to a TP executable. In the
example the file was called u/interops/AIX.crs6a. You can choose a name, but you
are recommended to include the name of your queue manager in it. The contents
of the executable file must be:
#!/bin/sh
/opt/mqm/bin/amqcrs6a -m aix

where aix is the queue manager name («A¬). After creating this file, enable it for
execution by running the command:
chmod 755 /u/interops/AIX.crs6a

As an alternative to creating an executable file, you can specify the path on the
Add LU 6.2 TPN Profile panel, using command line parameters.

Specifying a path in one of these two ways ensures that SNA receiver channels
activate correctly when a sender channel initiates a conversation.

MQSeries for AIX sender-channel definitions using TCP

def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

Chapter 14. Example configuration - IBM MQSeries for AIX 213

AIX configuration
def chl (AIX.OS2.TCP) chltype(sdr) + «H¬
trptype(tcp) +
conname(remote_tcpip_hostname) +
xmitq(OS2) + «F¬
replace

MQSeries for AIX receiver-channel definitions using TCP

def ql (AIX.LOCALQ) replace «B¬

def chl (OS2.AIX.TCP) chltype(rcvr) + «J¬

trptype(tcp) +
replace

MQSeries for AIX sender-channel definitions using UDP

def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (AIX.OS2.UDP) chltype(sdr) + «H¬

trptype(udp) +
conname(remote_udpip_hostname) +
xmitq(OS2) + «F¬
replace

MQSeries for AIX receiver-channel definitions using UDP

def ql (AIX.LOCALQ) replace «B¬

def chl (OS2.AIX.UDP) chltype(rcvr) + «J¬

trptype(udp) +
replace

214 MQSeries Intercommunication

 Chapter 15. Example configuration - IBM MQSeries for
DIGITAL UNIX (Compaq Tru64 UNIX)
| This chapter shows how to set up TCP communication links from MQSeries for
| DIGITAL UNIX (Compaq Tru64 UNIX) to MQSeries products on other platforms.

| Note: MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX), V2.2.1 supports the
| TCP communication protocol only.

| Once the connection is established, you need to define some channels to complete
| the configuration. This process is described in “MQSeries for DIGITAL UNIX
| (Compaq Tru64 UNIX) configuration”.

| See “Chapter 7. Example configuration chapters in this book” on page 97 for

| background information about this chapter and how to use it.

Establishing a TCP connection

| 1. Edit the file /etc/services.

| Note: To edit the /etc/services file, you must be logged in as a superuser or

| root. If you do not have the following line in that file, add it as shown:
| MQSeries 1414/tcp # MQSeries channel listener
| 2. Edit the file /etc/inetd.conf. If you do not have the following line in that file,
| add it as shown:
| MQSeries stream tcp nowait root /opt/mqm/bin/amqcrsta amqcrsta
| [-m queue.manager.name]
| 3. Find the process ID of the inetd with the command:
| ps -ef | grep inetd
| 4. Run the command:
| kill -1 inetd processid

| What next?
| Inetd is now ready to listen for incoming requests and pass them to MQSeries. You
| are ready to complete the configuration as described in the next section.
|
| MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX) configuration
| Before beginning the installation process ensure that you have first created the
| mqm user and group, and set the password.

| Start any channel using the command:

| runmqchl -c channel.name -m qmname
| Notes:
| 1. Sample programs are installed in /opt/mqm/samp.
| 2. Error logs are stored in /var/mqm/qmgrs/qmname/errors.

© Copyright IBM Corp. 1993, 2000 215

 Digital UNIX configuration
| 3. When you are using the command interpreter runmqsc to enter administration
| commands, a + at the end of a line indicates that the next line is a continuation.
| Ensure that there is a space between the last parameter and the continuation
| character.

| Basic configuration
| 1. Create the queue manager from the UNIX prompt using the command:
| crtmqm -u dlqname -q qmname

| where:
| qmname Is the name of the queue manager
| -q Indicates that this is to become the default queue manager
| -u dlqname
| Specifies the name of the undeliverable message queue

| This command creates a queue manager and sets the DEADQ attribute of the
| queue manager, but does not create the undeliverable message queue.
| 2. Start the queue manager from the UNIX prompt using the command:
| strmqm qmname

| where qmname is the name given to the queue manager when it was created.

| Channel configuration
| This section describes the configuration to be performed on the Digital UNIX
| queue manager to implement the single channel, and the MQSeries objects
| associated with it.

| Examples are given at the end of this chapter for connecting MQSeries for
| DIGITAL UNIX (Compaq Tru64 UNIX) and MQSeries for OS/2 Warp. If you wish
| to connect to another MQSeries product use the appropriate set of values from the
| table in place of those for OS/2.

| In each example, the MQSC command is shown. Either start runmqsc from a
| UNIX prompt and enter each command in turn, or build the commands into a
| command file.

| Note: The words in bold are user-specified and reflect the names of MQSeries
| objects used throughout these examples. All others are keywords and should
| be entered as shown.
| Table 22. Configuration worksheet for MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)
| ID Parameter Name Reference Example Used User Value
| Definition for local node
| «A¬ Queue Manager Name DECUX
| «B¬ Local queue name DECUX.LOCALQ
| Connection to MQSeries for OS/2 Warp

| The values in this section of the table must match those used in Table 15 on page 164.
| «C¬ Remote queue manager name «A¬ OS2
| «D¬ Remote queue name OS2.REMOTEQ
| «E¬ Queue name at remote system «B¬ OS2.LOCALQ
| «F¬ Transmission queue name OS2

216 MQSeries Intercommunication

 Digital UNIX configuration
| Table 22. Configuration worksheet for MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX) (continued)
| ID Parameter Name Reference Example Used User Value
| «H¬ Sender (TCP) channel name DECUX.OS2.TCP
| «J¬ Receiver (TCP) channel name «H¬ OS2.DECUX.TCP
| Connection to MQSeries for Windows NT

| The values in this section of the table must match those used in Table 17 on page 185.
| «C¬ Remote queue manager name «A¬ WINNT
| «D¬ Remote queue name WINNT.REMOTEQ
| «E¬ Queue name at remote system «B¬ WINNT.LOCALQ
| «F¬ Transmission queue name WINNT
| «H¬ Sender (TCP) channel name DECUX.WINNT.TCP
| «J¬ Receiver (TCP) channel name «H¬ WINNT.DECUX.TCP
| Connection to MQSeries for AIX

| The values in this section of the table must match those used in Table 21 on page 211.
| «C¬ Remote queue manager name «A¬ AIX
| «D¬ Remote queue name AIX.REMOTEQ
| «E¬ Queue name at remote system «B¬ AIX.LOCALQ
| «F¬ Transmission queue name AIX
| «H¬ Sender (TCP) channel name DECUX.AIX.TCP
| «J¬ Receiver (TCP) channel name «H¬ AIX.DECUX.TCP
| Connection to MQSeries for AT&T GIS UNIX

| The values in this section of the table must match those used in Table 26 on page 253.
| «C¬ Remote queue manager name «A¬ GIS
| «D¬ Remote queue name GIS.REMOTEQ
| «E¬ Queue name at remote system «B¬ GIS.LOCALQ
| «F¬ Transmission queue name GIS
| «H¬ Sender (TCP) channel name DECUX.GIS.TCP
| «J¬ Receiver (TCP) channel name «H¬ GIS.DECUX.TCP
| Connection to MQSeries for Sun Solaris

| The values in this section of the table must match those used in Table 28 on page 272.
| «C¬ Remote queue manager name «A¬ SOLARIS
| «D¬ Remote queue name SOLARIS.REMOTEQ
| «E¬ Queue name at remote system «B¬ SOLARIS.LOCALQ
| «F¬ Transmission queue name SOLARIS
| «H¬ Sender (TCP) channel name DECUX.SOLARIS.TCP
| «J¬ Receiver (TCP) channel name «H¬ SOLARIS.DECUX.TCP
| Connection to MQSeries for AS/400.

| The values in this section of the table must match those used in Table 43 on page 472.
| «C¬ Remote queue manager name «A¬ AS400
| «D¬ Remote queue name AS400.REMOTEQ
| «E¬ Queue name at remote system «B¬ AS400.LOCALQ
| «F¬ Transmission queue name AS400
| «H¬ Sender (TCP) channel name DECUX.AS400.TCP
| «J¬ Receiver (TCP) channel name «H¬ AS400.DECUX.TCP

Chapter 15. Example configuration - IBM MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX) 217
 Digital UNIX configuration
| Table 22. Configuration worksheet for MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX) (continued)
| ID Parameter Name Reference Example Used User Value
| Connection to MQSeries for OS/390 without CICS

| The values in this section of the table must match those used in Table 37 on page 406.
| «C¬ Remote queue manager name «A¬ MVS
| «D¬ Remote queue name MVS.REMOTEQ
| «E¬ Queue name at remote system «B¬ MVS.LOCALQ
| «F¬ Transmission queue name MVS
| «H¬ Sender (TCP) channel name DECUX.MVS.TCP
| «J¬ Receiver (TCP) channel name «H¬ MVS.DECUX.TCP
| Connection to MQSeries for VSE/ESA

| The values in this section of the table must match those used in Table 45 on page 490.
| «C¬ Remote queue manager name «A¬ VSE
| «D¬ Remote queue name VSE.REMOTEQ
| «E¬ Queue name at remote system «B¬ VSE.LOCALQ
| «F¬ Transmission queue name VSE
| «G¬ Sender (SNA) channel name DECUX.VSE.SNA
| «I¬ Receiver (SNA) channel name «G¬ VSE.DECUX.SNA
|

| MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| sender-channel definitions using TCP/IP
| def ql (OS2) + «F¬
| usage(xmitq) +
| replace
|
| def qr (OS2.REMOTEQ) + «D¬
| rname(OS2.LOCALQ) + «E¬
| rqmname(OS2) + «C¬
| xmitq(OS2) + «F¬
| replace
|
| def chl (DECUX.OS2.TCP) chltype(sdr) + «H¬
| trptype(tcp) +
| conname(remote_tcpip_hostname) +
| xmitq(OS2) + «F¬
| replace

| MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| receiver-channel definitions using TCP/IP
| def ql (DECUX.LOCALQ) replace «B¬
|
| def chl (OS2.DECUX.TCP) chltype(rcvr) + «J¬
| trptype(tcp) +
| replace

218 MQSeries Intercommunication

|

Chapter 16. Example configuration - IBM MQSeries for HP-UX

This chapter gives an example of how to set up communication links from
MQSeries for HP-UX to MQSeries products on the following platforms:
v OS/2
v Windows NT
v AIX
| v Digital UNIX
v AT&T GIS UNIX4
v Sun Solaris
| v OS/400
v OS/390 or MVS/ESA without CICS
v VSE/ESA

First it describes the parameters needed for an LU 6.2 connection, then it describes
“Establishing a session using HP SNAplus2” on page 223 and “Establishing a TCP
connection” on page 237.

Once the connection is established, you need to define some channels to complete
the configuration. This is described in “MQSeries for HP-UX configuration” on
page 238.

See “Chapter 7. Example configuration chapters in this book” on page 97 for

background information about this chapter and how to use it.

Configuration parameters for an LU 6.2 connection

Table 23 presents a worksheet listing all the parameters needed to set up
communication from HP-UX to one of the other MQSeries platforms. The
worksheet shows examples of the parameters, which have been tested in a
working environment, and leaves space for you to fill in your own values. An
explanation of the parameter names follows the worksheet. Use the worksheet in
this chapter in conjunction with the worksheet in the chapter for the platform to
which you are connecting.

Configuration worksheet
Use this worksheet to record the values you use for your configuration. Where
numbers appear in the Reference column they indicate that the value must match
that in the appropriate worksheet elsewhere in this book. The examples that follow
in this chapter refer back to the values in the ID column. The entries in the
Parameter Name column are explained in “Explanation of terms” on page 222.
Table 23. Configuration worksheet for HP SNAplus2
ID Parameter Name Reference Example User Value
Parameters for local node
«1¬ Configuration file name sna_node.cfg
«2¬ Control point name HPUXPU
«3¬ Node ID to send 05D 54321
«4¬ Network name NETID

4. This platform has become NCR UNIX SVR4 MP-RAS, R3.0

© Copyright IBM Corp. 1993, 2000 219

HP-UX and LU 6.2
Table 23. Configuration worksheet for HP SNAplus2 (continued)
ID Parameter Name Reference Example User Value
«5¬ Local APPC LU HPUXLU
«6¬ APPC mode #INTER
«7¬ Invokable TP MQSERIES
«8¬ Token-Ring adapter address 100090DC2C7C
«9¬ Port name MQPORT
«10¬ Full path to executable /opt/mqm/bin/amqcrs6a
«11¬ Local queue manager hpux
Connection to an OS/2 system

The values in this section of the table must match those used in Table 14 on page 138, as indicated.
«12¬ Link station name OS2CONN
«13¬ Network name «2¬ NETID
«14¬ CP name «3¬ OS2PU
«15¬ Remote LU «6¬ OS2LU
«16¬ Application TP «8¬ MQSERIES
«17¬ Mode name «17¬ #INTER
«18¬ CPI-C symbolic destination name OS2CPIC
«19¬ Remote network address «10¬ 10005AFC5D83
«20¬ Node ID to receive «4¬ 05D 12345
Connection to a Windows NT system

The values in this section of the table must match those used in Table 16 on page 170, as indicated.
«12¬ Link station name NTCONN
«13¬ Network name «2¬ NETID
«14¬ CP name «3¬ WINNTCP
«15¬ Remote LU «5¬ WINNTLU
«16¬ Application TP «7¬ MQSERIES
«17¬ Mode name «17¬ #INTER
«18¬ CPI-C symbolic destination name NTCPIC
«19¬ Remote network address «9¬ 08005AA5FAB9
«20¬ Node ID to receive «4¬ 05D 30F65
Connection to an AIX system

The values in this section of the table must match those used in Table 20 on page 197, as indicated.
«12¬ Link station name AIXCONN
«13¬ Network name «1¬ NETID
«14¬ CP name «2¬ AIXPU
«15¬ Remote LU «4¬ AIXLU
«16¬ Application TP «6¬ MQSERIES
«17¬ Mode name «14¬ #INTER
«18¬ CPI-C symbolic destination name AIXCPIC
«19¬ Remote network address «8¬ 123456789012
«20¬ Node ID to receive «3¬ 071 23456
Connection to an AT&T GIS UNIX system

The values in this section of the table must match those used in the table Table 25 on page 243, as indicated.
«12¬ Link station name GISCONN
«13¬ Network name «2¬ NETID

220 MQSeries Intercommunication

 HP-UX and LU 6.2
Table 23. Configuration worksheet for HP SNAplus2 (continued)
ID Parameter Name Reference Example User Value
«14¬ CP name «3¬ GISPU
«15¬ Remote LU GISLU
«16¬ Application TP «5¬ MQSERIES
«17¬ Mode name «7¬ #INTER
«18¬ CPI-C symbolic destination name GISCPIC
«19¬ Remote network address «8¬ 10007038E86B
«20¬ Node ID to receive «9¬ 03E 00018
Connection to a Sun Solaris system

The values in this section of the table must match those used in Table 27 on page 257, as indicated.
«12¬ Link station name SOLCONN
«13¬ Network name «2¬ NETID
«14¬ CP name «3¬ SOLARPU
«15¬ Remote LU «7¬ SOLARLU
«16¬ Application TP «8¬ MQSERIES
«17¬ Mode name «17¬ #INTER
«18¬ CPI-C symbolic destination name SOLCPIC
«19¬ Remote network address «5¬ 08002071CC8A
«20¬ node ID to receive «6¬ 05D 310D6
Connection to an AS/400 system

The values in this section of the table must match those used in Table 42 on page 460, as indicated.
«12¬ Link station name AS4CONN
«13¬ Network name «1¬ NETID
«14¬ CP name «2¬ AS400PU
«15¬ Remote LU «3¬ AS400LU
«16¬ Application TP «8¬ MQSERIES
«17¬ Mode name «17¬ #INTER
«18¬ CPI-C symbolic destination name AS4CPIC
«19¬ Remote network address «4¬ 10005A5962EF
Connection to an OS/390 or MVS/ESA system without CICS

The values in this section of the table must match those used in Table 36 on page 396, as indicated.
«12¬ Link station name MVSCONN
«13¬ Network name «2¬ NETID
«14¬ CP name «3¬ MVSPU
«15¬ Remote LU «4¬ MVSLU
«16¬ Application TP «7¬ MQSERIES
«17¬ Mode name «10¬ #INTER
«18¬ CPI-C symbolic destination name MVSCPIC
«19¬ Remote network address «8¬ 400074511092
Connection to a VSE/ESA system

The values in this section of the table must match those used in Table 44 on page 485, as indicated.
«12¬ Link station name VSECONN
«13¬ Network name «1¬ NETID
«14¬ CP name «2¬ VSEPU
«15¬ Remote LU «3¬ VSELU

Chapter 16. Example configuration - IBM MQSeries for HP-UX 221

HP-UX and LU 6.2
Table 23. Configuration worksheet for HP SNAplus2 (continued)
ID Parameter Name Reference Example User Value
«16¬ Application TP «4¬ MQ01 MQ01
«17¬ Mode name #INTER
«18¬ CPI-C symbolic destination name VSECPIC
«19¬ Remote network address «5¬ 400074511092

Explanation of terms
«1¬ Configuration file name
This is the unique name of the SNAplus2 configuration file. The default for
this name is sna_node.cfg.
Although it is possible to edit this file it is strongly recommended that
configuration is done using xsnapadmin.
«2¬ Control point name
This is the unique Control point name for this workstation. In the SNA
network, the Control point is an addressable location (PU type 2.1). Your
network administrator will assign this to you.
«3¬ Node ID to send
This is the unique ID of this workstation. On other platforms this is often
referred to as the Exchange ID or XID. Your network administrator will
assign this ID for you.
«4¬ Network name
This is the unique ID of the network to which you are connected. It is an
alphanumeric value and can be 1-8 characters long. The network name
works with the Control point name to uniquely identify a system. Your
network administrator will tell you the value.
«5¬ Local APPC LU
An LU manages the exchange of data between transactions. The local
APPC LU name is the name of the LU on your system. Your network
administrator will assign this to you.
«6¬ APPC mode
This is the name given to the set of parameters that control the APPC
conversation. This name must be defined at each partner system. Your
network administrator will assign this to you.
«7¬ Invokable TP
MQSeries applications trying to converse with this workstation will specify
a symbolic name for the program to be run at the receiving end. This will
have been defined on the channel definition at the sender. For simplicity,
wherever possible use a transaction program name of MQSERIES, or in the
case of a connection to VSE/ESA, where the length is limited to 4 bytes,
use MQTP.
See Table 19 on page 194 for more information.
«8¬ Token-ring adapter address
Use the HP-UX System Administration Manager (SAM) to discover the
adapter address for this workstation. You need root authority to use SAM.
From the initial menu, select Networking and Communications, then
select Network Interface cards followed by LAN 0 (or whichever LAN
you are using). The adapter address is displayed under the heading Station

222 MQSeries Intercommunication

 HP-UX and LU 6.2
Address (hex). The card name represents the appropriate card type. If you
do not have root level authority, your HP-UX system administrator can tell
you the value.
«9¬ Port name
This is a meaningful symbolic name that is used to associate the definitions
with a network interface (in this case, a Token-Ring adapter). A separate
Port must be defined for each physical device attached to the workstation.
«10¬ Full path to executable
On HP SNAplus2 Release 5, this is the path and name of a shell script file
that invokes the actual program to be run when a conversation is initiated
with this workstation. You can choose the path and name of the script file.
The contents of the file are illustrated in “MQSeries for HP-UX invokable
TP setup” on page 241. On HP SNAplus2 Release 6, this is the path and
name of the program to be run when a conversation is initiated with this
workstation. You enter the path in the TP invocation screen (see “Adding
a TP definition using HP SNAplus2 Release 6” on page 235).
«11¬ Local queue manager
This is the name of the queue manager on your local system.
«10¬ Link station name
This is a meaningful symbolic name by which the connection to a peer or
host node is known. It defines a logical path to the remote system. Its
name is used only inside SNAplus2 and is specified by you. The
connection must be associated with an existing Link and owned by one
local node. You must define one connection for each partner or host
system.
«18¬ CPI-C symbolic destination name
This is a name given to the definition of a partner node. You choose the
name. It need be unique only on this machine. Later you can use this name
in the MQSeries sender channel definition.
«20¬ Node ID to receive
This is the unique ID of the partner workstation with which you will be
communicating. On other platforms this is often referred to as the Exchange
ID or XID. For a connection to a host system any values except 000 FFFFF
and FFF FFFFF may be specified. Your network administrator will assign
this ID for you.

Establishing a session using HP SNAplus2

The following information guides you through the tasks you must perform to
create the SNA infrastructure that MQSeries requires. This example creates the
definitions for a partner node and LU on OS/2.

Use snap start followed by xsnapadmin to enter the HP SNAplus2 configuration

panels. You need root authority to use xsnapadmin.

SNAplus2 configuration
SNAplus2 configuration involves the following steps:
1. Defining a local node
2. Adding a Token Ring Port
3. Defining a local LU

Chapter 16. Example configuration - IBM MQSeries for HP-UX 223

Using HP SNAplus2
The SNAplus2 main menu, from which you will start, is shown below:

224 MQSeries Intercommunication

 Using HP SNAplus2
Defining a local node
1. From the SNAplus2 main menu, select the Services pull-down:

2. Select Configure node parameters.... The following panel is displayed:

3. Complete the Control point name with the values Network name («4¬) and
Control point name («2¬).
4. Enter the Control point name («2¬) in the Control point alias field.
5. Enter the Node ID («3¬).
6. Select End node.
7. Press OK.
A default independent local LU is defined.

Adding a Token Ring Port

1. From the main SNAplus2 menu, select the Connectivity and dependent LUs
panel.
2. Press Add. The following panel is displayed:

Chapter 16. Example configuration - IBM MQSeries for HP-UX 225

Using HP SNAplus2

3. Select a Token Ring Card port and press OK. The following panel is displayed:

4. Enter the SNA port name («9¬).

5. Enter a Description and press OK to take the default values.

Defining a local LU
1. From the main SNAplus2 menu, select the Independent local LUs panel.
2. Press Add. The following panel is displayed:

226 MQSeries Intercommunication

 Using HP SNAplus2

3. Enter the LU name («5¬) and press OK.

APPC configuration
APPC configuration involves the following steps:
1. Defining a remote node
2. Defining a partner LU
3. Defining a link station
4. Defining a mode
5. Adding CPI-C information
6. Adding a TP definition

Defining a remote node

1. From the main SNAplus2 menu, select the Remote systems panel.
2. Press Add. The following panel is displayed:

3. Select Define remote node and press OK. The following panel is displayed:

Chapter 16. Example configuration - IBM MQSeries for HP-UX 227

Using HP SNAplus2

4. Enter the Node’s SNA network name («13¬) and a Description.

5. Press OK.
6. A default partner LU with the same name is generated and a message is
displayed.
7. Press OK.

Defining a partner LU
1. From the main SNAplus2 menu, select the remote node in the Remote systems
panel.
2. Press Add. The following panel is displayed:

3. Select Define partner LU on node node name.

4. Press OK. The following panel is displayed:

228 MQSeries Intercommunication

 Using HP SNAplus2

5. Enter the partner LU name («15¬) and press OK.

Defining a link station

1. From the main SNAplus2 menu, select the Connectivity and dependent LUs
panel.
2. Select the MQPORT port.
3. Press Add. The following panel is displayed:

4. Select Add link station to port MQPORT.

5. Press OK. The following panel is displayed:

Chapter 16. Example configuration - IBM MQSeries for HP-UX 229

Using HP SNAplus2

6. Enter the Name of the link station («12¬).

7. Set the value of Activation to “On demand”.
8. Select Independent only.
9. Press Remote node... and select the value of the remote node («14¬).
10. Press OK.
11. Set the value of Remote node type to “End or LEN node”.
12. Enter the value for MAC address («19¬) and press Advanced.... The following
panel is displayed:

230 MQSeries Intercommunication

 Using HP SNAplus2

13. Select Reactivate link station after failure.

14. Press OK to exit the Advanced... panel.
15. Press OK again.

Defining a mode
1. From the SNAplus2 main menu, select the Services pull-down: The following
panel is displayed:

2. Select APPC. The following panel is displayed:

Chapter 16. Example configuration - IBM MQSeries for HP-UX 231

Using HP SNAplus2

3. Select Modes.... The following panel is displayed:

4. Press Add. The following panel is displayed:

232 MQSeries Intercommunication

 Using HP SNAplus2

5. Enter the Name to be given to the mode («17¬).

6. Set the values of Initial session limit to 8, Min con. winner sessions to 4, and
Auto-activated sessions to 0.
7. Press OK.
8. Press Done.

Adding CPI-C information

1. From the SNAplus2 main menu, select the Services pull-down:

2. Select APPC. The following panel is displayed:

Chapter 16. Example configuration - IBM MQSeries for HP-UX 233

Using HP SNAplus2

3. Select CPI-C.... The following panel is displayed:

4. Press Add. The following panel is displayed:

234 MQSeries Intercommunication

 Using HP SNAplus2

5. Enter the Name («18¬). Select Application TP and enter the value («16¬). Select
Use PLU alias and enter the name («15¬). Enter the Mode name («17¬).
6. Press OK.

Adding a TP definition using HP SNAplus2 Release 5

Invokable TP definitions are kept in the file /etc/opt/sna/sna_tps. This should be
edited to add a TP definition. Add the following lines:
[MQSERIES]
PATH = /users/interops/HPUX.crs6a
TYPE = NON-QUEUED
USERID = mqm
ENV = APPCLLU=HPUXLU
ENV = APPCTPN=MQSERIES

See “MQSeries for HP-UX invokable TP setup” on page 241 for more information
about TP definitions.

Adding a TP definition using HP SNAplus2 Release 6

To add a TP definition:
1. Select Services pulldown and select APPC as for CPI-C information.
2. Select Transaction Programs. The following panel is displayed:

Chapter 16. Example configuration - IBM MQSeries for HP-UX 235

Using HP SNAplus2

3. Select Add. The following panel is displayed:

4. Enter TP name («7¬) in the Application TP field.

5. Mark Incoming Allocates as non-queued.
6. Enter Full path to executable («10¬).
7. Enter -m Local queue manager («11¬) in the Arguments field.
8. Enter mqm in the User ID and Group ID fields.
9. Enter environment variables APPCLLU=local LU («5¬) and
APPCTPN=Invokable TP («7¬) separated by the pipe character in the
Environment field.
10. Press OK to save your definition.

236 MQSeries Intercommunication

 Using HP SNAplus2
HP-UX operation
The SNAplus2 control daemon is started with the snap start command. Depending
on the options selected at installation, it may already be running.

The xsnapadmin utility controls SNAplus2 resources.

Logging and tracing are controlled from here. Log and trace files can be found in
the /var/opt/sna directory. The logging files sna.aud and sna.err can be read
using a standard editor such as vi.

In order to read the trace files sna1.trc and sna2.trc they must first be formatted by
running the command snaptrcfmt -f sna1.trc -o sna1 which produces a sna1.dmp
file which can be read using a normal editor.

The configuration file itself is editable but this is not a recommended method of
configuring SNAplus2.

The APPCLU environment variables must be set before starting a sender channel
from the HP-UX system. The command can be either entered interactively or
added to the logon profile. Depending on the level of BOURNE shell or KORN
shell program being used, the command will be:
export APPCLLU=HPUXLU «5¬ newer level

or
APPCLLU=HPUXLU «5¬ older level
export

What next?
The connection is now established. You are ready to complete the configuration.
Go to “MQSeries for HP-UX configuration” on page 238.

Establishing a TCP connection

1. Edit the file /etc/services.

Note: To edit the /etc/services file, you must be logged in as a superuser or

root. If you do not have the following line in that file, add it as shown:
MQSeries 1414/tcp # MQSeries channel listener
2. Edit the file /etc/inetd.conf. If you do not have the following line in that file,
add it as shown:
MQSeries stream tcp nowait root /opt/mqm/bin/amqcrsta amqcrsta
[-m queue.manager.name]
3. Find the process ID of the inetd with the command:
ps -ef | grep inetd
4. Run the command:
kill -1 inetd processid

What next?
The connection is now established. You are ready to complete the configuration.
Go to “MQSeries for HP-UX configuration” on page 238.

Chapter 16. Example configuration - IBM MQSeries for HP-UX 237

HP-UX configuration

MQSeries for HP-UX configuration

Before beginning the installation process ensure that you have first created the
mqm user and group, and set the password.

Start any channel using the command:

runmqchl -c channel.name
Notes:
1. Sample programs are installed in /opt/mqm/samp.
2. Error logs are stored in /var/mqm/qmgrs/qmgrname/errors.
3. When you are using the command interpreter runmqsc to enter administration
commands, a + at the end of a line indicates that the next line is a continuation.
Ensure that there is a space between the last parameter and the continuation
character.

Basic configuration
1. Create the queue manager from the UNIX prompt using the command:
crtmqm -u dlqname -q hpux

where:
hpux Is the name of the queue manager
-q Indicates that this is to become the default queue manager
-u dlqname
Specifies the name of the undeliverable message queue

This command creates a queue manager and a set of default objects. It sets the
DEADQ attribute of the queue manager but does not create the undeliverable
message queue.
2. Start the queue manager from the UNIX prompt using the command:
strmqm hpux

where hpux is the name given to the queue manager when it was created.

Channel configuration
The following section details the configuration to be performed on the HP-UX
queue manager to implement the channel described in Figure 32 on page 97.

In each case the MQSC command is shown. Either start runmqsc from a UNIX
prompt and enter each command in turn, or build the commands into a command
file.

Examples are given for connecting MQSeries for HP-UX and MQSeries for OS/2
Warp. If you wish connect to another MQSeries product use the appropriate set of
values from the table in place of those for OS/2.

Note: The words in bold are user-specified and reflect the names of MQSeries
objects used throughout these examples. If you change the names used here,
ensure that you also change the other references made to these objects
throughout this book. All others are keywords and should be entered as
shown.

238 MQSeries Intercommunication

 HP-UX configuration
Table 24. Configuration worksheet for MQSeries for HP-UX
ID Parameter Name Reference Example Used User Value
Definition for local node
«A¬ Queue Manager Name HPUX
«B¬ Local queue name HPUX.LOCALQ
Connection to MQSeries for OS/2 Warp

The values in this section of the table must match those used in Table 15 on page 164, as indicated.
«C¬ Remote queue manager name «A¬ OS2
«D¬ Remote queue name OS2.REMOTEQ
«E¬ Queue name at remote system «B¬ OS2.LOCALQ
«F¬ Transmission queue name OS2
«G¬ Sender (SNA) channel name HPUX.OS2.SNA
«H¬ Sender (TCP/IP) channel name HPUX.OS2.TCP
«I¬ Receiver (SNA) channel name «G¬ OS2.HPUX.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ OS2.HPUX.TCP
Connection to MQSeries for Windows NT

The values in this section of the table must match those used in Table 17 on page 185, as indicated.
«C¬ Remote queue manager name «A¬ WINNT
«D¬ Remote queue name WINNT.REMOTEQ
«E¬ Queue name at remote system «B¬ WINNT.LOCALQ
«F¬ Transmission queue name WINNT
«G¬ Sender (SNA) channel name HPUX.WINNT.SNA
«H¬ Sender (TCP/IP) channel name HPUX.WINNT.TCP
«I¬ Receiver (SNA) channel name «G¬ WINNT.HPUX.SNA
«J¬ Receiver (TCP) channel name «H¬ WINNT.HPUX.TCP
Connection to MQSeries for AIX

The values in this section of the table must match those used in Table 21 on page 211, as indicated.
«C¬ Remote queue manager name «A¬ AIX
«D¬ Remote queue name AIX.REMOTEQ
«E¬ Queue name at remote system «B¬ AIX.LOCALQ
«F¬ Transmission queue name AIX
«G¬ Sender (SNA) channel name HPUX.AIX.SNA
«H¬ Sender (TCP) channel name HPUX.AIX.TCP
«I¬ Receiver (SNA) channel name «G¬ AIX.HPUX.SNA
«J¬ Receiver (TCP) channel name «H¬ AIX.HPUX.TCP
| Connection to MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| The values in this section of the table must match those used in Table 22 on page 216, as indicated.
| «C¬ Remote queue manager name «A¬ DECUX
| «D¬ Remote queue name DECUX.REMOTEQ
| «E¬ Queue name at remote system «B¬ DECUX.LOCALQ
| «F¬ Transmission queue name DECUX
| «H¬ Sender (TCP) channel name DECUX.HPUX.TCP
| «J¬ Receiver (TCP) channel name «H¬ HPUX.DECUX.TCP
Connection to MQSeries for OS/390 or MVS/ESA without CICS

The values in this section of the table must match those used in Table 26 on page 253, as indicated.

Chapter 16. Example configuration - IBM MQSeries for HP-UX 239

 HP-UX configuration
Table 24. Configuration worksheet for MQSeries for HP-UX (continued)
ID Parameter Name Reference Example Used User Value
«C¬ Remote queue manager name «A¬ GIS
«D¬ Remote queue name GIS.REMOTEQ
«E¬ Queue name at remote system «B¬ GIS.LOCALQ
«F¬ Transmission queue name GIS
«G¬ Sender (SNA) channel name HPUX.GIS.SNA
«H¬ Sender (TCP) channel name HPUX.GIS.TCP
«I¬ Receiver (SNA) channel name «G¬ GIS.HPUX.SNA
«J¬ Receiver (TCP) channel name «H¬ GIS.HPUX.TCP
Connection to MQSeries for Sun Solaris

The values in this section of the table must match those used in Table 28 on page 272, as indicated.
«C¬ Remote queue manager name SOLARIS
«D¬ Remote queue name SOLARIS.REMOTEQ
«E¬ Queue name at remote system «B¬ SOLARIS.LOCALQ
«F¬ Transmission queue name SOLARIS
«G¬ Sender (SNA) channel name HPUX.SOLARIS.SNA
«H¬ Sender (TCP/IP) channel name HPUX.SOLARIS.TCP
«I¬ Receiver (SNA) channel name «G¬ SOLARIS.HPUX.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ SOLARIS.HPUX.TCP
| Connection to MQSeries for AS/400

| The values in this section of the table must match those used in Table 43 on page 472, as indicated.
| «C¬ Remote queue manager name AS400
| «D¬ Remote queue name AS400.REMOTEQ
| «E¬ Queue name at remote system «B¬ AS400.LOCALQ
| «F¬ Transmission queue name AS400
| «G¬ Sender (SNA) channel name HPUX.AS400.SNA
| «H¬ Sender (TCP/IP) channel name HPUX.AS400.TCP
| «I¬ Receiver (SNA) channel name «G¬ AS400.HPUX.SNA
| «J¬ Receiver (TCP) channel name «H¬ AS400.HPUX.TCP
Connection to MQSeries for OS/390 or MVS/ESA without CICS

The values in this section of the table must match those used in Table 37 on page 406, as indicated.
«C¬ Remote queue manager name MVS
«D¬ Remote queue name MVS.REMOTEQ
«E¬ Queue name at remote system «B¬ MVS.LOCALQ
«F¬ Transmission queue name MVS
«G¬ Sender (SNA) channel name HPUX.MVS.SNA
«H¬ Sender (TCP) channel name HPUX.MVS.TCP
«I¬ Receiver (SNA) channel name «G¬ MVS.HPUX.SNA
«J¬ Receiver (TCP) channel name «H¬ MVS.HPUX.TCP
Connection to MQSeries for VSE/ESA

The values in this section of the table must match those used in Table 45 on page 490, as indicated.
«C¬ Remote queue manager name VSE
«D¬ Remote queue name VSE.REMOTEQ
«E¬ Queue name at remote system «B¬ VSE.LOCALQ
«F¬ Transmission queue name VSE

240 MQSeries Intercommunication

 HP-UX configuration
Table 24. Configuration worksheet for MQSeries for HP-UX (continued)
ID Parameter Name Reference Example Used User Value
«G¬ Sender channel name HPUX.VSE.SNA
«I¬ Receiver channel name «G¬ VSE.HPUX.SNA

MQSeries for HP-UX sender-channel definitions using SNA

def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (HPUX.OS2.SNA) chltype(sdr) + «G¬

trptype(lu62) +
conname('OS2CPIC') + «16¬
xmitq(OS2) + «F¬
replace

MQSeries for HP-UX receiver-channel definitions using SNA

def ql (HPUX.LOCALQ) replace «B¬

def chl (OS2.HPUX.SNA) chltype(rcvr) + «I¬

trptype(lu62) +
replace

MQSeries for HP-UX invokable TP setup

| This is not required for HP SNAplus2 Release 6.

During the HP SNAplus2 configuration process, you created an invokable TP

definition, which points to an executable file. In the example, the file was called
/users/interops/HPUX.crs6a. You can choose what you call this file, but you are
recommended to include the name of your queue manager in the name. The
contents of the executable file must be:
#!/bin/sh
/opt/mqm/bin/amqcrs6a -m hpux

where hpux is the name of your queue manager «A¬.

This ensures that SNA receiver channels activate correctly when a sender channel
initiates a conversation.

MQSeries for HP-UX sender-channel definitions using TCP

def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (HPUX.OS2.TCP) chltype(sdr) + «H¬

Chapter 16. Example configuration - IBM MQSeries for HP-UX 241

HP-UX configuration
trptype(tcp) +
conname(remote_tcpip_hostname) +
xmitq(OS2) + «F¬
replace

MQSeries for HP-UX receiver-channel definitions using TCP/IP

def ql (HPUX.LOCALQ) replace «B¬

def chl (OS2.HPUX.TCP) chltype(rcvr) + «J¬

trptype(tcp) +
replace

242 MQSeries Intercommunication

 Chapter 17. Example configuration - IBM MQSeries for AT&T
GIS UNIX Version 2.2
This chapter gives an example of how to set up communication links from
MQSeries for AT&T GIS UNIX to MQSeries products on the following platforms:
v OS/2
v Windows NT
v AIX
| v Digital UNIX
v HP-UX
v Sun Solaris
| v OS/400
v OS/390 or MVS/ESA without CICS
v VSE/ESA

First it describes the parameters needed for an LU 6.2 connection, then it describes
“Establishing a connection using AT&T GIS SNA Server” on page 246 and
“Establishing a TCP connection” on page 251.

Once the connection is established, you need to define some channels to complete
the configuration. This is described in “Channel configuration” on page 252.

See “Chapter 7. Example configuration chapters in this book” on page 97 for

background information about this chapter and how to use it.

Configuration parameters for an LU 6.2 connection

Table 25 presents a worksheet listing all the parameters needed to set up
communication from AT&T GIS UNIX5 to one of the other MQSeries platforms.
The worksheet shows examples of the parameters, which have been tested in a
working environment, and leaves space for you to fill in your own values. An
explanation of the parameter names follows the worksheet. Use the worksheet in
this chapter in conjunction with the worksheet in the chapter for the platform to
which you are connecting.

Configuration worksheet
Use the following worksheet to record the values you will use for this
configuration. Where numbers appear in the Reference column they indicate that
the value must match that in the appropriate worksheet elsewhere in this book.
The examples that follow in this chapter refer back to the values in the ID column
of this table. The entries in the Parameter Name column are explained in
“Explanation of terms” on page 246.
Table 25. Configuration worksheet for AT&T GIS SNA Services
ID Parameter Name Reference Example User Value
Parameters for local node
«1¬ Configuration 010
«2¬ Network name NETID

5. This platform has become NCR UNIX SVR4 MP-RAS, R3.0

© Copyright IBM Corp. 1993, 2000 243

AT&T GIS UNIX and LU 6.2
Table 25. Configuration worksheet for AT&T GIS SNA Services (continued)
ID Parameter Name Reference Example User Value
«3¬ Control Point name GISPU
«4¬ Local LU name GISLU
«5¬ LU 6.2 Transaction Program name MQSERIES
«6¬ Local PU name GISPU
«7¬ Mode name #INTER
«8¬ Token-Ring adapter address 10007038E86B
«9¬ Local XID 03E 00018
Connection to an OS/2 system

The values in this section of the table must match those used in Table 14 on page 138, as indicated.
«10¬ Remote Node name «3¬ OS2PU
«11¬ Network name «2¬ NETID
«12¬ Remote LU name «6¬ OS2LU
«13¬ Remote Transaction Program name «8¬ MQSERIES
«14¬ LU 6.2 CPI-C side information symbolic OS2CPIC
destination
«15¬ Mode name «17¬ #INTER
«16¬ LAN destination address «10¬ 10005AFC5D83
Connection to a Windows NT system

The values in this section of the table must match those used in Table 16 on page 170, as indicated.
«10¬ Remote Node name «3¬ WINNTCP
«11¬ Network name «2¬ NETID
«12¬ Remote LU name «5¬ WINNTLU
«13¬ Remote Transaction Program name «7¬ MQSERIES
«14¬ LU 6.2 CPI-C side information symbolic NTCPIC
destination
«15¬ Mode name «17¬ #INTER
«16¬ LAN destination address «9¬ 08005AA5FAB9
Connection to an AIX system

The values in this section of the table must match those used in Table 20 on page 197, as indicated.
«10¬ Remote Node name «2¬ AIXPU
«11¬ Network name «1¬ NETID
«12¬ Remote LU name «4¬ AIXLU
«13¬ Remote Transaction Program name «6¬ MQSERIES
«14¬ LU 6.2 CPI-C side information symbolic AIXCPIC
destination
«15¬ Mode name «14¬ #INTER
«16¬ LAN destination address «8¬ 123456789012
Connection to an HP-UX system

The values in this section of the table must match those used in Table 23 on page 219, as indicated.
«10¬ Remote Node name «2¬ HPUXPU
«11¬ Network name «4¬ NETID
«12¬ Remote LU name «5¬ HPUXLU
«13¬ Remote Transaction Program name «7¬ MQSERIES
«14¬ LU 6.2 CPI-C side information symbolic HPUXCPIC
destination

244 MQSeries Intercommunication

 AT&T GIS UNIX and LU 6.2
Table 25. Configuration worksheet for AT&T GIS SNA Services (continued)
ID Parameter Name Reference Example User Value
«15¬ Mode name «6¬ #INTER
«16¬ LAN destination address «8¬ 100090DC2C7C
Connection to a Sun Solaris system

The values in this section of the table must match those used in Table 27 on page 257, as indicated.
«10¬ Remote Node name «3¬ SOLARPU
«11¬ Network name «2¬ NETID
«12¬ Remote LU name «7¬ SOLARLU
«13¬ Remote Transaction Program name «8¬ MQSERIES
«14¬ LU 6.2 CPI-C side information symbolic SOLCPIC
destination
«15¬ Mode name «17¬ #INTER
«16¬ LAN destination address «5¬ 08002071CC8A
Connection to an AS/400 system

The values in this section of the table must match those used in Table 42 on page 460, as indicated.
«10¬ Remote Node name «2¬ AS400PU
«11¬ Network name «1¬ NETID
«12¬ Remote LU name «3¬ AS400LU
«13¬ Remote Transaction Program name «8¬ MQSERIES
«14¬ LU 6.2 CPI-C side information symbolic AS4CPIC
destination
«15¬ Mode name «17¬ #INTER
«16¬ LAN destination address «4¬ 10005A5962EF
Connection to an OS/390 or MVS/ESA system without CICS

The values in this section of the table must match those used in Table 36 on page 396, as indicated.
«10¬ Remote Node name «3¬ MVSPU
«11¬ Network name «2¬ NETID
«12¬ Remote LU name «4¬ MVSLU
«13¬ Remote Transaction Program name «7¬ MQSERIES
«14¬ LU 6.2 CPI-C side information symbolic MVSCPIC
destination
«15¬ Mode name «10¬ #INTER
«16¬ LAN destination address «8¬ 400074511092
Connection to a VSE/ESA system

The values in this section of the table must match those used in Table 44 on page 485, as indicated.
«10¬ Remote Node name «2¬ VSEPU
«11¬ Network name «1¬ NETID
«12¬ Remote LU name «3¬ VSELU
«13¬ Remote Transaction Program name «4¬ MQ01
«14¬ LU 6.2 CPI-C side information symbolic VSECPIC
destination
«15¬ Mode name #INTER
«16¬ LAN destination address «5¬ 400074511092

Chapter 17. Example configuration - IBM MQSeries for AT&T GIS UNIX Version 2.2 245
AT&T GIS UNIX and LU 6.2
Explanation of terms
«1¬ Configuration
This is the unique ID of the SNA Server configuration you are creating or
modifying. Valid values are between 0 and 255.
«2¬ Network name
This is the unique ID of the network to which you are connected. Your
network administrator will tell you this value.
«3¬ Control Point name
This is a unique Control Point name for this workstation. Your network
administrator will assign this to you.
«4¬ Local LU name
A logical unit (LU) manages the exchange of data between systems. The
local LU name is the name of the LU on your system. Your network
administrator will assign this to you.
«5¬ LU 6.2 Transaction Program name
MQSeries applications trying to converse with this workstation will specify
a symbolic name for the program to be run at the receiving end. This will
have been defined on the channel definition at the sender. Wherever
possible we use a transaction program name of MQSERIES, or in the case
of a connection to VSE/ESA, where the length is limited to 4 bytes, use
MQTP.
See Table 19 on page 194 for more information.
«6¬ Local PU name
This is a unique PU name for this workstation. Your network administrator
will assign this to you.
«7¬ Mode name
This is the name given to the set of parameters that control the APPC
conversation. This name must be defined at each partner system. Your
network administrator will assign this to you.
«8¬ Token-ring adapter address
The is the 12-character hex address of the token-ring card.
«10¬ Remote Node name
This is a meaningful symbolic name by which the connection to a partner
node is known. It is used only inside SNA Server setup and is specified by
you.
«14¬ LU 6.2 CPI-C Side Information Symbolic Destination
This is a name given to the definition of a partner node. You supply the
name. It need be unique only on this machine. You will later use the name
in the MQSeries sender channel definition.

Establishing a connection using AT&T GIS SNA Server

The following information guides you through the tasks you must perform to
create the SNA infrastructure that MQSeries requires. This example creates the
definitions for a new partner node and LU on OS/2.

Use snamgr to enter the AT&T GIS SNA Server configuration panels. You need
root authority to use snamgr.

246 MQSeries Intercommunication

 Using AT&T GIS SNA Server
Throughout the following example, only the panels containing information that
must be added or updated are shown. Preceding each panel is a list of the
sequence of panels that you must invoke to proceed from the initial menu to the
relevant customization panel.

Note: SNA Server works better in an Xterm session than it does in an ASCII
session such as TELNET.

Defining local node characteristics

Setting up the local node involves the following steps:
1. Configuring the SNA subsystem
2. Defining a mode
3. Defining a local Transaction Program

Configuring the SNA subsystem

Proceed through these panels:
1 SNA Manager
2 Configuration
3 SNA Subsystem Configuration
4 SNA Subsystem Configuration Creation

5 Create a Configuration

Enter a unique configuration identifier (0-255) 010

Enter the configuration identifier («1¬).

6 Parameter File Configuration

Will LU 6.2 be used? Y

Enter Y.

1 SNA Configuration of the Local Node

Node Parameters:

Node ID of Local Node 00

PU Resource Name (optional) GISPU

Network Identifier (optional) NETID

Control Point (CP) Name (optional) GISPU

Local LU 6.2 Parameters:

LU 6.2 Logical Unit Name GISLU

Max Number of LU 6.2 Sessions 0100

Enter the values for Node ID of Local Node, PU Resource Name («6¬), Network
Identifier («2¬), CP Name («3¬), LU 6.2 Logical Unit Name («4¬), and Max
Number of LU 6.2 Sessions.

Chapter 17. Example configuration - IBM MQSeries for AT&T GIS UNIX Version 2.2 247
Using AT&T GIS SNA Server
Defining a mode
Proceed through these panels:
2 Local Configuration

Select Define a mode.

3 Conversation Mode Definition

Mode Name #INTER

Maximum Number of Sessions 008

Number of Locally Controlled Sessions 004

Honor Pending Conversation Requests Before

an Existing Session is Terminated? N

Number of Automatically Established Sessions 004

Code Set to be Used During Transmission of TP Data E

Enter the values for Mode Name («7¬), Maximum Number of Sessions, and
Number of Locally Controlled Sessions.

4 Conversation Mode Definition for Max RU

Send Max RU Size Upper Bound 03840

Send Max RU Size Lower Bound 00128

Receive Max RU Size Upper Bound 03840

Receive Max RU Size Lower Bound 00128

Defining a local Transaction Program

2 Local Configuration

Select Define a RECEIVE_ALLOCATE local TP.

3 Receive_Allocate Transaction Program Definition

TP name MQSERIES_______________________

TP start type A (M = Manual, A = Automatic)

receive_allocate timer (seconds) -1__ (0 - 9999, -1)

Incoming allocate timer (seconds) -1__ (0 - 9999, -1)

Max number of auto-started TP instances 1_ (1 - 99)

Enter the values for TP name («5¬), and set the TP start type to A.

Note: Before this will work you need to associate the TP name with an executable
program. You do this outside snamgr by creating a symbolic link entry in
the directory /usr/lbin either before or after you configure SNA Server.
Enter the following commands:
cd /usr/lbin
ln -s /opt/mqm/bin/amqcrs6a MQSeries «5¬

248 MQSeries Intercommunication

 Using AT&T GIS SNA Server
Connecting to a partner node
To connect to a partner node you need to:
1. Configure a remote node
2. Define a partner LU
3. Add a CPI-C Side Entry

Configuring a remote node

Proceed through these panels:
2 Local Configuration

Select End Local Configuration.

1 Remote Node Definition

Select Peer Node Definition.

2 Remote Node Configuration

Remote Node Name OS2PU

Type of Link Connection TR

SNA Logical Connection ID 00

Link to Backup (Optional) ____

Enter the values for Remote Node Name («10¬), Type of Link Connection, and
SNA Logical Connection ID.

3 SNA/TR Configuration for Connection 01

Token Ring Adapter ID 01

Maximum Send BTU Length 1033

Local XID 03E00018

Data link role of local system NEG_

Remote DLSAP 04

Remote MAC Address 10005AFC5D83

Route Discovery Command T

Broadcast Timer 1_

Enter the values for Token Ring Adapter ID, Local XID («9¬), and Remote MAC
address («16¬).

4 Configuration of TR Adapter 01 for Connection 01

Local DLSAP 04

Adapter Type ild_

Chapter 17. Example configuration - IBM MQSeries for AT&T GIS UNIX Version 2.2 249
Using AT&T GIS SNA Server
Defining a partner LU
Proceed through these panels:

1 LU 6.2 Logical Unit Definition

To complete the definition of Remote

Peer Node, OS2, you need to
define at least one Remote LU 6.2
Logical Unit.

Press CONT to Continue.

2 Partner LU 6.2 Definition

Locally Known Name OS2LU

Network Identifier NETID

Network Name (LUNAME) OS2LU

Uninterpreted Name OS2LU

Session Capability P

Enter the values for Locally Known Name («12¬), Network Identifier («11¬),
Network Name (LUNAME) («12¬), and Uninterpreted Name («12¬),

3 Automatic Activation

Auto Activate at Start of Day? N

4 LU 6.2 Partner Definition

Do you want to define another

remote LU 6.2 Logical Unit in
the remote node, OS2? N

Adding a CPI-C Side Entry

Proceed through these panels:
1 SNA MANAGER
2 Configuration
3 CPI-C Side Information

4 Add a CPI-C Side Information File

Enter the CPI-C Side Information File Name OS2CPIC

(This name is the Symbolic Destination Name used by

the CPI-C program to reference side information.)

Enter the name of the CPI-C Side Information File («14¬).

250 MQSeries Intercommunication

 Using AT&T GIS SNA Server

5 Add CPI-C Side Information

Symbolic destination name: OS2CPIC

Partner LU name OS2LU

Mode name #INTER

TP name MQSERIES

Conversation security type NONE___

Security user ID __________

Security password __________

Enter the values for Partner LU name («12¬), Mode name («15¬), and TP name
(«13¬).

What next?
The LU 6.2 connection is now established. You are ready to complete the
configuration. Go to “MQSeries for AT&T GIS UNIX configuration”.

Establishing a TCP connection

1. Edit the file /etc/services.

Note: To edit the /etc/services file, you must be logged in as a superuser or

root. If you do not have the following line in that file, add it as shown:
MQSeries 1414/tcp # MQSeries channel listener
2. Edit the file /usr/etc/inetd.conf. If you do not have the following line in that
file, add it as shown:
MQSeries stream tcp nowait root /opt/mqm/bin/amqcrsta amqcrsta
[-m queue.manager.name]
3. Find the process ID of the inetd with the command:
ps -ef | grep inetd
4. Run the command:
kill -1 inetd processid

The command kill -1 can be unreliable. If it doesn’t work, use the command
kill -9 and then restart /usr/etc/inetd manually.

What next?
The LU 6.2 connection is now established. You are ready to complete the
configuration. Go to “MQSeries for AT&T GIS UNIX configuration”.

MQSeries for AT&T GIS UNIX configuration

Before beginning the installation process ensure that you have first created the
mqm user and group, and set the password.

Start any channel using the command:

runmqchl -c channel.name

Chapter 17. Example configuration - IBM MQSeries for AT&T GIS UNIX Version 2.2 251
AT&T GIS UNIX configuration
Notes:
1. Sample programs are installed in /opt/mqm/samp.
2. Error logs are stored in /var/mqm/qmgrs/qmgrname/errors.
3. When you are using the command interpreter runmqsc to enter administration
commands, a + at the end of a line indicates that the next line is a continuation.
Ensure that there is a space between the last parameter and the continuation
character.

Basic configuration
1. Create the queue manager from the UNIX prompt using the command:
crtmqm -u dlqname -q gis

where:
gis Is the name of the queue manager
-q Indicates that this is to become the default queue manager
-u dlqname
Specifies the name of the undeliverable message queue
2. Start the queue manager from the UNIX prompt using the command:
strmqm gis

where gis is the name given to the queue manager when it was created.
3. Before creating your own objects you must first create the system default
objects. These are a number of definitions for required objects and templates on
which user definitions will be modelled.
Create the default objects from the UNIX prompt using the command:
runmqsc gis < /opt/mqm/samp/amqscoma.tst > defobj.out

where gis is the name of the queue manager. Display the file defobj.out and
ensure that all objects were created successfully. There is a report at the end of
the file.

Channel configuration
The following section details the configuration to be performed on the AT&T GIS
UNIX queue manager to implement the channel described in Figure 32 on page 97.

In each case the MQSC command is shown. Either start runmqsc from a UNIX
prompt and enter each command in turn, or build a command file of the same
format as amqscoma.tst and use it as before to create the objects.

Examples are given for connecting MQSeries for AT&T GIS UNIX and MQSeries
for OS/2 Warp. If you wish to connect to another MQSeries product use the
appropriate set of values from the table in place of those for OS/2.

Note: The words in bold are user-specified and reflect the names of MQSeries
objects used throughout these examples. If you change the names used here,
ensure that you also change the other references made to these objects
throughout this book. All others are keywords and should be entered as
shown.

252 MQSeries Intercommunication

 AT&T GIS UNIX configuration
Table 26. Configuration worksheet for MQSeries for AT&T GIS UNIX
ID Parameter Name Reference Example Used User Value
Definition for local node
«A¬ Queue Manager Name GIS
«B¬ Local queue name GIS.LOCALQ
Connection to MQSeries for OS/2 Warp

The values in this section of the table must match those used in Table 15 on page 164, as indicated.
«C¬ Remote queue manager name «A¬ OS2
«D¬ Remote queue name OS2.REMOTEQ
«E¬ Queue name at remote system «B¬ OS2.LOCALQ
«F¬ Transmission queue name OS2
«G¬ Sender (SNA) channel name GIS.OS2.SNA
«H¬ Sender (TCP/IP) channel name GIS.OS2.TCP
«I¬ Receiver (SNA) channel name «G¬ OS2.GIS.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ OS2.GIS.TCP
Connection to MQSeries for Windows NT

The values in this section of the table must match those used in Table 17 on page 185, as indicated.
«C¬ Remote queue manager name «A¬ WINNT
«D¬ Remote queue name WINNT.REMOTEQ
«E¬ Queue name at remote system «B¬ WINNT.LOCALQ
«F¬ Transmission queue name WINNT
«G¬ Sender (SNA) channel name GIS.WINNT.SNA
«H¬ Sender (TCP/IP) channel name GIS.WINNT.TCP
«I¬ Receiver (SNA) channel name «G¬ WINNT.GIS.SNA
«J¬ Receiver (TCP) channel name «H¬ WINNT.GIS.TCP
Connection to MQSeries for AIX

The values in this section of the table must match those used in Table 21 on page 211, as indicated.
«C¬ Remote queue manager name «A¬ AIX
«D¬ Remote queue name AIX.REMOTEQ
«E¬ Queue name at remote system «B¬ AIX.LOCALQ
«F¬ Transmission queue name AIX
«G¬ Sender (SNA) channel name GIS.AIX.SNA
«H¬ Sender (TCP) channel name GIS.AIX.TCP
«I¬ Receiver (SNA) channel name «G¬ AIX.GIS.SNA
«J¬ Receiver (TCP) channel name «H¬ AIX.GIS.TCP
| Connection to MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| The values in this section of the table must match those used in Table 22 on page 216, as indicated.
| «C¬ Remote queue manager name «A¬ DECUX
| «D¬ Remote queue name DECUX.REMOTEQ
| «E¬ Queue name at remote system «B¬ DECUX.LOCALQ
| «F¬ Transmission queue name DECUX
| «H¬ Sender (TCP) channel name DECUX.GIS.TCP
| «J¬ Receiver (TCP) channel name «H¬ GIS.DECUX.TCP
Connection to MQSeries for HP-UX

The values in this section of the table must match those used in Table 24 on page 239, as indicated.

Chapter 17. Example configuration - IBM MQSeries for AT&T GIS UNIX Version 2.2 253
 AT&T GIS UNIX configuration
Table 26. Configuration worksheet for MQSeries for AT&T GIS UNIX (continued)
ID Parameter Name Reference Example Used User Value
«C¬ Remote queue manager name «A¬ HPUX
«D¬ Remote queue name HPUX.REMOTEQ
«E¬ Queue name at remote system «B¬ HPUX.LOCALQ
«F¬ Transmission queue name HPUX
«G¬ Sender (SNA) channel name GIS.HPUX.SNA
«H¬ Sender (TCP) channel name GIS.HPUX.TCP
«I¬ Receiver (SNA) channel name «G¬ HPUX.GIS.SNA
«J¬ Receiver (TCP) channel name «H¬ HPUX.GIS.TCP
Connection to MQSeries for Sun Solaris

The values in this section of the table must match those used in Table 28 on page 272, as indicated.
«C¬ Remote queue manager name SOLARIS
«D¬ Remote queue name SOLARIS.REMOTEQ
«E¬ Queue name at remote system «B¬ SOLARIS.LOCALQ
«F¬ Transmission queue name SOLARIS
«G¬ Sender (SNA) channel name GIS.SOLARIS.SNA
«H¬ Sender (TCP/IP) channel name GIS.SOLARIS.TCP
«I¬ Receiver (SNA) channel name «G¬ SOLARIS.GIS.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ SOLARIS.GIS.TCP
| Connection to MQSeries for AS/400

| The values in this section of the table must match those used in Table 43 on page 472, as indicated.
| «C¬ Remote queue manager name AS400
| «D¬ Remote queue name AS400.REMOTEQ
| «E¬ Queue name at remote system «B¬ AS400.LOCALQ
| «F¬ Transmission queue name AS400
| «G¬ Sender (SNA) channel name GIS.AS400.SNA
| «H¬ Sender (TCP/IP) channel name GIS.AS400.TCP
| «I¬ Receiver (SNA) channel name «G¬ AS400.GIS.SNA
| «J¬ Receiver (TCP) channel name «H¬ AS400.GIS.TCP
Connection to MQSeries for OS/390 or MVS/ESA without CICS

The values in this section of the table must match those used in Table 37 on page 406, as indicated.
«C¬ Remote queue manager name MVS
«D¬ Remote queue name MVS.REMOTEQ
«E¬ Queue name at remote system «B¬ MVS.LOCALQ
«F¬ Transmission queue name MVS
«G¬ Sender (SNA) channel name GIS.MVS.SNA
«H¬ Sender (TCP) channel name GIS.MVS.TCP
«I¬ Receiver (SNA) channel name «G¬ MVS.GIS.SNA
«J¬ Receiver (TCP) channel name «H¬ MVS.GIS.TCP
Connection to MQSeries for VSE/ESA

The values in this section of the table must match those used in Table 45 on page 490, as indicated.
«C¬ Remote queue manager name VSE
«D¬ Remote queue name VSE.REMOTEQ
«E¬ Queue name at remote system «B¬ VSE.LOCALQ
«F¬ Transmission queue name VSE

254 MQSeries Intercommunication

 AT&T GIS UNIX configuration
Table 26. Configuration worksheet for MQSeries for AT&T GIS UNIX (continued)
ID Parameter Name Reference Example Used User Value
«G¬ Sender channel name GIS.VSE.SNA
«I¬ Receiver channel name «G¬ VSE.GIS.SNA

MQSeries for AT&T GIS UNIX sender-channel definitions using

SNA
def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (GIS.OS2.SNA) chltype(sdr) + «G¬

trptype(lu62) +
conname('OS2CPIC') + «14¬
xmitq(OS2) + «F¬
replace

MQSeries for AT&T GIS UNIX receiver-channel definitions using

SNA
def ql (GIS.LOCALQ) replace «B¬

def chl (OS2.GIS.SNA) chltype(rcvr) + «I¬

trptype(lu62) +
replace

MQSeries for AT&T GIS UNIX sender-channel definitions using

TCP
def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (GIS.OS2.TCP) chltype(sdr) + «H¬

trptype(tcp) +
conname(remote_tcpip_hostname) +
xmitq(OS2) + «F¬
replace

MQSeries for AT&T GIS UNIX receiver-channel definitions using

TCP/IP
def ql (GIS.LOCALQ) replace «B¬

def chl (OS2.GIS.TCP) chltype(rcvr) + «J¬

trptype(tcp) +
replace

Chapter 17. Example configuration - IBM MQSeries for AT&T GIS UNIX Version 2.2 255
AT&T GIS UNIX configuration

256 MQSeries Intercommunication

 Chapter 18. Example configuration - IBM MQSeries for Sun
Solaris
This chapter gives an example of how to set up communication links from
MQSeries for Sun Solaris to MQSeries products on the following platforms:
v OS/2
v Windows NT
v AIX
| v Digital UNIX
v HP-UX
v AT&T GIS UNIX6
| v OS/400
v OS/390 or MVS/ESA without CICS
v VSE/ESA

First it describes the parameters needed for an LU 6.2 connection, then it describes
“Establishing a connection using SunLink Version 9.1” on page 261 and
“Establishing a TCP connection” on page 271.

Once the connection is established, you need to define some channels to complete
the configuration. This is described in “MQSeries for Sun Solaris configuration” on
page 271.

See “Chapter 7. Example configuration chapters in this book” on page 97 for

background information about this chapter and how to use it.

Configuration parameters for an LU 6.2 connection

Table 27 presents a worksheet listing all the parameters needed to set up
communication from Sun Solaris to one of the other MQSeries platforms. The
worksheet shows examples of the parameters, which have been tested in a
working environment, and leaves space for you to fill in your own values. An
explanation of the parameter names follows the worksheet. Use the worksheet in
this chapter in conjunction with the worksheet in the chapter for the platform to
which you are connecting.

Configuration worksheet
Use this worksheet to record the values you use for your configuration. Where
numbers appear in the Reference column they indicate that the value must match
that in the appropriate worksheet elsewhere in this book. The examples that follow
in this chapter refer back to the values in the ID column. The entries in the
Parameter Name column are explained in “Explanation of terms” on page 260.
Table 27. Configuration worksheet for SunLink Version 9.1
ID Parameter Name Reference Example User Value
Parameters for local node
«1¬ PU 2.1 server name SOLSERV
«2¬ Network name NETID

6. This platform has become NCR UNIX SVR4 MP-RAS, R3.0

© Copyright IBM Corp. 1993, 2000 257

Sun Solaris and LU 6.2
Table 27. Configuration worksheet for SunLink Version 9.1 (continued)
ID Parameter Name Reference Example User Value
«3¬ CP name SOLARPU
«4¬ Line name MQLINE
«5¬ Local MAC address 08002071CC8A
«6¬ Local terminal ID 05D 310D6
«7¬ Local LU name SOLARLU
«8¬ TP name MQSERIES
«9¬ Command Path home/interops/crs6a
Connection to an OS/2 system

The values in this section of the table must match those used in Table 14 on page 138, as indicated.
«10¬ Unique session name OS2SESS
«11¬ Network name «2¬ NETID
«12¬ DLC name OS2QMGR
«13¬ Remote CP name OS2PU
«14¬ Local LSAP x‘04’, x‘08’, x‘0C’, ...
«15¬ Partner LU «6¬ OS2LU
«16¬ TP name «8¬ MQSERIES
«17¬ Mode name «17¬ #INTER
«18¬ CPI-C file name /home/mqstart/OS2CPIC
«19¬ Remote MAC address «10¬ 10005AFC5D83
Connection to a Windows NT system

The values in this section of the table must match those used in Table 16 on page 170, as indicated.
«10¬ Unique session name WINNTSESS
«11¬ Network name «2¬ NETID
«12¬ DLC name NTQMGR
«13¬ Remote CP name WINNTPU
«14¬ Local LSAP x‘04’, x‘08’, x‘0C’, ...
«15¬ Partner LU «6¬ WINNTLU
«16¬ TP name «8¬ MQSERIES
«17¬ Mode name «17¬ #INTER
«18¬ CPI-C file name /home/mqstart/NTCPIC
«19¬ Remote MAC address «10¬ 10005AFC5D83
Connection to an AIX system

The values in this section of the table must match those used in Table 20 on page 197, as indicated.
«10¬ Unique session name AIXSESS
«11¬ Network name «1¬ NETID
«12¬ DLC name AIXQMGR
«13¬ Remote CP name «2¬ AIXPU
«14¬ Local LSAP x‘04’, x‘08’, x‘0C’, ...
«15¬ Partner LU «4¬ AIXLU
«16¬ TP name «6¬ MQSERIES
«17¬ Mode name «14¬ #INTER
«18¬ CPI-C file name /home/mqstart/AIXCPIC
«19¬ Remote MAC address «15¬ 10005AFC5D83

258 MQSeries Intercommunication

 Sun Solaris and LU 6.2
Table 27. Configuration worksheet for SunLink Version 9.1 (continued)
ID Parameter Name Reference Example User Value
Connection to an HP-UX system

The values in this section of the table must match those used in Table 23 on page 219, as indicated.
«10¬ Unique session name HPUXSESS
«11¬ Network name «4¬ NETID
«12¬ DLC name HPUXQMGR
«13¬ Remote CP name HPUXPU
«14¬ Local LSAP x‘04’, x‘08’, x‘0C’, ...
«15¬ Partner LU «5¬ HPUXLU
«16¬ TP name «7¬ MQSERIES
«17¬ Mode name «17¬ #INTER
«18¬ CPI-C file name /home/mqstart/HPCPIC
«19¬ Remote MAC address «19¬ 10005AFC5D83
Connection to an AT&T GIS UNIX system

The values in this section of the table must match those used in the Table 25 on page 243, as indicated.
«10¬ Unique session name GISSESS
«11¬ Network name «2¬ NETID
«12¬ DLC name GISQMGR
«13¬ Remote CP name GISPU
«14¬ Local LSAP x‘04’, x‘08’, x‘0C’, ...
«15¬ Partner LU «6¬ GISLU
«16¬ TP name «8¬ MQSERIES
«17¬ Mode name «17¬ #INTER
«18¬ CPI-C file name /home/mqstart/ATTCPIC
«19¬ Remote MAC address «10¬ 10005AFC5D83
Connection to an AS/400 system

The values in this section of the table must match those used in Table 42 on page 460, as indicated.
«10¬ Unique session name AS400SESS
«11¬ Network name «2¬ NETID
«12¬ DLC name ASQMGR
«13¬ Remote CP name AS400PU
«14¬ Local LSAP x‘04’, x‘08’, x‘0C’, ...
«15¬ Partner LU «6¬ AS400LU
«16¬ TP name «8¬ MQSERIES
«17¬ Mode name «17¬ #INTER
«18¬ CPI-C file name /home/mqstart/400CPIC
«19¬ Remote MAC address «10¬ 10005AFC5D83
Connection to an OS/390 or MVS/ESA system without CICS

The values in this section of the table must match those used in Table 36 on page 396, as indicated.
«10¬ Unique session name MVSSESS
«11¬ Network name «2¬ NETID
«12¬ DLC name MVSQMGR
«13¬ Remote CP name MVSPU
«14¬ Local LSAP x‘04’, x‘08’, x‘0C’, ...
«15¬ Partner LU «6¬ MVSLU

Chapter 18. Example configuration - IBM MQSeries for Sun Solaris 259
Sun Solaris and LU 6.2
Table 27. Configuration worksheet for SunLink Version 9.1 (continued)
ID Parameter Name Reference Example User Value
«16¬ TP name «8¬ MQSERIES
«17¬ Mode name «17¬ #INTER
«18¬ CPI-C file name /home/mqstart/MVSCPIC
«19¬ Remote MAC address «10¬ 10005AFC5D83
Connection to a VSE/ESA system

The values in this section of the table must match those used in Table 44 on page 485, as indicated.
«10¬ Unique session name VSESESS
«11¬ Network name «2¬ NETID
«12¬ DLC name VSEQMGR
«13¬ Remote CP name VSEPU
«14¬ Local LSAP x‘04’, x‘08’, x‘0C’, ...
«15¬ Partner LU «6¬ VSELU
«16¬ TP name «8¬ MQSERIES
«17¬ Mode name «17¬ #INTER
«18¬ CPI-C file name /home/mqstart/VSECPIC
«19¬ Remote MAC address «10¬ 10005AFC5D83

Explanation of terms
«1¬ PU2.1 server name
This is the name of the PU2.1 server for the local control point.
«2¬ Network name
This is the unique ID of the network to which you are connected. It is an
alphanumeric value and can be 1-8 characters long. The network name
works with the Control Point name to uniquely identify a system. Your
network administrator will tell you the value.
«3¬ CP name
This is the unique Control Point name for this workstation. Your network
administrator will assign this to you.
«4¬ Line name
This is the name that identifies the connection to the LAN.
«5¬ Local MAC address
This is the network address of the token-ring card. The address to be
specified is found in the ether value displayed in response to the
ifconfig tr0 command issued at a root level of authority. (Tr0 is the name
of the machine’s token-ring interface.) If you do not have the necessary
level of authority, your Sun Solaris system administrator can tell you the
value.
«6¬ Local terminal ID
This is the unique ID of this workstation. On other platforms this is often
referred to as the Exchange ID or XID. Your network administrator will
assign this ID for you.
«7¬ Local LU name
An LU manages the exchange of data between transactions. The local LU
name is the name of the LU on your system. Your network administrator
will assign this to you.

260 MQSeries Intercommunication

 Sun Solaris and LU 6.2
«8¬ TP name
MQSeries applications trying to converse with this workstation will specify
a symbolic name for the program to be run at the receiving end. This will
have been defined on the channel definition at the sender. For simplicity,
wherever possible use a transaction program name of MQSERIES, or in the
case of a connection to VSE/ESA, where the length is limited to 4 bytes,
use MQ01.
See Table 19 on page 194 for more information.
«9¬ TP path
This is the path and name of the script file that invokes the MQSeries
program to run.
«10¬ Unique session name
This is the unique name of the Partner LU/Mode definition.
«12¬ DLC name
This is the name of the link to the remote system.
«13¬ Remote CP name
This is the name of the control point on the remote system.
«18¬ CPI-C file name
This is the full path and name of the file which holds CPI-C side
information for a partner system. There must be a separate CPI-C file for
each partner. For increased flexibility, include the full path and file name in
the MQSeries sender channel definition.

Establishing a connection using SunLink Version 9.1

This section describes how to establish a connection using SunLink Version 9.1 The
topics discussed are:
v SunLink 9.0 base configuration
v Invokable TPs
v CPI-C side information

SunLink 9.1 base configuration

To start the SunLink 9.1 graphical interface:
1. Enter sungmi at the command line.
It is assumed that the domain, manager systems, and default system were
defined during installation.
2. On the main screen, highlight Config1 in the resource tree and select File and
Open. A window entitled Connect to domain appears:

Chapter 18. Example configuration - IBM MQSeries for Sun Solaris 261
Using SunLink

3. Enter required details to connect to the required domain.

Configuring a PU 2.1 server

1. Double click on Systems in the resource tree to display a list of systems.
2. Double click on System name in the resource tree to open its subordinate
entries.
3. Using the right mouse button, highlight PU2.1 Servers in the resource tree and
select New and PU2.1 Server from the pop-up menu. A window entitled Create
PU2.1 Server appears:

4. Enter the PU2.1 Name («1¬).

5. Enter the CP Name. This consists of the Network Name («2¬)and the CP Name
(«3¬).
6. Click on Advanced >>. The advanced window appears:

262 MQSeries Intercommunication

 Using SunLink

7. Enter the SunOp Service and LU6.2 Service

8. Click on OK when you are happy with the settings.

Adding a LAN connection

1. Double click on PU2.1 Servers in the resource tree to display the name of the
PU2.1 server.
2. Using the right mouse button, highlight the server name in the resource tree
and select New and LAN Connection from the pop-up menu. A window
entitled Create LAN Connection appears:

3. Enter a Line Name («4¬) and Local MAC Address («5¬).

4. Click on Advanced>> The advanced window appears:

Chapter 18. Example configuration - IBM MQSeries for Sun Solaris 263
Using SunLink

5. Check the LAN Speed is correct.

6. Click on OK when you are happy with the settings.

Configuring a connection to a remote PU

1. Double click the PU2.1 server name in the resource tree to open its
suborditnate entries.
2. Double click on LAN Connections.
3. Using the right mouse button, highlight the LAN connection name in the
resource tree and select New and DLC from the pop-up menu. A window
entitled Create DLC appears:

264 MQSeries Intercommunication

 Using SunLink

4. Enter the DLC Name («12¬) and Remote MAC Address («19¬).
5. Click on Advanced>>. A window entitled Create DLC (advanced) appears:

6. Enter the Local LSAP for this DLC («14¬), Local Terminal ID («6¬), and
Remote CP Name («13¬).
7. When you are happy with the settings, click on OK.

Configuring an independent LU
1. Double click on Systems in the resource tree to display a list of systems.
2. Double click on the system name to open its subordinate entries.
3. Double click on PU2.1 Servers to display a list of servers.
4. Double click on the PU2.1 server name to open its subordinate entries.

Chapter 18. Example configuration - IBM MQSeries for Sun Solaris 265
Using SunLink
5. From the main window, select Edit, New, and Independent LU to display the
Create Independent LU window:

6. Enter the Local LU Name («7¬).

7. Click on Advanced>>. An advanced Create Independent LU window appears:

266 MQSeries Intercommunication

 Using SunLink

8. Enter the Network Qual Name. This consists of the Network Name («2¬) and
the Local LU («7¬).
9. Click on OK

Configuring a partner LU
1. Double click on the PU2.1 server name in the resource tree to open its
subordinate entries.
2. From the main window, select Edit, New, and Partner LU to display the Create
Partner LU window:

Chapter 18. Example configuration - IBM MQSeries for Sun Solaris 267
Using SunLink

3. Enter the Partner LU («15¬) and the Local LU Name («7¬).

4. Click on Advanced>>. The advanced Create Partner LU window appears:

5. Choose a Local LU from the drop-down list.

6. Click on OK.

Configuring the session mode

1. Double click on the PU2.1 server name to open its subordinate entries.
2. Double click on Partner LU in the resource tree to display a list of partner LUs.
3. Click on the partner LU to select it.
4. From the main window, select Edit, New, and Mode to display the Create
Mode window:

268 MQSeries Intercommunication

 Using SunLink

5. Enter the Mode Name («17¬) and DLC Name («12¬).

6. Click on Advanced>>. The advanced Create Mode window appears:

7. Enter the Unique Session Name («10¬).

8. When you are happy with the settings, click on OK.

Configuring a transaction program

1. Double click on the PU2.1 server name to open its subordinate entries.
2. Click on Transaction Programs in the resource tree to select it.
3. From the main window, select Edit, New, and Transaction Program to display
the Create Transaction Program window:

Chapter 18. Example configuration - IBM MQSeries for Sun Solaris 269
Using SunLink

4. Enter the TP Name («8¬) and Local LU («7¬).

5. Enter a path to the invokable TP in the Command Path («9¬) field:
6. Click on Advanced>>. The advanced Create Transaction Program window
appears:

7. When you are happy with the settings, click on OK.

Invokable TP path
In order to set required environment variables a script file should be defined for
each invokable TP containing the following:
#!/bin/ksh
export APPC_GATEWAY=zinfandel
export APPC_LOCAL_LU=SOLARLU
/opt/mqm/bin/amqcrs6a -m SOLARIS -n MQSERIES

CPI-C side information

In common with most other platforms, MQSeries for Sun Solaris Version 5.1 uses
CPI-C side information files («18¬) to hold information about its partner systems.
In SunLink 9.1, these are ASCII files (one per partner).

270 MQSeries Intercommunication

 Using SunLink
PTNR_LU_NAME = OS2LU «15¬
MODE_NAME = #INTER «17¬
TP_NAME = MQSERIES «16¬
SECURITY = NONE

Figure 35. CPI-C side information file for SunLink Version 9.0

The location of the file must be specified either explicitly in the conname
parameter of the sender channel definition or in the search path. It is better to
specify it fully in the conname parameter because the value of the PATH
environment variable can vary from user to user.

What next?
The connection is now established. You are ready to complete the configuration.
Go to “MQSeries for Sun Solaris configuration”.

Establishing a TCP connection

To establish a TCP connection, follow these steps.
1. Edit the file /etc/services.

Note: To edit the /etc/services file, you must be logged in as a superuser or

root. If you do not have the following line in that file, add it as shown:
MQSeries 1414/tcp # MQSeries channel listener
2. Edit the file /etc/inetd.conf. If you do not have the following line in that file,
add it as shown:
MQSeries stream tcp nowait mqm /opt/mqm/bin/amqcrsta amqcrsta
[-m queue.manager.name]
3. Find the process ID of the inetd with the command:
ps -ef | grep inetd
4. Run the command:
kill -1 inetd processid

What next?
The TCP/IP connection is now established. You are ready to complete the
configuration. Go to “MQSeries for Sun Solaris configuration”.

MQSeries for Sun Solaris configuration

Before beginning the installation process ensure that you have first created the
mqm user and group, and set the password.

Start any channel using the command:

runmqchl -c channel.name
Notes:
1. Sample programs are installed in /opt/mqm/samp.
2. Error logs are stored in /var/mqm/qmgrs/qmgrname/errors.
3. When you are using the command interpreter runmqsc to enter administration
commands, a + at the end of a line indicates that the next line is a continuation.
Ensure that there is a space between the last parameter and the continuation
character.

Chapter 18. Example configuration - IBM MQSeries for Sun Solaris 271
 Sun Solaris configuration
| 4. For an SNA or LU6.2 channel, if you experience an error when you try to load
| the communications library, probably file liblu62.so cannot be found. A likely
| solution to this problem is to add its location, which is probably
| /opt/SUNWlu62, to LD_LIBRARY_PATH.

Basic configuration
1. Create the queue manager from the UNIX prompt using the command:
crtmqm -u dlqname -q solaris

where:
solaris
Is the name of the queue manager
-q Indicates that this is to become the default queue manager
-u dlqname
Specifies the name of the undeliverable message queue

This command creates a queue manager and a set of default objects.

2. Start the queue manager from the UNIX prompt using the command:
strmqm solaris

where solaris is the name given to the queue manager when it was created.

Channel configuration
The following section details the configuration to be performed on the Sun Solaris
queue manager to implement the channel described in Figure 32 on page 97.

The MQSC command to create each object is shown. Either start runmqsc from a
UNIX prompt and enter each command in turn, or build the commands into a
command file.

Examples are given for connecting MQSeries for Sun Solaris and MQSeries for
OS/2 Warp. If you wish to connect to another MQSeries product use the
appropriate set of values from the table in place of those for OS/2.

Note: The words in bold are user-specified and reflect the names of MQSeries
objects used throughout these examples. If you change the names used here,
ensure that you also change the other references made to these objects
throughout this book. All others are keywords and should be entered as
shown.
Table 28. Configuration worksheet for MQSeries for Sun Solaris
ID Parameter Name Reference Example Used User Value
Definition for local node
«A¬ Queue Manager Name SOLARIS
«B¬ Local queue name SOLARIS.LOCALQ
Connection to MQSeries for OS/2 Warp

The values in this section of the table must match those used in Table 15 on page 164, as indicated.
«C¬ Remote queue manager name «A¬ OS2
«D¬ Remote queue name OS2.REMOTEQ
«E¬ Queue name at remote system «B¬ OS2.LOCALQ
«F¬ Transmission queue name OS2
«G¬ Sender (SNA) channel name SOLARIS.OS2.SNA

272 MQSeries Intercommunication

 Sun Solaris configuration
Table 28. Configuration worksheet for MQSeries for Sun Solaris (continued)
ID Parameter Name Reference Example Used User Value
«H¬ Sender (TCP/IP) channel name SOLARIS.OS2.TCP
«I¬ Receiver (SNA) channel name «G¬ OS2.SOLARIS.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ OS2.SOLARIS.TCP
Connection to MQSeries for Windows NT

The values in this section of the table must match those used in Table 17 on page 185, as indicated.
«C¬ Remote queue manager name «A¬ WINNT
«D¬ Remote queue name WINNT.REMOTEQ
«E¬ Queue name at remote system «B¬ WINNT.LOCALQ
«F¬ Transmission queue name WINNT
«G¬ Sender (SNA) channel name SOLARIS.WINNT.SNA
«H¬ Sender (TCP/IP) channel name SOLARIS.WINNT.TCP
«I¬ Receiver (SNA) channel name «G¬ WINNT.SOLARIS.SNA
«J¬ Receiver (TCP) channel name «H¬ WINNT.SOLARIS.TCP
Connection to MQSeries for AIX

The values in this section of the table must match those used in Table 21 on page 211, as indicated.
«C¬ Remote queue manager name «A¬ AIX
«D¬ Remote queue name AIX.REMOTEQ
«E¬ Queue name at remote system «B¬ AIX.LOCALQ
«F¬ Transmission queue name AIX
«G¬ Sender (SNA) channel name SOLARIS.AIX.SNA
«H¬ Sender (TCP) channel name SOLARIS.AIX.TCP
«I¬ Receiver (SNA) channel name «G¬ AIX.SOLARIS.SNA
«J¬ Receiver (TCP) channel name «H¬ AIX.SOLARIS.TCP
| Connection to MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| The values in this section of the table must match those used in Table 22 on page 216, as indicated.
| «C¬ Remote queue manager name «A¬ DECUX
| «D¬ Remote queue name DECUX.REMOTEQ
| «E¬ Queue name at remote system «B¬ DECUX.LOCALQ
| «F¬ Transmission queue name DECUX
| «H¬ Sender (TCP) channel name DECUX.SOLARIS.TCP
| «J¬ Receiver (TCP) channel name «H¬ SOLARIS.DECUX.TCP
Connection to MQSeries for HP-UX

The values in this section of the table must match those used in Table 24 on page 239, as indicated.
«C¬ Remote queue manager name «A¬ HPUX
«D¬ Remote queue name HPUX.REMOTEQ
«E¬ Queue name at remote system «B¬ HPUX.LOCALQ
«F¬ Transmission queue name HPUX
«G¬ Sender (SNA) channel name SOLARIS.HPUX.SNA
«H¬ Sender (TCP) channel name SOLARIS.HPUX.TCP
«I¬ Receiver (SNA) channel name «G¬ HPUX.SOLARIS.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ HPUX.SOLARIS.TCP
Connection to MQSeries for AT&T GIS UNIX

The values in this section of the table must match those used in Table 26 on page 253, as indicated.

Chapter 18. Example configuration - IBM MQSeries for Sun Solaris 273
 Sun Solaris configuration
Table 28. Configuration worksheet for MQSeries for Sun Solaris (continued)
ID Parameter Name Reference Example Used User Value
«C¬ Remote queue manager name «A¬ GIS
«D¬ Remote queue name GIS.REMOTEQ
«E¬ Queue name at remote system «B¬ GIS.LOCALQ
«F¬ Transmission queue name GIS
«G¬ Sender (SNA) channel name SOLARIS.GIS.SNA
«H¬ Sender (TCP/IP) channel name SOLARIS.GIS.TCP
«I¬ Receiver (SNA) channel name «G¬ GIS.SOLARIS.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ GIS.SOLARIS.TCP
| Connection to MQSeries for AS/400

| The values in this section of the table must match those used in Table 43 on page 472, as indicated.
| «C¬ Remote queue manager name AS400
| «D¬ Remote queue name AS400.REMOTEQ
| «E¬ Queue name at remote system «B¬ AS400.LOCALQ
| «F¬ Transmission queue name AS400
| «G¬ Sender (SNA) channel name SOLARIS.AS400.SNA
| «H¬ Sender (TCP) channel name SOLARIS.AS400.TCP
| «I¬ Receiver (SNA) channel name «G¬ AS400.SOLARIS.SNA
| «J¬ Receiver (TCP) channel name «H¬ AS400.SOLARIS.TCP
Connection to MQSeries for OS/390 or MVS/ESA without CICS

The values in this section of the table must match those used in Table 37 on page 406, as indicated.
«C¬ Remote queue manager name MVS
«D¬ Remote queue name MVS.REMOTEQ
«E¬ Queue name at remote system «B¬ MVS.LOCALQ
«F¬ Transmission queue name MVS
«G¬ Sender (SNA) channel name SOLARIS.MVS.SNA
«H¬ Sender (TCP) channel name SOLARIS.MVS.TCP
«I¬ Receiver (SNA) channel name «G¬ MVS.SOLARIS.SNA
«J¬ Receiver (TCP) channel name «H¬ MVS.SOLARIS.TCP
Connection to MQSeries for VSE/ESA

The values in this section of the table must match those used in Table 45 on page 490, as indicated.
«C¬ Remote queue manager name VSE
«D¬ Remote queue name VSE.REMOTEQ
«E¬ Queue name at remote system «B¬ VSE.LOCALQ
«F¬ Transmission queue name VSE
«G¬ Sender channel name SOLARIS.VSE.SNA
«I¬ Receiver channel name «G¬ VSE.SOLARIS.SNA

274 MQSeries Intercommunication

 Sun Solaris configuration
MQSeries for Sun Solaris sender-channel definitions using SNA
def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (SOLARIS.OS2.SNA) chltype(sdr) + «G¬

trptype(lu62) +
conname('/home/mqstart/OS2CPIC') + «14¬
xmitq(OS2) + «F¬
replace

MQSeries for Sun Solaris receiver-channel definitions using SNA

def ql (SOLARIS.LOCALQ) replace «B¬

def chl (OS2.SOLARIS.SNA) chltype(rcvr) + «I¬

trptype(lu62) +
replace

MQSeries for Sun Solaris sender-channel definitions using TCP

def ql (OS2) + «F¬
usage(xmitq) +
replace

def qr (OS2.REMOTEQ) + «D¬

rname(OS2.LOCALQ) + «E¬
rqmname(OS2) + «C¬
xmitq(OS2) + «F¬
replace

def chl (SOLARIS.OS2.TCP) chltype(sdr) + «H¬

trptype(tcp) +
conname(remote_tcpip_hostname) +
xmitq(OS2) + «F¬
replace

MQSeries for Sun Solaris receiver-channel definitions using

TCP/IP
def ql (SOLARIS.LOCALQ) replace «B¬

def chl (OS2.SOLARIS.TCP) chltype(rcvr) + «J¬

trptype(tcp) +
replace

Chapter 18. Example configuration - IBM MQSeries for Sun Solaris 275
Sun Solaris configuration

276 MQSeries Intercommunication

Chapter 19. Setting up communication in Digital OpenVMS
systems
Distributed queue management (DQM) is a remote queuing facility for MQSeries.
It provides channel control programs for the queue manager that form the interface
to communication links, controllable by the system operator. The channel
definitions held by distributed-queuing management use these connections.

When a distributed-queuing management channel is started, it tries to use the

connection specified in the channel definition. For this to succeed, it is necessary
for the connection to be defined and available. This chapter explains how to do
this.

For OS/2 and Windows NT, see “Chapter 10. Setting up communication for OS/2
and Windows NT” on page 123. For UNIX systems, see “Chapter 13. Setting up
communication in UNIX systems” on page 191. For Tandem NSK, see “Chapter 20.
Setting up communication in Tandem NSK” on page 289.

Deciding on a connection
There are four forms of communication for MQSeries on Digital OpenVMS
systems:
v TCP
v LU 6.2
v DECnet Phase IV
v DECnet Phase V

Each channel definition must specify one only as the transmission protocol
(Transport Type) attribute. One or more protocols may be used by a queue
manager.

For MQSeries clients, it may be useful to have alternative channels using different
transmission protocols. See the MQSeries Clients book.

© Copyright IBM Corp. 1993, 2000 277

 Defining a TCP connection

Defining a TCP connection

The channel definition at the sending end specifies the address of the target. The
TCP service is configured for the connection at the receiving end.

Sending end
Specify the host name, or the TCP address of the target machine, in the Connection
Name field of the channel definition. Port number 1414 is assigned by the Internet
Assigned Numbers Authority to MQSeries.

To use a port number other than the default, change the connection name field
thus:
Connection Name REMHOST(1822)

where REMHOST is the hostname of the remote machine and 1822 is the port number
required. (This must be the port that the listener at the receiving end is listening
on.)

Alternatively you can change the default sending port number by specifying it in
the queue manager configuration file (qm.ini):
TCP:
Port=1822

For more information about the values you set using qm.ini, see “Appendix D.
Configuration file stanzas for distributed queuing” on page 637.

Receiving channels using Compaq (DIGITAL) TCP/IP services

(UCX) for OpenVMS
To use Compaq (DIGITAL) TCP/IP Services (UCX) for OpenVMS, you must
configure a UCX service as follows:
1. Create a file consisting of one line and containing the DCL command to start
the TCP/IP receiver program, amqcrsta.exe:
$ mcr amqcrsta [-m Queue_Man_Name]

Place this file in the SYS$MANAGER directory. In this example the name of the
file is MQRECV.COM.
Notes:
a. If you have multiple queue managers you must make a new file and UCX
service for each queue manager.
b. Ensure that the protection on the file and its parent directory allow it to be
executable, that is, the protection is /PROT=W:RE.
| 2. Create a UCX service to start the receiving channel program automatically:
| $ UCX
| UCX> set service <p1>/port=<p2>/protocol=TCP/user_name=MQM -
| UCX> /process=<p3>/file=<p4>/limit=<p5>

| where:
| p1 Is the service name, for example MQSERIES01. A unique name is
| required for each queue manager defined.
| p2 Is the TCP/IP port number in the range 1 to 65 535. The default value
| for MQSeries is 1414.

278 MQSeries Intercommunication

 Defining a TCP connection
| p3 Is the process name. This consists of a string up to 15 characters long.
| p4 Is the name of the startup command file, for example,
| SYS$MANAGER:MQRECV.COM.
| p5 Is the process limit. This is the maximum number of connections
| allowed using the port number. If this limit is reached, subsequent
| requests are rejected.

| Note: Each channel represents a single connection to the queue

| manager.

| If a receiving channel does not start when the sending end starts, it is probably
| due to the permissions on the file being incorrect.
3. To enable the service upon every system IPL (reboot), issue the command

$ UCX SET CONFIGURATION ENABLE SERVICE MQSERIES

Using the TCP/IP SO_KEEPALIVE option

If you want to use the SO_KEEPALIVE option (as discussed in “Checking that the
other end of the channel is still available” on page 66) you must the add the
following entry to your queue manager configuration file (qm.ini) or the Windows
NT registry:
TCP:
KeepAlive=yes

Receiving channels using Cisco MultiNet for OpenVMS

To use Cisco MultiNet for OpenVMS, you must configure a MultiNet service as
follows:
1. Create a file consisting of one line and containing the DCL command to start
the TCP receiver program, amqcrsta.exe:
$ mcr amqcrsta.exe [-m Queue_Man_Name]

Place this file in the SYS$MANAGER directory.

Notes:
a. If you have multiple queue managers you must make a new file and
MultiNet service for each queue manager.
b. Ensure that the protection on the file and its parent directory allow it to be
executable, that is, the protection is /PROT=W:RE.
2. Create a MultiNet service to start the receiving channel program automatically:
$ multinet configure/server
MultiNet Server Configuration Utility 3.5 (101)
[Reading in configuration from MULTINET:SERVICES.MASTER_SERVER]
SERVER-CONFIG> add MQSeries
[Adding new configuration entry for service “MQSERIES”]
Protocol: [TCP]
TCP Port number: 1414
Program to run: sys$manager:mqrecv.com
[Added service MQSERIES to configuration]
[Selected service is now MQSERIES]
SERVER-CONFIG> set flags UCX_SERVER
MQSERIES flags set to <UCX_SERVER>]
SERVER-CONFIG> set username MQM
[Username for service MQSERIES set to MQM]
SERVER-CONFIG> exit
[Writing configuration to MULTINET_COMMON_ROOT:SERVICES.MASTER_SERVER]
$

Chapter 19. Setting up communication in Digital OpenVMS systems 279

Defining a TCP connection
The service is enabled automatically after the next system IPL (reboot). To enable
the service immediately, issue the command:

'MULTINET
CONFIGURE /SERVER RESTART'.

Receiving channels using Attachmate PathWay for OpenVMS

To use Attachmate PathWay for OpenVMS to start channels, you must configure a
PathWay service as follows:
1. Create a file consisting of one line and containing the DCL command to start
the TCP/IP receiver program, amqcrsta.exe:
$ mcr amqcrsta [-m Queue_Manager_Name]

Place this file in the SYS$MANAGER directory. In this example the name
mqrecv.com is used.
2. Create an Attachmate service to start the receiving channel program
automatically.
You do this by adding the following lines to the file
TWG$COMMON:[NETDIST.ETC]SERVERS.DAT.
# MQSeries
service-name MQSeries
program SYS$MANAGER:MQRECV.COM
socket-type SOCK_STREAM
socket-options SO_ACCEPTCONN | SO_KEEPALIVE
socket-address AF_INET , 1414
working-set 512
priority 4
INIT TCP_Init
LISTEN TCP_Listen
CONNECTED TCP_Connected
SERVICE Run_Program
username MQM
device-type UCX

Receiving channels using Process Software Corporation

TCPware
To use Process Software Corporation TCPware, you must configure a TCPware
service as follows:
1. Create a file consisting of one line and containing the DCL command to start
the TCP receiver program amqcrsta.exe:
$ mcr amqcrsta (-m Queue_Manager_Name)

Place this file in the SYS$MANAGER directory. In this example the name of the
file is MQRECV.COM.
Notes:
a. If you have multiple queue managers you must make a new file and
TCPware service for each queue manager.
b. Ensure that the protection on the file and its parent directory allow it to be
executable, that is, the protection is /PROT=W:RE.
2. Create a TCPware service to start the receiving channel program automatically:
a. Edit the TCPWARE:SERVICES. file and add an entry for the service you
want to use:
MQSeries 1414/tcp # MQSeries port

280 MQSeries Intercommunication

 Defining a TCP connection
b. Edit the TCPWARE:SERVERS.COM file and add an entry for the service
defined in the previous step:
$! SERVERS.COM
$!
$ RUN TCPWARE:NETCU
ADD SERVICE MQSeries BG_TCP -

/INPUT=SYS$MANAGER:MQRECV.COM -
/LIMIT=6 -
/OPTION=KEEPALIVE -
/USERNAME=MQM

EXIT
3. The service is enabled automatically after the next system IPL. To enable the
service immediately issue the command:
@TCPWARE:SERVERS.COM

Defining an LU 6.2 connection

MQSeries for Digital OpenVMS uses the DECnet SNA APPC/LU 6.2 Programming
Interface. This interface requires access through DECnet to a suitably configured
SNA Gateway, for example, the SNA Gateway-ST, or SNA Gateway-CT.

SNA configuration
To enable MQSeries to work with DECnet APPC/LU 6.2 you must complete your
Gateway SNA configuration first. The Digital SNA configuration must be in
agreement with the Host SNA configuration.
Notes:
1. When configuring your host system, be aware that the DECnet SNA Gateway
supports PU 2.0 and not node type 2.1. This means that the LUs on the Digital
SNA node must be dependent LUs. They reside on the Digital SNA node and
so must be defined and configured there. However, because they are dependent
LUs, they have to be activated by VTAM, by means of an ACTLU command,
and so they also need to be defined to VTAM as dependent LUs.
2. Ensure that the SNA libraries are installed as shared images upon each system
IPL by running the command @SYS$STARTUP:SNALU62$STARTUP.COM in the system
startup procedure.

To configure your SNA Gateway, set up the SNAGATEWAY_<node>_SNA.COM file,

where <node> is replaced with the node name of your DECnet SNA gateway.

Do this by responding to the configuration prompts in the Gateway installation

procedure, or by directly editing the file.

The SNA Gateway installation procedure creates the file in the directory
SYS$COMMON:[SNA$CSV].

The configuration information in this file is downloaded to the Gateway when you
run the NCP LOAD NODE command.
Notes:
1. Online changes to the current Gateway configuration can be made using the
utility SNANCP.
2. SNA resources can be monitored using the SNAP utility.

Chapter 19. Setting up communication in Digital OpenVMS systems 281

Defining an LU 6.2 connection
A sample SNA Gateway Configuration file follows:
$!+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
$! Start of file: SYS$COMMON:[SNA$CSV]SNAGATEWAY_SNAGWY_SNA.COM
$! DECnet SNA Gateway-ST SNA configuration file
$! Created: 23-FEB-1996 19:10:43.68 by SNACST$CONFIGURE V1.2
$! Host node: CREAMP User$ CHO
$!+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
$ v = f$verify(1)
$ RUN SYS$SYSTEM:SNANCP
SET LINE SYN-0 - // Line definition
DUPLEX FULL -
PROTOCOL SDLC POINT -
SIGNALLING NORMAL -
CLOCK EXTERNAL -
MODEM TYPE NORMAL -
RECEIVE BUFFERS 34 -
LOGGING INFORMATIONAL -
BUFFER SIZE 265
SET CIRCUIT SDLC-0 - // Circuit definition
LINE SYN-0 -
DUPLEX FULL -
RESPONSE MODE NORMAL -
STATION ADDRESS C1 -
LOGGING INFORMATIONAL -
STATION ID 0714002A // XID
SET PU SNA-0 CIRCUIT SDLC-0 -
LU LIST 1-32 -
SEGMENT SIZE 265 - // must equal MAXDATA on Host PU definition
LOGGING WARNING
SET CIRCUIT SDLC-0 STATE ON
SET LINE SYN-0 STATE ON
SET SERVER SNA-ACCESS -
LOGGING WARNING -
NOTE “Gateway Access Server” -
STATE ON
SET ACCESS NAME VTAMSDR PU SNA-0 LU 2 APPL MVSLU LOGON LU62SS
SET ACCESS NAME VTAMRCVR PU SNA-0 LU 3 APPL MVSLU LOGON LU62SS
$ EXIT $STATUS + (0 * 'f$verify(v)')
$!+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
$! End of file: SYS$COMMON:[SNA$CSV]SNAGATEWAY_SNAGWY_SNA.COM
$!+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Defining access names

You should set up a separate Access name for each MQSeries channel. This ensures
that the VMS system and the remote system agree on the LU used for the channel.

Note: If you use a single access name, with a range of LUs specified, the Gateway
selects the LUs in a circular order. Therefore the LU selected by the Gateway
may not correspond with the LU used by the Host channel, because the
Host associates a specific LU with a channel.

The access name is used only to communicate between the DECnet SNA APPC
program and the Gateway. It has no network meaning.
Notes:
1. The LUs are single session. You must define a separate LU for each channel if
they are to run simultaneously.
2. You are advised to use names that associate the access name to the
corresponding channel, but you can choose any name.
3. The APPL in the ACCESS name definition must match the remote (in this case
MVSLU) APPL in VTAM.
4. The LU number must correspond to the LOCADDR in the LU definition
statement in VTAM. Here is an example VTAM line and LU definitions:
IYA8L007 LINE ADDRESS=(007,FULL),
ISTATUS=ACTIVE
IYA8P307 PU ADDR=C2,
ISTATUS=ACTIVE,
IRETRY=NO,

282 MQSeries Intercommunication

 Defining an LU 6.2 connection
MAXDATA=521,
MAXOUT=7,
PASSLIM=7,
PUTYPE=2
IYA83071 LU LOCADDR=2,PACING=1,DLOGMOD=LU62CP1
IYA83072 LU LOCADDR=3
5. The LOGON must specify the logmode entry on the VTAM host that specifies
parameters acceptable to the SNA Gateway. Here is an example of a single
session logmode entry:
LU62SS MODEENT LOGMODE=LU62SS,
TYPE=0, ONLY TYPE RECOGNIZED
FMPROF=X’13’, SNA
TSPROF=X’07’, SNA
PRIPROT=X’B0’, PRIMARY PROTOCOL
SECPROT=X’B0’, SECONDARY PROTOCOL
COMPROT=X’50B1’, COMMON PROTOCOL
SSNDPAC=X’00’,
SRCVPAC=X’00’,
RUSIZES=X’8989’, RUSIZES IN-4096 OUT-4096
PSNDPAC=X’00’,
PSERVIC=X’060200000000000000002C00’,

The DECnet SNA Gateway Guide to IBM Parameters details the parameters
expected by the Gateway.

Specifying SNA configuration parameters to MQSeries

MQSeries obtains knowledge of the SNA resources by passing the Gateway Node
name and the Access name to the channel program.

Passing parameters to sender and requester channel pairs

For sender and requester channel pairs specify the Gateway Node and Access
Name in the CONNAME string in the channel definition.

The CONNAME also includes the TPNAME that is used by the SNA Allocate verb
to invoke the remote program.

The format of the CONNAME is: CONNAME('GatewayNode.AccessName(TpName)').

For example: CONNAME('SNAGWY.VTAMSDR(MQSERIES)'), where SNAGWY is the Gateway

node, VTAMSDR is the access name, and MQSeries is the TPNAME.

Note: Do not use the TPNAME field in the channel definition.

Running senders and requesters

Senders, requesters, and fully qualified servers can be explicitly run by performing
a START CHANNEL command in runmqsc.

Senders and requesters on Digital OpenVMS initiate a session by issuing an

INIT-SELF to request a BIND from the host. In issuing the Allocate verb, the
MQSeries channel program takes the LU name and the Mode Name from the
Access Name.

MQSeries then allocates a conversation using the specified TPNAME.

Passing parameters to servers and receivers

For servers and receivers, specify the Gateway Node, Access Name, and TPNAME
as command line parameters to the runmqlsr command.

Chapter 19. Setting up communication in Digital OpenVMS systems 283

Defining an LU 6.2 connection
Running servers and receivers
Servers and receivers are started by running the runmqlsr command.
$ RUNMQLSR -m QMname -n TPname -g GatewayNode(AccessName)

Note: Each server and receiver channel requires its own listener process.

You can include these commands in the MQSeries startup file,

SYS$STARTUP:MQS_STARTUP.

Receivers and servers issue the ACTIVATE_SESSION request to the Gateway in

passive mode. In passive mode the channel program waits for a BIND from the
remote system, which puts the LU into the active-listening state, waiting for a bind
from the host.

You can check the LU status using SNANCP to make sure that you are in
active-listening state on the correct LU. If a BIND from the host arrives specifying
the LU that is in active-listening state, the session will be established. After
establishing the session, the host attempts to allocate a conversation.

The TPNAME used by the host sender/requester channel must be the same name
as that specified on the command line in order to establish the conversation.

Note: RUNMQLSR recycles when a remote channel disconnects. There is a finite

period of time before the listener is ready to accept further binds from the
host.

Ending the SNA Listener process

To find the batch job number for the SNA listener process, type:
$ show queue / all

To end the SNA Listener process type:

$ delete /entry=<jobnumber>

where <jobnumber> is the job number of the listener batch job.

Sample MQSeries configuration

*
* channel configuration for saturn.queue.manager for LU6.2
*
def ql('HOST_SENDER_TQ') usage(xmitq)

def chl('HOST.TO.VMS') chltype(rcvr) trptype(lu62) +

seqwrap(999999999)
def chl('VMS.TO.HOST') chltype(sdr) trptype(lu62) +
conname('SNAGWY.VTAMSDR(MQSERIES)') +
xmitq('HOST_SENDER_TQ') seqwrap(999999999)

In this example two channels, a sender and a receiver, have been set up.

On the remote system you need to configure the corresponding channels. Channels
that talk to each other must have the same name.
v The OpenVMS sender, VMS.TO.HOST, talks to a receiver called VMS.TO.HOST
on the host system.
v The OpenVMS receiver, HOST.TO.VMS talks to a sender HOST.TO.VMS on the
host system.

284 MQSeries Intercommunication

 Defining an LU 6.2 connection
The commands to start each channel are:
// Start sender channel to host system
$ runmqchl -m “saturn.queue.manager” -c “VMS.TO.HOST”
// Set up listener to lesten for incoming SNA requests.
$ runmqlsr -m “saturn.queue.manager” -n “TPNAME” -g SNAGWY(VTAMRCVR)

Note: The TPNAME must match the outbound TPNAME on the MVS sender channel
side. This is specified in the MVS side information, for example:
SIDELETE
DESTNAME(ID1)
SIADD
DESTNAME(ID1)
MODENAME(LU62SS)
TPNAME(MQSERIES)
PARTNER_LU(IYA83072)

Problem solving
Error PUNOTAVA - PU has not been activated

This error indicates a lack of connectivity between the two machines. Make sure
your line and circuit are set to state ON. Use SNATRACE at the circuit level to
verify that the Digital OpenVMS machine is polling. If no response is received for
the poll, check that the PU on the host is enabled. If the line will not go to the ON
STATE check your physical line. If the trace shows the host responding to the poll,
but the PU still does not become active, check your setting of the STATION ID.

Failure to allocate conversation

This error is returned by a sender or requester to indicate that allocate failed. Run
trace to verify that the session can be established. Verify that the Digital OpenVMS
machine sends the INIT-SELF (010681). If there is no response to the INIT-SELF
make sure that the host MQSeries channel is started. If the BIND from the host is
rejected by the Digital OpenVMS machine analyze the Digital bind response. Use
the DECnet SNA Gateway Guide to IBM Parameters to see what is set incorrectly in
the mode. If a session is established and the conversation allocate request is
rejected verify that the TPNAMEs are configured the same on both systems.

For receivers and servers verify that a BIND is sent by the host. If not, enable the
Host MQSeries channel. If the BIND is rejected check the reason for rejection.
Make sure that the Digital OpenVMS listener LU is the LU with which the host is
trying to establish a session.

MQSeries connection failure

After establishing a conversation the two MQSeries channels engage in a protocol

to establish an MQSeries channel connection. If this fails, the reason for failure
should be indicated in the error logs on the two systems. Check both logs and
correct the indicated problem. For example the connection fails if one system has a
SEQWRAP value of 999999999 and the other 999999. In the SNATRACE you will
see that the allocate succeeded and that MQ™ is trying to establish a channel
connection. At this point the MQSeries logs are the best aid in resolving problems.

Defining a DECnet Phase IV connection

The channel definition at the sending end specifies the address of the target. The
DECnet network object is configured for the connection at the receiving end.

Chapter 19. Setting up communication in Digital OpenVMS systems 285

DECnet Phase IV connections
Sending end
Specify the DECnet node name and the DECNET object name in the Connection
Name field of the channel definition. You need a different DECnet object for each
separate queue manager that is defined. For example, to specify DECnet object
MQSERIES on node FOONT enter the following when defining the channel:
CONNAME('FOONT(MQSERIES)')

Receiving on DECnet Phase IV

To use DECnet Phase IV to start channels, you must configure a DECnet object as
follows:
1. Create a file consisting of one line and containing the DCL command to start
the DECnet receiver program, amqcrsta.exe:
$ mcr amqcrsta [-m Queue_Man_Name] -t DECnet

Place this file in the SYS$MANAGER directory. In this example the file is
named MQRECVDECNET.COM.
Notes:
a. If you have multiple queue managers you must make a new file and
DECnet object for each queue manager.
b. If a receiving channel does not start when the sending end starts, it is
probably due to the permissions on this file being incorrect.
2. Create a DECnet object to start the receiving channel program automatically.
You must supply the correct password for MQSeries.
$ MCR NCP
NCP> define object MQSERIES
Object number (0-255): 0
File name (filename):sys$manager:mqrecvdecnet.com
Privileges (List of VMS privileges):
Outgoing connect privileges (List of VMS privileges):
User ID (1-39 characters): mqm
Password (1-39 characters): mqseries
Account (1-39 characters):
Proxy access (INCOMING, OUTGOING, BOTH, NONE, REQUIRED):
NCP> set known objects all
NCP> exit

Note: You could use proxy user identifiers rather than actual user identifiers.
This will prevent any unauthorized access to the database. Information
on how to set up proxy identifiers is given in the Digital DECnet for
OpenVMS Networking Manual.
3. Ensure that all known objects are set when DECnet is started.

Defining a DECnet Phase V connection

Set up the MQSeries configuration for channel objects:
1. Start the NCL configuration interface by issuing the following command:
$ MC NCL
NCL>
2. Create a session control application entity by issuing the following commands:
NCL> create session control application MQSERIES
NCL> set sess con app MQSERIES address {name=MQSERIES}
NCL> set sess con app MQSERIES image name -
_ SYS$MANAGER:MQRECVDECNET.COM
NCL> set sess con app MQSERIES user name “MQM”
NCL> set sess con app MQSERIES node synonym true
NCL> show sess con app MQSERIES all [characteristics]

286 MQSeries Intercommunication

 DECnet Phase V connections
Note: User-defined values are in uppercase.
3. Create the command file as for DECnet PhaseIV.
4. The log file for the object is net$server.log in the sys$login directory for the
application-specified user name.
5. To enable the session control application upon every system IPL (reboot), add
the preceding NCL commands to the file
SYS$MANAGER:NET$APPLICATION_LOCAL.NCL.

Chapter 19. Setting up communication in Digital OpenVMS systems 287

DECnet Phase V connections

288 MQSeries Intercommunication

Chapter 20. Setting up communication in Tandem NSK
Distributed queue management (DQM) is a remote queuing facility for MQSeries.
It provides channel control programs for the queue manager that form the interface
to communication links, controllable by the system operator. The channel
definitions held by distributed-queuing management use these connections.

When a distributed-queuing management channel is started, it tries to use the

connection specified in the channel definition. For this to succeed, it is necessary
for the connection to be defined and available. This chapter explains how to do
this.

For OS/2 and Windows NT, see “Chapter 10. Setting up communication for OS/2
and Windows NT” on page 123. For UNIX systems, see “Chapter 13. Setting up
communication in UNIX systems” on page 191. For Digital OpenVMS, see
“Chapter 19. Setting up communication in Digital OpenVMS systems” on page 277.

Deciding on a connection
There are two forms of communication for MQSeries for Tandem NonStop Kernel:
v TCP
v LU 6.2

Each channel definition must specify one only as the transmission protocol
(Transport Type) attribute. One or more protocols may be used by a queue
manager.

When connecting to MQSeries clients, it may be useful to have alternative channels

using different transmission protocols. See the MQSeries Clients book for more
information. (There is no MQSeries for Tandem NonStop Kernel client.)

SNA channels
The following channel attributes are necessary for SNA channels in MQSeries for
Tandem NonStop Kernel:
CONNAME
The value of CONNAME depends on whether SNAX or ICE is used as the
communications protocol:
If SNAX is used:
CONNAME(’$PPPP.LOCALLU.REMOTELU’)
Applies to sender, requester, and fully-qualified server channels,
where:
$PPPP Is the process name of the SNAX/APC process.
LOCALLU
Is the name of the Local LU.
REMOTELU
Is the name of the partner LU on the remote machine.

For example:
CONNAME('$BP01.IYAHT080.IYCNVM03')

© Copyright IBM Corp. 1993, 2000 289

SNA channels
CONNAME(’$PPPP.LOCALLU’)
Applies to receiver and non fully-qualified server channels, where:
$PPPP Is the process name of the SNAX/APC process.
LOCALLU
Is the name of the Local LU. This value can be an asterisk
(*), indicating any name.

For example:
CONNAME('$BP01.IYAHT080')

If ICE is used:
CONNAME(’$PPPP.#OPEN.LOCALLU.REMOTELU’)
Applies to sender, requester, and fully-qualified server channels,
where:
$PPPP Is the process name of the ICE process.
#OPEN
Is the ICE open name.
LOCALLU
Is the name of the Local LU.
REMOTELU
Is the name of the partner LU on the remote machine.

For example:
CONNAME('$ICE.#IYAHT0C.IYAHT0C0.IYCNVM03')
CONNAME(’$PPPP.#OPEN.LOCALLU’)
Applies to receiver and non fully-qualified server channels, where:
$PPPP Is the process name of the SNAX/APC process.
#OPEN
Is the ICE open name.
LOCALLU
Is the name of the Local LU. This value can be an asterisk
(*), indicating any name.

For example:
CONNAME('$ICE.#IYAHT0C.IYAHT0C0')
MODENAME
Is the SNA mode name. For example, MODENAME(LU62PS).
TPNAME(’LOCALTP[.REMOTETP]’)
Is the Transaction Process (TP) name.
LOCALTP
Is the local name of the TP.
REMOTETP
Is the name of the TP on the remote machine. This value is
optional. If it is not specified, and the channel is one that initiates a
conversation (that is, a sender, requester, or fully-qualified server
channel) the LOCALTP name is used.

Both the LOCALTP and REMOTETP values can be up to 16 characters in

length.
Notes:
1. If SNAX is being used to facilitate SNA communications, the values in
the LOCALTP field in the TPNAME must match TPs defined to SNAX.
You are recommended to use uppercase when defining an LU name.

290 MQSeries Intercommunication

 SNA channels
2. If ICE is being used, TPNAMEs do not need to be defined to ICE; they
need only be present in the MQSeries channel definitions.

LU 6.2 responder processes

There is no SNA listener process in MQSeries for Tandem NonStop Kernel. Each
channel initiated from a remote system (receiver, server, or requester that has a
fully-qualified server on the remote system or a requester that has a sender on the
remote system) must have its own, unique TP name on which it can listen. This TP
name is specified as the LOCALTP value.

Such channels must be defined to MQSC with the attribute

AUTOSTART(ENABLED) to ensure that there is an LU 6.2 responder process
listening on this TP name whenever the queue manager is started. This LU 6.2
responder process (MQLU6RES) services incoming SNA requests for its particular
TP. If the channel is newly defined, or has been recently altered, an LU 6.2
responder process can be started for that channel by issuing either the MQSC
command START CHANNEL (using runmqsc) or the runmqchl control command
from the TACL prompt.

SNA channels defined AUTOSTART(DISABLED) do not listen for incoming SNA

requests. LU 6.2 responder processes are not started for such channels. A message
is logged to MQERRLG1 whenever an LU 6.2 responder process is started.

TCP channels
For information about using a nondefault TCP process for communications via
TCP, and information about the TCP ports a queue manager listens on, see the
MQSeries for Tandem NonStop Kernel System Management Guide.

Chapter 20. Setting up communication in Tandem NSK 291

Communications examples

Communications examples
This section provides communications setup examples for SNA (SNAX and ICE)
and TCP.

SNAX communications example

This section provides:
v An example SCF configuration file for the SNA line
v Some example SYSGEN parameters to support the line
v An example SCF configuration file for the SNA process definition
v Some example MQSC channel definitions

SCF SNA line configuration file

Here is an example SCF configuration file:

==
== SCF configuration file for defining SNA LINE, PUs, and LUs to VTAM
== Line is called $SNA02 and SYSGEN'd into the Tandem system
==

ALLOW ALL
ASSUME LINE $SNA02

ABORT, SUB LU
ABORT, SUB PU
ABORT

DELETE, SUB LU
DELETE, SUB PU
DELETE

292 MQSeries Intercommunication

 Communications examples
==
== ADD $SNA02 LINE DEFINITION
==

ADD LINE $SNA02, STATION SECONDARY, MAXPUS 5, MAXLUS 1024, RECSIZE 2048, &
CHARACTERSET ASCII, MAXLOCALLUS 256, &
PUIDBLK %H05D, PUIDNUM %H312FB

==
== ADD REMOTE PU OBJECT, LOCAL IS IMPLICITLY DEFINED AS #ZNT21
==

ADD PU #PU2, ADDRESS 1, MAXLUS 16, RECSIZE 2046, TYPE (13,21), &
TRRMTADDR 04400045121088, DYNAMIC ON, &
ASSOCIATESUBDEV $CHAMB.#p2, &
TRSSAP %H04, &
CPNAME IYAQCDRM, SNANETID GBIBMIYA

==
== ADD LOCAL LU OBJECT
==

ADD LU #ZNTLU1, TYPE (14,21), RECSIZE 1024, &

CHARACTERSET ASCII, PUNAME #ZNT21, SNANAME IYAHT080

==
== ADD PARTNER LU OBJECTS
==

== spinach (HP)

ADD LU #PU2LU1, TYPE(14,21), PUNAME #PU2, SNANAME IYABT0F0

== stingray (AIX)

ADD LU #PU2LU2, TYPE(14,21), PUNAME #PU2, SNANAME IYA3T995

== coop007 (OS/2)

ADD LU #PU2LU3, TYPE(14,21), PUNAME #PU2, SNANAME IYAFT170

== MVS CICS

ADD LU #PU2LU4, TYPE(14,21), PUNAME #PU2, SNANAME IYCMVM03

== MVS Non-CICS

ADD LU #PU2LU5, TYPE(14,21), PUNAME #PU2, SNANAME IYCNVM03

== finnr100 (NT)

ADD LU #PU2LU6, TYPE(14,21), PUNAME #PU2, SNANAME IYAFT080

== winas18 (AS400)

Chapter 20. Setting up communication in Tandem NSK 293

Communications examples

ADD LU #PU2LU7, TYPE(14,21), PUNAME #PU2, SNANAME IYAFT110

== MQ-Portuguese (OS/2)

ADD LU #PU2LU8, TYPE(14,21), PUNAME #PU2, SNANAME IYAHT090

== VSE

ADD LU #PU2LU10, TYPE(14,21), PUNAME #PU2, SNANAME IYZMZSI2

== START UP TOKEN RING ASSOCIATE SUB DEVICE $CHAMB.#P2

== then start the line, pu's, and lu's

START LINE $CHAMB, SUB ALL

START
START, SUB PU

STATUS
STATUS, SUB PU
STATUS, SUB LU

SYSGEN parameters
The following are CONFTEXT file entries for a SYSGEN to support the SNA and
token ring lines:

!**************************************************************************
! LAN MACRO
!**************************************************************************
! This macro is used for all 361x LAN controllers
! REQUIRES T9375 SOFTWARE PACKAGE

C3613|MLAM = MLAM
TYPE 56, SUBTYPE 0,
PROGRAM C9376P00,
INTERRUPT IOP|INTERRUPT|HANDLER,
MAXREQUESTSIZE 32000,
RSIZE 32000,
BURSTSIZE 16,
LINEBUFFERSIZE 32,
STARTDOWN #;

!**************************************************************************
! SNAX macro for Token ring lines
!**************************************************************************
TOKEN|RING|SNAX|MACRO = SNATS
TYPE 58,
SUBTYPE 4,
RSIZE 1024,
SUBTYPE 4,
FRAMESIZE 1036 # ;

294 MQSeries Intercommunication

 Communications examples
!**************************************************************************
! SNAX MANAGER
!**************************************************************************
SSCP|MACRO = SNASVM
TYPE 13, SUBTYPE 5,
RSIZE 256 #;

!**************************************************************************
! LAN CONTROLLER
!**************************************************************************
LAN1 3616 0,1 %130 ;

!*********** Service manager

SNAX 6999 0,1 %370 ;

!*********** SNAX/Token Ring Pseudocontroller

RING 6997 0,1 %360 ;

!*********** Token Ring Line

$CHAMB LAN1.0, LAN1.1 C3613|MLAM, NAME #LAN1;

!*********** Configure the SSCP

$SSCP SNAX.0, SNAX.1 SSCP|MACRO;

!*********** Sna lines for Dummy Controller over Token Ring

$SNA01 RING.0, RING.1 TOKEN|RING|SNAX|MACRO;
$SNA02 RING.2, RING.3 TOKEN|RING|SNAX|MACRO;

SNAX/APC process configuration

The following definitions configure the example APC process (process name
$BP01) via SCF for the SNA line.

Note: The pathway process $BP01 is created using the Tandem utility APCRUN.

==
== SCF Configuration file for SNAX/APC Lus
==

ALLOW ERRORS

ASSUME PROCESS $BP01

ABORT SESSION *
ABORT TPN *
ABORT PTNR-MODE *
ABORT PTNR-LU *
ABORT LU *

DELETE TPN *
DELETE PTNR-MODE *
DELETE PTNR-LU *
DELETE LU *

==
== ADD LOCAL LU
==
ADD LU IYAHT080, SNANAME GBIBMIYA.IYAHT080, SNAXFILENAME $SNA02.#ZNTLU1, &
MAXSESSION 256, AUTOSTART YES

Chapter 20. Setting up communication in Tandem NSK 295

Communications examples

== TPnames for MQSeries

ADD TPN IYAHT080.INTCRS6A

ADD TPN IYAHT080.DUMMY, GENERALTPREADY yes, SESSIONCONTROL yes, &
REMOTEATTACHTIMER -1, REMOTEATTACH queue

=== Spinach (HP) Partner LU

ADD PTNR-LU IYAHT080.IYABT0F0, SNANAME GBIBMIYA.IYABT0F0, &

PERIPHERAL-NODE NO, PARALLEL-SESSION-LU YES

ADD PTNR-MODE IYAHT080.IYABT0F0.LU62PS, MODENAME LU62PS, &

DEFAULTMAXSESSION 8, DEFAULTMINCONWINNER 4, &
DEFAULTMINCONLOSER 3, MAXAUTOACT 1, RCVWINDOW 4, &
DEFAULTMAXINRUSIZE 1024, DEFAULTMAXOUTRUSIZE 1024, &
SENDWINDOW 4

ADD TPN IYAHT080.MH01SDRCSDR

ADD TPN IYAHT080.MH01RQSDSDR
ADD TPN IYAHT080.MH01RQSVSVR
ADD TPN IYAHT080.MH01SDRCRCVR
ADD TPN IYAHT080.MH01RQSVRQSTR
ADD TPN IYAHT080.MH01RQSDRQSTR

==
== Winas18 (AS400) Partner LU
==

ADD PTNR-LU IYAHT080.IYAFT110, SNANAME GBIBMIYA.IYAFT110, &

PERIPHERAL-NODE NO, PARALLEL-SESSION-LU YES

ADD PTNR-MODE IYAHT080.IYAFT110.LU62PS, MODENAME LU62PS, &

DEFAULTMAXSESSION 8, DEFAULTMINCONWINNER 4, &
DEFAULTMINCONLOSER 3, MAXAUTOACT 1, RCVWINDOW 4, &
DEFAULTMAXINRUSIZE 1024, DEFAULTMAXOUTRUSIZE 1024, &
SENDWINDOW 4

ADD TPN IYAHT080.M401SDRCSDR

ADD TPN IYAHT080.M401RQSDSDR
ADD TPN IYAHT080.M401RQSVSVR
ADD TPN IYAHT080.M401SDRCRCVR
ADD TPN IYAHT080.M401RQSVRQSTR
ADD TPN IYAHT080.M401RQSDRQSTR

296 MQSeries Intercommunication

 Communications examples

==
== Stingray (AIX) Partner LU
==

ADD PTNR-LU IYAHT080.IYA3T995, SNANAME GBIBMIYA.IYA3T995, &

PERIPHERAL-NODE NO, PARALLEL-SESSION-LU YES

ADD PTNR-MODE IYAHT080.IYA3T995.LU62PS, MODENAME LU62PS, &

DEFAULTMAXSESSION 8, DEFAULTMINCONWINNER 4, &
DEFAULTMINCONLOSER 3, MAXAUTOACT 1, RCVWINDOW 4, &
DEFAULTMAXINRUSIZE 1024, DEFAULTMAXOUTRUSIZE 1024, &
SENDWINDOW 4

ADD TPN IYAHT080.MA02SDRCSDR

ADD TPN IYAHT080.MA02RQSDSDR
ADD TPN IYAHT080.MA02RQSVSVR
ADD TPN IYAHT080.MA02SDRCRCVR
ADD TPN IYAHT080.MA02RQSVRQSTR
ADD TPN IYAHT080.MA02RQSDRQSTR

==
== coop007 (OS/2) Partner LU
==

ADD PTNR-LU IYAHT080.IYAFT170, SNANAME GBIBMIYA.IYAFT170, &

PERIPHERAL-NODE NO, PARALLEL-SESSION-LU YES

ADD PTNR-MODE IYAHT080.IYAFT170.LU62PS, MODENAME LU62PS, &

DEFAULTMAXSESSION 8, DEFAULTMINCONWINNER 4, &
DEFAULTMINCONLOSER 3, MAXAUTOACT 1, RCVWINDOW 4, &
DEFAULTMAXINRUSIZE 1024, DEFAULTMAXOUTRUSIZE 1024, &
SENDWINDOW 4

ADD TPN IYAHT080.MO02SDRCSDR

ADD TPN IYAHT080.MO02RQSDSDR
ADD TPN IYAHT080.MO02RQSVSVR
ADD TPN IYAHT080.MO02SDRCRCVR
ADD TPN IYAHT080.MO02RQSVRQSTR
ADD TPN IYAHT080.MO02RQSDRQSTR

==
== MQ-Portuguese (OS/2) Partner LU
==

ADD PTNR-LU IYAHT080.IYAHT090, SNANAME GBIBMIYA.IYAHT090, &

PERIPHERAL-NODE NO, PARALLEL-SESSION-LU YES

ADD PTNR-MODE IYAHT080.IYAHT090.LU62PS, MODENAME LU62PS, &

DEFAULTMAXSESSION 8, DEFAULTMINCONWINNER 4, &
DEFAULTMINCONLOSER 3, MAXAUTOACT 1, RCVWINDOW 4, &
DEFAULTMAXINRUSIZE 1024, DEFAULTMAXOUTRUSIZE 1024, &
SENDWINDOW 4

Chapter 20. Setting up communication in Tandem NSK 297

Communications examples
==
== finnr100 (NT) Partner LU
==

ADD PTNR-LU IYAHT080.IYAFT080, SNANAME GBIBMIYA.IYAFT080, &

PERIPHERAL-NODE NO, PARALLEL-SESSION-LU YES

ADD PTNR-MODE IYAHT080.IYAFT080.LU62PS, MODENAME LU62PS, &

DEFAULTMAXSESSION 8, DEFAULTMINCONWINNER 4, &
DEFAULTMINCONLOSER 3, MAXAUTOACT 1, RCVWINDOW 4, &
DEFAULTMAXINRUSIZE 1024, DEFAULTMAXOUTRUSIZE 1024, &
SENDWINDOW 4

ADD TPN IYAHT080.MW01SDRCSDR

ADD TPN IYAHT080.MW01RQSDSDR
ADD TPN IYAHT080.MW01RQSVSVR
ADD TPN IYAHT080.MW01SDRCRCVR
ADD TPN IYAHT080.MW01RQSVRQSTR
ADD TPN IYAHT080.MW01RQSDRQSTR

==
== MVS CICS Partner LU
==

ADD PTNR-LU IYAHT080.IYCMVM03, SNANAME GBIBMIYA.IYCMVM03, &

PERIPHERAL-NODE NO, PARALLEL-SESSION-LU YES

ADD PTNR-MODE IYAHT080.IYCMVM03.LU62PS, MODENAME LU62PS, &

DEFAULTMAXSESSION 8, DEFAULTMINCONWINNER 4, &
DEFAULTMINCONLOSER 3, MAXAUTOACT 1, RCVWINDOW 4, &
DEFAULTMAXINRUSIZE 1024, DEFAULTMAXOUTRUSIZE 1024, &
SENDWINDOW 4

ADD TPN IYAHT080.VM03SDRCSDR

ADD TPN IYAHT080.VM03RQSDSDR
ADD TPN IYAHT080.VM03RQSVSVR
ADD TPN IYAHT080.VM03SDRCRCVR
ADD TPN IYAHT080.VM03RQSVRQSTR
ADD TPN IYAHT080.VM03RQSDRQSTR

==
== MVS Non CICS Partner LU
==

ADD PTNR-LU IYAHT080.IYCNVM03, SNANAME GBIBMIYA.IYCNVM03, &

PERIPHERAL-NODE NO, PARALLEL-SESSION-LU YES

ADD PTNR-MODE IYAHT080.IYCNVM03.LU62PS, MODENAME LU62PS, &

DEFAULTMAXSESSION 8, DEFAULTMINCONWINNER 4, &
DEFAULTMINCONLOSER 3, MAXAUTOACT 1, RCVWINDOW 4, &
DEFAULTMAXINRUSIZE 1024, DEFAULTMAXOUTRUSIZE 1024, &
SENDWINDOW 4

ADD TPN IYAHT080.VM03NCMSDRCSDR

ADD TPN IYAHT080.VM03NCMRQSDSDR
ADD TPN IYAHT080.VM03NCMRQSVSVR
ADD TPN IYAHT080.VM03NCMSDRCRCVR
ADD TPN IYAHT080.VM03NCMRQSVRQSTR
ADD TPN IYAHT080.VM03NCMRQSDRQSTR

298 MQSeries Intercommunication

 Communications examples
==
== VSE Partner LU
==

ADD PTNR-LU IYAHT080.IYZMZSI2, SNANAME GBIBMIYA.IYZMZSI2, &

PERIPHERAL-NODE NO, PARALLEL-SESSION-LU YES

ADD PTNR-MODE IYAHT080.IYZMZSI2.LU62PS, MODENAME LU62PS, &

DEFAULTMAXSESSION 8, DEFAULTMINCONWINNER 4, &
DEFAULTMINCONLOSER 3, MAXAUTOACT 1, RCVWINDOW 4, &
DEFAULTMAXINRUSIZE 1024, DEFAULTMAXOUTRUSIZE 1024, &
SENDWINDOW 4

==
== Start the LUs
==

START LU IYAHT080, SUB ALL

START TPN *

Channel definitions
Here are some example MQSeries channel definitions that support the SNAX
configuration:
v A sender channel to MQSeries on OS/390 (not using CICS):
DEFINE CHANNEL(MT01.VM03.SDRC.0002) CHLTYPE(SDR) +
TRPTYPE(LU62) +
SEQWRAP(9999999) MAXMSGL(2048) +
XMITQ('VM03NCM.TQ.SDRC.0001') +
CONNAME('$BP01.IYAHT080.IYCNVM03') +
MODENAME('LU62PS') TPNAME(DUMMY)
v A receiver channel from MQSeries on OS/390:
DEFINE CHANNEL(VM03.MT01.SDRC.0002) CHLTYPE(RCVR) +
TRPTYPE(LU62) REPLACE DESCR('Receiver channel from VM03NCM') +
SEQWRAP(9999999) +
MAXMSGL(2048) AUTOSTART(ENABLED) +
CONNAME('$BP01.IYAHT080') TPNAME(VM03NCMSDRCRCVR)
v A server channel to MQSeries on OS/390 which is capable of initiating a
conversation, or being initiated by a remote requester channel:
DEFINE CHANNEL(MT01.VM03.RQSV.0002) CHLTYPE(SVR) +
TRPTYPE(LU62) +
SEQWRAP(9999999) MAXMSGL(2048) +
XMITQ('VM03NCM.TQ.RQSV.0001') +
CONNAME('$BP01.IYAHT080.IYCNVM03') +
MODENAME('LU62PS') TPNAME(VM03NCMRQSVSVR.DUMMY) +
AUTOSTART(ENABLED)

where DUMMY is the TPNAME the MVS queue manager is listening on.

ICE communications example

There are two stages in configuring ICE for MQSeries:
1. The ICE process itself must be configured.
2. Line ($ICE01, in the following example) and SNA information must be input to
the ICE process.

Configuring the ICE process

Here is an example ICE process configuration. This configuration is located by
default in a file called GOICE:

Chapter 20. Setting up communication in Tandem NSK 299

Communications examples

?tacl macro
clear all
param backupcpu 1
param cinittimer 120
param collector $0
param config icectl
param idblk 05d
param idnum 312FF
param cpname IYAHR00C
param datapages 64
param dynamicrlu yes
param genesis $gen
param maxrcv 4096
param loglevel info
param netname GBIBMIYA
param password xxxxxxxxxxxxxxxxxxxx
param retrys1 5
param secuserid super.super
param startup %1%
param timer1 20
param timer2 300
param usstable default
run $system.ice.ice/name $ICE,nowait,cpu 0,pri 180,highpin off/

Note: The password param has been replaced by xxxxxxxxxxxxxxxxxxxx.

Defining the line and APC information

Once the ICE process has been started with this configuration, the following
information is input to the ICE process using the Node Operator Facility (NOF**).
This example defines a line called $ICE01 running on the token ring port
$CHAMB.#ICE:

==
== ICE definitions for PU IYAHR00C.
== Local LU for this PU is IYAHT0C0.
==

ALLOW ERRORS

OPEN $ICE

ABORT LINE $ICE01, SUB ALL

DELETE LINE $ICE01, SUB ALL

==
== ADD TOKEN RING LINE
==

ADD LINE $ICE01, TNDM $CHAMB.#ICE, &

IDBLK %H05D, &
PROTOCOL TOKENRING, WRITEBUFFERSIZE 8192

300 MQSeries Intercommunication

 Communications examples

==
== ADD PU OBJECT
==

ADD PU IYAHR00C, LINE $ICE01, MULTIROUTE YES, &

DMAC 400045121088, DSAP %H04, &
NETNAME GBIBMIYA, IDNUM %H312FF, IDBLK %H05D, &
RCPNAME GBIBMIYA.IYAQCDRM, SSAP %H08

==
== Add Local APPL Object
==

DELETE APPL IYAHT0C0

ADD APPL IYAHT0C0, ALIAS IYAHT0C0, LLU IYAHT0C0, PROTOCOL CPIC, &
OPENNAME #IYAHT0C

==
== Add Mode LU62PS
==

DELETE MODE LU62PS

ADD MODE LU62PS, MAXSESS 8, MINCONWIN 4, MINCONLOS 3

==
== Add Partner LU Objects
==

== spinach (HP)

ABORT RLU IYABT0F0

DELETE RLU IYABT0F0
ADD RLU IYABT0F0, MODE LU62PS, PARSESS YES

== stingray (AIX)

ABORT RLU IYA3T995

DELETE RLU IYA3T995
ADD RLU IYA3T995, MODE LU62PS, PARSESS YES

== coop007 (OS/2)

ABORT RLU IYAFT170

DELETE RLU IYAFT170
ADD RLU IYAFT170, MODE LU62PS, PARSESS YES

Chapter 20. Setting up communication in Tandem NSK 301

Communications examples
== MVS CICS

ABORT RLU IYCMVM03

DELETE RLU IYCMVM03
ADD RLU IYCMVM03, MODE LU62PS, PARSESS YES

== MVS Non-CICS

ABORT RLU IYCNVM03

DELETE RLU IYCNVM03
ADD RLU IYCNVM03, MODE LU62PS, PARSESS YES

== finnr100 (NT)

ABORT RLU IYAFT080

DELETE RLU IYAFT080
ADD RLU IYAFT080, MODE LU62PS, PARSESS YES

== winas18 (AS400)

ABORT RLU IYAFT110

DELETE RLU IYAFT110
ADD RLU IYAFT110, MODE LU62PS, PARSESS YES

ABORT RLU IYAHT080

DELETE RLU IYAHT080
ADD RLU IYAHT080, MODE LU62PS, PARSESS YES

==
== START UP ICE LINE $ICE01 AND SUB DEVICE
==

START LINE $ICE01, SUB ALL

Note: In order for this configuration to work, the port #ICE must have been
defined to the token ring line. For example, these commands could be
entered into SCF:
add port $chamb.#ice, type tr8025, address %H08
start port $chamb.#ice

where $chamb is a token-ring controller, and the SAP of the port is %08.

302 MQSeries Intercommunication

 Communications examples
Channel definitions for ICE
Here are some MQSeries channel definitions that would support this ICE
configuration:
v A sender channel to MQSeries on OS/390 (not using CICS):
DEFINE CHANNEL(MT01.VM03.SDRC.ICE) CHLTYPE(SDR) +
TRPTYPE(LU62) +
SEQWRAP(9999999) MAXMSGL(2048) +
XMITQ('VM03NCM.TQ.SDRC.ICE') +
CONNAME('$ICE.#IYAHT0C.IYAHT0C0.IYCNVM03') +
MODENAME('LU62PS') TPNAME(DUMMY)
v A receiver channel from MQSeries on OS/390:
DEFINE CHANNEL(VM03.MT01.SDRC.ICE) CHLTYPE(RCVR) +
TRPTYPE(LU62) REPLACE DESCR('Receiver channel from VM03NCM') +
SEQWRAP(9999999) +
MAXMSGL(2048) AUTOSTART(ENABLED) +
CONNAME('$ICE.#IYAHT0C.IYAHT0C0') TPNAME(VM03NCMSDRCRCVR)
v A server channel to MQSeries on OS/390 that is capable of initiating a
conversation, or being initiated by a remote requester channel:
DEFINE CHANNEL(MT01.VM03.RQSV.ICE) CHLTYPE(SVR) +
TRPTYPE(LU62) +
SEQWRAP(9999999) MAXMSGL(2048) +
XMITQ('VM03NCM.TQ.RQSV.ICE') +
CONNAME('$ICE.#IYAHT0C.IYAHT0C0.IYCNVM03') +
MODENAME('LU62PS') TPNAME(VM03NCMRQSVSVR.DUMMY) +
AUTOSTART(ENABLED)

where DUMMY is the TPNAME the MVS queue manager is listening on.

TCP/IP communications example

This example shows how to establish communications with a remote MQSeries
system over TCP/IP.

TCPConfig stanza in QMINI

The QMINI file must contain an appropriate TCPConfig stanza. For example:
TCPConfig:
TCPPort=1414
TCPNumListenerPorts=1
TCPListenerPort=1996
TCPKeepAlive=1

The TCPPort value is the default outbound port for channels without a port value
in the CONNAME field. TCPListenerPort identifies the port on which the TCP
listener will listen.

| A queue manager can have multiple TCP/IP listeners. If this is the case, the
| QMINI file must have a TCPListenerPort entry for each listener, and
| TCPNumListenerPort must be updated to match. For example, the TCPConfig stanza
| above would be changed as follows:
| TCPConfig:
| TCPPort=1414
| TCPNumListenerPorts=2
| TCPListenerPort=1997
| TCPKeepAlive=1

| Defining a TCP sender channel

A TCP sender channel must be defined. In this example, the queue manager is
MH01 on a host called SPINACH:

Chapter 20. Setting up communication in Tandem NSK 303

Communications examples
DEFINE CHANNEL(MT01_MH01_SDRC_0001) CHLTYPE(SDR) +
TRPTYPE(TCP) +
SEQWRAP(9999999) MAXMSGL(4194304) +
XMITQ('MH01_TQ_SDRC_0001') +
CONNAME('SPINACH.HURSLEY.IBM.COM(2000)')

This channel would try to attach to a TCP/IP port number 2000 on the host
SPINACH.

The following example shows a TCP/IP sender channel definition for a queue
manager MH01 on the host SPINACH using the default outbound TCP/IP port:
DEFINE CHANNEL(MT01_MH01_SDRC_0001) CHLTYPE(SDR) +
TRPTYPE(TCP) +
SEQWRAP(9999999) MAXMSGL(4194304) +
XMITQ('MH01_TQ_SDRC_0001') +
CONNAME('SPINACH.HURSLEY.IBM.COM')

No port number is specified in the CONNAME. Therefore, the value specified on

the TCPPort entry in the QMINI file (1414) is used.

Defining a TCP receiver channel

An example TCP receiver channel:
DEFINE CHANNEL(MH01_MT01_SDRC_0001) CHLTYPE(RCVR) +
TRPTYPE(TCP)

A TCP receiver channel requires no CONNAME value, but a TCP listener must be
running. There are two ways of starting a TCP listener. Either:
1. Go into the queue manager’s pathway using pathcom, and enter:
start server mqs-tcplis00

or
2. From the TACL prompt, enter
runmqlsr -m QMgrName

Note: If problems are encountered with the TACL from which the runmqlsr is
running, the listener will be unable to access its home terminal and out file.
runmqlsr is useful for testing, but you are recommended to use the listener
from within the queue manager’s pathway as shown in step 1.

A TCP/IP listener, which will listen on the port defined in the QMINI file (in this
example, 1996), is started.

Note: This port number can be overridden by the -p Port flag on runmqlsr.

Defining a TCP/IP sender channel on the remote system

The sender channel definition on the remote system to connect to this receiver
channel could look like:
DEFINE CHANNEL(MH01_MT01_SDRC_0001) CHLTYPE(SDR) +
TRPTYPE(TCP) +
XMITQ('MT01_TQ_SDRC_0001') +
CONNAME('TANDEM.ISC.UK.IBM.COM(1996)')

304 MQSeries Intercommunication

Chapter 21. Message channel planning example for
distributed platforms
This chapter provides a detailed example of how to connect two queue managers
together so that messages can be sent between them. The example illustrates the
preparations needed to allow an application using queue manager QM1 to put
messages on a queue at queue manager QM2. An application running on QM2 can
retrieve these messages, and send responses to a reply queue on QM1.

The example illustrates the use of TCP/IP connections. The example assumes that
channels are to be triggered to start when the first message arrives on the
transmission queue they are servicing. You must start the channel initiator in order
for triggering to work.

This example uses SYSTEM.CHANNEL.INITQ as the initiation queue. This queue

is already defined by MQSeries. You can use a different initiation queue, but you
will have to define it yourself and specify the name of the queue when you start
the channel initiator.

What the example shows

The example shows the MQSeries commands (MQSC) that you can use.

In all the examples, the MQSC commands are shown as they would appear in a
file of commands, and as they would be typed at the command line. The two
methods look identical, but, to issue a command at the command line, you must
first type runmqsc, for the default queue manager, or runmqsc qmname where qmname
is the name of the required queue manager. Then type any number of commands,
as shown in the examples.

An alternative method is to create a file containing these commands. Any errors in

the commands are then easy to correct. If you called your file mqsc.in then to run
it on queue manager QMNAME use:
runmqsc QMNAME < mqsc.in > mqsc.out

You could verify the commands in your file before running it using:
runmqsc -v QMNAME < mqsc.in > mqsc.out

For portability, you should restrict the line length of your commands to 72
characters. Use a concatenation character to continue over more than one line. On
Tandem NSK use Ctrl-y to end the input at the command line, or enter the exit or
quit command. On OS/2, Windows NT, or Digital OpenVMS use Ctrl-z. On UNIX
systems use Ctrl-d. Alternatively, on V5.1 of MQSeries for AIX, HP-UX, OS/2
Warp, Sun Solaris, and Windows NT, use the end command.

Figure 36 on page 306 shows the example scenario.

© Copyright IBM Corp. 1993, 2000 305

Planning example for distributed platforms

Application Queue manager 'QM1' Queue manager 'QM2' Application

Payroll Payroll
Query
query processing
Queue remote 'PAYROLL.QUERY'
message

Channel

Query

Que ue transmission ' QM2' QM1.TO.QM2 Q u e u e l o c a l ' PAY R O L L '

message

Reply

'SYSTEM.CHANNEL.INITQ' Que ue transmission ' QM1'

message

Reply

Queue local 'PAYROLL.REPLY' QM2.TO.QM1 'SYSTEM.CHANNEL.INITQ'

message

Figure 36. The message channel example for OS/2, Windows NT, and UNIX systems

The example involves a payroll query application connected to queue manager

QM1 that sends payroll query messages to a payroll processing application
running on queue manager QM2. The payroll query application needs the replies
to its queries sent back to QM1. The payroll query messages are sent from QM1 to
QM2 on a sender-receiver channel called QM1.TO.QM2, and the reply messages
are sent back from QM2 to QM1 on another sender-receiver channel called
QM2.TO.QM1. Both of these channels are triggered to start as soon as they have a
message to send to the other queue manager.

The payroll query application puts a query message to the remote queue
“PAYROLL.QUERY” defined on QM1. This remote queue definition resolves to the
local queue “PAYROLL” on QM2. In addition, the payroll query application
specifies that the reply to the query is sent to the local queue “PAYROLL.REPLY”
on QM1. The payroll processing application gets messages from the local queue
“PAYROLL” on QM2, and sends the replies to wherever they are required; in this
case, local queue “PAYROLL.REPLY” on QM1.

In the example definitions for TCP/IP, QM1 has a host address of 9.20.9.31 and is
listening on port 1411, and QM2 has a host address of 9.20.9.32 and is listening on
port 1412. The example assumes that these are already defined on your system and
available for use.

The object definitions that need to be created on QM1 are:

v Remote queue definition, PAYROLL.QUERY
v Transmission queue definition, QM2 (default=remote queue manager name)
v Process definition, QM1.TO.QM2.PROCESS (not needed for V5.1 of MQSeries for
AIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT)
v Sender channel definition, QM1.TO.QM2
v Receiver channel definition, QM2.TO.QM1
v Reply-to queue definition, PAYROLL.REPLY

306 MQSeries Intercommunication

 Planning example for distributed platforms
The object definitions that need to be created on QM2 are:
v Local queue definition, PAYROLL
v Transmission queue definition, QM1 (default=remote queue manager name)
v Process definition, QM2.TO.QM1.PROCESS (not needed for V5.1 of MQSeries for
AIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT)
v Sender channel definition, QM2.TO.QM1
v Receiver channel definition, QM1.TO.QM2

The connection details are supplied in the CONNAME attribute of the sender
channel definitions.

You can see a diagram of the arrangement in Figure 36 on page 306.

Queue manager QM1 example

The following object definitions allow applications connected to queue manager
QM1 to send request messages to a queue called PAYROLL on QM2, and to receive
replies on a queue called PAYROLL.REPLY on QM1.

All the object definitions have been provided with the DESCR and REPLACE
attributes. The other attributes supplied are the minimum required to make the
example work. The attributes that are not supplied take the default values for
queue manager QM1.

Run the following commands on queue manager QM1.

Remote queue definition
DEFINE QREMOTE(PAYROLL.QUERY) DESCR('Remote queue for QM2') REPLACE +
PUT(ENABLED) XMITQ(QM2) RNAME(PAYROLL) RQMNAME(QM2)

Note: The remote queue definition is not a physical queue, but a means of
directing messages to the transmission queue, QM2, so that they can
be sent to queue manager QM2.
Transmission queue definition
DEFINE QLOCAL(QM2) DESCR('Transmission queue to QM2') REPLACE +
USAGE(XMITQ) PUT(ENABLED) GET(ENABLED) TRIGGER TRIGTYPE(FIRST) +
INITQ(SYSTEM.CHANNEL.INITQ) PROCESS(QM1.TO.QM2.PROCESS)

When the first message is put on this transmission queue, a trigger

message is sent to the initiation queue, SYSTEM.CHANNEL.INITQ. The
channel initiator gets the message from the initiation queue and starts the
channel identified in the named process.
Process definition
DEFINE PROCESS(QM1.TO.QM2.PROCESS) DESCR('Process for starting channel') +
REPLACE APPLTYPE(OS2) USERDATA(QM1.TO.QM2)

The channel initiator uses this process information to start channel

QM1.TO.QM2. (This sample definition uses OS2 as the application type).

Note: For V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and
Windows NT the need for a process definition can be eliminated by
specifying the channel name in the TRIGGERDATA attribute of the
transmission queue.

Chapter 21. Message channel planning example for distributed platforms 307
Planning example for distributed platforms
Sender channel definition
DEFINE CHANNEL(QM1.TO.QM2) CHLTYPE(SDR) TRPTYPE(TCP) +
REPLACE DESCR('Sender channel to QM2') XMITQ(QM2) +
CONNAME('9.20.9.32(1412)')
Receiver channel definition
DEFINE CHANNEL(QM2.TO.QM1) CHLTYPE(RCVR) TRPTYPE(TCP) +
REPLACE DESCR('Receiver channel from QM2')
Reply-to queue definition
DEFINE QLOCAL(PAYROLL.REPLY) REPLACE PUT(ENABLED) GET(ENABLED) +
DESCR('Reply queue for replies to query messages sent to QM2')

The reply-to queue is defined as PUT(ENABLED). This ensures that reply

messages can be put to the queue. If the replies cannot be put to the
reply-to queue, they are sent to the dead-letter queue on QM1 or, if this
queue is not available, remain on transmission queue QM1 on queue
manager QM2. The queue has been defined as GET(ENABLED) to allow
the reply messages to be retrieved.

Queue manager QM2 example

The following object definitions allow applications connected to queue manager
QM2 to retrieve request messages from a local queue called PAYROLL, and to put
replies to these request messages to a queue called PAYROLL.REPLY on queue
manager QM1.

You do not need to provide a remote queue definition to enable the replies to be
returned to QM1. The message descriptor of the message retrieved from local
queue PAYROLL contains both the reply-to queue and the reply-to queue manager
names. Therefore, as long as QM2 can resolve the reply-to queue manager name to
that of a transmission queue on queue manager QM2, the reply message can be
sent. In this example, the reply-to queue manager name is QM1 and so queue
manager QM2 simply requires a transmission queue of the same name.

All the object definitions have been provided with the DESCR and REPLACE
attributes and are the minimum required to make the example work. The attributes
that are not supplied take the default values for queue manager QM2.

Run the following commands on queue manager QM2.

Local queue definition
DEFINE QLOCAL(PAYROLL) REPLACE PUT(ENABLED) GET(ENABLED) +
DESCR('Local queue for QM1 payroll details')

This queue is defined as PUT(ENABLED) and GET(ENABLED) for the

same reason as the reply-to queue definition on queue manager QM1.
Transmission queue definition
DEFINE QLOCAL(QM1) DESCR('Transmission queue to QM1') REPLACE +
USAGE(XMITQ) PUT(ENABLED) GET(ENABLED) TRIGGER TRIGTYPE(FIRST) +
INITQ(SYSTEM.CHANNEL.INITQ) PROCESS(QM2.TO.QM1.PROCESS)

When the first message is put on this transmission queue, a trigger

message is sent to the initiation queue, SYSTEM.CHANNEL.INITQ. The
channel initiator gets the message from the initiation queue and starts the
channel identified in the named process.

308 MQSeries Intercommunication

 Planning example for distributed platforms
Process definition
DEFINE PROCESS(QM2.TO.QM1.PROCESS) DESCR('Process for starting channel') +
REPLACE APPLTYPE(OS2) USERDATA(QM2.TO.QM1)

The channel initiator uses this process information to start channel

QM2.TO.QM1. (This sample definition uses OS2 as the application type.)

Note: For V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and
Windows NT the need for a process definition can be eliminated by
specifying the channel name in the TRIGGERDATA attribute of the
transmission queue.
Sender channel definition
DEFINE CHANNEL(QM2.TO.QM1) CHLTYPE(SDR) TRPTYPE(TCP) +
REPLACE DESCR('Sender channel to QM1') XMITQ(QM1) +
CONNAME('9.20.9.31(1411)')
Receiver channel definition
DEFINE CHANNEL(QM1.TO.QM2) CHLTYPE(RCVR) TRPTYPE(TCP) +
REPLACE DESCR('Receiver channel from QM1')

Running the example

Once these definitions have been created, you need to:
v Start the channel initiator on each queue manager.
v Start the INETD daemon for each queue manager. On OS/2, Windows NT, and
Tandem NSK, you can use the MQSeries listener in place of INETD.

For information about starting the channel initiator and listener, see “Chapter 10.
Setting up communication for OS/2 and Windows NT” on page 123 and
“Chapter 13. Setting up communication in UNIX systems” on page 191.

Note: On OS/2 and Windows NT, you can also run the channel as a thread; see
the MQSeries Command Reference book for information about how to define a
channel as a threaded channel.

Expanding this example

This simple example could be expanded with:
v The use of LU 6.2 communications for interconnection with CICS systems, and
transaction processing.
v Adding more queue, process, and channel definitions to allow other applications
to send messages between the two queue managers.
v Adding user-exit programs on the channels to allow for link encryption, security
checking, or additional message processing.
v Using queue-manager aliases and reply-to queue aliases to understand more
about how these can be used in the organization of your queue manager
network.

Chapter 21. Message channel planning example for distributed platforms 309
Planning example for distributed platforms

310 MQSeries Intercommunication

Chapter 22. Example SINIX and DC/OSx configuration files
This chapter contains working examples of SNA LU 6.2 configuration files for
SINIX and DC/OSx.
Notes:
1. The TCP/IP names for the SINIX machines involved are forties, which is an
RM400, and bight, which is an RM200.
2. The name of the queue manager on forties is MP01, and the name of the
queue manager on bight is MP02.
3. Both machines are running the SINIX-N operating system.
4. The LU names have a resemblance to the TCP/IP names.
5. The XIDs have been arbitrarily chosen to reflect the RM model numbers.
6. The machine rameses is a DC/OSx MIS-2ES/2 machine using the DC/OSx
operating system. The configuration for rameses is different because the
operating system SNA software on DC/OSx is different.
7. The name of the queue manager on rameses is MP04.

The preceding information can be summarized as follows:

Machine name Machine model Operating system Queue manager

forties RM400 SINIX-N MP01
bight RM200 SINIX-N MP02
rameses MIS-2ES/2 DC/OSx MP04

You should use these examples as a basis for your system. You need to generate
configuration files that are appropriate to your SNA network.

For a further description on the contents of KOGS files and Transit (SINIX LU6.2)
setup, see the Transit SINIX Version 3.2 Administration of Transit manual.

The KOGS files can be found in the directory /opt/lib/transit/KOGS.

“Working configuration files for Pyramid DC/OSx” on page 313 shows example
working configuration files from the DC/OSx machine rameses. The file is
/etc/opt/lu62/cpic_cfg. For further information on the format of this file see the
Pyramid Technology publications OpenNet LU 6.2, System Administrator’s Guide,
and OpenNet SNA Engine, System Administrator’s Guide.

“Output of dbd command” on page 314 is the output of the dbd command on
cfg.ncpram, which is a binary configuration file created by the cm command.

© Copyright IBM Corp. 1993, 2000 311

SINIX and DC/OSx configuration

Configuration file on bight

* Transit config file for bight (RM200).
* Versionen und Korrekturstaende
* TRANSIT-SERVER V 3.3 confnuc.h K1
* SNA_Kgen K1
XLINK lforties,
ACT = AUTO,
TYP = LAN,
XID = 00000400,
CPNAME = CP.FORTIES,
CONFSTR = /opt/lib/llc2/conf.str,
DEVICE = tr0,
SSAP = 04
XPU pbight,
TYP = PEER,
CONNECT = AUTO,
* DISCNT = AUTO,
LINK = lforties,
NVSCONNECT = PARTNER,
MAXDATA = 1033,
XID = 00000200,
CPNAME = CP.BIGHT,
ROLE = NEG,
PAUSE = 3,
RETRIES = 10,
DMAC = 000F01626436,
DSAP = 04,
RWINDOW = 7
XLU forties,
TYP = 6,
PUCONNECT = APHSTART,
CTYP = PUBLIC,
SESS-LMT = 130,
SESS-CTR = IND,
NETNAME = SNI.FORTIES,
PAIR = bight MODE1
XRLU bight,
NETNAME = SNI.BIGHT,
PU = pbight
XMODE MODE1,
SESS-MAX = 13,
SESS-LOS = 6,
SESS-WIN = 7,
SESS-AUTO = 7,
SRU-MAX = 87,
RRU-MAX = 87,
PAC-SEND = 0,
PAC-RCV = 0
XSYMDEST sendMP02,
RLU = bight,
MODE = MODE1,
TP = recvMP02,
TP-TYP = USER,
SEC-TYP = NONE
XTP recvMP01,
UID = guenther,
TYP = USER,
PATH = /home/guenther/recvMP01.sh,
SECURE = NO
XEND

312 MQSeries Intercommunication

 SINIX and DC/OSx configuration

Configuration file on forties

* Transit config file for forties (RM 400).
* Versionen und Korrekturstaende
* TRANSIT-SERVER V 3.3 confnuc.h K1
* SNA_Kgen K1
XLINK lbight,
ACT = AUTO,
TYP = LAN,
XID = 00000200,
CPNAME = CP.BIGHT,
CONFSTR = /opt/lib/llc2/conf.str,
DEVICE = tr0,
SSAP = 04

XPU pforties,
TYP = PEER,
CONNECT = AUTO,
DISCNT = AUTO,
LINK = lbight,
NVSCONNECT = PARTNER,
MAXDATA = 1033,
XID = 00000400,
CPNAME = CP.FORTIES,
ROLE = NEG,
PAUSE = 3,
RETRIES = 10,
DMAC = 00006f106935,
DSAP = 04,
RWINDOW = 7
XLU bight,
TYP = 6,
PUCONNECT = APHSTART,
CTYP = PUBLIC,
SESS-LMT = 15,
SESS-CTR = IND,
NETNAME = SNI.BIGHT,
PAIR = forties MODE1
XRLU forties,
NETNAME = SNI.FORTIES,
PU = pforties
XMODE MODE1,
SESS-MAX = 13,
SESS-LOS = 7,
SESS-WIN = 6,
SESS-AUTO = 6,
SRU-MAX = 87,
RRU-MAX = 87,
PAC-SEND = 0,
PAC-RCV = 0
XSYMDEST sendMP01,
RLU = forties,
MODE = MODE1,
TP = recvMP01,
TP-TYP = USER,
SEC-TYP = NONE
XTP recvMP02,
UID = guenther,
TYP = USER,
PATH = /home/guenther/recvMP02.sh,
SECURE = NO

XEND

Working configuration files for Pyramid DC/OSx

#
# This is the side information file for CPI-C.
#
# The default file name is /etc/opt/lu62/cpic_cfg, use set environmental
# variable CPIC_CFG to change the default.
#
#
# The lines starting with # are for comments; no blank lines are allowed.
# The format of each line is "1 2 3 4 5 6 7 8 9" all in one line.

Chapter 22. Example SINIX and DC/OSx configuration files 313

SINIX and DC/OSx configuration
# 1 - symbolic destination name
# 2 - local LU name (locally known name)
# 3 - remote LU name (locally known name)
# 4 - mode name
# 5 - remote TP name
# 6 - trace flag (1 if you want the trace on, 0 otherwise)
# 7 - security type (0 for none, 2 for program)
# 8 - user id (omit if security type is 0)
# 9 - password (omit if security type is 0)
#
# The following are some examples:
#
#sendMP02 LRAMESES BIGHT MODE1 recvMP02 1 0
sendMP02 IYAFT1F0 IYAFT000 LU62PS recvMP02 1 0
sendMP03 IYAFT1F0 IYAFT010 LU62PS recvMP03 1 0
sendMP01 IYAFT1F0 IYAET120 LU62PS recvMP01 1 0
sdEH01rc IYAFT1F0 IYABT0F0 LU62PS MP04RCV 1 0
sdEH01sv IYAFT1F0 IYABT0F0 LU62PS MP04SVR 1 0
sendM401 IYAFT1F0 IYAFT110 LU62PS INTCRS6A 1 0
sendvm02 IYAFT1F0 IYCNVM02 LU62PS DUMMY 1 0
sndvm2rc IYAFT1F0 IYCMVM02 LU62PS CKRC 1 0
sndvm2sd IYAFT1F0 IYCMVM02 LU62PS CKSD 1 0
sndvm2sv IYAFT1F0 IYCMVM02 LU62PS CKSV 1 0

Output of dbd command

**** COMMUNICATIONS MANAGER DATABASE ****
Database version number 80

SNA CONTROLLER
controller name: SNA
controller execute name:
'startsna62 -c 24'
62 MANAGER
62 manager name: LU62MGR
62 manager execute name:
'lu62mgr'

LOCAL PU
local pu name: IYAFT1F0
controller name: SNA
non-specific type pu
unsolicited recfms is NOT supported
xid format (0/3): 3

LOCAL LU
fully qualified local lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f1 c6 f0
fully qualified local lu name (ebcdic): GBIBMIYA.IYAFT1F0
locally known local lu name: IYAFT1F0
local pu name: IYAFT1F0
lu number at the pu: 1
lu6.2 type lu
62 manager name: LU62MGR
lu session limit: 100
share limit: 2
send window size: 7
LU configuration options:
is NOT the default lu
will NOT terminate on disconnect
printer can NOT be used in system mode
independent LU on BF connections
REMOTE PU
remote pu name: CPPG

REMOTE LU
fully qualified remote lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f0 f0 f0
fully qualified remote lu name (ebcdic): GBIBMIYA.IYAFT000
locally known remote lu name: IYAFT000
fully qualified local lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f1 c6 f0
fully qualified local lu name (ebcdic): GBIBMIYA.IYAFT1F0
uniterpreted remote lu name (hex): c9 e8 c1 c6 e3 f0 f0 f0
uniterpreted remote lu name (ebcdic): IYAFT000
remote pu name: CPPG
session initiation requests are initiate or queue
parallel sessions supported

314 MQSeries Intercommunication

 SINIX and DC/OSx configuration
no security information accepted
lu-lu verification NOT required
lu-lu password not displayed for security reasons
REMOTE LU
fully qualified remote lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f0 f1 f0
fully qualified remote lu name (ebcdic): GBIBMIYA.IYAFT010
locally known remote lu name: IYAFT010
fully qualified local lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f1 c6 f0
fully qualified local lu name (ebcdic): GBIBMIYA.IYAFT1F0
uniterpreted remote lu name (hex): c9 e8 c1 c6 e3 f0 f1 f0
uniterpreted remote lu name (ebcdic): IYAFT010
remote pu name: CPPG
session initiation requests are initiate or queue
parallel sessions supported
no security information accepted
lu-lu verification NOT required
lu-lu password not displayed for security reasons

REMOTE LU
fully qualified remote lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c5 e3 f1 f2 f0
fully qualified remote lu name (ebcdic): GBIBMIYA.IYAET120
locally known remote lu name: IYAET120
fully qualified local lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f1 c6 f0
fully qualified local lu name (ebcdic): GBIBMIYA.IYAFT1F0
uniterpreted remote lu name (hex): c9 e8 c1 c5 e3 f1 f2 f0
uniterpreted remote lu name (ebcdic): IYAET120
remote pu name: CPPG
session initiation requests are initiate or queue
parallel sessions supported
no security information accepted
lu-lu verification NOT required
lu-lu password not displayed for security reasons
MODE
mode name (hex): e2 d5 c1 e2 e5 c3 d4 c7
mode name (ebcdic): SNASVCMG
fully qualified local lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f1 c6 f0
fully qualified local lu name (ebcdic): GBIBMIYA.IYAFT1F0
fully qualified remote lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f0 f0 f0
fully qualified remote lu name (ebcdic): GBIBMIYA.IYAFT000
line class name: leased
send pacing window: 7
receive pacing window: 7
lower bound max RU size, send: 128
upper bound max RU size, send: 896
lower bound max RU size, receive: 128
upper bound max RU size, receive: 896
synchronization level of none or confirm
either lu may attempt to reinitiate the session
cryptography not supported
contention-winner automatic initiation limit: 1

MODE
mode name (hex): d3 e4 f6 f2 d7 e2
mode name (ebcdic): LU62PS
fully qualified local lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f1 c6 f0
fully qualified local lu name (ebcdic): GBIBMIYA.IYAFT1F0
fully qualified remote lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f0 f0 f0
fully qualified remote lu name (ebcdic): GBIBMIYA.IYAFT000
line class name: leased
send pacing window: 7
receive pacing window: 7
lower bound max RU size, send: 128
upper bound max RU size, send: 896
lower bound max RU size, receive: 128
upper bound max RU size, receive: 896
synchronization level of none or confirm
either lu may attempt to reinitiate the session
cryptography not supported
contention-winner automatic initiation limit: 5

MODE
mode name (hex): e2 d5 c1 e2 e5 c3 d4 c7
mode name (ebcdic): SNASVCMG
fully qualified local lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f1 c6 f0
fully qualified local lu name (ebcdic): GBIBMIYA.IYAFT1F0
fully qualified remote lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f0 f1 f0
fully qualified remote lu name (ebcdic): GBIBMIYA.IYAFT010
line class name: leased

Chapter 22. Example SINIX and DC/OSx configuration files 315

SINIX and DC/OSx configuration
send pacing window: 7
receive pacing window: 7
lower bound max RU size, send: 128
upper bound max RU size, send: 896
lower bound max RU size, receive: 128
upper bound max RU size, receive: 896
synchronization level of none or confirm
either lu may attempt to reinitiate the session
cryptography not supported
contention-winner automatic initiation limit: 1
MODE
mode name (hex): d3 e4 f6 f2 d7 e2
mode name (ebcdic): LU62PS
fully qualified local lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f1 c6 f0
fully qualified local lu name (ebcdic): GBIBMIYA.IYAFT1F0
fully qualified remote lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f0 f1 f0
fully qualified remote lu name (ebcdic): GBIBMIYA.IYAFT010
line class name: leased
send pacing window: 7
receive pacing window: 7
lower bound max RU size, send: 128
upper bound max RU size, send: 896
lower bound max RU size, receive: 128
upper bound max RU size, receive: 896
synchronization level of none or confirm
either lu may attempt to reinitiate the session
cryptography not supported
contention-winner automatic initiation limit: 5
MODE
mode name (hex): e2 d5 c1 e2 e5 c3 d4 c7
mode name (ebcdic): SNASVCMG
fully qualified local lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f1 c6 f0
fully qualified local lu name (ebcdic): GBIBMIYA.IYAFT1F0
fully qualified remote lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c5 e3 f1 f2 f0
fully qualified remote lu name (ebcdic): GBIBMIYA.IYAET120
line class name: leased
send pacing window: 7
receive pacing window: 7
lower bound max RU size, send: 128
upper bound max RU size, send: 896
lower bound max RU size, receive: 128
upper bound max RU size, receive: 896
synchronization level of none or confirm
either lu may attempt to reinitiate the session
cryptography not supported
contention-winner automatic initiation limit: 1

MODE
mode name (hex): d3 e4 f6 f2 d7 e2
mode name (ebcdic): LU62PS
fully qualified local lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c6 e3 f1 c6 f0
fully qualified local lu name (ebcdic): GBIBMIYA.IYAFT1F0
fully qualified remote lu name (hex): c7 c2 c9 c2 d4 c9 e8 c1 4b c9 e8 c1 c5 e3 f1 f2 f0
fully qualified remote lu name (ebcdic): GBIBMIYA.IYAET120
line class name: leased
send pacing window: 7
receive pacing window: 7
lower bound max RU size, send: 128
upper bound max RU size, send: 896
lower bound max RU size, receive: 128
upper bound max RU size, receive: 896
synchronization level of none or confirm
either lu may attempt to reinitiate the session
cryptography not supported
contention-winner automatic initiation limit: 5
TRANSACTION PROGRAM
transaction program name (hex): 99 85 83 a5 d4 d7 f0 f4
transaction program name (ebcdic): recvMP04
transaction program execute name:
'/home/guenther/recvMP04.sh'
tp is enabled
tp supports basic conversations
tp supports mapped conversations
tp supports confirm synchronization
tp supports no synchronization
no verification is required
number of pip fields required: 0

316 MQSeries Intercommunication

 SINIX and DC/OSx configuration
privilege mask (hex): 0
(no privileges)

TRANSACTION PROGRAM
transaction program name (hex): 06 f1
transaction program name (ebcdic): ?1
transaction program execute name:
'06f1'
tp is enabled
tp supports basic conversations
tp supports confirm synchronization
tp supports no synchronization
no verification is required
number of pip fields required: 0
privilege mask (hex): 82
(cnos - allocate_service_tp privileges)
TOKEN RING COMMUNICATIONS MEDIA
line name: LINE0
line number: 0
controller name: SNA
line class: leased
LOCAL LINK STATION
link station name: LYAFT1F0
pu name: IYAFT1F0
line name: LINE0
secondary station
LSAP address (in hex): 04
i-field size: 1033
Acknowledgement delay window size : 7
Acknowledgement delay timeout in tenth of seconds : 3
Retry count : 20
Retry timeout in seconds : 3
send xid block number: 0 5d
send xid id number: 3 0f 5c
send xid control vector:
REMOTE LINK STATION
link station name: LCPPG
pu name: CPPG
line name: LINE0
primary station
MAC address: 40 00 45 12 10 88
LSAP address (in hex): 04
i-field size: 1033
Remote station type : BF
send xid block number:
send xid id number:
send xid control vector:

Chapter 22. Example SINIX and DC/OSx configuration files 317

SINIX and DC/OSx configuration

318 MQSeries Intercommunication

Part 4. DQM in MQSeries for OS/390
Chapter 23. Monitoring and controlling Running the example. . . . . . . . . . . 349
channels on OS/390 . . . . . . . . . . 321 Expanding this example . . . . . . . . . 349
The DQM channel control function . . . . . . 321
Using the panels and the commands . . . . . 322 Chapter 26. Monitoring and controlling
Using the initial panel . . . . . . . . . 322 channels in OS/390 with CICS . . . . . . . 351
Managing your channels . . . . . . . . . 324 The DQM channel control function . . . . . . 351
Defining a channel . . . . . . . . . . 324 CICS regions . . . . . . . . . . . . 352
Altering a channel definition . . . . . . . 325 Starting DQM panels . . . . . . . . . . 352
Displaying a channel definition . . . . . . 325 The Message Channel List panel . . . . . . . 353
Displaying information about DQM . . . . . 326 Keyboard functions . . . . . . . . . . 353
Deleting a channel definition . . . . . . . 326 Function keys . . . . . . . . . . . 353
Starting a channel initiator . . . . . . . . 327 Enter key . . . . . . . . . . . . . 354
Stopping a channel initiator . . . . . . . 328 Clear key . . . . . . . . . . . . . 354
Starting a channel listener . . . . . . . . 329 Unassigned keys and unavailable choices . . 354
Stopping a channel listener . . . . . . . . 329 Selecting a channel . . . . . . . . . . 354
Starting a channel . . . . . . . . . . . 330 Working with channels . . . . . . . . . 354
Testing a channel . . . . . . . . . . . 331 Creating a channel . . . . . . . . . . 356
Resetting message sequence numbers for a Altering a channel. . . . . . . . . . . 356
channel . . . . . . . . . . . . . . 332 Browsing a channel . . . . . . . . . . 356
Resolving in-doubt messages on a channel . . 333 Renaming a channel . . . . . . . . . . 357
Stopping a channel . . . . . . . . . . 334 Selected menu-bar choice . . . . . . . . 357
Displaying channel status . . . . . . . . 335 Start . . . . . . . . . . . . . . 357
Displaying cluster channels. . . . . . . . 337 Stop . . . . . . . . . . . . . . 359
Resync . . . . . . . . . . . . . 361
Chapter 24. Preparing MQSeries for OS/390 . . 339 Reset . . . . . . . . . . . . . . 362
Setting up communication . . . . . . . . . 339 Resolve . . . . . . . . . . . . . 363
TCP setup . . . . . . . . . . . . . 339 Display status . . . . . . . . . . . 364
Connecting to TCP . . . . . . . . . 340 Display settings . . . . . . . . . . 365
Receiving on TCP . . . . . . . . . . 340 Ping . . . . . . . . . . . . . . 366
Using the TCP listener backlog option . . . 340 Exit. . . . . . . . . . . . . . . 366
APPC/MVS setup . . . . . . . . . . . 341 Edit menu-bar choice . . . . . . . . . . 367
Connecting to APPC/MVS (LU 6.2) . . . . 342 Copy . . . . . . . . . . . . . . 367
Receiving on LU 6.2 . . . . . . . . . 342 Create . . . . . . . . . . . . . . 368
Defining DQM requirements to MQSeries . . . . 342 Alter . . . . . . . . . . . . . . 370
Defining MQSeries objects . . . . . . . . . 342 Delete . . . . . . . . . . . . . . 370
Synchronization queue . . . . . . . . . 343 Find . . . . . . . . . . . . . . 370
Channel command queues . . . . . . . . 343 View menu-bar choice . . . . . . . . . 371
Channel operation considerations . . . . . . 344 Help menu-bar choice . . . . . . . . . 372
OS/390 Automatic Restart Management (ARM) 344 The channel definition panels . . . . . . . . 372
Channel menu-bar choice . . . . . . . . 373
Chapter 25. Message channel planning example Saving changes . . . . . . . . . . . 373
for OS/390 . . . . . . . . . . . . . . 345 Exit from the panel . . . . . . . . . 373
What the example shows . . . . . . . . . 345 Help menu-bar choice . . . . . . . . . 373
Queue manager QM1 example . . . . . . 346 Channel settings panel fields . . . . . . . . 374
Remote queue definition . . . . . . . 346 Details of sender channel settings panel . . . 376
Transmission queue definition . . . . . . 347 Details of receiver channel settings panel . . . 377
Process definition . . . . . . . . . . 347 Details of server channel settings panel. . . . 378
Sender channel definition . . . . . . . 347 Details of requester channel settings panel. . . 379
Receiver channel definition . . . . . . . 347
Reply-to queue definition . . . . . . . 347 Chapter 27. Preparing MQSeries for OS/390
Queue manager QM2 example . . . . . . 347 when using CICS . . . . . . . . . . . 381
Local queue definition . . . . . . . . 348 Setting up CICS communication for MQSeries for
Transmission queue definition . . . . . . 348 OS/390 . . . . . . . . . . . . . . . 381
Process definition . . . . . . . . . . 348 Connecting CICS systems . . . . . . . . 381
Sender channel definition . . . . . . . 348 Communication between queue managers 381
Receiver channel definition . . . . . . . 348 Intersystem communication . . . . . . 382

© Copyright IBM Corp. 1993, 2000 319

DQM in MQSeries for OS/390
Defining an LU 6.2 connection . . . . . . 382 Installing the new group definition . . . . . 404
Installing the connection. . . . . . . . . 383 What next? . . . . . . . . . . . . . 404
Communications between CICS systems Establishing a TCP connection. . . . . . . . 404
attached to one queue manager . . . . . . 383 What next? . . . . . . . . . . . . . 405
Connection names for function shipping . . 383 MQSeries for OS/390 configuration . . . . . . 405
Defining DQM requirements to MQSeries . . . . 384 Channel configuration . . . . . . . . . 405
Defining MQSeries objects . . . . . . . . . 384 MQSeries for OS/390 sender-channel
Multiple message channels per transmission definitions using non-CICS LU 6.2 . . . . 408
queue . . . . . . . . . . . . . . . 384 MQSeries for OS/390 receiver-channel
Channel operation considerations . . . . . . 385 definitions using non-CICS LU 6.2 . . . . 408
MQSeries for OS/390 sender-channel
Chapter 28. Message channel planning example definitions using TCP . . . . . . . . 409
for OS/390 using CICS. . . . . . . . . . 387 MQSeries for OS/390 receiver-channel
definitions using TCP . . . . . . . . 409
Chapter 29. Example configuration - IBM MQSeries for OS/390 sender-channel
MQSeries for OS/390 . . . . . . . . . . 395 definitions using CICS . . . . . . . . 409
Configuration parameters for an LU 6.2 connection 395 MQSeries for OS/390 receiver-channel
Configuration worksheet . . . . . . . . 396 definitions using CICS . . . . . . . . 409
Explanation of terms . . . . . . . . . . 398 Defining a local queue . . . . . . . . . 409
Establishing an LU 6.2 connection . . . . . . 400 Defining a remote queue . . . . . . . . 412
Defining yourself to the network . . . . . . 400 Defining a sender channel when not using CICS 413
Defining a connection to a partner . . . . . 402 Defining a receiver channel when not using
What next? . . . . . . . . . . . . . 402 CICS . . . . . . . . . . . . . . . 415
Establishing an LU 6.2 connection using CICS . . 402 Defining a sender channel using CICS . . . . 417
Defining a connection . . . . . . . . . 402 Defining a receiver channel using CICS . . . 418
Defining the sessions . . . . . . . . . . 403

This part of the book describes the MQSeries distributed queue management
function for MQSeries for OS/390 using native OS/390 communication protocols
(SNA LU 6.2 and TCP/IP). You can also use CICS ISC for distributed queuing.

Note: You can use distributed queuing both with CICS and without CICS
simultaneously on the same MQSeries instance, but they will have no
knowledge of each other, or of each other’s channels. It is up to you to
ensure that they have distinct sets of channel names. Most of the
information here applies equally to MQSeries for MVS/ESA.

320 MQSeries Intercommunication

Chapter 23. Monitoring and controlling channels on OS/390
Use the DQM commands and panels to create, monitor, and control the channels to
remote queue managers. Each OS/390 queue manager has a DQM program (the
channel initiator) for controlling interconnections to compatible remote queue
managers using native OS/390 facilities.

The implementation of these panels and commands on OS/390 is integrated into

the operations and control panels and the MQSC commands. No differentiation is
made in the organization of these two sets of panels and commands.

If you are using CICS for DQM, see “Chapter 26. Monitoring and controlling
channels in OS/390 with CICS” on page 351. Most of the information here applies
equally to MQSeries for MVS/ESA.

The DQM channel control function

The channel control function provides the administration and control of message
channels between MQSeries for OS/390 and compatible systems. See Figure 28 on
page 58 for a conceptual picture.

The channel control function consists of panels, commands and programs, a

synchronization queue, channel command queues, and the channel definitions. The
following is a brief description of the components of the channel control function.
v The channel definitions are held as objects in page set zero, like other MQSeries
objects in OS/390.
v You use the operations and control panels or MQSC commands to:
– Create, copy, display, alter, and delete channel definitions
– Start and stop channel initiators and listeners
– Start, stop, and ping channels, reset channel sequence numbers, and resolve
in-doubt messages when links cannot be re-established
– Display status information about channels
– Display information about DQM

In particular, you can use the CSQINPX initialization input data set to issue your
MQSC commands. This can be processed every time you start the channel
initiator. See the MQSeries for OS/390 System Management Guide for information
about this.
v There is a queue (SYSTEM.CHANNEL.SYNCQ) used for channel
re-synchronization purposes. You should define this with INDXTYPE(MSGID)
for performance reasons.
v Channel command queues (SYSTEM.CHANNEL.INITQ and
SYSTEM.CHANNEL.REPLY.INFO) are used to hold commands for channel
initiators, channels, and listeners, and replies from them.
v The channel control function program runs in its own address space, separate
from the queue manager, and comprises the channel initiator, listeners, MCAs,
trigger monitor, and command handler.

© Copyright IBM Corp. 1993, 2000 321

Using panels and commands

Using the panels and the commands

You can use either the MQSC commands or the operations and control panels to
manage DQM. For information about the syntax of the MQSC commands, see the
MQSeries Command Reference book.

Using the initial panel

For an introduction to invoking the operations and control panels, using the
function keys, and getting help, see the MQSeries for OS/390 System Management
Guide.

Note: To use the operations and control panels, you must have the correct security
authorization; see the MQSeries for OS/390 System Management Guide for
information. Figure 37 shows the panel that is displayed when you start a
panel session.

IBM MQSeries for OS/390 - Main Menu

Complete fields. Then press Enter.

Action . . . . . . . . 1 1. Display 5. Perform

2. Define 6. Start
3. Alter 7. Stop
4. Delete

Object type . . . . . CHANNEL +

Name . . . . . . . . . *
Like . . . . . . . . . ________________________________________________

Connect to queue
manager . . . . . . : MQ25
Target queue manager : MQ25
Response wait time . : 10 seconds

(C) Copyright IBM Corporation 1993,1999. All rights reserved.

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F4=Prompt F6=QueueMgr F9=Swap
F10=Messages F12=Cancel

Figure 37. The operations and controls initial panel

From this panel you can:

v Select the action you want to perform by typing in the appropriate number in
the Action field.
v Specify the object type that you want to work with. Press F4 for a list of object
types if you are not sure what they are.
v Display a list of objects of the type specified. Type in an asterisk (*) in the Name
field and press Enter to display a list of objects (of the type specified) that have
already been defined on this subsystem. You can then select one or more objects
to work with in sequence. Figure 38 on page 323 shows a list of channels
produced in this way.
v Define an object with the same attributes as an existing object. See “Defining a
channel” on page 324.
v Choose the local queue manager you want, and whether you want the
commands issued on that queue manager or on some remote queue manager.
v Choose the wait time for responses to be received.

322 MQSeries Intercommunication

 Using panels and commands

List Channels Row 1 of 8

Type action codes. Then press Enter.

1=Display 2=Define like 3=Alter 4=Delete 5=Perform
6=Start 7=Stop

Name Type Status

_ SYSTEM.DEF.CLNTCONN CHLCLNTCONN
_ SYSTEM.DEF.CLUSRCVR CHLCLUSRCVR
_ SYSTEM.DEF.CLUSSDR CHLCLUSSDR
_ SYSTEM.DEF.RECEIVER CHLRECEIVER
_ SYSTEM.DEF.REQUESTER CHLREQUESTER
_ SYSTEM.DEF.SENDER CHLSENDER
_ SYSTEM.DEF.SERVER CHLSERVER
_ SYSTEM.DEF.SVRCONN CHLSVRCONN
******** End of list ********

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F5=Refresh F7=Bkwd F8=Fwd
F9=Swap F10=Messages F11=Status F12=Cancel

Figure 38. Listing channels

Chapter 23. Monitoring and controlling channels on OS/390 323

Managing channels

Managing your channels

Table 29 lists the tasks that you can perform to manage your channels, channel
initiators, and listeners. It also gives the name of the relevant MQSC command,
and points to the page where each task is discussed.
Table 29. Channel tasks
Task to be performed MQSC command See page
Define a channel DEFINE CHANNEL 324
Alter a channel definition ALTER CHANNEL 325
Display a channel definition DISPLAY CHANNEL 325
Delete a channel definition DELETE CHANNEL 326
Start a channel initiator START CHINIT 327
Stop a channel initiator STOP CHINIT 328
Display channel initiator information DISPLAY DQM 326
Start a channel listener START LISTENER 329
Stop a channel listener STOP LISTENER 329
Start a channel START CHANNEL 330
Test a channel PING CHANNEL 331
Reset message sequence numbers for a RESET CHANNEL 332
channel
Resolve in-doubt messages on a channel RESOLVE CHANNEL 333
Stop a channel STOP CHANNEL 334
Display channel status DISPLAY CHSTATUS 335
Display cluster channels DISPLAY CLUSQMGR 337

Defining a channel
To define a channel using the MQSC commands, use DEFINE CHANNEL.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 2 (Define)
Object type CHLtype (for example CHLSENDER) or CHANNEL
Name CHANNEL.TO.DEFINE

You are presented with some panels to complete with information about the
attributes you want for the channel you are defining. These panels are shown on
page 415.

Note: If you entered CHANNEL in the object type field, you are presented with
the Select a Valid Channel Type panel first.

If you want to define a channel with the same attributes as an existing channel,
put the name of the channel you want to copy in the Like field on the initial
panel. The subsequent panels will already contain these attribute values, but you
can change any that you want to before pressing Enter.

324 MQSeries Intercommunication

 Defining a channel
If you have not used the Like field, the panels will contain the system default
attribute values. Change any that you want to, and then press Enter to create the
channel definition.

For information about the channel attributes, see “Chapter 6. Channel attributes”
on page 77.
Notes:
1. If you are using distributed queuing with CICS as well, don’t use any of the
same channel names.
2. You are strongly recommended to name all the channels in your network
uniquely. As shown in Table 1 on page 30, including the source and target
queue manager names in the channel name is a good way to do this.

Altering a channel definition

To alter a channel definition using the MQSC commands, use ALTER CHANNEL.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 3 (Alter)
Object type CHLtype (for example CHLSENDER) or CHANNEL
Name CHANNEL.TO.ALTER

You are presented with some panels containing information about the current
attributes of the channel. Change any of the unprotected fields that you want by
overtyping the new value, and then press Enter to change the channel definition.

For information about the channel attributes, see “Chapter 6. Channel attributes”
on page 77.

Displaying a channel definition

To display a channel definition using the MQSC commands, use DISPLAY
CHANNEL.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 1 (Display)
Object type CHLtype (for example CHLSENDER) or CHANNEL
Name CHANNEL.TO.DISPLAY

You are presented with some panels displaying information about the current
attributes of the channel.

For information about the channel attributes, see “Chapter 6. Channel attributes”
on page 77. For information about channel status, press F11 (Connects). See
“Displaying channel status” on page 335 for information about this.

Chapter 23. Monitoring and controlling channels on OS/390 325

Displaying information about DQM
Displaying information about DQM
To display information about the channel initiator using the MQSC commands, use
DISPLAY DQM.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 1 (Display)
Object type SYSTEM
Name Blank

You are presented with another panel. Select control type 1 on this panel.
Notes:
1. Displaying distributed queuing information may take some time if you have
lots of channels.
2. Channel status is not available for client-connection channels.

Deleting a channel definition

To delete a channel definition using the MQSC commands, use DELETE
CHANNEL.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 4 (Delete)
Object type CHLtype (for example CHLSENDER) or CHANNEL
Name CHANNEL.TO.DELETE

You are presented with some panels containing information about the current
attributes of the channel. If required, you can scroll through these panels to verify
that you are deleting the correct channel definition. Press Enter to delete the
channel definition; you will be asked to confirm that you want to delete the
channel definition by pressing Enter again.

Note: The channel initiator has to be running before a channel definition can be
deleted (except for client-connection channels).

For information about the channel attributes, see “Chapter 6. Channel attributes”
on page 77.

326 MQSeries Intercommunication

 Starting a channel initiator
Starting a channel initiator
To start a channel initiator using the MQSC commands, use START CHINIT.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 6 (Start)
Object type SYSTEM
Name Blank

The Start a System Function panel is displayed:

Start a System Function

Select function type, complete fields, then press Enter to start system
function.

Function type . . . . . . . _ 1. Channel initiator

2. Channel listener for LU 6.2
3. Channel listener for TCP

Channel initiator
Parameter module name . . ________
JCL substitution . . . . ________________________________________________
________________________________________________

Listener for LU6.2

LU name . . . . . . . . . _________________

Listener for TCP

Port number . . . . . . . 1414

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F9=Swap F10=Messages F12=Cancel

Figure 39. Starting a system function

Select function type 1 (channel initiator), and press Enter. The channel initiator
parameter module name defaults to CSQXPARM. If you want to use a different
parameter module, enter the name on the panel.

Note: If you are using Interlink TCP, this must be started before you start the
channel initiator. If you are using IBM TCP, you can start the channel
initiator first but, unless you are using OE sockets, you will need to restart
the channel initiator after you have started TCP, in order to establish
communication. If you are using LU 6.2, this can be started before or after
the channel initiator.

Chapter 23. Monitoring and controlling channels on OS/390 327

Stopping a channel initiator
Stopping a channel initiator
To stop a channel initiator using the MQSC commands, use STOP CHINIT.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 7 (Stop)
Object type SYSTEM
Name Blank

The Stop a System Function panel is displayed:

Stop a System Function

Select function type, then press Enter to stop system function.

Function type . . . . . . . _ 1. Channel initiator

2. Channel listener for LU 6.2
3. Channel listener for TCP

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F9=Swap F10=Messages F12=Cancel

Figure 40. Stopping a function control

Select function type 1 (channel initiator) and press Enter.

The channel initiator will wait for all running channels to stop in quiesce mode
before it stops.

Note: If some of the channels are receiver or requester channels that are running
but not active, a stop request issued to either the receiver’s or sender’s
channel initiator will cause it to stop immediately.

However, if messages are flowing, the channel initiator waits for the current batch
of messages to complete before it stops.

328 MQSeries Intercommunication

 Starting a channel listener
Starting a channel listener
To start a channel listener using the MQSC commands, use START LISTENER.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 6 (Start)
Object type SYSTEM
Name Blank

The Start a System Function panel is displayed (see Figure 39 on page 327).

Select function type 2 or 3 (channel listener for LU 6.2 or TCP respectively),

complete any other fields required (LU name or port number respectively), and
press Enter.

Stopping a channel listener

To stop a channel listener using the MQSC commands, use STOP LISTENER.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 7 (Stop)
Object type SYSTEM
Name Blank

The Stop a System Function panel is displayed (see Figure 40 on page 328).

Select control type 2 or 3 (channel listener for LU 6.2 or TCP respectively) and
press Enter.

Chapter 23. Monitoring and controlling channels on OS/390 329

Starting a channel
Starting a channel
To start a channel using the MQSC commands, use START CHANNEL.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 6 (Start)
Object type CHLtype (for example CHLSENDER) or CHANNEL
Name CHANNEL.TO.USE

The Start a Channel panel is displayed:

Start a Channel

Press Enter to confirm that the channel is to be started.

Channel name . . . . . . . : CHANNEL.TO.USE

Channel type . . . . . . . : CHLSENDER
Description . . . . . . . : Description of CHANNEL.TO.USE

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F9=Swap F10=Messages F12=Cancel

Figure 41. Starting a channel

Press Enter to start the channel.

330 MQSeries Intercommunication

 Testing a channel
Testing a channel
To test a channel using the MQSC commands, use PING CHANNEL.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 5 (Perform)
Object type CHLSENDER, CHLSERVER, or CHANNEL
Name CHANNEL.TO.USE

The Perform a Channel Function panel is displayed:

Perform a Channel Function

Select function type, complete fields, then press Enter.

Function type . . . . . . . . _ 1. Reset sequence number

2. Ping
3. Resolve with commit
4. Resolve with backout

Channel name . . . . . . . : CHANNEL.TO.USE

Channel type . . . . . . . : CHLSENDER
Description . . . . . . . . : Description of CHANNEL.TO.USE

Reset
Sequence number . . . . . 1 1 - 999999999

Ping
Data length . . . . . . . 16 16 - 32768

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F9=Swap F10=Messages F12=Cancel

Figure 42. Testing a channel

The data length is initially set to 16. Change this if you want, select function type 2
(ping), and press Enter.

Chapter 23. Monitoring and controlling channels on OS/390 331

Resetting message sequence numbers
Resetting message sequence numbers for a channel
To reset channel sequence numbers using the MQSC commands, use RESET
CHANNEL.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 5 (Perform)
Object type CHLtype (for example CHLSENDER) or CHANNEL
Name CHANNEL.TO.USE

The Perform a Channel Function panel is displayed:

Perform a Channel Function

Select function type, complete fields, then press Enter.

Function type . . . . . . . . _ 1. Reset sequence number

2. Ping
3. Resolve with commit
4. Resolve with backout

Channel name . . . . . . . : CHANNEL.TO.USE

Channel type . . . . . . . : CHLSENDER
Description . . . . . . . . : Description of CHANNEL.TO.USE

Reset
Sequence number . . . . . 1 1 - 999999999

Ping
Data length . . . . . . . 16 16 - 32768

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F9=Swap F10=Messages F12=Cancel

Figure 43. Resetting channel sequence numbers

The sequence number field is initially set to one. Change this if you want, select
Function type 1 (reset), and press Enter.

332 MQSeries Intercommunication

 Resolving in-doubt messages
Resolving in-doubt messages on a channel
To resolve in-doubt messages on a channel using the MQSC commands, use
RESOLVE CHANNEL.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 9 (Perform)
Object type CHLSENDER, CHLSERVER, or CHANNEL
Name CHANNEL.TO.USE

The Perform a Channel Function panel is displayed:

Perform a Channel Function

Select function type, complete fields, then press Enter.

Function type . . . . . . . . _ 1. Reset sequence number

2. Ping
3. Resolve with commit
4. Resolve with backout

Channel name . . . . . . . : CHANNEL.TO.USE

Channel type . . . . . . . : CHLSENDER
Description . . . . . . . . : Description of CHANNEL.TO.USE

Reset
Sequence number . . . . . 1 1 - 999999999

Ping
Data length . . . . . . . 16 16 - 32768

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F9=Swap F10=Messages F12=Cancel

Figure 44. Resolving in-doubt messages

Select Function type 3 or 4 (resolve with commit or backout), and press Enter. (See
“In-doubt channels” on page 69 for more information.)

Chapter 23. Monitoring and controlling channels on OS/390 333

Stopping a channel
Stopping a channel
To stop a channel using the MQSC commands, use STOP CHANNEL.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Field Value
Action 7 (Stop)
Object type CHLtype (for example CHLSENDER) or CHANNEL
Name CHANNEL.TO.USE

The Stop a Channel panel is displayed:

Stop a Channel

Select stop mode, then press Enter to stop channel.

Channel name . . . . . . . : CHANNEL.TO.USE

Channel type . . . . . . . : CHLSENDER
Description . . . . . . . : Description of CHANNEL.TO.USE

Stop mode . . . . . . . . . 1 1. Quiesce

2. Force

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F9=Swap F10=Messages F12=Cancel

Figure 45. Stopping a channel

Choose the stop mode that you require:

Quiesce
The channel will stop when the current message is completed and the
batch will then be ended, even if the batch size value has not been reached
and there are messages already waiting on the transmission queue. No
new batches will be started. This is the default.
Force The channel will stop immediately. If a batch of messages is in progress, an
‘in-doubt’ situation may result.

Press Enter to stop the channel.

See “Stopping and quiescing channels (not MQSeries for Windows)” on page 67 for
more information. For information about restarting stopped channels, see
“Restarting stopped channels” on page 69.

334 MQSeries Intercommunication

 Displaying channel status
Displaying channel status
To display the status of a channel or a set of channels using the MQSC commands,
use DISPLAY CHSTATUS.

Note: Displaying channel status information may take some time if you have lots
of channels.

Using the operations and control panels on the List Channel panel (see Figure 38
on page 323), a summary of the channel status is shown for each channel as
follows:

INACTIVE No connections are active

status One connection is active
nnn status More than one connection is current and all current connections have
the same status
nnn CURRENT More than one connection is current and the current connections do not
all have the same status
Blank MQSeries is unable to determine how many connections are active (for
example, because the channel initiator is not running)

where nnn is the number of active connections, and status is one of the following:

INIT INITIALIZING
BIND BINDING
START STARTING
RUN RUNNING
STOP STOPPING or STOPPED
RETRY RETRYING
REQST REQUESTING

To display more information about the channel status, press the Status key (F11) on
the List Channel or the Display, Alter, or Delete channel panels to display the List
Channels - Current Status panel (see Figure 46 on page 336).

Chapter 23. Monitoring and controlling channels on OS/390 335

Displaying channel status

List Channels - Current Status Row 1 of 16

Use '/' to select one or more connections, then press Enter to display current
connection status.

Channel name Connection name State

Type Messages Last message time Start time Retry/Stop
_ RMA0.CIRCUIT.ACL.F RMA1 STOP
_ CHLSENDER 557735 1997-03-24 09.51.11 1997-03-21 10.22.36
_ RMA0.CIRCUIT.ACL.N RMA1
_ CHLSENDER 378675 1997-03-24 09.51.10 1997-03-21 10.23.09
_ RMA0.CIRCUIT.CL.F RMA2
_ CHLSENDER 45544 1997-03-24 09.51.08 1997-03-24 01.12.51
_ RMA0.CIRCUIT.CL.N RMA2
_ CHLSENDER 45560 1997-03-24 09.51.11 1997-03-24 01.13.55
_ RMA1.CIRCUIT.CL.F RMA1
_ CHLRECEIVER 360757 1997-03-24 09.51.11 1997-03-21 10.24.12
_ RMA1.CIRCUIT.CL.N RMA1
_ CHLRECEIVER 302870 1997-03-24 09.51.09 1997-03-21 10.23.40
******** End of list ********

Command ===>
F1=Help F2=Split F3=Exit F5=Refresh F7=Bkwd F8=Fwd
F9=Swap F10=Messages F11=Saved F12=Cancel

Figure 46. Listing channel connections

The values for status are as follows:

INIT INITIALIZING
BIND BINDING
START STARTING
RUN RUNNING
STOP STOPPING or STOPPED
RETRY RETRYING
REQST REQUESTING
DOUBT STOPPED and INDOUBT(YES)

See “Channel states” on page 62 for more information about these.

You can press F11 to see a similar list of channel connections with saved status;
press F11 to get back to the current list.

Use a slash (/) to select a connection and press Enter. Note that the saved status
does not apply until at least one batch of messages has been transmitted on the
channel. The Display Channel Connection Current Status panels are displayed:

336 MQSeries Intercommunication

 Displaying channel status

Display Channel Connection Current Status

More: +

Channel name . . . . . . . : CSQ1.TO.CSQ2

Channel type . . . . . . . : CHLSENDER

Connection name . . . . . : CSQ2

Transmission queue . . . . : CSQ1.TO.CSQ2.XMITQ

Status . . . . . . . . . . : RUN
Last sequence number . . . : 6
Last LUW ID . . . . . . . : F2F6F1F2F2F6F2F8
Indoubt . . . . . . . . . : NO
Current messages . . . . . : 0
Current sequence number . : 6
Current LUW ID . . . . . . : F2F6F1F3F3F9F0F1

Command ===> ___________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Figure 47. Displaying channel connections - first panel

Display Channel Connection Current Status

Press F7 to see previous fields.

More: -
Channel start time . . . . : 1998-08-10 14.33.26
Last message/call time . . :
Batches completed . . . . . : 0
Messages/calls . . . . . . : 0
Bytes sent . . . . . . . . : 0
Bytes received . . . . . . : 0
Transmissions sent . . . . : 0
Transmissions received . . : 0
Short retry attempts left . : 10
Long retry attempts left . : 999999999
Stop request outstanding . : N Y=Yes,N=No
Maximum message length . . : 4194304
Batch size . . . . . . . . : 50
Heartbeat interval . . . . : 300 seconds
Nonpersistent messages . . : F F=Fast,N=Normal

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Figure 48. Displaying channel connections - second panel

Displaying cluster channels

To display all the cluster channels that have been defined (explicitly or using
auto-definition), use the MQSC command, DISPLAY CLUSQMGR.

Using the operations and control panels, starting from the initial panel, complete
these fields and press Enter:

Chapter 23. Monitoring and controlling channels on OS/390 337

Displaying cluster channels
Field Value
Action 1 (Display)
Object type CLUSCHL
Name *

You are presented with a panel like figure 49, in which the information for each
cluster channel occupies three lines, and includes its channel, cluster, and queue
manager names. For cluster-sender channels, the overall state is shown.

List Cluster-queue-manager Channels Row 1 of 9

Type action codes. Then press Enter.

1=Display 5=Perform 6=Start 7=Stop

Channel name Connection name State

Type Cluster name Suspended
Queue manager name
_ TO.MQ90.T HURSLEY.MACH90.COM(1590)
_ CHLCLUSRCVR VJH01T N
_ MQ90
_ TO.MQ95.T HURSLEY.MACH95.COM(1595) RUN
_ CHLCLUSSDRA VJH01T N
_ MQ95
_ TO.MQ96.T HURSLEY.MACH96.COM(1596) RUN
_ CHLCLUSSDRB VJH01T N
_ MQ96
******** End of list ********

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F5=Refresh F7=Bkwd F8=Fwd
F9=Swap F10=Messages F11=Status F12=Cancel

Figure 49. Listing cluster channels

To display full information about one or more channels, type Action code 1 against
their names and press Enter. Use Action codes 5, 6, or 7 to perform functions (such
as ping, resolve, and reset), and start or stop a cluster channel.

To display more information about the channel status, press the Status key (F11).

338 MQSeries Intercommunication

Chapter 24. Preparing MQSeries for OS/390
This chapter describes the MQSeries for OS/390 preparations you need to make
before you can start to use distributed queuing. (If you want to use CICS ISC for
distributed queuing, see “Chapter 27. Preparing MQSeries for OS/390 when using
CICS” on page 381.) Most of the information here applies equally to MQSeries for
MVS/ESA.

To enable distributed queuing, you must perform the following three tasks:
v Customize the distributed queuing facility and define the MQSeries objects
required; this is described in the MQSeries for OS/390 System Management Guide.
v Define access security; this is described in the MQSeries for OS/390 System
Management Guide.
v Set up your communications; this is described in this chapter.

Setting up communication
When a distributed-queuing management channel is started, it tries to use the
connection specified in the channel definition. For this to succeed, it is necessary
for the connection to be defined and available. This section explains how to do
this.

There are two forms of communication protocol that can be used:

v TCP
v LU 6.2 through APPC/MVS

TCP setup
The TCP address space name must be specified in the TCP system parameters data
set, tcpip.TCPIP.DATA. In the data set, a “TCPIPJOBNAME TCPIP_proc” statement
must be included.

The channel initiator address space must have authority to read the data set. The
following techniques can be used to access your TCPIP.DATA data set, depending
on which TCP/IP product and interface you are using:
v Environment variable, RESOLVER_CONFIG
v HFS file, /etc/resolv.conf
v //SYSTCPD DD statement
v //SYSTCPDD DD statement
v jobname/userid.TCPIP.DATA
v SYS1.TCPPARMS(TCPDATA)
v zapname.TCPIP.DATA

You must also be careful to specify the high-level qualifier for TCP/IP correctly.

For more information, see the following:

v TCP/IP OpenEdition: Planning and Release Guide, SC31-8303
v OS/390 OpenEdition Planning, SC28-1890
v Your TCPaccess documentation

© Copyright IBM Corp. 1993, 2000 339

Setting up communication
Each TCP channel when started will use TCP resources; you may need to adjust
the following parameters in your PROFILE.TCPIP configuration data set:
ACBPOOLSIZE
Add one per started TCP channel, plus one
CCBPOOLSIZE
Add one per started TCP channel, plus one per DQM dispatcher, plus one
DATABUFFERPOOLSIZE
Add two per started TCP channel, plus one
MAXFILEPROC
Controls how many channels each dispatcher in the channel initiator can
handle.
This parameter is specified in the BPXPRMxx member of SYSI.PARMLIB. If
you are using OpenEdition sockets, ensure that you specify a value large
enough for your needs.

Connecting to TCP
The connection name (CONNAME) field in the channel definition should be set to
either the TCP network address of the target, in dotted decimal form (for example
9.20.9.30) or the host name (for example MVSHUR1). If the connection name is a
host name, a TCP name server is required to convert the host name into a TCP
host address. (This is a function of TCP, not MQSeries.)

On the initiating end of a connection (sender, requester, and server channel types)
it is possible to provide an optional port number for the connection, for example:
Connection name
9.20.9.30(1555)

In this case the initiating end will attempt to connect to a receiving program
listening on port 1555.

Receiving on TCP
Receiving channel programs are started in response to a startup request from the
sending channel. To do this, a listener program has to be started to detect incoming
network requests and start the associated channel. You start this listener program
with the START LISTENER command, or using the operations and control panels.

By default, the TCP Listener program uses port 1414.

Using the TCP listener backlog option

When receiving on TCP/IP, a maximum number of outstanding connection
requests is set. This can be considered a backlog of requests waiting on the TCP/IP
port for the listener to accept the request.

The default listener backlog value on OS/390 is 255. If the backlog reaches this
values, the TCP/IP connection is rejected and the channel will not be able to start.

For MCA channels, this results in the channel going into a RETRY state and
retrying the connection at a later time.

For client connections, the client receives an MQRC_Q_MGR_NOT_AVAILABLE

reason code from MQCONN and should retry the connection at a later time.

However, to avoid this error, you can add an entry in the qm.ini file:

340 MQSeries Intercommunication

 Setting up communication
TCP:
ListenerBacklog = n

This overrides the default maximum number of outstanding requests (255) for the
TCP/IP listener.

Note: Some operating systems support a larger value than the default. If necessary,
this can be used to avoid reaching the connection limit.

To run the listener with the backlog option switched on, use the RUNMQLSR -B
command. For information about the RUNMQLSR command, see the MQSeries System
Administration book.

APPC/MVS setup
Each instance of the channel initiator must have the name of the LU that it is to
use defined to APPC/MVS, in the APPCPMxx member of SYS1.PARMLIB, as in
the following example:
LUADD ACBNAME(luname) NOSCHED TPDATA(CSQ.APPCTP)

luname is the name of the logical unit to be used. NOSCHED is required; TPDATA is not
used. No additions are necessary to the ASCHPMxx member, or to the APPC/MVS
TP profile data set.

The side information data set must be extended to define the connections used by
DQM. See the supplied sample CSQ4SIDE for details of how to do this using the
APPC utility program ATBSDFMU. For details of the TPNAME values to use, see
the Multiplatform APPC Configuration Guide (“Red Book”) and the following table
for information:
Table 30. Settings on the local OS/390 system for a remote queue manager platform
Remote platform TPNAME
OS/390 or The same as TPNAME in the corresponding side information on the
MVS/ESA remote queue manager.
OS/390 or CKRC (sender) CKSV (requester) CKRC (server)
MVS/ESA using
CICS
OS/400 The same as the compare value in the routing entry on the OS/400
system.
OS/2 As specified in the OS/2 Run Listener command, or defaulted from the
OS/2 queue manager configuration file.
Digital OVMS As specified in the Digital OVMS Run Listener command.
Tandem NSK The same as the TPNAME specified in the receiver-channel definition.
Other UNIX The same as TPNAME in the corresponding side information on the
systems remote queue manager.
Windows NT As specified in the Windows NT Run Listener command, or the
invokable Transaction Program that was defined using TpSetup on
Windows NT.

If you have more than one queue manager on the same machine, ensure that the
TPnames in the channel definitions are unique.

See the Multiplatform APPC Configuration Guide also for information about the
VTAM definitions that may be required.

Chapter 24. Preparing MQSeries for OS/390 341

Setting up communication
In an environment where the queue manager is communicating via APPC with a
queue manager on the same or another OS/390 system, ensure that either the
VTAM definition for the communicating LU specifies SECACPT(ALREADYV), or
that there is a RACF® APPCLU profile for the connection between LUs, which
specifies CONVSEC(ALREADYV).

The OS/390 command VARY ACTIVE must be issued against both base and
listener LUs before attempting to start either inbound or outbound
communications.

Connecting to APPC/MVS (LU 6.2)

The connection name (CONNAME) field in the channel definition should be set to
the symbolic destination name, as specified in the side information data set for
APPC/MVS.

The LU name to use (defined to APPC/MVS as described above) must also be

specified in the channel initiator parameters. It must be set to the same LU that
will be used for receiving by the listener.

The channel initiator uses the “SECURITY(SAME)” APPC/MVS option, so it is the

user ID of the channel initiator address space that is used for outbound
transmissions, and will be presented to the receiver.

Receiving on LU 6.2
Receiving MCAs are started in response to a startup request from the sending
channel. To do this, a listener program has to be started to detect incoming
network requests and start the associated channel. The listener program is an
APPC/MVS server. You start it with the START LISTENER command, or using the
operations and control panels. You must specify the LU name to use by means of a
symbolic destination name defined in the side information data set. The local LU
so identified must be the same as that used for outbound transmissions, as set in
the channel initiator parameters.

Defining DQM requirements to MQSeries

In order to define your distributed-queuing requirements, you have to:
v Define the channel initiator procedures and data sets
v Define the channel definitions
v Define the queues and other objects
v Define access security

See the MQSeries for OS/390 System Management Guide for information about these
tasks.

Defining MQSeries objects

Use one of the MQSeries command input methods to define MQSeries objects.
Refer to “Chapter 23. Monitoring and controlling channels on OS/390” on page 321
for information about defining objects.

342 MQSeries Intercommunication

 Defining MQSeries objects
You define:
v A local queue with the usage of XMITQ for each sending message channel.
v Remote queue definitions.
A remote queue object has three distinct uses, depending upon the way the
name and content are specified:
– Remote queue definition
– Queue manager alias definition
– Reply-to queue alias definition
This is shown in Table 2 on page 37.
v A process specifying the trigger data for a channel that is triggered by messages
appearing on the transmission queue. The transmission queue must name
SYSTEM.CHANNEL.INITQ as the initiation queue.
– The process definition parameter, USERDATA, must contain the name of the
channel to be started by this process
– The application identifier (APPLICID) must be CSQX START
– The application type (APPLTYPE) must be set to MVS

For example:
DEFINE QLOCAL(MYXMITQ) USAGE(XMITQ) TRIGGER(YES) +
INITQ(SYSTEM.CHANNEL.INITQ) PROCESS(MYPROCESS)
DEFINE PROCESS(MYPROCESS) APPLTYPE(MVS) APPLICID('CSQX START') +
USERDATA(MYCHANNEL)
DEFINE CHL(MYCHANNEL) CHLTYPE(SDR) TRTYPE(TCP) +
XMITQ(MYXMITQ) CONNAME('9.20.9.30(1555)')

Note: The trigger monitor program is actually the channel initiator itself; no
separate program needs to be started.

The supplied sample CSQ4INYD gives additional examples of the necessary

definitions.

Synchronization queue
DQM requires a queue for use with sequence numbers and logical units of work
identifiers (LUWID). You must ensure that a queue is available with the name
SYSTEM.CHANNEL.SYNCQ (see the MQSeries for OS/390 System Management
Guide).

Make sure that you define this queue using INDXTYPE(MSGID). This will improve
the speed at which it can be accessed.

Channel command queues

You need to ensure that channel command queues exist for your system with the
names SYSTEM.CHANNEL.INITQ and SYSTEM.CHANNEL.REPLY.INFO.

If the channel initiator detects a problem with the SYSTEM.CHANNEL.INITQ, it

will be unable to continue normally until the problem is corrected. The problem
could be one of the following:
v The queue is full
v The queue is not enabled for put
v The page set that the queue is on is full
v The channel initiator does not have the correct security authorization to the
queue

Chapter 24. Preparing MQSeries for OS/390 343

Defining MQSeries objects
If the definition of the queue is changed to GET(DISABLED) while the channel
initiator is running, it will not be able to get messages from the queue, and will
terminate.

Channel operation considerations

1. Because the channel initiator uses a number of asynchronously operating
dispatchers, the order in which operator messages appear on the log may be
out of chronological sequence.
2. MCAs for receiver channels may keep the destination queues open even when
messages are not being transmitted; this results in the queues appearing to be
‘in use’.
3. If you change security access for a user ID, the change may not take effect
immediately. See the MQSeries for OS/390 System Management Guide for more
information.
4. If TCP is stopped for some reason and then restarted, the MQSeries for OS/390
TCP listener waiting on a TCP port is stopped.
If you are using the OpenEdition sockets interface, (for example, if you are
using the IUCV interface or the Interlink SNSTCPAccess interface,) the channel
initiator must be stopped and manually restarted when TCP returns. Then, the
listener must also be manually restarted to resume communications.
If you are using the OpenEdition sockets interface, automatic channel reconnect
allows the channel initiator to detect that TCP/IP is not available and to
automatically restart the TCP/IP listener when TCP/IP returns. This alleviates
the need for operations staff to notice the problem with TCP/IP and manually
restart the listener. While the listener is out of action, the channel initiator can
also be used to retry the listener at the interval specified by LSTRTMR in the
channel initiator parameter module. These attempts can continue until TCP/IP
returns and the listener successfully restarts automatically. For information
about LSTRTMR, see the MQSeries for OS/390 System Management Guide.
5. If APPC is stopped, the listener is also stopped. Again, in this case, the listener
automatically retries at the LSTRTMR interval so that, if APPC restarts, the
listener can restart too.

OS/390 Automatic Restart Management (ARM)

Automatic restart management (ARM) is an OS/390 recovery function that can
improve the availability of specific batch jobs or started tasks (for example,
subsystems), and therefore result in a faster resumption of productive work.

To use ARM, you must set up your queue managers and channel initiators in a
particular way to make them restart automatically. For information about this, see
the MQSeries for OS/390 System Management Guide.

344 MQSeries Intercommunication

Chapter 25. Message channel planning example for OS/390
This chapter provides a detailed example of how to connect two OS/390 or
MVS/ESA queue managers together so that messages can be sent between them.
The example illustrates the preparations needed to allow an application using
queue manager QM1 to put messages on a queue at queue manager QM2. An
application running on QM2 can retrieve these messages, and send responses to a
reply queue on QM1.

The example illustrates the use of both TCP/IP and LU 6.2 connections. The
example assumes that channels are to be triggered to start when the first message
arrives on the transmission queue they are servicing.

What the example shows

The example shows the MQSeries commands (MQSC) that you can use in
MQSeries for OS/390 for DQM.

Application Queue manager 'QM1' Queue manager 'QM2' Application

Payroll Query
Payroll
query Queue remote 'PAYROLL.QUERY' processing
message
Channel
Query
Queue transmission 'QM2' QM1.TO.QM2 Queue local 'PAYROLL'
message

Reply
'SYSTEM.CHANNEL.INITQ' Queue transmission 'QM1'
message

Reply
Queue local 'PAYROLL.REPLY' QM2.TO.QM1 'SYSTEM.CHANNEL.INITQ'
message

Figure 50. The message channel example for MQSeries for OS/390

It involves a payroll query application connected to queue manager QM1 that

sends payroll query messages to a payroll processing application running on queue
manager QM2. The payroll query application needs the replies to its queries sent
back to QM1. The payroll query messages are sent from QM1 to QM2 on a
sender-receiver channel called QM1.TO.QM2, and the reply messages are sent back
from QM2 to QM1 on another sender-receiver channel called QM2.TO.QM1. Both
of these channels are triggered to start as soon as they have a message to send to
the other queue manager.

The payroll query application puts a query message to the remote queue
“PAYROLL.QUERY” defined on QM1. This remote queue definition resolves to the
local queue “PAYROLL” on QM2. In addition, the payroll query application
specifies that the reply to the query is sent to the local queue “PAYROLL.REPLY”
on QM1. The payroll processing application gets messages from the local queue

© Copyright IBM Corp. 1993, 2000 345

Planning example for OS/390
“PAYROLL” on QM2, and sends the replies to wherever they are required; in this
case, local queue “PAYROLL.REPLY” on QM1.

Both queue managers are assumed to be running on OS/390. In the example

definitions for TCP/IP, QM1 has a host address of 9.20.9.31 and is listening on port
1411, and QM2 has a host address of 9.20.9.32 and is listening on port 1412. In the
definitions for LU 6.2, QM1 is listening on a symbolic luname called LUNAME1
and QM2 is listening on a symbolic luname called LUNAME2. The example
assumes that these are already defined on your OS/390 system and available for
use.

The object definitions that need to be created on QM1 are:

v Remote queue definition, PAYROLL.QUERY
v Transmission queue definition, QM2 (default=remote queue manager name)
v Process definition, QM1.TO.QM2.PROCESS
v Sender channel definition, QM1.TO.QM2
v Receiver channel definition, QM2.TO.QM1
v Reply-to queue definition, PAYROLL.REPLY

The object definitions that need to be created on QM2 are:

v Local queue definition, PAYROLL
v Transmission queue definition, QM1 (default=remote queue manager name)
v Process definition, QM2.TO.QM1.PROCESS
v Sender channel definition, QM2.TO.QM1
v Receiver channel definition, QM1.TO.QM2

The example assumes that all the SYSTEM.COMMAND.* and

SYSTEM.CHANNEL.* queues required to run DQM have been defined as shown
in the supplied sample definitions, CSQ4INSG and CSQ4INSX.

The connection details are supplied in the CONNAME attribute of the sender
channel definitions.

You can see a diagram of the arrangement in Figure 50 on page 345.

Queue manager QM1 example

The following object definitions allow applications connected to queue manager
QM1 to send request messages to a queue called PAYROLL on QM2, and to receive
replies on a queue called PAYROLL.REPLY on QM1.

All the object definitions have been provided with the DESCR and REPLACE
attributes. The other attributes supplied are the minimum required to make the
example work. The attributes that are not supplied take the default values for
queue manager QM1.

Run the following commands on queue manager QM1.

Remote queue definition

DEFINE QREMOTE(PAYROLL.QUERY) DESCR('Remote queue for QM2') REPLACE +
PUT(ENABLED) XMITQ(QM2) RNAME(PAYROLL) RQMNAME(QM2)

Note: The remote queue definition is not a physical queue, but a means of
directing messages to the transmission queue, QM2, so that they can be sent
to queue manager QM2.

346 MQSeries Intercommunication

 Planning example for OS/390
Transmission queue definition
DEFINE QLOCAL(QM2) DESCR('Transmission queue to QM2') REPLACE +
USAGE(XMITQ) PUT(ENABLED) GET(ENABLED) TRIGGER TRIGTYPE(FIRST) +
INITQ(SYSTEM.CHANNEL.INITQ) PROCESS(QM1.TO.QM2.PROCESS)

When the first message is put on this transmission queue, a trigger message is sent
to the initiation queue, SYSTEM.CHANNEL.INITQ. The channel initiator gets the
message from the initiation queue and starts the channel identified in the named
process. The channel initiator can only get trigger messages from the
SYSTEM.CHANNEL.INITQ queue, so you should not use any other queue as the
initiation queue.

Process definition
DEFINE PROCESS(QM1.TO.QM2.PROCESS) DESCR('Process for starting channel') +
REPLACE APPLTYPE(MVS) APPLICID('CSQX START') USERDATA(QM1.TO.QM2)

The channel initiator uses this process information to start channel QM1.TO.QM2.

Sender channel definition

For a TCP/IP connection:
DEFINE CHANNEL(QM1.TO.QM2) CHLTYPE(SDR) TRPTYPE(TCP) +
REPLACE DESCR('Sender channel to QM2') XMITQ(QM2) +
CONNAME('9.20.9.32(1412)')

For an LU 6.2 connection:

DEFINE CHANNEL(QM1.TO.QM2) CHLTYPE(SDR) TRPTYPE(LU62) +
REPLACE DESCR('Sender channel to QM2') XMITQ(QM2) +
CONNAME('LUNAME2')

Receiver channel definition

For a TCP/IP connection:
DEFINE CHANNEL(QM2.TO.QM1) CHLTYPE(RCVR) TRPTYPE(TCP) +
REPLACE DESCR('Receiver channel from QM2')

For an LU 6.2 connection:

DEFINE CHANNEL(QM2.TO.QM1) CHLTYPE(RCVR) TRPTYPE(LU62) +
REPLACE DESCR('Receiver channel from QM2')

Reply-to queue definition

DEFINE QLOCAL(PAYROLL.REPLY) REPLACE PUT(ENABLED) GET(ENABLED) +
DESCR('Reply queue for replies to query messages sent to QM2')

The reply-to queue is defined as PUT(ENABLED). This ensures that reply

messages can be put to the queue. If the replies cannot be put to the reply-to
queue, they are sent to the dead-letter queue on QM1 or, if this queue is not
available, remain on transmission queue QM1 on queue manager QM2. The queue
has been defined as GET(ENABLED) to allow the reply messages to be retrieved.

Queue manager QM2 example

The following object definitions allow applications connected to queue manager
QM2 to retrieve request messages from a local queue called PAYROLL, and to put
replies to these request messages to a queue called PAYROLL.REPLY on queue
manager QM1.

You do not need to provide a remote queue definition to enable the replies to be
returned to QM1. The message descriptor of the message retrieved from local
queue PAYROLL contains both the reply-to queue and the reply-to queue manager

Chapter 25. Message channel planning example for OS/390 347

Planning example for OS/390
names. Therefore, as long as QM2 can resolve the reply-to queue manager name to
that of a transmission queue on queue manager QM2, the reply message can be
sent. In this example, the reply-to queue manager name is QM1 and so queue
manager QM2 simply requires a transmission queue of the same name.

All the object definitions have been provided with the DESCR and REPLACE
attributes and are the minimum required to make the example work. The attributes
that are not supplied take the default values for queue manager QM2.

Run the following commands on queue manager QM2.

Local queue definition

DEFINE QLOCAL(PAYROLL) REPLACE PUT(ENABLED) GET(ENABLED) +
DESCR('Local queue for QM1 payroll details')

This queue is defined as PUT(ENABLED) and GET(ENABLED) for the same

reason as the reply-to queue definition on queue manager QM1.

Transmission queue definition

DEFINE QLOCAL(QM1) DESCR('Transmission queue to QM1') REPLACE +
USAGE(XMITQ) PUT(ENABLED) GET(ENABLED) TRIGGER TRIGTYPE(FIRST) +
INITQ(SYSTEM.CHANNEL.INITQ) PROCESS(QM2.TO.QM1.PROCESS)

When the first message is put on this transmission queue, a trigger message is sent
to the initiation queue, SYSTEM.CHANNEL.INITQ. The channel initiator gets the
message from the initiation queue and starts the channel identified in the named
process. The channel initiator can only get trigger messages from
SYSTEM.CHANNEL.INITQ so you should not use any other queue as the
initiation queue.

Process definition
DEFINE PROCESS(QM2.TO.QM1.PROCESS) DESCR('Process for starting channel') +
REPLACE APPLTYPE(MVS) APPLICID('CSQX START') USERDATA(QM2.TO.QM1)

The channel initiator uses this process information to start channel QM2.TO.QM1.

Sender channel definition

For a TCP/IP connection:
DEFINE CHANNEL(QM2.TO.QM1) CHLTYPE(SDR) TRPTYPE(TCP) +
REPLACE DESCR('Sender channel to QM1') XMITQ(QM1) +
CONNAME('9.20.9.31(1411)')

For an LU 6.2 connection:

DEFINE CHANNEL(QM2.TO.QM1) CHLTYPE(SDR) TRPTYPE(LU62) +
REPLACE DESCR('Sender channel to QM1') XMITQ(QM1) +
CONNAME('LUNAME1')

Receiver channel definition

For a TCP/IP connection:
DEFINE CHANNEL(QM1.TO.QM2) CHLTYPE(RCVR) TRPTYPE(TCP) +
REPLACE DESCR('Receiver channel from QM1')

For an LU 6.2 connection:

DEFINE CHANNEL(QM1.TO.QM2) CHLTYPE(RCVR) TRPTYPE(LU62) +
REPLACE DESCR('Receiver channel from QM1')

348 MQSeries Intercommunication

 Planning example for OS/390

Running the example

When you have created the required objects, you must:
v Start the channel initiator for both queue managers
v Start the listener for both queue managers

The applications can then send messages to each other. Because the channels are
triggered to start by the arrival of the first message on each transmission queue,
you do not need to issue the START CHANNEL MQSC command.

For details about starting a channel initiator see “Starting a channel initiator” on
page 327, and for details about starting a listener see “Starting a channel listener”
on page 329.

Expanding this example

This example can be expanded by:
v Adding more queue, process, and channel definitions to allow other applications
to send messages between the two queue managers.
v Adding user exit programs on the channels to allow for link encryption, security
checking, or additional message processing.
v Using queue manager aliases and reply-to queue aliases to understand more
about how these can be used in the organization of your queue manager
network.

Chapter 25. Message channel planning example for OS/390 349

Planning example for OS/390

350 MQSeries Intercommunication

Chapter 26. Monitoring and controlling channels in OS/390
with CICS
You monitor and control the channels to remote queue managers from the
distributed queue management (DQM) panels. Each OS/390 queue manager has a
set of DQM CICS transactions for controlling interconnections to compatible
remote queue managers using CICS intersystem communication (ISC) facilities.

The DQM channel control function

The channel control function provides the administration and control of message
channels using CICS between MQSeries for OS/390 and compatible systems. See
Figure 28 on page 58 for a conceptual picture.

The channel control function consists of CICS panels and programs, a sequence
number queue, a channel command queue, and a VSAM file for the channel
definitions. The following is a brief description of the components of the channel
control function.
v The channel definition file (CDF):
– Is a VSAM file
– Is indexed on channel name
– Holds channel definitions
– Must be available to the CICS regions in which the channel control program
runs, and where the message channel agent (MCA) programs run
v You use channel definition panels to:
– Create, copy, display, alter, find, and delete channel definitions
– Start channels, reset channel sequence numbers, stop channels, ping channels,
resync channels, and resolve in-doubt messages when links cannot be
re-established
– Display status information about channels

The panels are CICS basic-mapping support maps.

v Sequence numbers and logical unit of work IDs (LUWIDs) are stored in the
sequence number queue, SYSTEM.CHANNEL.SEQNO, and are used for channel
re-synchronization purposes.
v A channel command queue, SYSTEM.CHANNEL.COMMAND, is used to hold
certain commands for channels.
v The programs are a series of CICS transactions, which include transactions for
the MCAs. There are different MCAs available for each type of channel. The
names are contained in the following table. Other transactions provide channel
control, command handling, and trigger monitoring.
Table 31. Program and transaction names
Program name Channel type CICS transaction ID
CSQKMSGS Sender CKSG
CSQKMSGR Receiver CKRC
CSQKMSGQ Requester CKRQ
CSQKMSGV Server CKSV

© Copyright IBM Corp. 1993, 2000 351

Channel control function

v A transient data queue CKMQ for error messages.

CICS regions
Figure 51 shows a configuration of two CICS regions, connected to a single queue
manager. The regions have multiregion operation (MRO) links to one another, for
function shipping of EXEC CICS START commands from the channel control
program.

R e m o te
s y s te m
queue
m anager

C o m m u n ic a tio n
link. LU 6.2

CICS-B CICS-C
C h a n n el
M essage C h a n n el d e fin itio n
channel c o n tr o l f i le
agent C IC S/M R O program
program C o n n e ctio n

Q ueue t r a n s m is s io n

Figure 51. Sample configuration of channel control and MCA. MRO is used for an EXEC
CICS START of the MCA, and for an EXEC CICS READ of the channel definition file by the
MCA. Communication with the remote queue manager is through CICS ISC, not MRO.

Starting DQM panels

You invoke DQM panels with the CKMC CICS transaction. On invocation, DQM
presents you with the main Message Channel List panel. All activity with the other
panels follows from selections made on this panel.

352 MQSeries Intercommunication

 Message Channel List panel

The Message Channel List panel

The main panel is called the Message Channel List panel; for an example of it, see
Figure 52. It has a menu bar with choices you can pull down to reveal the various
options you can select for these choices. The work area of the panel is used to
present a selection column, and three other columns showing the:
v Full name of each channel
v Type of channel
v CICS system identifier

Selected Edit View Help

------------------------------------------------------------------------------
MCSELB IBM MQSeries for OS/390 - Message Channel List VICY14

Select a channel name. Then select an action.

More: +
Channel name Type Sysid
VC13.TO.VC14.REQSER REQUESTER VR14
VC13.2.VC14.JAC3 RECEIVER VR14
VC13.2.VC14.MROSER REQUESTER VR14
VC13.2.VC14.REQSEND REQUESTER VR14
VC13.2.VC14.SENDER SENDER VR14
VICY13.TO.VICY14 RECEIVER VR14
VICY13.TO.VICY14.CB REQUESTER VR14
VICY13.TO.VICY14.NS RECEIVER VR14
VICY13.TO.VICY14.NSR RECEIVER VR14
VICY13.TO.VICY14.NS2 RECEIVER VR14
VICY13.TO.VICY14.SER REQUESTER VR14
VICY13.TO.VICY14.SVR REQUESTER VR14

(C) Copyright IBM Corporation 1993, 1999. All rights reserved.

F1=Help F3=Exit F5=Refresh now F6=Find F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 52. The Message Channel List panel

Keyboard functions
The following sections describe the function, Enter, and Clear keys, as well as what
happens if you press any unassigned keys associated with this panel.

Function keys
The function keys control the use of the panel. They are listed below, together with
their purpose.

F1 Call help panels

F3 Exit from the panel and the program
F5 Refresh the screen fields with current data
F6 Find a particular channel name
F7 Scroll the panel backward to display more channels
F8 Scroll the panel forward to display more channels
F10 Move the cursor to the menu bar
F12 Cancel pull-down menus or secondary windows, if any, otherwise as F3

Note: Function keys 13 to 24 have the same functions as functions keys 1 to 12,
respectively.

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 353
Message Channel List panel
Enter key
Pressing the Enter key while the cursor is on a menu-bar choice results in the
pull-down menu for that choice appearing.

Pressing the Enter key while the cursor is not on a menu-bar choice and a channel
selection has been made selects the default option, Display Settings.

Pressing the Enter key while the cursor is not on a menu-bar choice and no
channel selection has been made results in the panel being redisplayed.

Clear key
If you find while typing that what you have typed is not correct, press the Clear
key on your terminal to revert all the input fields to their previous state.

For individual fields, use the ‘Erase EOF’, or ‘Ctrl Delete’, depending upon the
type of terminal you are using.

Unassigned keys and unavailable choices

If you press a function key, or an attention key that has not been assigned an
action, a warning message is displayed that states that the key is invalid.

Selecting a channel
To select a channel, begin at the Message Channel List panel:
1. Move the cursor to the left of the required channel name.
2. Type a slash (/) character.
3. Press F10 to move the cursor to the menu bar, or press the Enter key to browse
the channel settings.

If you try to select more than one channel, only the first one you select is valid.

Working with channels

When a channel has been selected, function key F10 moves the cursor to the menu
bar (see Table 32). The menu-bar choices are:
Table 32. Message Channel List menu-bar choices
Selected Edit View Help

Selecting each of these choices causes its pull-down menu to be displayed (see
Figure 53 on page 355).

When you select an option that requires further information, such as a channel
name, an action window appears with an entry field for the data.

In general, any incorrect input from the keyboard results in a warning message
being issued.

354 MQSeries Intercommunication

 Message Channel List panel

Selected Edit View Help

+--------------------------+--------------------------------------------------
| 1. Start |r OS/390 - Message Channel List VICY14
| 2. Stop... |
| 3. Resync |select an action.
| 4. Reset... | More: - +
| 5. Resolve... |e Sysid
| 6. Display Status |UESTER VR14
| 7. Display Settings |EIVER VR14
| 8. Ping... |UESTER VR14
| 9. Exit F3 |UESTER VR14
+--------------------------+DER VR14

Selected Edit View Help

------------------ +--------------------------+-------------------------------
MCSELB IBM M | 1. Copy... | Channel List VICY14
| 2. Create... |
Select a channel n | 3. Alter |
| 4. Delete... | More: - +
Channel name | 5. Find... F6 |
VC13.TO.VC14.SEQ +--------------------------+
VC13.2.VC14.JAC3 RECEIVER VR14
VC13.2.VC14.MROSER REQUESTER VR14
VC13.2.VC14.REQSEND REQUESTER VR14
VC13.2.VC14.SENDER SENDER VR14

Selected Edit View Help

--------------------------------- +------------------------+------------------
MCSELB IBM MQSeries for MVS | 1. Include all | VICY14
| 2. Include... |
Select a channel name. Then selec | 3. Refresh now F5 |
+------------------------+ More: - +
Channel name Type Sysid
VC13.TO.VC14.SEQSER REQUESTER VR14
VC13.2.VC14.JAC3 RECEIVER VR14
VC13.2.VC14.MROSER REQUESTER VR14
VC13.2.VC14.REQSEND REQUESTER VR14
VC13.2.VC14.SENDER SENDER VR14

Selected Edit View Help

----------------------------------------------- +---------------------------+-
MCSELB IBM MQSeries for OS/390 - Message | 1. Using help |
| 2. General help |
Select a channel name. Then select an action. | 3. Keys help |
| 4. Tutorial |
Channel name Type Sysid | 5. Product Info |
VC13.TO.VC14.SEQSER REQUESTER VR14 +---------------------------+
VC13.2.VC14.JAC3 RECEIVER VR14
VC13.2.VC14.MROSER REQUESTER VR14
VC13.2.VC14.REQSEND REQUESTER VR14
VC13.2.VC14.SENDER SENDER VR14

Figure 53. The Message Channel List panel pull-down menus

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 355
Message Channel List panel
Creating a channel
To create a new channel, begin at the Message Channel List panel:
1. Press function key F10 and move the cursor to the Edit choice on the menu bar.
2. Press the Enter key to display the Edit pull-down menu, and select the Create
option.
3. Press the Enter key to display the Create action window.
4. Type the name of the channel in the field provided.
5. Select the channel type for this end of the link.
6. Press the Enter key.
Notes:
1. If you are using distributed queuing without CICS as well, don’t use any of the
same channel names.
2. You are recommended to name all the channels in your network uniquely. As
shown in Table 1 on page 30, including the source and target queue manager
names in the channel name is a good way to do this.

You are presented with the appropriate Settings panel for the type of channel you
have chosen. Fill in the fields with the information you have gathered previously,
and select the Save option from the Channel pull-down menu.

You are provided with help in deciding on the content of the various fields in the
descriptions of the channel definition panels in the following sections of this
chapter.

Altering a channel
To alter an existing channel, begin at the Message Channel List panel:
1. Select a channel.
2. Press function key F10 and move the cursor to the Edit choice on the menu bar.
3. Press the Enter key to display the Edit pull-down menu, and select the Alter
option.

You are presented with the appropriate Settings panel for the channel you have
chosen. Alter the fields with the information you have gathered previously, and
select the Save option from the Channel pull-down menu.

You are provided with help in deciding on the content of the various fields in the
descriptions of the channel definition panels in the following sections of this
chapter, and in the contextual help panels.

Browsing a channel
To browse the settings of a channel, begin at the Message Channel List panel:
1. Select a channel.
2. Press the Enter key.

If you try to select more than one channel, only the first one you select is valid.

This results in the respective Settings panel being displayed with details of the
current settings for the channel, but with the fields protected against user input.

356 MQSeries Intercommunication

 Message Channel List panel
If the Channel pull-down menu is selected from the menu bar, the Save option is
unavailable and this is indicated by an asterisk (*) in place of the first letter, as
shown in Figure 54.

Channel Help
+------------------+----------------------------------------------------------
| 1. *ave |13.2.VC14.SENDER - Settings VICY14
| 2. Exit F3 |
+------------------+
More: +
Channel type . . . . . . : SENDER

Target system id . . . . :
Transmission queue name . : JACK
Batch size . . . . . . . : 0001
Sequence number wrap . . : 0999999

Figure 54. The Channel pull-down menu

Renaming a channel
To rename a message channel, begin at the Message Channel List panel:
1. Ensure that the channel is inactive.
2. Select the channel.
3. Use Copy to create a duplicate with the new name.
4. Use Delete to delete the original channel.

If you decide to rename a message channel, ensure that both ends of the channel
are renamed at the same time.

Selected menu-bar choice

The options available in the Selected pull-down menu are:

Menu option Description

Start Starts the selected channel.
Stop Requests the channel to close down, immediately, or controlled.
Resync Requests the channel to re-synchronize with the remote end, and
then close. No messages are sent.
Reset Requests the channel to reset the sequence numbers on this end of
the link. The numbers must be equal at both ends for the channel to
start.
Resolve Requests the channel to resolve in doubt messages without
establishing connection to the other end.
Display Status Displays the current status of the channel.
Display Settings Displays the current settings for the channel.
Ping Exchanges a data message with the remote end.
Exit Exits from the program.

Start
The Start option is available for sender and requester channels, and moreover
should not be necessary where a sender channel has been set up with queue
manager triggering. For the method of setting up triggering, see “How to trigger
channels” on page 358.

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 357
Message Channel List panel
When a server channel has been fully defined as a sender, then the same applies as
for sender channels.

When you choose the Start option, an EXEC CICS START call is issued to the
MCA, which reads the channel definition file and opens the transmission queue. A
channel startup sequence is executed which remotely starts the corresponding
MCA of the receiver or server channel. When they are running, the sender and
server processes await messages arriving on the transmission queue and transmit
them as they arrive.

Using the Start option always causes re-synchronization where necessary.

For the start to succeed:

v Channel definitions, local and remote must exist.
v The associated transmission queue must exist and it must be enabled for GETs.
If sequential numbering is required, then no other process can have the
transmission queue open for input.
v CICS transactions, local (and remote if it is OS/390 using CICS) must exist.
v CICS communication must be running.
v The queue managers must be running, local and remote.
v Channel must be inactive.
v Sequence number queue must exist on the receiving system (if it is OS/390
using CICS).

It is not necessary that:

v Messages be available
v Remote queue definitions be used
v Remote destination queues be available

A message is returned to the panel confirming that the request to start a channel
has been accepted. For confirmation that the start command has succeeded, check
the system console for the CICS system hosting the MCA, or the transient data
queue.

The sender, server, and requester channel transactions can be started automatically
by CICS, if necessary. This is achieved by arranging for the MCA CICS transaction
to be started by the CICS system in the required way. This is similar to the
triggering startup in that the MCA is passed the required information in a trigger
message. For example, it can be customized to start at a certain time every day, or
at regular intervals. When started, it retrieves its channel definition and responds
accordingly.

How to trigger channels: If triggering is to be used to start a channel when

messages arrive on the associated transmission queue, use MQSeries for OS/390
operations and control panels or MQSC commands to set it up in accordance with
the details on triggering in the MQSeries Application Programming Guide, after
having collected all the planning data.

Trigger control is exercised by means of the trigger control parameter in the

transmission queue definition. You need to set up the transmission queue for the
channel, specifying TRIGGER, define an initiation queue, and define a process. For
example:

358 MQSeries Intercommunication

 Message Channel List panel
DEFINE QLOCAL(MYXMITQ) USAGE(XMITQ) TRIGGER INITQ(MYINITQ) +
TRIGTYPE(FIRST) PROCESS(MYPROCESS)

DEFINE QLOCAL(MYINITQ)

DEFINE PROCESS(MYPROCESS) APPLTYPE(CICS) APPLICID(CKSG) +

USERDATA(MYCHANNEL)

On the process definition:

APPLICID
Names the application that is to be triggered. If you have a fully defined
server channel (see “Message channels” on page 7), this ID should be
CKSG rather than CKSV. CKSV should be used only for requester-server
channels that are to be initiated only by the requester.
APPLTYPE
Specifies that this is a CICS application.
USERDATA
Specifies the name of the sender channel to be started.

Following the definitions, the long-running trigger process, CKTI, must be started
to monitor the initiation queue:
CKQC STARTCKTI MYINITQ

CKTI waits for trigger messages from the initiation queue, and starts an instance of
CKSG for the sender channel in response to the trigger messages. If the channel
experiences problems, the trigger control parameter on the transmission queue
definition is set to NOTRIGGER by the MCA, and the transmission queue is set to
GET(DISABLED). After diagnosis and correction and before you can restart
triggering, you must reset the TRIGGER parameter, for example with the MQSeries
for OS/390 operations and control panels, and must reset the transmission queue
to GET(ENABLED).

Stop
Use the Stop option to request the channel to stop activity.

The Stop option presents an action window to allow you to confirm your intention
to stop the channel, for all four types of channel. For sender and server channels
only, you can select the type of stop you require: IMMEDIATE, or QUIESCE. See
Figure 55 on page 360 and Figure 56 on page 361.

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 359
Message Channel List panel

Selected Edit View Help

+--------------------------+--------------------------------------------------
| 2 1. Start |r OS/390 - Message Channel List VICY03
| 2. Stop... |
| 3. Resy +--------------------------------------------------+
| 4. Rese | VC13.2.VC14 - Stop | More:
| 5. Reso | |
| 6. Disp | Select one. Then press Enter. |
| 7. Disp | |
| 8. Ping | Channel type . . . : SENDER |
| 9. Exit | |
+---------- | _ 1. Stop (quiesce) |
BREN.VR04 | 2. Stop (immediate) |
CRIS.VR01 | |
CRIS.VR01 | F1=Help F12=Cancel |
CRIS.VR03 +--------------------------------------------------+
CRIS.VR03.TO.VR04 SENDER
TEST.REQUESTER REQUESTER
TEST.SERVER SERVER

F1=Help F3=Exit F5=Refresh now F6=Find F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 55. Sender/server Stop action window

Stop immediate: This choice forces the channel to close down immediately, if
necessary, without completing the current batch of messages, but an attempt is
made to syncpoint with the other end of the channel.

Stop immediate is implemented by setting the channel’s transmission queue to

GET DISABLED. This means that if multiple channels are active against a
transmission queue, issuing a stop immediate against one of the channels causes
all channels to be stopped. You need to reset this queue to GET ENABLED using
the MQSeries for OS/390 operations and control panels or MQSC commands
before you attempt to restart the channels.

For more information, see the “Stopping and quiescing channels (not MQSeries for
Windows)” on page 67.

360 MQSeries Intercommunication

 Message Channel List panel

Selected Edit View Help

+--------------------------+--------------------------------------------------
| 2 1. Start |r OS/390 - Message Channel List VICY03
| 2. Stop... |
| 3. Resy +--------------------------------------------------+
| 4. Rese | VC13.2.VC14 - Stop | More:
| 5. Reso | |
| 6. Disp | Select one. Then press Enter. |
| 7. Disp | |
| 8. Ping | Channel type . . . : RECEIVER |
| 9. Exit | |
+---------- | _ 1. Stop (quiesce) |
BREN.VR04 | 2. *top (immediate) |
CRIS.VR01 | |
CRIS.VR01 | F1=Help F12=Cancel |
CRIS.VR03 +--------------------------------------------------+
CRIS.VR03.TO.VR04 SENDER
TEST.REQUESTER REQUESTER
TEST.SERVER SERVER

F1=Help F3=Exit F5=Refresh now F6=Find F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 56. Requester/receiver Stop action window

Stop quiesce: This choice requests the channel to close down in an orderly way;
the current batch of messages is completed, and the syncpoint procedure is carried
out with the other end of the channel.

For more information, see “Stopping and quiescing channels (not MQSeries for
Windows)” on page 67. For information about restarting stopped channels, see
“Restarting stopped channels” on page 69.

Resync
A message channel is synchronized when there are no in-doubt messages. That is,
the sending channel and the receiving channel are agreed on the current unit of
work number. The Resync option is valid for sender and server channels, but
server channels must be fully defined. The option allows the operator to request
the channel to re-synchronize with the remote end by resolving any in-doubt
messages.

There is no panel associated with this option.

It is to be used only where the channel is currently inactive and in-doubt messages
exist. The channel starts up, resolves the in-doubt messages, and then terminates. It
is not intended that the channel should send messages after the resolution has
been completed.

If the re-synchronization of a channel is not successful, you may need to examine

the content of the system sequence number queue, using the Display Status option
from the Selected pull-down menu on the Message Channel List panel. Compare
the sequence numbers, or LUWIDs, at the sending and receiving ends of the
channel in order to ascertain what needs to be done to restore synchronization.

It may be necessary to reset sequence numbers, or resolve in-doubt message status,

if a channel remains out of synchronization.

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 361
Message Channel List panel
If a channel terminates abnormally, the sender may be left in doubt as to whether
the receiver has received and committed one message, or a batch of messages.
When the channel is restarted, the channel program automatically re-synchronizes
before sending any new messages.

However, there are times when you may want to re-synchronize the in-doubt
messages, but not send any new ones. For example:
v You may want to reset sequence numbers before sending the next batch of
messages.
v You may want to close out a batch, but hold the remaining messages for later
transmission.

The channel program started by this option establishes a session with a partner. It
then exchanges the re-synchronization flows. Then, instead of starting new
message traffic, it sends a disconnect flow. The result is that the channel terminates
normally, without any in-doubt messages. It is ready to be restarted or reset, as
required.

For the re-synchronization to succeed:

v Channel definitions, local and remote must exist
v Transmission queue is available and usable
v CICS transactions, local (and remote if using OS/390 with CICS) must exist
v CICS communication must be running
v Queue managers must be running, local and remote
v Sequence number queue must exist on the receiving system (if using OS/390
with CICS)
v The channel must be inactive

A message is returned to the panel indicating whether the request to

re-synchronize a channel has succeeded. If the Resync process was not successful,
check the system console, or transient data queue (TDQ), for the CICS system
hosting the MCA for error messages.

Reset
Use the Reset option to request the channel to reset the sequence number. For a
view of the Reset Channel Sequence Number action window, see Figure 57 on
page 363. The change must be made separately on each end of the link, with care,
and can be done only on inactive channels that have no in-doubt units of work
outstanding.

The current sequence number is retrieved and changed to the value requested by
the user.

For the reset to succeed:

v The channel sequence number record must exist
v The channel must be inactive
v The channel must not be in doubt
v The channel definition, local, must exist
v CICS transactions, local, must exist
v The CICS system hosting the MCA must be connected to the queue manager
Notes:
1. To be effective, the sequence number must be reset in both the sender and the
receiver channel definitions. The starting sequence number is not negotiated
when a channel starts up, nor is there a default provided. Both ends of a
channel definition must have the same sequence number value.

362 MQSeries Intercommunication

 Message Channel List panel
2. In MQSeries for OS/390 using CICS, DQM saves the last sequence number
sent, which means that to start the next message with sequence number 100, for
example, you need to reset the sequence number to 99.
3. If you delete the channel definition at the partner end of the channel (by
deleting and recreating the partner queue manager), you must reset the channel
sequence number to 0 at the OS/390 end and to 1 at the partner end.

Selected Edit View Help

+--------------------------+--------------------------------------------------
| 4 1. Start |r OS/390 - Message Channel List VICY14
| 2. Stop... |
| 3. Resy +------------------------------------------------------+
| 4. Rese | Reset Channel Sequence Number |More: +
| 5. Reso | |
| 6. Disp | Type new sequence number. Then press Enter. |
| 7. Disp | |
| 8. Ping | Channel name . . . : VC13.2.VC14.SENDER |
| 9. Exit | Channel type . . . : SENDER |
+---------- | |
VC13.2.VC | Sequence number . . . _______ |
VC13.2.VC | |
VC13.2.VC | F1=Help F12=Cancel |
/ VC13.2.VC +------------------------------------------------------+
VC14.2.VC13 SENDER VR14

Figure 57. The Reset Channel Sequence Number action window

Resolve
Use the Resolve option to request a channel to commit or back out in-doubt
messages. This may be used when the other end of the link has terminated, and
there is no prospect of it returning. Any outstanding units of work need to be
resolved with either backout or commit. Backout restores messages to the
transmission queue, while Commit discards them.

The Resolve option is needed when the Resync option is not available, or not
effective, and messages are held in doubt by a sender or server. The option accepts
one of two parameters: Backout or Commit. See Figure 58 on page 364.

The channel program does not try to establish a session with a partner. Instead, it
determines the logical unit of work identifier (LUWID) which represents the
in-doubt messages. It then issues, as requested, either:
v Backout to restore the messages to the transmission queue; or
v Commit to delete the messages from the transmission queue

For the resolution to succeed:

v The channel must be inactive
v The channel must be in doubt
v The channel type must be sender or server
v The channel definition, local, must exist
v CICS transactions, local, must exist
v Queue manager must be running, local
v The CICS system hosting the MCA must be connected to the queue manager

See “In-doubt channels” on page 69 for more information.

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 363
Message Channel List panel

Selected Edit View Help

+--------------------------+--------------------------------------------------
| 5 1. Start |r OS/390 - Message Channel List VICY14
| 2. Stop... |
| 3. Resy +------------------------------------------------------+
| 4. Rese | Resolve Channel |More: - +
| 5. Reso | |
| 6. Disp | Select one. Then press Enter. |
| 7. Disp | |
| 8. Ping | Channel name . . . : VC14.2.VC13 |
| 9. Exit | Channel type . . . : SENDER |
+---------- | |
/ VC14.2.VC | _ 1. Backout (Restore messages to queue ) |
VICY13.TO | 2. Commit (Delete messages from queue) |
VICY13.TO | |
VICY13.TO | F1=Help F12=Cancel |
VICY13.TO +------------------------------------------------------+
VICY13.TO.VICY14.NS2 RECEIVER VR14

Figure 58. The Resolve Channel action window

Display status
Use the Display Status option to display the current status of the channel. The
following information is displayed:
v Whether the channel is active or inactive
v The in-doubt status of sender and server channels
v The sequence number last sent, if sequence numbering is in effect
v The last LUWID number, if available. Available means:
– Always available for receiver and requester channels
– Available for sender and server channels when:
- Sequence numbering is in effect
- No sequence numbering in effect, but the channel is in doubt

That is, the LUWID number is not available for sender and server channels
when sequence numbering is not in effect and the channel is not in doubt

For an example of sender and server status panels, see Figure 59 on page 365, and
for an example of receiver and requester status panels, see Figure 60 on page 365.

‘Not available’ status is acceptable when:

v Shown for a sequence number, if the channel is active
v Shown for an LUWID when the channel is not in doubt

Otherwise, if a ‘Not available’ status is shown in any of the fields, this indicates
that an error has occurred, and you should refer to the console log to find the error
messages associated with this problem.

364 MQSeries Intercommunication

 Message Channel List panel

Selected Edit View Help

+--------------------------+--------------------------------------------------
| 6 1. Start |r OS/390 - Message Channel List VICY13
| 2. Stop... |
| 3. Resy +--------------------------------------------------+
| 4. Rese | Display Channel Status | More: - +
| 5. Reso | |
| 6. Disp | Channel name . . . : VICY13.TO.VICY14 |
| 7. Disp | Channel type . . . : SENDER |
| 8. Ping | |
| 9. Exit | Status . . . . . . : Inactive |
+---------- | Indoubt status . . : Not in-doubt |
VICY13.TO | Sequence Number |
VICY13.TO | Last sent . . . . : 0001046 |
VICY13.TO | Last LUWID . . . . : A81D750042ECAD05 |
VICY13.TO | |
VICY13.TO | F1=Help F12=Cancel |
VICY13.TO.+--------------------------------------------------+
VICY13.TO.VICY15 SERVER VR13

F1=Help F3=Exit F5=Refresh now F6=Find F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 59. An example of a sender channel Display Channel Status window. The server
channel Display Channel Status panel looks the same, except that the Channel type field is
changed to SERVER.

Selected Edit View Help

+--------------------------+--------------------------------------------------
| 6 1. Start |r OS/390 - Message Channel List VICY13
| 2. Stop... |
| 3. Resy +--------------------------------------------------+
| 4. Rese | Display Channel Status | More: - +
| 5. Reso | |
| 6. Disp | Channel name . . . : VC14.2.VC13 |
| 7. Disp | Channel type . . . : RECEIVER |
| 8. Ping | |
| 9. Exit | Status . . . . . . : Inactive |
+---------- | Sequence Number |
VICY13.TO | Last sent . . . . : Not in effect |
VICY13.TO | Last LUWID . . . . : A81D750042ECAD05 |
VICY13.TO | |
VICY13.TO | F1=Help F12=Cancel |
VICY13.TO +--------------------------------------------------+
VICY13.TO.VICY14 REQUESTER VR13
VICY13.TO.VICY15 SERVER VR13

F1=Help F3=Exit F5=Refresh now F6=Find F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 60. An example of a receiver channel Display Channel Status window. The requester
channel Display Channel Status window looks the same, except that the Channel type field
is changed to REQUESTER.

Display settings
Use the Display Settings option to display the current definitions for the channel.
This choice displays the appropriate panel for the type of channel with the fields
displaying the current values of the parameters, and protected against user input:
v Sender: see Figure 71 on page 376
v Receiver: see Figure 73 on page 377

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 365
Message Channel List panel
v Server: see Figure 75 on page 378
v Requester: see Figure 77 on page 379

Protected input is shown with colon characters (:) at the end of field descriptions,
and the Save option is not available on the Channel pull-down menu.

You can select this choice from the Message Channel List panel by choosing a
channel and pressing Enter, without using the menu bar, ensuring that the cursor
is not on the menu bar.

Ping
Use the Ping option to exchange a data message with the remote end. This gives
you some confidence that the link is available and functioning. It can be issued
from sender and server channels only, but server channels must be fully defined.

Ping does not involve the use of transmission queues and target queues. It uses
channel definitions, the related CICS communication link, the network setup, and
the queue managers at both ends.

The corresponding channel is started at the far side of the link, and performs the
startup parameter negotiation.

If an error occurs, an error message is displayed on the panel, and additional

messages may be written to the console, or the CICS transient data queue.

The Ping panel offers you the opportunity to enter a message of up to 20

characters to be exchanged across the link. If you do not make use of this, a
default message is used.

The result of the message exchange is presented in the Ping panel for you, and this
is the returned message text, together with the time the message was sent, and the
time the reply was received.

Installations may supply their own applications to exchange particular information,

such as system identifiers. Figure 61 shows a view of the Ping action window.

Selected Edit View Help

+--------------------------+--------------------------------------------------
| 1. Start |r OS/390 - Message Channel List VICY14
| 2. Stop... |
| 3. Resy +--------------------------------------------------+
| 4. Rese | VC14.2.VC13 - Ping | More: - +
| 5. Reso | |
| 6. Disp | Type ping data. Then press Enter. |
| 7. Disp | |
| 8. Ping | Ping data . . . . . . TESTING PING |
| 9. Exit | |
+---------- | Time sent . . . . . : 11:29:37 |
/ VC14.2.VC | Time received . . . : 11:29:37 |
VICY13.TO | |
VICY13.TO | F1=Help F12=Cancel |
VICY13.TO +--------------------------------------------------+
VICY13.TO.VICY14.NSR RECEIVER VR14

Figure 61. The Ping action window

Exit
Use the Exit option to exit the current function: channel settings, help, or message
channel list.

366 MQSeries Intercommunication

 Message Channel List panel
A secondary window appears when you try to exit a channel settings panel
without first saving any changed definitions. This is a safe exit to prevent
inadvertent loss of data. The secondary window is shown in Figure 62.

Channel Help
+------------------+----------------------------------------------------------
| 1. Save |13.2.VC14.SENDER - Settings VICY14
| 2. Exit F3 |
+---------- +--------------------------------------------------+
| VC13.2.VC14.SENDER - Exit | More: +
Channel typ | |
| Channel type . . . : SENDER |
Target syst | |
Transmissio | The updated channel definition has |
Batch size | not been saved. |
Sequence nu | |
Max message | 2 1. Save and exit. |
Max transmi | 2. Exit without saving. |
Disconnect | |
Transaction | F1=Help F12=Cancel |
Connection +--------------------------------------------------+
CICS profile name . . . . .

Figure 62. The Exit confirmation secondary window

Edit menu-bar choice

The options available in the Edit pull-down menu are:
v Copy
v Create
v Alter
v Delete
v Find

In any of the action windows and settings panels associated with Edit, you can
type the channel name in uppercase or lowercase, but it may be converted to
uppercase when you press the Enter key, depending upon your Typeterm
definition.

Copy
Use the Copy option to copy an existing channel. The Copy action window (see
Figure 63 on page 368) enables you to define the new channel name. You can use
the characters shown in “Create” on page 368 in the name.

Press the Enter key on the Copy action window to display the channel settings
panel with details of current system values. You can change any of the new
channel settings. You save the new channel definition by selecting Channel from
the menu bar, and selecting the Save option from the pull-down menu.

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 367
Message Channel List panel

Selected Edit View Help

------------------ +--------------------------+-------------------------------
MCSELB IBM M | 1 1. Copy... | Channel List VICY14
| 2. Create... |
Select a ch +------------------------------------------------------+
| VC13.2.VC14.SENDER - Copy |More: - +
Channel n | |
VC13.TO.V | Type name of new channel. Then press Enter. |
VC13.2.VC | |
VC13.2.VC | Channel type . . . : SENDER |
VC13.2.VC | |
/ VC13.2.VC | Channel name . . . . ____________________ |
VC14.2.VC | |
VICY13.TO | F1=Help F12=Cancel |
VICY13.TO +------------------------------------------------------+
VICY13.TO.VICY14.NS RECEIVER VR14

Figure 63. The Copy action window

Create
Use the Create option to create a new channel definition from a screen of fields
filled with default values supplied by MQSeries for OS/390. Figure 64 on page 369
shows you where to type the name of the channel, and how to select the type of
channel you are creating.

When you press the Enter key, the appropriate channel settings panel is displayed.
Type information in all the necessary fields in this panel and then save the
definition by selecting Channel from the menu bar, and selecting the Save option
from the pull-down menu.

The channel name must be the same at both ends of the channel, and unique
within the network. You can use the following characters in the name:

Uppercase A-Z
Lowercase a-z
Numerics 0-9
Period ’.’
Forward slash ’/’
Underscore ’_’
Percentage sign ’%’

368 MQSeries Intercommunication

 Message Channel List panel

Selected Edit View Help

------------------ +--------------------------+-------------------------------
MCSELB IBM M | 2 1. Copy... | Channel List VICY14
| 2. Create... |
Select a ch +------------------------------------------------------+
| Create |More: - +
Channel n | |
VC13.TO.V | Type name of channel. Select channel type. |
VC13.2.VC | Then press Enter. |
VC13.2.VC | |
VC13.2.VC | Channel name . . . . ____________________ |
/ VC13.2.VC | |
VC14.2.VC | Channel type . . . . _ 1. Sender |
VICY13.TO | 2. Server |
VICY13.TO | 3. Receiver |
VICY13.TO | 4. Requester |
VICY13.TO | |
VICY13.TO | F1=Help F12=Cancel |
VICY13.TO +------------------------------------------------------+

Figure 64. The Create action window

All panels have default values supplied for some fields. You can change the values
when you are creating or copying channels. For examples of the channel definition
panels showing the default values, see Figure 65.

Press the Enter key on the Create action window to display the channel settings
panel with details of default values.

You can create your own set of channel default values by setting up dummy
channels with the required defaults for each channel type, and copying them each
time you want to create new channel definitions.

Channel Help
------------------------------------------------------------------------------
MCATTB1 TEST.CHANNEL - Settings VICY13

More: +
Channel type . . . . . . . SENDER

Target system id . . . . . ____

Transmission queue name . . _______________________________________________
Batch size . . . . . . . . 0001
Sequence number wrap . . . 0999999
Max message size . . . . . 0032000
Max transmission . . . . . 32000
Disconnect interval . . . . 0001
Transaction id . . . . . . CKSG
Connection name . . . . . . ____
CICS profile name . . . . . ________
LU 6.2 TP name . . . . . . ________________________________
________________________________

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 65. Example of default values during Create for a channel. The values supplied
cannot be customized.

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 369
Message Channel List panel
Alter
Use the Alter option to change an existing channel definition, except for the
channel name. Simply type over the fields to be changed in the channel definition
panel, and then save the updated definition by selecting Channel from the menu
bar, and selecting the Save option from the pull-down menu.

Delete
Use the Delete option to delete the selected channel. For the secondary window
requesting confirmation of your intention, see Figure 66.

Selected Edit View Help

------------------ +--------------------------+-------------------------------
MCSELB IBM M | 4 1. Copy... | Channel List VICY14
| 2. Create... |
Select a ch +------------------------------------------------------+
| VC13.2.VC14.SENDER - Delete |More: - +
Channel n | |
VC13.TO.V | The channel definition will be deleted. |
VC13.2.VC | |
VC13.2.VC | Channel type . . . : SENDER |
VC13.2.VC | |
/ VC13.2.VC | _ 1. Keep channel |
VC14.2.VC | 2. Delete channel |
VICY13.TO | |
VICY13.TO | F1=Help F12=Cancel |
VICY13.TO +------------------------------------------------------+
VICY13.TO.VICY14.NSR RECEIVER VR14

Figure 66. The Delete action window

Find
Use the Find option to locate a particular channel name from the list of available
channels. If the name of the channel you want is found, it is placed at the top of
the list on the Message Channel List panel. The Find a Channel action window is
shown in Figure 67.

Selected Edit View Help

------------------ +--------------------------+-------------------------------
MCSELB IBM M | 5 1. Copy... | Channel List VICY14
| 2. Create... |
Select a ch +--------------------------------------------------+
| Find a Channel | More: - +
Channel n | |
VC13.TO.V | Type name of channel. Then press Enter. |
VC13.2.VC | |
VC13.2.VC | Channel name . . . ____________________ |
VC13.2.VC | |
/ VC13.2.VC | |
VC14.2.VC | F1=Help F12=Cancel |
VICY13.TO +--------------------------------------------------+
VICY13.TO.VICY14.CB REQUESTER VR14

Figure 67. The Find a Channel action window

You can partially define the channel name using a terminating asterisk, for
example, channel.lon*. This results in the first channel name to be found with these
initial letters being placed at the top of the list.

370 MQSeries Intercommunication

 Message Channel List panel
View menu-bar choice
The options available in the View pull-down menu change the current view of the
list shown on the Message Channel List panel; see Figure 68.
Menu option
Description
Include all
All channels are included in the list.
Include...
Select the channels to be included in the list, by means of an action
window.
You can partially define the channel name using a terminating asterisk, for
example, channel.lon*. This results in channel names found with these
initial letters being included in the list.
Also in the action window is a field to allow you to specify a channel type,
or all types of channel.
Refresh now F5
Updates the panel with fresh data from the system.

Selected Edit View Help

--------------------------------- +------------------------+------------------
MCSELB IBM MQSeries for MVS | 2 1. Include all | VICY13
| 2. Include... |
Select a ch +------------------------------------------------------+
| Include search criteria |More: +
Channel n | |
TEST.CHAN | Type name of channel (use * for generic.) |
VC13.TO.V | Select channel type. Then press Enter |
VC13.2.VC | |
VC13.2.VC | Channel name . . . . vi* |
VC13.2.VC | |
VC13.2.VC | Channel type . . . . 5 1. Sender |
VC13.2.VC | 2. Server |
VC13.2.VC | 3. Receiver |
VICY13.TO | 4. Requester |
VICY13.TO | 5. All channel types |
VICY13.TO | |
VICY13.TO | F1=Help F12=Cancel |
+------------------------------------------------------+

F1=Help F3=Exit F5=Refresh now F6=Find F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 68. The Include search criteria action window

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 371
Message Channel List panel
Help menu-bar choice
The Help pull-down menu is shown in Figure 69.

Selected Edit View Help

----------------------------------------------- +---------------------------+-
MCSELB IBM MQSeries for OS/390 - Message | _ 1. Using help |
| 2. General help |
Select a channel name. Then select an action. | 3. Keys help |
| 4. Tutorial |
Channel name Type Sysid | 5. Product Info |
VC13.TO.VC14.SEQSER REQUESTER VR14 +---------------------------+
VC13.2.VC14.JAC3 RECEIVER VR14

Figure 69. The Help pull-down menu

The channel definition panels

The four channel Settings panels for defining channels (one for each of sender,
receiver, server, and requester) have a menu bar with choices you can pull down to
reveal various options you can select for these choices. See Table 33.

The menu-bar choices are:

Table 33. Menu-bar choices on channel panels
Channel Help

The work area of the panels is used to present the fields of attributes or settings
for the channel.

The function keys control the use of the panels to:

v Call help panels
v Move the cursor to the menu bar
v Refresh the panel
v Cancel a pull-down menu or a secondary window
v Exit from the panel
v Scroll forward and backward through settings

The method of using the panels is:

v For new channels, fill in the data fields, then select Channel from the menu bar,
and select the Save option from the pull-down menu.

Note: Default values supplied by MQSeries for OS/390 are presented in some
fields. The defaults cannot be changed, but the values presented can be
changed.
v For existing channels, type over the data presented in the fields with new data.
Then select Channel from the menu bar, and select the Save option from the
pull-down menu.

372 MQSeries Intercommunication

 Channel definition panels
Channel menu-bar choice
The Channel menu-bar choice enables you to save any changes you have made to
channel definitions, and to return to the Message Channel List panel.

Saving changes
If there are no errors, selecting the Save option from the Channel pull-down menu
saves any changes you have made to channel definitions. You are returned to the
Message Channel List panel.

If there are errors, you are returned to the Settings panel with an error message,
and all fields containing errors are highlighted. The cursor is positioned on the first
field in error. The changes are not saved.

Exit from the panel

Selecting the Save option from the Channel pull-down menu saves the changes
you have made and returns you to the Message Channel List panel.

Selecting the Exit option from the Channel pull-down menu, or pressing F3 or F12,
returns you to the Message Channel List panel.

However, if you have not saved the changes you made, a secondary window
requesting confirmation of your intention to exit without saving the data is
presented; see Figure 62 on page 367. If you want to save the changes you have
made, select Save and exit. If you have had second thoughts about the changes
you have made, select Exit without saving.

Help menu-bar choice

The Help pull-down menu is shown in Figure 70.

Channel Help
--------------+---------------------+-----------------------------------
MCATTB1 | _ 1. Using help | - Settings CICS01
| 2. General help |
| 3. Keys help |
| 4. Tutorial |
Channel type | 5. Product Info |
Transmission q| |___________________________________
Batch size . +---------------------+

Figure 70. The Help choice pull-down menu

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 373
Channel settings panel fields

Channel settings panel fields

The fields in these panels define the attributes of the channels. The channel settings
panel fields that you can change are shown in Table 34. You can find details for
each field in “Chapter 6. Channel attributes” on page 77.

A “U” signifies that the field is available for use with the indicated type of
channel, while an “O” means that these fields are only needed for server channels
when they are to be used as sender channels.
Table 34. Channel attribute fields per channel type
Attribute field Sender Server Receiver Requester
Batch size U U U U
CICS profile name U O U
Connection name U O U
Disconnect interval U U
LU62 TP name (see Note) U O U
Maximum message size U U U U
Maximum transmission size U U U U
Message exit U U U U
PUT authority U U
Retry count U O U
Retry fast interval U O U
Retry slow interval U O U
Receive exit U U U U
Sequence number wrap U U U U
Sequential delivery U U U U
Security exit U U U U
Send exit U U U U
Target system identifier U U U U
Transmission queue name U U
Transaction identifier U O U
Note: See also the Multiplatform APPC Configuration Guide (“Red Book”) and Table 35 for
information.

Table 35. Settings for LU 6.2 TP name on the local OS/390 system for a remote queue
manager platform
Remote platform Sender/server Requester
OS/390 using CKRC CKSV1
CICS
OS/390 without As specified in the side As specified in the side
CICS and UNIX information on remote queue information on remote queue
systems manager system manager system
OS/2 As specified in the OS/2 Run As specified in the OS/2 Run
Listener command, or defaulted Listener command, or defaulted
from the OS/2 queue manager from the OS/2 queue manager
configuration file configuration file

374 MQSeries Intercommunication

 Channel settings panel fields
Table 35. Settings for LU 6.2 TP name on the local OS/390 system for a remote queue
manager platform (continued)
Remote platform Sender/server Requester
OS/400 The same as the compare value in The same as the compare value in
the routing entry on the OS/400 the routing entry on the OS/400
system system
Digital OVMS As specified in the Digital OVMS As specified in the Digital OVMS
Run Listener command Run Listener command
Tandem NSK The same as the TPNAME The same as the TPNAME
specified in the receiver-channel specified in the receiver-channel
definition definition
Windows NT As specified in the Windows NT As specified in the Windows NT
Run Listener command, or the Run Listener command, or the
invokable Transaction Program invokable Transaction Program
that was defined using TpSetup on that was defined using TpSetup on
Windows NT Windows NT
Note: 1 If you have a fully defined server channel, (see “Message channels” on page 7), its
definition should specify a transaction ID of CKSG.

If you have more than one queue manager on the same machine, ensure that the
TPnames in the channel definitions are unique. To modify a TPname, use
CSQ4SIDE or CKMC.

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 375
Channel settings panel fields
Details of sender channel settings panel
This section provides details of the sender channel settings panel, as shown in
Figures 71 and 72.

Channel Help
------------------------------------------------------------------------------
MCATTB1 HURSLEY.TO.SYDNEY - Settings VICY14

More: +
Channel type . . . . . . : SENDER

Target system id . . . . :
Transmission queue name . : TX1
Batch size . . . . . . . : 0001
Sequence number wrap . . : 0999999
Max message size . . . . : 0032000
Max transmission . . . . : 32000
Disconnect interval . . . : 0001
Transaction id . . . . . : CKSG
Connection name . . . . . : HtoH
CICS profile name . . . . :
LU 6.2 TP name . . . . . : CKRC

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 71. The sender channel settings panel

Channel Help
------------------------------------------------------------------------------
MCATTC1 HURSLEY.TO.SYDNEY - Settings VICY14

More: -
Channel type . . . . . . : SENDER

Sequential delivery . . . : 0 (0=No or 1=Yes)

Retry
Count . . . . . . . . . : 005
Fast interval . . . . . : 005
Slow interval . . . . . : 030

Exit routines
Security . . . . . . . :
Message . . . . . . . . :
Send . . . . . . . . . :
Receive . . . . . . . :

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 72. The sender channel settings panel - screen 2

376 MQSeries Intercommunication

 Channel settings panel fields
Details of receiver channel settings panel
This section provides details of the receiver channel settings panels, as shown in
Figures 73 and 74.

Channel Help
------------------------------------------------------------------------------
MCATTB3 VICY13.TO.VICY14 - Settings VICY14

More: +
Channel type . . . . . . : RECEIVER

Target system id . . . . :

Batch size . . . . . . . : 0100

Sequence number wrap . . : 0099920
Max message size . . . . : 0032000
Max transmission . . . . : 32000

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 73. The receiver channel settings panel

Channel Help
------------------------------------------------------------------------------
MCATTC3 VICY13.TO.VICY14 - Settings VICY14

Type information. Then select an action.

More: -
Channel type . . . . . . : RECEIVER

Sequential delivery . . . : 1 (0=No or 1=Yes)

Put authority . . . . . . : 1 (1=Process or 2=Context)

Exit routines
Security . . . . . . . :
Message . . . . . . . . :
Send . . . . . . . . . :
Receive . . . . . . . . :

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 74. The receiver channel settings panel - screen 2

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 377
Channel settings panel fields
Details of server channel settings panel
This section provides details of the server channel settings panels, as shown in
Figures 75 and 76.

Channel Help
------------------------------------------------------------------------------
MCATTB1 HURSLEY.TO.SYDNEY - Settings VICY14

More: +
Channel type . . . . . . : SERVER

Target system id . . . . :
Transmission queue name . : TX1
Batch size . . . . . . . : 0001
Sequence number wrap . . : 0999999
Max message size . . . . : 0032000
Max transmission . . . . : 32000
Disconnect interval . . . : 0001
Transaction id . . . . . :
Connection name . . . . . :
CICS profile name . . . . :
LU 6.2 TP name . . . . . :

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 75. The server channel settings panel

Channel Help
------------------------------------------------------------------------------
MCATTC1 HURSLEY.TO.SYDNEY - Settings VICY14

More: -
Channel type . . . . . . : SERVER

Sequential delivery . . . : 0 (0=No or 1=Yes)

Retry
Count . . . . . . . . . : 005
Fast interval . . . . . : 005
Slow interval . . . . . : 030

Exit routines
Security . . . . . . . :
Message . . . . . . . . :
Send . . . . . . . . . :
Receive . . . . . . . :

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 76. The server channel settings panel - screen 2

378 MQSeries Intercommunication

 Channel settings panel fields
Details of requester channel settings panel
This section provides details of each field in the requester channel settings panels,
as shown in Figures 77 and 78.

Channel Help
------------------------------------------------------------------------------
MCATTB4 VICY13.TO.VICY14.CB - Settings VICY14

More: +
Channel type . . . . . . : REQUESTER

Target system id . . . . :

Batch size . . . . . . . : 0001

Sequence number wrap . . : 0999999
Max message size . . . . : 0032000
Max transmission . . . . : 32000

Transaction id . . . . . : CKRQ
Connection name . . . . . : VC13
CICS profile name . . . . : LU6PROF
LU 6.2 TP name . . . . . : CKSV

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 77. The requester channel settings panel

Channel Help
------------------------------------------------------------------------------
MCATTC4 VICY13.TO.VICY14.CB - Settings VICY14

More: -
Channel type . . . . . . : REQUESTER

Sequential delivery . . . : 0 (0=No or 1=Yes)

Put authority . . . . . . : 1 (1=Process or 2=Context)

Retry
Count . . . . . . . . . : 005
Fast interval . . . . . : 005
Slow interval . . . . . : 030
Exit routines
Security . . . . . . . :
Message . . . . . . . . :
Send . . . . . . . . . :
Receive . . . . . . . . :

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 78. The requester channel settings panel - screen 2

Chapter 26. Monitoring and controlling channels in OS/390 with CICS 379
Channel settings panel fields

380 MQSeries Intercommunication

Chapter 27. Preparing MQSeries for OS/390 when using CICS
This chapter describes the MQSeries for OS/390 and CICS preparations you need
to make before you can start to use CICS for distributed queuing.

To enable distributed queuing, you must perform the following three tasks:
v Customize the distributed queuing facility and define the MQSeries objects
required; this is described in the MQSeries for OS/390 System Management Guide.
v Define access security; this is described in the MQSeries for OS/390 System
Management Guide.
v Set up your communications; this is described in this chapter.

Setting up CICS communication for MQSeries for OS/390

Distributed queue management (DQM) provides channel control programs which
form the interface to CICS communication links, controllable by the system
operator. The channel definitions held by DQM use these CICS connections.

When a channel is started, it tries to use the CICS connection specified in the
channel definition. For this to succeed, it is necessary for the CICS connection to be
defined and available. This section explains how to do this.

If more than one CICS system is associated with any one MQSeries for OS/390,
and each CICS system is running some DQM functions, you need to define
connections between the CICS systems. This chapter also explains how to do this.

Connecting CICS systems

Part of the installation of DQM requires the definition and installation of CICS
logical unit type 6.2 (LU 6.2) connections that provide the physical link between
the CICS systems serving the local queue manager, and the systems serving the
remote queue managers. To set up these connections, use the CICS
Intercommunication Guide.

One OS/390 system can be host to a number of CICS systems at the same time,
and each CICS system is able to connect to one queue manager at any one time.

You provide communication links so that queue managers may use these links,
through CICS intersystem communication (ISC) to reach other queue managers on
OS/390 systems (using CICS or not), and on other non-OS/390 systems, provided
they are using the standard queue manager intercommunication protocol,
MQSeries Message Channel Protocol.

Communication between queue managers

There are two forms of communication between CICS systems:
v Intersystem communication (ISC): communication between a CICS system and
other systems in a data communication network that support the logical unit
type 6.1 or logical unit type 6.2 protocols of IBM Systems Network Architecture
(SNA).
v Multiregion operation (MRO): communication between CICS systems running in
different address spaces of the same OS/390 system.

© Copyright IBM Corp. 1993, 2000 381

CICS communication
Only ISC LU 6.2 protocols are used for connecting two queue managers over a
DQM channel, even where they both reside in the same OS/390 system.

Note: CICS for MVS/ESA Version 4 Release 1.0 or higher is required for MQSeries
distributed queue management.

Intersystem communication
The connection type must be ISC LU 6.2, but can be defined as one of the
following:
v LU 6.2 single-session terminal
v LU 6.2 single-session connection
v LU 6.2 parallel-session connection

Before deciding the type of connection to be defined, you should consider the
following points:
v The number of channels to be defined between the two systems
v The maximum number of channels that are to be active at any one time
v How often the connection is used
v The number of channels per transmission queue
v The number of channels that can be active per connection

Note: Multiple channels can be active on the same connection.

To define an LU 6.2 link between the two CICS systems, you should refer to the
following books:
v CICS Intercommunication Guide, SC33-1695.
v CICS Resource Definition Guide, SC33-1684.
paying particular attention to the sections discussing communication resources.

Defining an LU 6.2 connection

When you decide which type of LU 6.2 connection is to be established between the
local and remote CICS systems, the process of definition can take place.

Only one ISC connection can be active between any two CICS systems at the same
time. However, a single CICS system can have connections to multiple remote
CICS systems at the same time.

The sender and requester channel definitions require the provision of the LU 6.2
connection name and, optionally, the CICS profile name to be used.

382 MQSeries Intercommunication

 CICS communication
The relationship between CICS profiles and connections is shown in Figure 79 .
The uppercase fields are the names of the CEDA transaction entry, and the
lowercase values are fields within those definitions that are relevant to the
example.

PROFILE=MYPROF
modename=CICSISC0
SESSION=SES1
connection=CON1
modename=CICSISC0
CONNECTION=CON1
net name=luname

Figure 79. CICS LU 6.2 connection definition

If a sender channel is defined with the following characteristics, it causes a session

to be allocated using a SES1 session on connection CON1:
v CHANNEL=MY.CHANNEL
v CONNECTION NAME=CON1
v CICS PROFILE NAME=MYPROF

If no CICS profile name is specified in the channel definition, DQM does not
specify a profile when allocating a session.

Installing the connection

When you have defined the connection definitions on your CICS system
definitions (CSDs), these can be installed using the CICS CEDA INSTALL
command.

If you want to install these connections as part of the CICS initialization process,
you can add the group that contains the connection definitions to the CICS startup
list that is specified in the GRPLIST= parameter. You then need to cold start your
CICS system for the entries to become effective.

Communications between CICS systems attached to one

queue manager
DQM functions may be shared between more than one CICS system. When these
CICS systems are connected to, or associated with, the same queue manager, then
these CICS systems need to be set up correctly so that function shipping of EXEC
CICS commands and program invocation occur correctly.

Connection names for function shipping

Although CICS does not require that a connection name is the same as the DFHSIT
SYSIDNT name of the target CICS system, DQM requires that they are the same.

The type of connection can be either MRO or ISC.

Chapter 27. Preparing MQSeries for OS/390 when using CICS 383
Defining DQM requirements

Defining DQM requirements to MQSeries

In order to define your distributed-queuing requirements, you need to:
v Define MQSeries programs and data sets as CICS resources
v Define the channel definitions
v Define the CKMQ transient data queue
v Define MQSeries queues triggers and processes
v Define CICS resources used by distributed queuing
v Define access security

See the MQSeries for OS/390 System Management Guide for information about these
tasks.

Defining MQSeries objects

Use the MQSeries for OS/390 operations and control panels, or one of the other
MQSeries for OS/390 command input methods, to define MQSeries for OS/390
objects. Refer to the MQSeries Command Reference book for details of defining
objects.

You define:
v A local queue with the usage of (XMITQ) for each sending message channel.
v Remote queue definitions.
A remote queue object has three distinct uses, depending upon the way the
name and content are specified:
– Remote queue definition
– Queue manager alias definition
– Reply-to queue alias definition

This is shown in Table 2 on page 37.

v A process naming the MCA sender transaction, CKSG, as the application to be
triggered by messages appearing on the transmission queue. The process
definition parameter, USERDATA, must contain the name of the channel to be
started by this process. See “How to trigger channels” on page 358.

The supplied sample CSQ4DISQ gives examples of the necessary definitions.

Multiple message channels per transmission queue

It is possible to define more than one channel per transmission queue, but only
one of these channels needs to be active at any one time. The provision of multiple
channels is recommended to provide alternative routes between queue managers
for traffic balancing and link failure recovery.

You may start more than one channel to serve a transmission queue to increase
message throughput, but when doing so, ensure that the queue has a SHARE
attribute, and that there is not a need for sequential delivery of messages.

384 MQSeries Intercommunication

 Channel operation considerations

Channel operation considerations

Channels are designed to be active only when there is work for them to process.
This mechanism allows for conservation of limited system resources such as active
transactions and LU 6.2 sessions while at the same time delivering messages in a
timely fashion determined by the application. The mechanisms which are used to
determine when a channel is started and stopped are triggering and the disconnect
interval respectively.

This mechanism works well unless the operator wishes to terminate a channel
before the disconnect time interval expires. This can occur in the following
situations:
v System quiesce
v Resource conservation
v Unilateral action at one end of a channel

In these cases it is necessary to stop the channel using the STOP option from the
Message Channel List panel of the CKMC transaction. For information about what
happens when a channel is stopped in this way, and how to restart the channel,
see “Stopping and quiescing channels (not MQSeries for Windows)” on page 67.

Chapter 27. Preparing MQSeries for OS/390 when using CICS 385
DQM in MQSeries for OS/390

386 MQSeries Intercommunication

Chapter 28. Message channel planning example for OS/390
using CICS
This chapter provides a detailed example of how to connect queue managers
together to send messages from one to the other. The example gives you a
step-by-step implementation of a unidirectional interconnection of two queue
managers.

Figure 80 illustrates the interaction between all the system components used for
transferring messages between queue managers.

Application Queue manager 'QM1' Queue manager 'QM2' Application

Payroll Queue remote 'Payrollr' Payroll

reporter process

Queue transmission 'QM2' QM1.2.QM2.CHANNEL Queue local 'QM1_payroll'

Queue local 'Init_queue' CKTI

Trigger
monitor

Figure 80. Connecting two queue managers in MQSeries for OS/390 using CICS

In the following list, the numbered items refer to the boxed index numbers in the
figure.
1. The “Payroll reporter” application connects to queue manager “QM1”, opens
a queue called “Payrollr”, and places messages on the queue.
2. The attributes of Payrollr in queue manager QM1 are:

QUEUE Payrollr
TYPE QREMOTE
DESCR PAYROLL QUEUE ON QM2 QUEUE MANAGER
PUT ENABLED
DEFPRTY 0
DEFPSIST YES
RNAME QM1_payroll
RQMNAME QM2

From this information, the local queue manager QM1 determines that
messages for this queue have to be transmitted to a remote queue manager
QM2.

© Copyright IBM Corp. 1993, 2000 387

Planning example for OS/390 using CICS
For QM1, QM2 is just a transmission queue on which messages have to be
placed. A transmission queue is a local queue with its usage parameter set to
XMITQ.
3. The attributes of the transmission queue, QM2, in queue manager QM1 are:

QUEUE QM2
TYPE LOCAL
DESCR QUEUE MANAGER QM2 TRANSMISSION QUEUE
PUT ENABLED
DEFPRTY 0
DEFPSIST YES
OPPROCS 0
IPPROCS 0
CURDEPTH 0
MAXDEPTH 100000
PROCESS QM2.PROCESS
TRIGGER
MAXMSGL 4194304
BOTHRESH 0
BOQNAME
STGCLASS DEFAULT
INITQ Init_queue
USAGE XMITQ
SHARE
DEFSOPT EXCL
MSGDLVSQ FIFO
RETINTVL 0
TRIGTYPE FIRST
TRIGDPTH 1
TRIGMPRI 0
TRIGGERDATA 0
DEFTYPE PREDEFINED
NOHARDENBO
GET ENABLED

Messages that the application puts to Payrollr are actually placed on the
transmission queue QM2.
4. In this example, assume that the payroll message is the first message to be
placed on the empty transmission queue, and because of the triggering
attributes of the transmission queue, the queue manager determines that a
trigger message is to be issued.
The transmission queue definition refers to an initiation queue called
Init_queue, and the queue manager places a trigger message on this queue.
The transmission queue definition also refers to the trigger process definition,
and information from this definition is included in the trigger message.

388 MQSeries Intercommunication

 Planning example for OS/390 using CICS
The definition of the process in queue manager QM1 is:

PROCESS QM2.PROCESS
DESCR PROCESS DEFINITION - TO TRIGGER CHANNEL
QM1.2.QM2.CHANNEL
APPLTYPE CICS
APPLICID CKSG
USERDATA QM1.2.QM2.CHANNEL
ENVRDATA environment information

The result of this trigger processing is that a trigger message is placed on the
initiation queue, Init_queue.
5. If you experience trigger messages failing to appear when expected, refer to
the MQSeries Application Programming Guide.
6. The CKTI transaction is a long-running task that monitors the initiation queue,
Init_queue. CKTI processes the trigger message, an MQTM structure, to find
that it must start CKSG. CKSG is the CICS name of the sender channel MCA
transaction.
7. CKTI starts CKSG, passing the MQTM structure. The CKSG transaction starts
processing, receives the MQTM structure, and extracts the name of the
channel.
8. The channel name is used by CKSG to get the channel definition from the
channel definition file on QM1. The DQM display settings panel of the
channel in QM1.2.QM2.CHANNEL, is:

Channel Help
------------------------------------------------------------------------------
MCATTB1 QM1.2.QM2.CHANNEL - Settings CICSTQM2

More: +
Channel type . . . . . . : SENDER

Target system id . . . . :
Transmission queue name . : QM2
Batch size . . . . . . . : 0100
Sequence number wrap . . : 9999999
Max message size . . . . : 0031000
Max transmission . . . . : 32000
Disconnect interval . . . : 0015
Transaction id . . . . . : CKSG
Connection name . . . . . : QM2C
CICS profile name . . . . :
LU 6.2 TP name . . . . . : CKRC

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 81. Sender settings (1)

Chapter 28. Message channel planning example for OS/390 using CICS 389
Planning example for OS/390 using CICS

Channel Help
------------------------------------------------------------------------------
MCATTC1 QM1.2.QM2.CHANNEL - Settings CICSTQM2

More: -
Channel type . . . . . . : SENDER

Sequential delivery . . . : 0 (0=No or 1=Yes)

Retry
Count . . . . . . . . . : 005
Fast interval . . . . . : 005
Slow interval . . . . . : 030

Exit routines
Security . . . . . . . :
Message . . . . . . . . :
Send . . . . . . . . . :
Receive . . . . . . . :

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 82. Sender settings (2)

The channel definition shows that CKSG must allocate a session on the CICS
QM2C connection and invoke the CKRC transaction at the destination CICS
system.
9. The QM2C connection definition provides a communications link to the CICS
system at the remote installation. The definition is as follows:

OBJECT CHARACTERISTICS
CEDA View
Connection : QM2C
Group : QM2CCONN
DEscription : LU 6.2 PARALLEL CONNECTION TO CICSTQM1
CONNECTION IDENTIFIERS
Netname : CICSTQM1
INDsys :
REMOTE ATTRIBUTES
REMOTESystem :
REMOTEName :
CONNECTION PROPERTIES
ACcessmethod : Vtam Vtam | IRc | INdirect | Xm
Protocol : Appc Appc | Lu61
SInglesess : No No | Yes
DAtastream : User User | 3270 | SCs | STrfield | Lms
RECordformat : U U | Vb
OPERATIONAL PROPERTIES
+ AUtoconnect : Yes No | Yes | All

APPLID=CICSTQM2

PF 1 HELP 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Figure 83. Connection definition (1)

390 MQSeries Intercommunication

 Planning example for OS/390 using CICS

OBJECT CHARACTERISTICS
CEDA VIew
+ INService : Yes Yes | No
SECURITY
SEcurityname :
ATtachsec : Local Local | Identify | Verify | Persistent
| Mixidpe
BINDPassword : PASSWORD NOT SPECIFIED
BINDSecurity : No No | Yes

APPLID=CICSTQM2

PF 1 HELP 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Figure 84. Connection definition (2)

10. The connection definition on the remote installation CICS system is called
QM1C, and is defined as follows:

OBJECT CHARACTERISTICS
CEDA View
Connection : QM1C
Group : QM1CCONN
DEscription : LU 6.2 PARALLEL CONNECTION TO CICSTQM2
CONNECTION IDENTIFIERS
Netname : CICSTQM2
INDsys :
REMOTE ATTRIBUTES
REMOTESystem :
REMOTEName :
CONNECTION PROPERTIES
ACcessmethod : Vtam Vtam | IRc | INdirect | Xm
Protocol : Appc Appc | Lu61
SInglesess : No No | Yes
DAtastream : User User | 3270 | SCs | STrfield | Lms
RECordformat : U U | Vb
OPERATIONAL PROPERTIES
+ AUtoconnect : Yes No | Yes | All

APPLID=CICSTQM1

PF 1 HELP 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Figure 85. Connection definition (1)

Chapter 28. Message channel planning example for OS/390 using CICS 391
Planning example for OS/390 using CICS

OBJECT CHARACTERISTICS
CEDA VIew
+ INService : Yes Yes | No
SECURITY
SEcurityname :
ATtachsec : Local Local | Identify | Verify | Persistent
| Mixidpe
BINDPassword : PASSWORD NOT SPECIFIED
BINDSecurity : No No | Yes

APPLID=CICSTQM1

PF 1 HELP 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Figure 86. Connection definition (2)

11. CKRC is started by CICS on the remote system, and is passed the channel
name during the initial data flows.
12. The transaction CKRC reads the definition for the receiver channel
QM1.2.QM2.CHANNEL from the channel definition file, which contains:

Channel Help
------------------------------------------------------------------------------
MCATTB3 QM1.2.QM2.CHANNEL - Settings CICSTQM1

More: +
Channel type . . . . . . : RECEIVER

Target system id . . . . :

Batch size . . . . . . . : 0100

Sequence number wrap . . : 9999999
Max message size . . . . : 0031000
Max transmission . . . . : 32000

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 87. Receiver channel settings (1)

392 MQSeries Intercommunication

 Planning example for OS/390 using CICS

Channel Help
------------------------------------------------------------------------------
MCATTC3 QM1.2.QM2.CHANNEL- Settings CICSTQM1

More: -
Channel type . . . . . . : RECEIVER

Sequential delivery . . . : 0 (0=No or 1=Yes)

Put authority . . . . . . : 1 (1=Process or 2=Context)

Exit routines
Security . . . . . . . :
Message . . . . . . . . :
Send . . . . . . . . . :
Receive . . . . . . . . :

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Figure 88. Receiver channel settings (2)

13. Once the message channel has completed the startup negotiation, the sender
channel passes messages to the receiver channel. The receiver channel takes
the name of the queue manager, queue name and message descriptor from the
transmission header, and issues an MQPUT1 call to put the message on the
local queue, QM1_payroll.
When the batch limit of 100 is reached, or when the transmission queue is
empty, the sender and receiver channels issue a syncpoint to commit the
changes through the queue managers.
14. The commit action by the QM2 queue manager makes the messages available
to the “Payroll process” application.

Chapter 28. Message channel planning example for OS/390 using CICS 393
Planning example for OS/390 using CICS

394 MQSeries Intercommunication

 Chapter 29. Example configuration - IBM MQSeries for OS/390
This chapter gives an example of how to set up communication links from
MQSeries for OS/390 or MVS/ESA to MQSeries products on the following
platforms:
v OS/2
v Windows NT
v AIX
| v Digital UNIX
v HP-UX
v AT&T GIS UNIX7
v Sun Solaris
| v OS/400
v VSE/ESA

(You can also connect any of the following:

OS/390 to OS/390
OS/390 to MVS/ESA
MVS/ESA to MVS/ESA
with or without CICS.)

First it describes the parameters needed for an LU 6.2 connection; then it describes:
v “Establishing an LU 6.2 connection” on page 400
v “Establishing an LU 6.2 connection using CICS” on page 402
v “Establishing a TCP connection” on page 404

Once the connection is established, you need to define some channels to complete
the configuration. This is described in “MQSeries for OS/390 configuration” on
page 405.

See “Chapter 7. Example configuration chapters in this book” on page 97 for

background information about this chapter and how to use it.

Configuration parameters for an LU 6.2 connection

Table 36 on page 396 presents a worksheet listing all the parameters needed to set
up communication from OS/390 to one of the other MQSeries platforms. The
worksheet shows examples of the parameters, which have been tested in a
working environment, and leaves space for you to fill in your own values. An
explanation of the parameter names follows the worksheet. Use the worksheet in
this chapter in conjunction with the worksheet in the chapter for the platform to
which you are connecting.

7. This platform has become NCR UNIX SVR4 MP-RAS, R3.0

© Copyright IBM Corp. 1993, 2000 395

OS/390 and LU 6.2
The steps required to set up an LU 6.2 connection are described in “Establishing an
LU 6.2 connection” on page 400 and “Establishing an LU 6.2 connection using
CICS” on page 402, with numbered cross references to the parameters on the
worksheet.

Configuration worksheet
Use this worksheet to record the values you use for your configuration. Where
numbers appear in the Reference column they indicate that the value must match
that in the appropriate worksheet elsewhere in this book. The examples that follow
in this chapter refer back to the values in the ID column. The entries in the
Parameter Name column are explained in “Explanation of terms” on page 398.
Table 36. Configuration worksheet for OS/390 using LU 6.2
ID Parameter Name Reference Example Used User Value
Definition for local node
«1¬ Command prefix +cpf
«2¬ Network ID NETID
«3¬ Node name MVSPU
«4¬ Local LU name MVSLU
«5¬ Symbolic destination M1
«6¬ Modename #INTER
«7¬ Local Transaction Program name MQSERIES
«8¬ LAN destination address 400074511092
Connection to an OS/2 system without using CICS

The values in this section of the table must match those used in Table 14 on page 138, as indicated.
«9¬ Symbolic destination M2
«10¬ Modename «17¬ #INTER
«11¬ Remote Transaction Program name «8¬ MQSERIES
«12¬ Partner LU name «6¬ OS2LU
Connection to an OS/2 system using CICS

The values in this section of the table must match those used in Table 14 on page 138, as indicated.
«13¬ Connection name OS2
«14¬ Group name EXAMPLE
«15¬ Session name OS2SESS
«16¬ Netname «6¬ OS2LU
Connection to a Windows NT system without using CICS

The values in this section of the table must match those used in Table 16 on page 170, as indicated.
«9¬ Symbolic destination M3
«10¬ Modename «17¬ #INTER
«11¬ Remote Transaction Program name «7¬ MQSERIES
«12¬ Partner LU name «5¬ WINNTLU
«17¬ Remote node ID «4¬ 05D 30F65
Connection to a Windows NT system using CICS

The values in this section of the table must match those used in Table 16 on page 170, as indicated.
«13¬ Connection name WNT
«14¬ Group name EXAMPLE
«15¬ Session name WNTSESS

396 MQSeries Intercommunication

 OS/390 and LU 6.2
Table 36. Configuration worksheet for OS/390 using LU 6.2 (continued)
ID Parameter Name Reference Example Used User Value
«16¬ Netname «6¬ WINNTLU
Connection to an AIX system without using CICS

The values in this section of the table must match those used in Table 20 on page 197, as indicated.
«9¬ Symbolic Destination M4
«10¬ Modename «14¬ #INTER
«11¬ Remote Transaction Program name «6¬ MQSERIES
«12¬ Partner LU name «4¬ AIXLU
Connection to an AIX system using CICS

The values in this section of the table must match those used in Table 20 on page 197, as indicated.
«13¬ Connection name AIX
«14¬ Group name EXAMPLE
«15¬ Session name AIXSESS
«16¬ Netname «4¬ AIXLU
Connection to an HP-UX system without using CICS

The values in this section of the table must match those used in Table 23 on page 219, as indicated.
«9¬ Symbolic Destination M5
«10¬ Modename «6¬ #INTER
«11¬ Remote Transaction Program name «7¬ MQSERIES
«12¬ Partner LU name «5¬ HPUXLU
Connection to an HP-UX system using CICS

The values in this section of the table must match those used in Table 23 on page 219, as indicated.
«13¬ Connection name HPUX
«14¬ Group name EXAMPLE
«15¬ Session name HPUXSESS
«16¬ Netname «5¬ HPUXLU
Connection to an AT&T GIS UNIX system without using CICS

The values in this section of the table must match those used in Table 25 on page 243, as indicated.
«9¬ Symbolic Destination M6
«10¬ Modename «15¬ #INTER
«11¬ Remote Transaction Program name «5¬ MQSERIES
«12¬ Partner LU name «4¬ GISLU
Connection to an AT&T GIS UNIX system using CICS

The values in this section of the table must match those used in Table 25 on page 243, as indicated.
«13¬ Connection name GIS
«14¬ Group name EXAMPLE
«15¬ Session name GISSESS
«16¬ Netname «4¬ GISLU
Connection to a Sun Solaris system without using CICS

The values in this section of the table must match those used in Table 27 on page 257, as indicated.
«9¬ Symbolic destination M7
«10¬ Modename «17¬ #INTER
«11¬ Remote Transaction Program name «8¬ MQSERIES
«12¬ Partner LU name «7¬ SOLARLU

Chapter 29. Example configuration - IBM MQSeries for OS/390 397

OS/390 and LU 6.2
Table 36. Configuration worksheet for OS/390 using LU 6.2 (continued)
ID Parameter Name Reference Example Used User Value
Connection to a Sun Solaris system using CICS

The values in this section of the table must match those used in Table 27 on page 257, as indicated.
«13¬ Connection name SOL
«14¬ Group name EXAMPLE
«15¬ Session name SOLSESS
«16¬ Netname «7¬ SOLARLU
Connection to an AS/400 system without using CICS

The values in this section of the table must match those used in Table 42 on page 460, as indicated.
«9¬ Symbolic Destination M8
«10¬ Modename «17¬ #INTER
«11¬ Remote Transaction Program name «8¬ MQSERIES
«12¬ Partner LU name «3¬ AS400LU
Connection to an AS/400 system using CICS

The values in this section of the table must match those used in Table 42 on page 460, as indicated.
«13¬ Connection name AS4
«14¬ Group name EXAMPLE
«15¬ Session name AS4SESS
«16¬ Netname «3¬ AS400LU
Connection to a VSE/ESA system without using CICS

The values in this section of the table must match those used in Table 44 on page 485, as indicated.
«9¬ Symbolic destination M9
«10¬ Modename #INTER
«11¬ Remote Transaction Program name «4¬ MQ01
«12¬ Partner LU name «3¬ VSELU
Connection to a VSE/ESA system using CICS

The values in this section of the table must match those used in Table 44 on page 485, as indicated.
«13¬ Connection name VSE
«14¬ Group name EXAMPLE
«15¬ Session name VSESESS
«16¬ Netname «3¬ VSELU

Explanation of terms
«1¬ Command prefix
This is the unique command prefix of your MQSeries for OS/390
queue-manager subsystem. The OS/390 systems programmer defines this
at installation time, in SYS1.PARMLIB(IEFSSNss), and will be able to tell
you the value.
«2¬ Network ID
The VTAM startup procedure in your installation is partly customized by
the ATCSTRxx member of the data set referenced by the DDNAME
VTAMLST. The Network ID is the value specified for the NETID parameter
in this member. For Network ID you must specify the name of the NETID

398 MQSeries Intercommunication

 OS/390 and LU 6.2
that owns the MQSeries communications subsystem (MQSeries channel
initiator or CICS for OS/390 as the case may be). Your network
administrator will tell you the value.
«3¬ Node name
VTAM, being a low-entry network node, does not have a Control Point
name for Advanced Peer-to-Peer Networking (APPN) use. It does however
have a system services control point name (SSCPNAME). For node name,
you must specify the name of the SSCP that owns the MQSeries
communications subsystem (MQSeries channel initiator or CICS for
OS/390 as the case may be). This is defined in the same ATCSTRxx
member as the Network ID. Your network administrator will tell you the
value.
«4¬ Local LU name
A logical unit (LU) is software that serves as an interface or translator
between a transaction program and the network. It manages the exchange
of data between transaction programs. The local LU name is the unique
VTAM APPLID of this MQSeries subsystem. Your network administrator
will tell you this value.
«5¬ «9¬ Symbolic destination
This is the name you give to the CPI-C side information profile. You need
a side information entry for each LU 6.2 listener.
«6¬ «10¬ Modename
This is the name given to the set of parameters that control the LU 6.2
conversation. An entry with this name and similar attributes must be
defined at each end of the session. In VTAM, this corresponds to a mode
table entry. You network administrator will assign this to you.
«7¬ «11¬ Transaction Program name
MQSeries applications trying to converse with this queue manager will
specify a symbolic name for the program to be run at the receiving end.
This will have been specified in the TPNAME attribute on the channel
definition at the sender. For simplicity, wherever possible use a transaction
program name of MQSERIES, or in the case of a connection to VSE/ESA,
where the length is limited to 4 bytes, use MQTP.
See Table 30 on page 341 for more information. If the receiving end is
OS/390 using CICS, special values are required.
«8¬ LAN destination address
This is the LAN destination address that your partner nodes will use to
communicate with this host. When you are using a 3745 network
controller, it will be the value specified in the LOCADD parameter for the
line definition to which your partner is physically connected. If your
partner nodes use other devices such as 317X or 6611 devices, the address
will have been set during the customization of those devices. Your network
administrator will tell you this value.
«12¬ Partner LU name
This is the LU name of the MQSeries queue manager on the system with
which you are setting up communication. This value is specified in the
side information entry for the remote partner.
«13¬ Connection name
(CICS only) This is a 4-character name by which each connection will be
individually known in CICS RDO.

Chapter 29. Example configuration - IBM MQSeries for OS/390 399

OS/390 and LU 6.2
«14¬ Group name
(CICS only) You choose your own 8-character name for this value. Your
system may already have a group defined for connections to partner
nodes. Your CICS administrator will give you a value to use.
«15¬ Session name
(CICS only) This is an 8-character name by which each group of sessions
will be individually known. For clarity we use the connection name,
concatenated with ‘SESS’.
«16¬ Netname
(CICS only) This is the LU name of the MQSeries queue manager on the
system with which you are setting up communication.
«17¬ Remote node ID
For a connection to Windows NT, this is the ID of the local node on the
Windows NT system with which you are setting up communication.

Establishing an LU 6.2 connection

To establish an LU 6.2 connection, there are two steps:
1. Define yourself to the network.
2. Define a connection to the partner.

Defining yourself to the network

1. SYS1.PARMLIB(APPCPMxx) contains the startup parameters for APPC. You
must add a line to this file to define the local LU name you intend to use for
the MQSeries LU 6.2 listener. The line you add should take the form
LUADD ACBNAME(mvslu)
NOSCHED
TPDATA(csq.appctp)

Specify values for ACBNAME(«4¬) and TPDATA.

The NOSCHED parameter tells APPC that our new LU will not be using the
LU 6.2 scheduler (ASCH), but has one of its own. TPDATA refers to the
Transaction Program data set in which LU 6.2 stores information about
transaction programs. Again, MQSeries will not use this, but it is required by
the syntax of the LUADD command.
2. Start the APPC subsystem with the command:
START APPC,SUB=MSTR,APPC=xx

where xx is the suffix of the PARMLIB member in which you added the LU in
step 1.

Note: If APPC is already running, it can be refreshed with the command:

SET APPC=xx

The effect of this is cumulative, that is, APPC will not lose its knowledge
of objects already defined to it in this or another PARMLIB member.
3. Add the new LU to a suitable VTAM major node definition. These are typically
in SYS1.VTAMLST. The APPL definition will look similar to the sample shown
in Figure 89 on page 401.

400 MQSeries Intercommunication

 LU 6.2 without CICS
MVSLU APPL ACBNAME=MVSLU, «4¬
APPC=YES,
AUTOSES=0,
DDRAINL=NALLOW,
DLOGMOD=#INTER, «6¬
DMINWNL=10,
DMINWNR=10,
DRESPL=NALLOW,
DSESLIM=60,
LMDENT=19,
MODETAB=MTCICS,
PARSESS=YES,
VERIFY=NONE,
SECACPT=ALREADYV,
SRBEXIT=YES

Figure 89. Channel Initiator APPL definition

4. Activate the major node. This can be done with the command:
V,NET,ACT,majornode
5. Add an entry defining your LU to the CPI-C side information data set. Use the
APPC utility program ATBSDFMU to do this. Sample JCL is in
thlqual.SCSQPROC(CSQ4SIDE) (where thlqual is the target library high-level
qualifier for MQSeries data sets in your installation.)
The entry you add will look like this:
SIADD
DESTNAME(M1) «5¬
MODENAME(#INTER) «6¬
TPNAME(MQSERIES) «7¬
PARTNER_LU(MVSLU) «4¬
6. Create the channel-initiator parameter module for your queue manager. Sample
JCL to do this is in thlqual.SCSQPROC(CSQ4XPRM). You must specify the
local LU («4¬) assigned to your queue manager in the LUNAME= parameter of
the CSQ6CHIP macro.

//SYSIN DD *
CSQ6CHIP ADAPS=8, X
ACTCHL=200, X
CURRCHL=200, X
DISPS=5, X
LUNAME=MVSLU, X
LU62CHL=200, X
TCPCHL=200, X
TCPKEEP=NO, X
TCPNAME=TCPIP, X
TCPTYPE=OESOCKET, X
TRAXSTR=YES, X
TRAXTBL=2
END
/*

Figure 90. Channel Initiator initialization parameters

7. Modify the job to assemble and link-edit the tailored version of the initiator
macro to produce a new load module.
8. Submit the job and verify that it completes successfully.

Chapter 29. Example configuration - IBM MQSeries for OS/390 401

LU 6.2 without CICS
9. Put the new initialization-parameters module in an APF-authorized user library.
Include this library in the STEPLIB concatenation for the channel initiator’s
started-task procedure, ensuring that it precedes the library
thlqual.SCSQAUTH.

Defining a connection to a partner

Note: This example is for a connection to an OS/2 system but the task is the same
for other platforms.

Add an entry to the CPI-C side information data set to define the connection.
Sample JCL to do this is in thlqual.SCSQPROC(CSQ4SIDE).

The entry you add will look like this:

SIADD
DESTNAME(M2) «9¬
MODENAME(#INTER) «10¬
TPNAME(MQSERIES) «11¬
PARTNER_LU(OS2LU) «12¬

What next?
The connection is now established. You are ready to complete the configuration.
Go to “MQSeries for OS/390 configuration” on page 405.

Establishing an LU 6.2 connection using CICS

Note: This example is for a connection to an OS/2 system. The steps are the same
whatever platform you are using; change the values as appropriate.

Defining a connection
1. At a CICS command line type:
CEDA DEF CONN(connection name) «13¬
GROUP(group name) «14¬

For example:
CEDA DEF CONN(OS2) GROUP(EXAMPLE)
2. Press Enter to define the connection to CICS.
A panel is displayed, as shown below.

402 MQSeries Intercommunication

 LU 6.2 with CICS

DEF CONN(OS2) GROUP(EXAMPLE)

OVERTYPE TO MODIFY CICS RELEASE = 0520
CEDA DEFine
Connection : OS2
Group : EXAMPLE
DEscription ==>
CONNECTION IDENTIFIERS
Netname ==> OS2LU
INDsys ==>
REMOTE ATTRIBUTES
REMOTESystem ==>
REMOTEName ==>
CONNECTION PROPERTIES
ACcessmethod ==> Vtam Vtam | IRc | INdirect | Xm
Protocol ==> Appc Appc | Lu61
SInglesess ==> No No | Yes
DAtastream ==> User User | 3270 | SCs | STrfield | Lms
RECordformat ==> U U | Vb
OPERATIONAL PROPERTIES
+ AUtoconnect ==> No No | Yes | All
I New group EXAMPLE created.
APPLID=MVSLU

DEFINE SUCCESSFUL TIME: 16.49.30 DATE: 95.065

PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

3. On this panel, change the Netname field in the CONNECTION IDENTIFIERS

section to be the LU name («16¬) of the target system. In the CONNECTION
PROPERTIES section set the ACcessmethod field to Vtam and the Protocol to
Appc.
4. Press Enter to make the change.

Defining the sessions

1. At a CICS command line type:
CEDA DEF SESS(session name) «15¬
GROUP(group name) «14¬

For example:
CEDA DEF SESS(OS2SESS) GROUP(EXAMPLE)
2. Press Enter to define the group of sessions for the connection.
A panel is displayed, as shown below.

Chapter 29. Example configuration - IBM MQSeries for OS/390 403

LU 6.2 with CICS

DEF SESS(OS2SESS) GROUP(EXAMPLE)

OVERTYPE TO MODIFY CICS RELEASE = 0520
CEDA DEFine
Sessions ==> OS2SESS
Group ==> EXAMPLE
DEscription ==>
SESSION IDENTIFIERS
Connection ==> OS2
SESSName ==>
NETnameq ==>
MOdename ==> #INTER
SESSION PROPERTIES
Protocol ==> Appc Appc | Lu61
MAximum ==> 008 , 004 0-999
RECEIVEPfx ==>
RECEIVECount ==> 1-999
SENDPfx ==>
SENDCount ==> 1-999
SENDSize ==> 04096 1-30720
+ RECEIVESize ==> 04096 1-30720
S CONNECTION MUST BE SPECIFIED.
APPLID=MVSLU

PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

3. On this panel, in the SESSION IDENTIFIERS section, specify the Connection

name («13¬) in the Connection field and set the MOdename to #INTER. In the
SESSION PROPERTIES section set the Protocol to Appc and the MAximum
field to 008 , 004.
4. Press Enter to make the change.

Installing the new group definition

To install the new group definition, type:
CEDA INS GROUP(group name) «14¬

at a CICS command line, and press Enter.

Note: If this connection group is already in use, severe errors will be reported. If
this occurs you must take the existing connections out of service, retry the
group installation, and then set the connections in service again using the
following commands:
1. CEMT I CONN
2. CEMT S CONN(*) OUTS
3. CEDA INS GROUP(Group name)
4. CEMT S CONN(*) INS

What next?
The connection is now established. You are ready to complete the configuration.
Go to “MQSeries for OS/390 configuration” on page 405.

Establishing a TCP connection

Edit the channel initiator initialization parameters. Sample JCL to do this is in
thlqual.SCSQPROC(CSQ4XPRM). You must add the name of the TCP address
space to the TCPNAME= parameter.

404 MQSeries Intercommunication

 OS/390 and TCP
//SYSIN DD *
CSQ6CHIP ADAPS=8, X
ACTCHL=200, X
CURRCHL=200, X
DISPS=5, X
LUNAME=MVSLU, X
LU62CHL=200, X
TCPCHL=200, X
TCPKEEP=NO, X
TCPNAME=TCPIP, X
TCPTYPE=OESOCKET, X
TRAXSTR=YES, X
TRAXTBL=2
END
/*

Figure 91. Channel Initiator initialization parameters

What next?
The TCP connection is now established. You are ready to complete the
configuration. Go to “MQSeries for OS/390 configuration”.

MQSeries for OS/390 configuration

If you are not using CICS:
1. Start the channel initiator using the command:
+cpf START CHINIT PARM(xparms) «1¬

where xparms is the name of the channel-initiator parameter module that you
created.
2. Start an LU 6.2 listener using the command:
+cpf START LSTR LUNAME(M1) TRPTYPE(LU62)

The LUNAME of M1 refers to the symbolic name you gave your LU («5¬). You
must specify TRPTYPE(LU62), otherwise the listener will assume you want
TCP.
3. Start a TCP listener using the command:
+cpf START LSTR

If you wish to use a port other than 1414 (the default MQSeries port), use the
command:
+cpf START LSTR PORT(1555)

MQSeries channels will not initialize successfully if the channel negotiation detects
that the message sequence number is different at each end. You may need to reset
this manually.

Note that the OS/390 product with CICS uses the message sequence number of the
message it last sent, while all other platforms use the sequence number of the next
message to be sent. This means you must reset the message sequence number to 0
at the OS/390 (with CICS) end of a channel and to 1 everywhere else.

Channel configuration
The following sections detail the configuration to be performed on the OS/390
queue manager to implement the channel described in Figure 32 on page 97.

Chapter 29. Example configuration - IBM MQSeries for OS/390 405

OS/390 configuration
Examples are given for connecting MQSeries for OS/390 and MQSeries for OS/2
Warp. If you wish to connect to another MQSeries product use the appropriate set
of values from the table in place of those for OS/2.

Note: The words in bold are user-specified and reflect the names of MQSeries
objects used throughout these examples. If you change the names used here,
ensure that you also change the other references made to these objects
throughout this book. All others are keywords and should be entered as
shown.
Table 37. Configuration worksheet for MQSeries for OS/390
ID Parameter Name Reference Example Used User Value
Definition for local node
«A¬ Queue Manager Name MVS
«B¬ Local queue name MVS.LOCALQ
Connection to MQSeries for OS/2 Warp

The values in this section of the table must match those used in Table 15 on page 164, as indicated.
«C¬ Remote queue manager name «A¬ OS2
«D¬ Remote queue name OS2.REMOTEQ
«E¬ Queue name at remote system «B¬ OS2.LOCALQ
«F¬ Transmission queue name OS2
«G¬ Sender (LU 6.2) channel name MVS.OS2.SNA
«H¬ Sender (TCP) channel name MVS.OS2.TCP
«I¬ Receiver (LU 6.2) channel name «G¬ OS2.MVS.SNA
«J¬ Receiver (TCP) channel name «H¬ OS2.MVS.TCP
«K¬ Sender (LU 6.2 using CICS) channel name MVS.OS2.CICS
«L¬ Receiver (LU 6.2 using CICS) channel name OS2.MVS.CICS
Connection to MQSeries for Windows NT

The values in this section of the table must match those used in Table 17 on page 185, as indicated.
«C¬ Remote queue manager name «A¬ WINNT
«D¬ Remote queue name WINNT.REMOTEQ
«E¬ Queue name at remote system «B¬ WINNT.LOCALQ
«F¬ Transmission queue name WINNT
«G¬ Sender (LU 6.2) channel name MVS.WINNT.SNA
«H¬ Sender (TCP) channel name MVS.WINNT.TCP
«I¬ Receiver (LU 6.2) channel name «G¬ WINNT.MVS.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ WINNT.MVS.TCP
«K¬ Sender (LU 6.2 using CICS) channel name MVS.WINNT.CICS
«L¬ Receiver (LU 6.2 using CICS) channel name WINNT.MVS.CICS
Connection to MQSeries for AIX

The values in this section of the table must match those used in Table 21 on page 211, as indicated.
«C¬ Remote queue manager name AIX
«D¬ Remote queue name AIX.REMOTEQ
«E¬ Queue name at remote system «B¬ AIX.LOCALQ
«F¬ Transmission queue name AIX
«G¬ Sender (LU 6.2) channel name MVS.AIX.SNA
«H¬ Sender (TCP/IP) channel name MVS.AIX.TCP
«I¬ Receiver (LU 6.2) channel name «G¬ AIX.MVS.SNA

406 MQSeries Intercommunication

 OS/390 configuration
Table 37. Configuration worksheet for MQSeries for OS/390 (continued)
ID Parameter Name Reference Example Used User Value
«J¬ Receiver (TCP/IP) channel name «H¬ AIX.MVS.TCP
«K¬ Sender (LU 6.2 using CICS) channel name MVS.AIX.CICS
«L¬ Receiver (LU 6.2 using CICS) channel name AIX.MVS.CICS
| Connection to MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| The values in this section of the table must match those used in Table 22 on page 216, as indicated.
| «C¬ Remote queue manager name DECUX
| «D¬ Remote queue name DECUX.REMOTEQ
| «E¬ Queue name at remote system «B¬ DECUX.LOCALQ
| «F¬ Transmission queue name DECUX
| «H¬ Sender (TCP) channel name DECUX.MVS.TCP
| «J¬ Receiver (TCP) channel name «H¬ MVS.DECUX.TCP
Connection to MQSeries for HP-UX

The values in this section of the table must match those used in Table 24 on page 239, as indicated.
«C¬ Remote queue manager name HPUX
«D¬ Remote queue name HPUX.REMOTEQ
«E¬ Queue name at remote system «B¬ HPUX.LOCALQ
«F¬ Transmission queue name HPUX
«G¬ Sender (LU 6.2) channel name MVS.HPUX.SNA
«H¬ Sender (TCP) channel name MVS.HPUX.TCP
«I¬ Receiver (LU 6.2) channel name «G¬ HPUX.MVS.SNA
«J¬ Receiver (TCP) channel name «H¬ HPUX.MVS.TCP
«K¬ Sender (LU 6.2 using CICS) channel name MVS.HPUX.CICS
«L¬ Receiver (LU 6.2 using CICS) channel name HPUX.MVS.CICS
Connection to MQSeries for AT&T GIS UNIX

The values in this section of the table must match those used in Table 26 on page 253, as indicated.
«C¬ Remote queue manager name GIS
«D¬ Remote queue name GIS.REMOTEQ
«E¬ Queue name at remote system «B¬ GIS.LOCALQ
«F¬ Transmission queue name GIS
«G¬ Sender (LU 6.2) channel name MVS.GIS.SNA
«H¬ Sender (TCP) channel name MVS.GIS.TCP
«I¬ Receiver (LU 6.2) channel name «G¬ GIS.MVS.SNA
«J¬ Receiver (TCP) channel name «H¬ GIS.MVS.TCP
«K¬ Sender (LU 6.2 using CICS) channel name MVS.GIS.CICS
«L¬ Receiver (LU 6.2 using CICS) channel name GIS.MVS.CICS
Connection to MQSeries for Sun Solaris

The values in this section of the table must match those used in Table 28 on page 272, as indicated.
«C¬ Remote queue manager name SOLARIS
«D¬ Remote queue name SOLARIS.REMOTEQ
«E¬ Queue name at remote system «B¬ SOLARIS.LOCALQ
«F¬ Transmission queue name SOLARIS
«G¬ Sender (LU 6.2) channel name MVS.SOLARIS.SNA
«H¬ Sender (TCP) channel name MVS.SOLARIS.TCP
«I¬ Receiver (LU 6.2) channel name «G¬ SOLARIS.MVS.SNA

Chapter 29. Example configuration - IBM MQSeries for OS/390 407

 OS/390 configuration
Table 37. Configuration worksheet for MQSeries for OS/390 (continued)
ID Parameter Name Reference Example Used User Value
«J¬ Receiver (TCP/IP) channel name «H¬ SOLARIS.MVS.TCP
| Connection to MQSeries for AS/400

| The values in this section of the table must match those used in Table 43 on page 472, as indicated.
| «C¬ Remote queue manager name AS400
| «D¬ Remote queue name AS400.REMOTEQ
| «E¬ Queue name at remote system «B¬ AS400.LOCALQ
| «F¬ Transmission queue name AS400
| «G¬ Sender (LU 6.2) channel name MVS.AS400.SNA
| «H¬ Sender (TCP/IP) channel name MVS.AS400.TCP
| «I¬ Receiver (LU 6.2) channel name «G¬ AS400.MVS.SNA
| «J¬ Receiver (TCP/IP) channel name «H¬ AS400.MVS.TCP
| «K¬ Sender (LU 6.2 using CICS) channel name MVS.AS400.CICS
| «L¬ Receiver (LU 6.2 using CICS) channel name AS400.MVS.CICS
Connection to MQSeries for VSE/ESA

The values in this section of the table must match those used in Table 45 on page 490, as indicated.
«C¬ Remote queue manager name VSE
«D¬ Remote queue name VSE.REMOTEQ
«E¬ Queue name at remote system «B¬ VSE.LOCALQ
«F¬ Transmission queue name VSE
«G¬ Sender channel name MVS.VSE.SNA
«I¬ Receiver channel name «G¬ VSE.MVS.SNA

MQSeries for OS/390 sender-channel definitions using non-CICS

LU 6.2
Local Queue
Object type : QLOCAL
Name : OS2 «F¬
Usage : X (XmitQ)

Remote Queue
Object type : QREMOTE
Name : OS2.REMOTEQ «D¬
Name on remote system : OS2.LOCALQ «E¬
Remote system name : OS2 «C¬
Transmission queue : OS2 «F¬

Sender Channel
Channel name : MVS.OS2.SNA «G¬
Transport type : L (LU6.2)
Transmission queue name : OS2 «F¬
Connection name : M2 «9¬

MQSeries for OS/390 receiver-channel definitions using

non-CICS LU 6.2
Local Queue
Object type : QLOCAL
Name : MVS.LOCALQ «B¬
Usage : N (Normal)

Receiver Channel
Channel name : OS2.MVS.SNA «I¬

408 MQSeries Intercommunication

 OS/390 configuration
MQSeries for OS/390 sender-channel definitions using TCP
Local Queue
Object type : QLOCAL
Name : OS2 «F¬
Usage : X (XmitQ)

Remote Queue
Object type : QREMOTE
Name : OS2.REMOTEQ «D¬
Name on remote system : OS2.LOCALQ «E¬
Remote system name : OS2 «C¬
Transmission queue : OS2 «F¬

Sender Channel
Channel name : MVS.OS2.TCP «H¬
Transport type : T (TCP)
Transmission queue name : OS2 «F¬
Connection name : os2.tcpip.hostname

MQSeries for OS/390 receiver-channel definitions using TCP

Local Queue
Object type : QLOCAL
Name : MVS.LOCALQ «B¬
Usage : N (Normal)

Receiver Channel
Channel name : OS2.MVS.TCP «J¬

MQSeries for OS/390 sender-channel definitions using CICS

Local Queue
Object type : QLOCAL
Name : OS2 «F¬
Usage : X (XmitQ)

Remote Queue
Object type : QREMOTE
Name : OS2.REMOTEQ «D¬
Name on remote system : OS2.LOCALQ «E¬
Remote system name : OS2 «C¬
Transmission queue : OS2 «F¬

Sender Channel
Channel name : MVS.OS2.CICS «K¬
Channel type : 1 (Sender)
Target system id : <blank>
Transmission queue name : OS2 «F¬
Transaction id : CKSG
Connection name : OS2 «13¬
LU62 TP name : MQSERIES

MQSeries for OS/390 receiver-channel definitions using CICS

Local Queue
Object type : QLOCAL
Name : MVS.LOCALQ «B¬
Usage : N (Normal)
Receiver Channel
Channel name : OS2.MVS.CICS «L¬
Channel type : 3 (Receiver)
Target system id : <blank>

Defining a local queue

1. From ISPF, access the MQSeries main menu.

Chapter 29. Example configuration - IBM MQSeries for OS/390 409

OS/390 configuration

IBM MQSeries for OS/390 - Main Menu

Complete fields. Then press Enter.

Action . . . . . . . . 1 1. Display 5. Perform

2. Define 6. Start
3. Alter 7. Stop
4. Delete

Object type . . . . . QLOCAL +

Name . . . . . . . . . MVS.LOCALQ
Like . . . . . . . . . ________________________________________________

Connect to queue
manager . . . . . . : MQ25
Target queue manager : MQ25
Response wait time . : 10 seconds

(C) Copyright IBM Corporation 1993,1999. All rights reserved.

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F4=Prompt F6=QueueMgr F9=Swap
F10=Messages F12=Cancel

2. Specify an Action of 2, enter an Object type of QLOCAL, and specify a Name for
the queue.
3. Press Enter.
The first Define a Local Queue panel is displayed. There are several panels in
all.
4. Use F7 and F8 to move backwards and forwards through the panels of
attributes and set each attribute as required.
Specifically, you should check the values for Usage and Trigger type.

Define a Local Queue

Complete fields, then press F8 for further fields, or Enter to define queue.

More: +

Queue name . . . . . . . . . MVS.LOCALQ

Description . . . . . . . . . ________________________________
________________________________

Put enabled . . . . . . . . . Y Y=Yes,N=No

Get enabled . . . . . . . . . Y Y=Yes,N=No
Usage . . . . . . . . . . . . N N=Normal,X=XmitQ
Storage class . . . . . . . . DEFAULT

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

410 MQSeries Intercommunication

 OS/390 configuration

Define a Local Queue

Press F7 or F8 to see other fields, or Enter to define queue.

More: - +

Default persistence . . . . . N Y=Yes,N=No

Default priority . . . . . . 0 0 - 9
Message delivery sequence . . P P=Priority,F=FIFO
Permit shared access . . . . N Y=Yes,N=No
Default share option . . . . E E=Exclusive,S=Shared
Index type . . . . . . . . . N N=None,M=MsgId,C=CorrelId,T=MsgToken
Maximum queue depth . . . . . 999999999 0 - 999999999
Maximum message length . . . 4194304 0 - 4194304
Retention interval . . . . . 999999999 0 - 999999999 hours

Cluster name . . . . . . . . ________________________________________________

Cluster namelist name . . . . ________________________________________________
Default bind . . . . . . . . O O=Open,N=Notfixed

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Define a Local Queue

Press F7 or F8 to see other fields, or Enter to define queue.

More: - +

Trigger Definition

Trigger type . . . . . . . . F F=First,E=Every,D=Depth,N=None

Trigger set . . . . . . .
N Y=Yes,N=No
Trigger message priority .
0 0 - 9
Trigger depth . . . . . 1 . 1 - 999999999
Trigger data . . . . . . .
________________________________
________________________________
Process name . . . . . . . ________________________________________________
Initiation queue . . . . . ________________________________________________

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Chapter 29. Example configuration - IBM MQSeries for OS/390 411

OS/390 configuration

Define a Local Queue

Press F7 or F8 to see other fields, or Enter to define queue.

More: - +

Event Control

Queue full . . . . . . . . E E=Enabled,D=Disabled

Upper queue depth . . . . D E=Enabled,D=Disabled

Threshold . . . . . . . . 80 0 - 100 %

Lower queue depth . . . . D E=Enabled,D=Disabled

Threshold . . . . . . . . 40 0 - 100 %

Service interval . . . . . N H=High,O=OK,N=None

Interval . . . . . . . . . 999999999 0 - 999999999 milliseconds

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Define a Local Queue

Press F7 to see previous fields, or Enter to define queue.

More: -

Backout Reporting

Backout threshold . . . . 0 0=No backout reporting

Harden backout counter . . N Y=Yes,N=No

Backout requeue name . . . ________________________________________________

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Defining a remote queue

1. From ISPF, access the MQSeries main menu.
2. Specify an Action of 2, enter an Object type of QREMOTE, and specify a Name
for the queue.
3. Press Enter. The Define a Remote Queue panels are displayed.

412 MQSeries Intercommunication

 OS/390 configuration

Define a Remote Queue

Complete fields, then press F8 for further fields, or Enter to define queue.

More: +

Queue name . . . . . . . . . OS2.REMOTEQ

Description . . . . . . . . . ________________________________
________________________________

Put enabled . . . . . . . . . Y Y=Yes,N=No

Default persistence . . . . . N Y=Yes,N=No
Default priority . . . . . . 0 0 - 9
Remote name . . . . . . . . . ________________________________________________
Remote queue manager . . . . ________________________________________________
Transmission queue . . . . . ________________________________________________

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Define a Remote Queue

Press F7 to see previous fields, or Enter to define queue.

More: -

Cluster name . . . . . . . . ________________________________________________

Cluster namelist name . . . . ________________________________________________
Default bind . . . . . . . . O O=Open,N=Notfixed

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

4. Set each parameter as required. Specifically, you should set the values for
Remote name, Remote queue manager, and Transmission queue.

Defining a sender channel when not using CICS

1. From ISPF, access the MQSeries main menu.
2. Specify an Action of 2, enter an Object type of CHLSENDER, and specify a Name
for the channel.
3. Press Enter.
The first Define a Sender Channel panel is displayed. There are three panels in
all.
4. Complete the parameter fields as indicated. In particular, specify the fields
Transport type, Connection name(«9¬), and Transmission queue name.

Chapter 29. Example configuration - IBM MQSeries for OS/390 413

OS/390 configuration

Define a Sender Channel

Complete fields, then press F8 for further fields, or Enter to define channel.

More: +

Channel name . . . . . . . . MVS.OS2.SNA

Description . . . . . . . . . ________________________________
________________________________

Transport type . . . . . . . L L=LU6.2,T=TCP

Connection name . . . . . . . ________________________________________________
Transmission queue . . . . . ________________________________________________
LU6.2 mode name . . . . . . . ________________________________________________
LU6.2 TP name . . . . . . . . ________________________________________________

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Define a Sender Channel

Press F7 or F8 to see other fields, or Enter to define channel.

More: - +

MCA user ID . . . . . . . . . ____________

Nonpersistent messages . . . F F=Fast,N=Normal

Maximum message length . . . 4194304 0 - 4194304
Batch size . . . . . . . . . 50 1 - 9999
Sequence number wrap . . . . 999999999 100 - 999999999
Heartbeat interval . . . . . 300 0 - 999999 seconds

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

414 MQSeries Intercommunication

 OS/390 configuration

Define a Sender Channel

Press F7 or F8 to see other fields, or Enter to define channel.

More: - +

Disconnect interval . . . . . 6000 0 - 999999 seconds

Batch interval . . . . . . . 0 0 - 999999999 milliseconds
Short retry interval . . . . 60 0 - 999999999 seconds
Short retry count . . . . . . 10 0 - 999999999
Long retry interval . . . . . 1200 0 - 999999999 seconds
Long retry count . . . . . . 999999999 0 - 999999999

Conversion by sender . . . . N Y=Yes,N=No

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Define a Sender Channel

Press F7 to see previous fields, or Enter to define channel.

More: -

Security exit name . . . . . ________

User data . . . . . . . . ________________________________

Send exit name . . . . . . . ________

User data . . . . . . . . ________________________________

Receive exit name . . . . . . ________

User data . . . . . . . . ________________________________

Message exit name . . . . . . ________

User data . . . . . . . . ________________________________

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Defining a receiver channel when not using CICS

1. From ISPF, access the MQSeries main menu.
2. Specify an Action of 2, an Object type of CHLRECEIVER, and specify a Name for
the channel.
3. Press Enter.
The first Define a Receiver Channel panel is displayed. There are two panels in
all. Set the parameter values as indicated.

Chapter 29. Example configuration - IBM MQSeries for OS/390 415

OS/390 configuration

Define a Receiver Channel

Complete fields, then press F8 for further fields, or Enter to define channel.

More: +

Channel name . . . . . . . . OS2.MVS.SNA

Description . . . . . . . . . ________________________________
________________________________

Put authority . . . . . . . . D D=Default,C=Context,M=MCAuser

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Define a Receiver Channel

Press F7 or F8 to see other fields, or Enter to define channel.

More: - +

MCA user ID . . . . . . . . . ____________

Nonpersistent messages . . . F F=Fast,N=Normal

Maximum message length . . . 4194304 0 - 4194304
Batch size . . . . . . . . . 50 1 - 9999
Sequence number wrap . . . . 999999999 100 - 999999999
Heartbeat interval . . . . . 300 0 - 999999 seconds

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

416 MQSeries Intercommunication

 OS/390 configuration

Define a Receiver Channel

Press F7 to see previous fields, or Enter to define channel.

More: -

Security exit name . . . . . ________

User data . . . . . . . . ________________________________

Send exit name . . . . . . . ________

User data . . . . . . . . ________________________________

Receive exit name . . . . . . ________

User data . . . . . . . . ________________________________

Message exit name . . . . . . ________

User data . . . . . . . . ________________________________

Command ===> __________________________________________________________________

F1=Help F2=Split F3=Exit F7=Bkwd F8=Fwd F9=Swap
F10=Messages F12=Cancel

Defining a sender channel using CICS

1. Run the CICS transaction CKMC. Select Edit and then Create. A pop-up
window appears.
2. Specify a Channel name and a Channel type.
3. Press Enter.
The Settings panel, which spans two screens, is displayed.
4. Complete the parameter fields as indicated. In particular, specify the
Transmission queue name, Connection name, and LU62 TP name. Allow the
other fields to default.

Channel Help
------------------------------------------------------------------------------
MCATTB1 MVS.OS2.CICS - Settings MVSLU

More: +
Channel type . . . . . . : SENDER

Target system id . . . . :
Transmission queue name . : OS2
Batch size . . . . . . . : 0001
Sequence number wrap . . : 0999999999
Max message size . . . . : 0032000
Max transmission . . . . : 32000
Disconnect interval . . . : 0001
Transaction id . . . . . : CKSG
Connection name . . . . . : <CICS connection to target, defined in CEDA>
CICS profile name . . . . :
LU62 TP name . . . . . . : MQSERIES

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Chapter 29. Example configuration - IBM MQSeries for OS/390 417

OS/390 configuration

Channel Help
------------------------------------------------------------------------------
MCATTC1 MVS.OS2.CICS - Settings MVSLU

More: -
Channel type . . . . . . : SENDER

Sequential delivery . . . : 0 (0=No or 1=Yes)

Retry
Count . . . . . . . . . : 005
Fast interval . . . . . : 005
Slow interval . . . . . : 030

Exit routines
Security . . . . . . . :
Message . . . . . . . . :
Send . . . . . . . . . :
Receive . . . . . . . :

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Defining a receiver channel using CICS

1. Run the CICS transaction CKMC. Select Edit and then Create. A pop-up
window appears.

Selected Edit View Help

------------------------------------------------------------------------------
MCSELB IBM MQSeries for OS/390 Message Channel List MVSLU

Select a channel name. Then select an action.

More:
Channel name Type Sysid
MVS.OS2.CICS SENDER HUR1

(C) Copyright IBM Corporation 1993, 1999. All rights reserved.

F1=Help F3=Exit F5=Refresh now F6=Find F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

2. Specify a Channel name and a Channel type.

3. Press Enter.
The Settings panel, which spans two screens, is displayed.
4. Set the parameter values as indicated. In particular, if translation is required,
set the Message field of the Exit routines section.

418 MQSeries Intercommunication

 OS/390 configuration

Channel Help
------------------------------------------------------------------------------
MCATTB3 OS2.MVS.CICS - Settings MVSLU

More:
Channel type . . . . . . : RECEIVER

Target system id . . . . :

Batch size . . . . . . . : 0001

Sequence number wrap . . : 0999999999
Max message size . . . . : 0032000
Max transmission . . . . : 32000

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Channel Help
------------------------------------------------------------------------------
MCATTC3 OS2.MVS.CICS - Settings MVSLU

More: -
Channel type . . . . . . : RECEIVER

Sequential delivery . . . : 0 (0=No or 1=Yes)

Put authority . . . . . . : 1 (1=Process or 2=Context)

Exit routines
Security . . . . . . . :
Message . . . . . . . . :
Send . . . . . . . . . :
Receive . . . . . . . . :

F1=Help F3=Exit F5=Refresh now F7=Bkwd F8=Fwd F10=Menu Bar

F12=Cancel

Chapter 29. Example configuration - IBM MQSeries for OS/390 419

DQM in MQSeries for OS/390

420 MQSeries Intercommunication

 Part 5. DQM in MQSeries for AS/400
Chapter 30. Monitoring and controlling Defining an LU 6.2 connection . . . . . . . 451
channels in MQSeries for AS/400 . . . . . . 423 Initiating end (Sending) . . . . . . . . . 452
The DQM channel control function . . . . . . 423 Initiated end (Receiver) . . . . . . . . . 455
Operator commands . . . . . . . . . . . 424 | Note on Work Management . . . . . . 457
Getting started . . . . . . . . . . . . . 426
Creating objects . . . . . . . . . . . . 426 Chapter 33. Example configuration - IBM
Creating a channel . . . . . . . . . . . 426 MQSeries for AS/400 . . . . . . . . . . 459
| Starting a channel . . . . . . . . . . . . 429 Configuration parameters for an LU 6.2 connection 459
Selecting a channel . . . . . . . . . . . 430 Configuration worksheet . . . . . . . . 459
Browsing a channel . . . . . . . . . . . 430 Explanation of terms . . . . . . . . . . 462
Renaming a channel . . . . . . . . . . . 432 How to find network attributes . . . . . 463
Work with channel status . . . . . . . . . 432 How to find the value of Resource name . . 463
Work-with-channel choices . . . . . . . . . 434 Establishing an LU 6.2 connection . . . . . . 464
Panel choices . . . . . . . . . . . . . 435 Local node configuration . . . . . . . . 464
F6=Create . . . . . . . . . . . . . 435 Creating a line description . . . . . . . 464
2=Change . . . . . . . . . . . . . 436 Adding a routing entry . . . . . . . . 465
3=Copy . . . . . . . . . . . . . . 436 Connection to partner node . . . . . . . 465
4=Delete . . . . . . . . . . . . . . 437 Creating a controller description . . . . . 465
5=Display . . . . . . . . . . . . . 437 Creating a device description . . . . . . 466
8=Work with Status . . . . . . . . . . 437 Creating CPI-C side information . . . . . 467
13=Ping . . . . . . . . . . . . . . 437 Adding a communications entry for APPC 468
Ping with LU 6.2 . . . . . . . . . . 437 Adding a configuration list entry . . . . . 468
14=Start . . . . . . . . . . . . . . 437 What next? . . . . . . . . . . . . . 469
15=End . . . . . . . . . . . . . . 438 Establishing a TCP connection. . . . . . . . 469
Stop immediate. . . . . . . . . . . 439 Adding a TCP/IP interface . . . . . . . . 469
Stop controlled . . . . . . . . . . . 439 Adding a TCP/IP loopback interface . . . . 469
16=Reset . . . . . . . . . . . . . . 439 Adding a default route . . . . . . . . . 470
17=Resolve . . . . . . . . . . . . . 439 What next? . . . . . . . . . . . . . 470
MQSeries for AS/400 configuration . . . . . . 471
Chapter 31. Preparing MQSeries for AS/400 . . 441 Basic configuration . . . . . . . . . . 471
Creating a transmission queue. . . . . . . . 441 Channel configuration . . . . . . . . . 471
Triggering channels . . . . . . . . . . . 443 MQSeries for AS/400 sender-channel
Channel programs. . . . . . . . . . . . 445 definitions using SNA . . . . . . . . 474
Channel states on OS/400 . . . . . . . . . 446 MQSeries for AS/400 receiver-channel
Other things to consider . . . . . . . . . . 447 definitions using SNA . . . . . . . . 474
Undelivered-message queue . . . . . . . 447 MQSeries for AS/400 sender-channel
Queues in use . . . . . . . . . . . . 447 definitions using TCP . . . . . . . . 475
Maximum number of channels . . . . . . 447 MQSeries for AS/400 receiver-channel
Multiple message channels per transmission definitions using TCP . . . . . . . . 475
queue . . . . . . . . . . . . . . . 447 Defining a queue . . . . . . . . . . . 475
Security of MQSeries for AS/400 objects . . . 447 Defining a channel . . . . . . . . . . 476
System extensions and user-exit programs . . . 448
Chapter 34. Message channel planning example
Chapter 32. Setting up communication for for OS/400 . . . . . . . . . . . . . . 477
MQSeries for AS/400 . . . . . . . . . . 449 What the example shows . . . . . . . . . 477
Deciding on a connection . . . . . . . . . 449 Queue manager QM1 example . . . . . . 478
Defining a TCP connection . . . . . . . . . 449 Queue manager QM2 example . . . . . . 480
Receiving on TCP . . . . . . . . . . . 450 Running the example. . . . . . . . . . . 482
Using the TCP SO_KEEPALIVE option . . . 450 Expanding this example . . . . . . . . . 482
Using the TCP listener backlog option . . . 450

This part of the book describes the MQSeries distributed queue management
function for MQSeries for AS/400.

© Copyright IBM Corp. 1993, 2000 421

DQM in MQSeries for AS/400

422 MQSeries Intercommunication

 Chapter 30. Monitoring and controlling channels in MQSeries
for AS/400
| Use the DQM commands and panels to create, monitor, and control the channels to
| remote queue managers. Each queue manager has a DQM program for controlling
| interconnections to compatible remote queue managers. See “Operator commands”
| on page 424 for a list of the commands you need when setting up and controlling
| message channels.

The DQM channel control function

The channel control function provides the interface and function for administration
and control of message channels between MQSeries for AS/400 and compatible
systems. See Figure 28 on page 58 for a conceptual picture.

The channel control function consists of MQSeries for AS/400 panels, commands,
programs, a sequence number file, and a file for the channel definitions. The
following is a brief description of the components of the channel control function:
v The channel definition file (CDF):
– Is indexed on channel name
– Holds channel definitions
v The channel commands are a subset of the MQSeries for AS/400 set of
commands.
Use the command GO CMDMQM to display the full set of MQSeries for AS/400
commands.
v You use channel definition panels, or commands to:
– Create, copy, display, change, and delete channel definitions
– Start and stop channels, ping, reset channel sequence numbers, and resolve
in-doubt messages when links cannot be re-established
– Display status information about channels
v Sequence numbers and logical unit of work (LUW) identifiers are stored in the
synchronization file, and are used for channel synchronization purposes.

© Copyright IBM Corp. 1993, 2000 423

 Operator commands

Operator commands
The following table shows the full list of MQSeries for AS/400 commands that you
may need when setting up and controlling channels. In general, issuing a
command results in the appropriate panel being displayed.

| The commands can be grouped as follows:

| v Channel commands
| CHGMQMCHL, Change MQM Channel
| CPYMQMCHL, Copy MQM Channel
| CRTMQMCHL, Create MQM Channel
| DLTMQMCHL, Delete MQM Channel
| DSPMQMCHL, Display MQM Channel
| ENDMQMCHL, End MQM Channel
| ENDMQMLSR, End MQM Listener
| PNGMQMCHL, Ping MQM Channel
| RSTMQMCHL, Reset MQM Channel
| RSVMQMCHL, Resolve MQM Channel
| STRMQMCHL, Start MQM Channel
| STRMQMCHLI, Start MQM Channel Initiator
| STRMQMLSR, Start MQM Listener
| WRKMQMCHL, Work with MQM Channel
| WRKMQMCHST, Work with MQM Channel Status
| v Cluster commands
| RFRMQMCL, Refresh Cluster
| RSMMQMCLQM, Resume Cluster Queue Manager
| RSTMQMCL, Reset Cluster
| SPDMQMCLQM, Suspend Cluster Queue Manager
| WRKMQMCL, Work with Clusters
| v Command Server commands
| DSPMQMCSVR, Display MQM Command Server
| ENDMQMCSVR, End MQM Command Server
| STRMQMCSVR, Start MQM Command Server
| v Data Type Conversion Command
| CVTMQMDTA, Convert MQM Data Type Command
| v Dead-Letter Queue Handler Command
| STRMQMDLQ, Start MQSeries Dead-Letter Queue Handler
| v Media Recovery Commands
| RCDMQMIMG, Record MQM Object Image
| RCRMQMOBJ, Recreate MQM Object
| v MQSeries command
| STRMQMMQSC, Start MQSC Commands
| v Name command
| DSPMQMOBJN, Display MQM Object Names
| v Namelist commands
| CHGMQMNL, Change MQM Namelist
| CPYMQMNL, Copy MQM Namelist
| CRTMQMNL, Create MQM Namelist
| DLTMQMNL, Delete MQM Namelist
| DSPMQMNL, Display MQM Namelist
| WRKMQMNL, Work with MQM Namelists
| v Process commands
| CHGMQMPRC, Change MQM Process

424 MQSeries Intercommunication

 Operator commands
| CPYMQMPRC, Copy MQM Process
| CRTMQMPRC, Create MQM Process
| DLTMQMPRC, Delete MQM Process
| DSPMQMPRC, Display MQM Process
| WRKMQMPRC, Work with MQM Processes
| v Queue commands
| CHGMQMQ, Change MQM Queue
| CLRMQMQ, Clear MQM Queue
| CPYMQMQ, Copy MQM Queue
| CRTMQMQ, Create MQM Queue
| DLTMQMQ, Delete MQM Queue
| DSPMQMQ, Display MQM Queue
| WRKMQMMSG, Work with MQM Messages
| WRKMQMQ, Work with MQM Queues
| v Queue Manager commands
| CCTMQM, Connect Message Queue Manager
| CHGMQM, Change Message Queue Manager
| CRTMQM, Create Message Queue Manager
| DLTMQM, Delete Message Queue Manager
| DSCMQM, Disconnect Message Queue Manager
| DSPMQM, Display Message Queue Manager
| ENDMQM, End Message Queue Manager
| STRMQM, Start Message Queue Manager
| WRKMQM, Work with Message Queue managers
| v Security commands
| DSPMQMAUT, Display MQM Object Authority
| GRTMQMAUT, Grant MQM Object Authority
| RVKMQMAUT, Revoke MQM Object Authority
| v Trace commands
| TRCMQM, Trace MQM Job
| v Transaction commands
| RSVMQMTRN, Resolve MQSeries Transaction
| WRKMQMTRN, Display MQSeries Transaction
| v Trigger Monitor commands
| STRMQMTRM, Start Trigger Monitor

Chapter 30. Monitoring and controlling channels in MQSeries for AS/400 425
 Getting started

Getting started
Use these commands and panels to:
1. Define message channels and associated objects
2. Monitor and control message channels

| By using the F4=Prompt key, you can specify the relevant queue manager. If you
| do not use the prompt, the default queue manager is assumed. With F4=Prompt,
| an additional panel is displayed where you may enter the relevant queue manager
| name and sometimes other data.

The objects you need to define with the panels are:

v Transmission queues
v Remote queue definitions
v Queue manager alias definitions
v Reply-to queue alias definitions
v Reply-to local queues
v Processes for triggering (MCAs)
v Message channel definitions

See “Chapter 2. Making your applications communicate” on page 17 for more

discussion on the concepts involved in the use of these objects.

Channels must be completely defined, and their associated objects must exist and
be available for use, before a channel can be started. This chapter shows you how
to do this.

In addition, the particular communication link for each channel must be defined
and available before a channel can be run. For a description of how LU 6.2 and
TCP/IP links are defined, see the particular communication guide for your
installation as listed in “Related publications” on page 662.

Creating objects
Use the CRTMQMQ command to create the queue and alias objects, such as:
transmission queues, remote queue definitions, queue manager alias definitions,
reply-to queue alias definitions, and reply-to local queues.

| For a list of default objects, see the MQSeries for AS/400 V5.1 System Administration
| book.

Creating a channel
To create a new channel:
1. Use F6 from the Work with MQM Channels panel (the second panel that
displays channel details).
Alternatively, use the CRTMQMCHL command from the command line.
Either way, this displays the Create Channel panel. Type:
v The name of the channel in the field provided
v The channel type for this end of the link
2. Press Enter.

Note: You are strongly recommended to name all the channels in your network
uniquely. As shown in Table 1 on page 30, including the source and target
queue manager names in the channel name is a good way to do this.

426 MQSeries Intercommunication

 Creating a channel
Your entries are validated and errors are reported immediately. Correct any errors
and continue.

You are presented with the appropriate channel settings panel for the type of
channel you have chosen. Fill in the fields with the information you have gathered
previously. See “Appendix A. Channel planning form” on page 623 for an example
of how you might want to gather information. Press Enter to create the channel.

You are provided with help in deciding on the content of the various fields in the
descriptions of the channel definition panels in the help panels, and in “Chapter 6.
Channel attributes” on page 77.

Create MQM Channel (CRTMQMCHL)

Type choices, press Enter.

Channel name . . . . . . . . . . > CHANNAME________________

Channel type . . . . . . . . . . > *SDR__ *RCVR, *SDR, *SVR, *RQSTR...
Message Queue Manager name *DFT__________________________________
_____
Replace . . . . . . . . . . . . *NO_ *NO, *YES
Transport type . . . . . . . . . *TCP____ *LU62, *TCP, *SYSDFTCHL
Text 'description' . . . . . . . > 'Example Channel Definition'_______________
___________________________________
Connection name . . . . . . . . *SYSDFTCHL_________________________________
______________________________________________________________________________
______________________________________________________________________________
______________________________________________________________________________
______________________________________________________________________________
______________________________________________________________________________
__________________________________________________
More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 92. Create channel (1)

Chapter 30. Monitoring and controlling channels in MQSeries for AS/400 427
Creating a channel

Create MQM Channel (CRTMQMCHL)

Type choices, press Enter.

Transmission queue . . . . . . . 'TRANSMISSION_QUEUE_NAME'__________________

__________________
Message channel agent . . . . . *NONE______ Name, *SYSDFTCHL, *NONE
Library . . . . . . . . . . . __________ Name
Message channel agent user ID . *SYSDFTCHL__ Character value...
Coded Character Set Identifier *SYSDFTCHL__ 0-9999, *SYSDFTCHL
Batch size . . . . . . . . . . . 50_________ 1-9999, *SYSDFTCHL
Disconnect interval . . . . . . 6000_______ 1-999999, *SYSDFTCHL
Short retry interval . . . . . . 60_________ 0-999999999, *SYSDFTCHL
Short retry count . . . . . . . 10_________ 0-999999999, *SYSDFTCHL
Long retry interval . . . . . . 1200_______ 0-999999999, *SYSDFTCHL
Long retry count . . . . . . . . 999999999__ 0-999999999, *SYSDFTCHL
Security exit . . . . . . . . . *NONE_____ Name, *SYSDFTCHL, *NONE
Library . . . . . . . . . . . __________ Name
Security exit user data . . . . *SYSDFTCHL______________________

More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 93. Create channel (2)

Create MQM Channel (CRTMQMCHL)

Type choices, press Enter.

Send exit . . . . . . . . . . . *NONE______ Name, *SYSDFTCHL, *NONE

Library . . . . . . . . . . . ___________ Name
+ for more values __________
Send exit user data . . . . . . ________________________________
+ for more values ________________________________
Receive exit . . . . . . . . . . *NONE_____ Name, *SYSDFTCHL, *NONE
Library . . . . . . . . . . . __________ Name
+ for more values __________
__________
Receive exit user data . . . . . ________________________________
+ for more values ________________________________
Message exit . . . . . . . . . . *NONE_____ Name, *SYSDFTCHL, *NONE
Library . . . . . . . . . . . __________ Name
+ for more values __________
__________
More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 94. Create channel (3)

428 MQSeries Intercommunication

 Creating a channel

Create MQM Channel (CRTMQMCHL)

Type choices, press Enter.

Message exit user data . . . . . ________________________________

+ for more values _____________________________
Convert message . . . . . . . . *SYSDFTCHL_ *YES, *NO, *SYSDFTCHL
Sequence number wrap . . . . . . 999999999__ 100-999999999, *SYSDFTCHL
Maximum message length . . . . . 4194304____ 0-4194304, *SYSDFTCHL
Heartbeat interval . . . . . . . 300________ 0-999999999, *SYSDFTCHL
Non Persistent Message Speed . . *FAST_____ *FAST, *NORMAL, *SYSDFTCHL
Password . . . . . . . . . . . . *SYSDFTCHL_ Character value, *BLANK...
Task User Profile . . . . . . . *SYSDFTCHL_ Character value, *BLANK...
Transaction Program Name . . . . *SYSDFTCHL

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 95. Create channel (4)

|
| Starting a channel
| Listeners are valid for TCP only. For SNA listeners, you must configure your
| communications subsystem.

| For applications to be able to exchange messages you must start a listener program
| for inbound connections using the STRMQMLSR command.

| For outbound connections you must start the channel in one of the following ways:
| 1. Use the CL command STRMQMCHL, specifying the channel name, to start the
| channel as a process or a thread, depending on the MCATYPE parameter. (If
| channels are started as threads, they are threads of a channel initiator.)
| STRMQMCHL CHLNAME(QM1.TO.QM2) MQNAME(MYQMGR)
| 2. Use a channel initiator to trigger the channel. One channel initiator is started
| automatically when the queue manager is started. This can be eliminated by
| changing the chinit stanza in the qm.ini file for that queue manager.
| 3. Use the WRKMQMCHL command to begin the Work with Channels panel and
| choose option 14 to start a channel.

Chapter 30. Monitoring and controlling channels in MQSeries for AS/400 429
Selecting a channel

Selecting a channel
To select a channel, use the WRKMQMCHL command to begin at the Work with
Channels panel:
1. Move the cursor to the option field at the left of the required channel name.
2. Type an option number.
3. Press Enter to activate your choice.

If you select more than one channel, the options are activated in sequence.

Work with MQM Channels

Queue Manager Name . . : CNX

Type options, press Enter.

2=Change 3=Copy 4=Delete 5=Display 8=Work with Status 13=Ping
14=Start 15=End 16=Reset 17=Resolve

Opt Name Type Transport Status

CHLNIC *RCVR *TCP INACTIVE
CORSAIR.TO.MUSTANG *SDR *LU62 INACTIVE
FV.CHANNEL.MC.DJE1 *RCVR *TCP INACTIVE
FV.CHANNEL.MC.DJE2 *SDR *TCP INACTIVE
FV.CHANNEL.MC.DJE3 *RQSTR *TCP INACTIVE
FV.CHANNEL.MC.DJE4 *SVR *TCP INACTIVE
FV.CHANNEL.PETER *RCVR *TCP INACTIVE
FV.CHANNEL.PETER.LU *RCVR *LU62 INACTIVE
FV.CHANNEL.PETER.LU1 *RCVR *LU62 INACTIVE
More...
Parameters or command
===>
F3=Exit F4=Prompt F5=Refresh F6=Create F9=Retrieve F12=Cancel
F21=Print

Figure 96. Work with channels

Browsing a channel
To browse the settings of a channel, use the WRKMQMCHL command to begin at
the Display Channel panel:
1. Move the cursor to the left of the required channel name.
2. Type option 5 (Display).
3. Press Enter to activate your choice.

If you select more than one channel, they are presented in sequence.

Alternatively, you can use the DSPMQMCHL command from the command line.

This results in the respective Display Channel panel being displayed with details
of the current settings for the channel. The fields are described in “Chapter 6.
Channel attributes” on page 77.

430 MQSeries Intercommunication

 Browsing a channel

Display MQM Channel

Channel name . . . . . . . . . : ST.JST.2TO1

Queue Manager Name . . . . . . : QMREL
Channel type . . . . . . . . . : *SDR
Transport type . . . . . . . . : *TCP
Text 'description' . . . . . . : John's sender to WINSDOA1

Connection name . . . . . . . : MUSTANG

Transmission queue . . . . . . : WINSDOA1

Message channel agent . . . . :

Library . . . . . . . . . . :
Message channel agent user ID : *NONE
Batch interval . . . . . . . . : 0
Batch size . . . . . . . . . . : 50
Disconnect interval . . . . . : 6000

F3=Exit F12=Cancel F21=Print

Figure 97. Display a TCP/IP channel (1)

Display MQM Channel

Short retry interval . . . . . : 60

Short retry count . . . . . . : 10
Long retry interval . . . . . : 6000
Long retry count . . . . . . . : 10
Security exit . . . . . . . . :
Library . . . . . . . . . . :
Security exit user data . . . :
Send exit . . . . . . . . . . :
Library . . . . . . . . . . :
Send exit user data . . . . . :
Receive exit . . . . . . . . . :
Library . . . . . . . . . . :
Receive exit user data . . . . :
Message exit . . . . . . . . . :
Library . . . . . . . . . . :
Message exit user data . . . . :
More...

F3=Exit F12=Cancel F21=Print

Figure 98. Display a TCP/IP channel (2)

Chapter 30. Monitoring and controlling channels in MQSeries for AS/400 431
 Renaming a channel

Display MQM Channel

Sequence number wrap . . . . . : 999999999

Maximum message length . . . . : 10000
Convert message . . . . . . . : *NO
Heartbeat interval . . . . . . . 300
Nonpersistent message speed . . *FAST

Bottom

F3=Exit F12=Cancel F21=Print

Figure 99. Display a TCP/IP channel (3)

Renaming a channel
To rename a message channel, begin at the Work with Channels panel:
1. End the channel.
2. Use option 3 (Copy) to create a duplicate with the new name.
3. Use option 5 (Display) to check that it has been created correctly.
4. Use option 4 (Delete) to delete the original channel.

If you decide to rename a message channel, ensure that both channel ends are
renamed at the same time.

Work with channel status

Use the WRKMQMCHST command to bring up the first of three screens showing
the status of your channels. You can view the three status screens in sequence
when you select Change-view (F11).

Alternatively, selecting option 8 (Work with Status) from the Work with MQM
Channels panel also brings up the first status panel.

| Work with channel status applies to all message channels. It does not apply to
| MQI channels other than server-connection channels on MQSeries for AS/400 V5.1.

Note: The Work with Channel Status screens only show channels that are active
after messages have been sent through the channel and the sequence
number has been incremented.

432 MQSeries Intercommunication

 Work with channel status

MQSeries Work with Channel Status

Type options, press Enter.

5=Display 13=Ping 14=Start 15=End 16=Reset 17=Resolve

Opt Name Connection Indoubt Last Seq

CARTS_CORSAIR_CHAN GBIBMIYA.WINSDOA1 NO 1
CHLNIC 9.20.2.213 NO 3
FV.CHANNEL.PETER2 9.20.2.213 NO 6225
JST.1.2 9.20.2.201 NO 28
MP_MUST_TO_CORS 9.20.2.213 NO 100
MUSTANG.TO.CORSAIR GBIBMIYA.WINSDOA1 NO 10
MP_CORS_TO_MUST 9.20.2.213 NO 101
JST.2.3 9.5.7.126 NO 32
PF_WINSDOA1_LU62 GBIBMIYA.IYA80020 NO 54
PF_WINSDOA1_LU62 GBIBMIYA.WINSDOA1 NO 500
ST.JCW.EXIT.2TO1.CHL 9.20.2.213 NO 216

Bottom
Parameters or command
===>
F3=Exit F4=Prompt F5=Refresh F6=Create F9=Retrieve F11=Change view
F12=Cancel F21=Print

Figure 100. Channel status (1)

Change the view with F11.

MQSeries Work with Channel Status

Type options, press Enter.

5=Display 13=Ping 14=Start 15=End 16=Reset 17=Resolve

Opt Transmission Queue LUWID

7516E58A40C000EC
7515A36C0D800157
7515E790AC8001CA
7516FF2284800009
75147C6629C0009D
7516DDE5778000A8
FV_MKP_TRANS_QUEUE 75147B61A44000FA
JST.3 75170185D0000133
PF.WINSDOA1 7516DA3955C00097
PF.WINSDOA1 7516DE2396C000BC
ST.JCW.EXIT.2TO1.XMIT.QUEUE 7516C51291400016

Bottom
Parameters or command
===>
F3=Exit F4=Prompt F5=Refresh F6=Create F9=Retrieve F11=Change view
F12=Cancel F21=Print

Figure 101. Channel status (2)

Chapter 30. Monitoring and controlling channels in MQSeries for AS/400 433
Work with channel status

MQSeries Work with Channel Status

Type options, press Enter.

5=Display 13=Ping 14=Start 15=End 16=Reset 17=Resolve

Indoubt Indoubt Indoubt

Opt Msgs Seq LUWID
0 0 0000000000000000
0 0 0000000000000000
0 0 0000000000000000
0 0 0000000000000000
0 0 0000000000000000
0 0 0000000000000000
0 101 75147B61A44000FA
0 32 75170185D0000133
0 54 7516DA3955C00097
0 500 7516DE2396C000BC
0 216 7516C51291400016

Bottom
Parameters or command
===>
F3=Exit F4=Prompt F5=Refresh F6=Create F9=Retrieve F11=Change view
F12=Cancel F21=Print

Figure 102. Channel status (3)

The options available in the Work with Channel Status panel are:

Menu option Description

5=Display Displays the channel settings.
13=Ping Initiates a Ping action, where appropriate.
14=Start Starts the channel.
15=End Stops the channel.
16=Reset Resets the channel sequence number.
17=Resolve Resolves an in-doubt channel situation, manually.
F11=Change view Cycles around the three status panels.

Work-with-channel choices
The Work with Channels panel is reached with the command WRKMQMCHL, and
it allows you to monitor the status of all channels listed, and to issue commands
against selected channels.

434 MQSeries Intercommunication

 Work-with-channel choices
The options available in the Work with Channel panel are:

Menu option Description

F6=Create Creates a channel.
2=Change Changes the attributes of a channel.
3=Copy Copies the attributes of a channel to a new channel.
4=Delete Deletes a channel.
5=Display Displays the current settings for the channel.
8=Work with status Displays the channel status panels.
13=Ping Runs the Ping facility to test the connection to the adjacent system
by exchanging a fixed data message with the remote end.
14=Start Starts the selected channel, or resets a disabled receiver channel.
15=End Requests the channel to close down.
16=Reset Requests the channel to reset the sequence numbers on this end of
the link. The numbers must be equal at both ends for the channel to
start.
17=Resolve Requests the channel to resolve in-doubt messages without
establishing connection to the other end.

Panel choices
The following choices are provided in the Work with MQM channels panel and the
Work with Channel Status panel.

F6=Create
| Use the Create option, or enter the CRTMQMCHL command from the command
| line, to obtain the Create Channel panel. There are examples of Create Channel
| panels, starting at Figure 92 on page 427.

With this panel, you create a new channel definition from a screen of fields filled
with default values supplied by MQSeries for AS/400. Type the name of the
channel, select the type of channel you are creating, and the communication
method to be used.

When you press Enter, the panel is displayed. Type information in all the required
fields in this panel, and the three pages making up the complete panel, and then
save the definition by pressing Enter.

The channel name must be the same at both ends of the channel, and unique
within the network. However, you should restrict the characters used to those that
are valid for MQSeries for AS/400 object names; see “Chapter 6. Channel
attributes” on page 77.

All panels have default values supplied by MQSeries for AS/400 for some fields.
You can customize these values, or you can change them when you are creating or
copying channels. To customize the values, see the MQSeries for AS/400 System
Administration.

You can create your own set of channel default values by setting up dummy
channels with the required defaults for each channel type, and copying them each
time you want to create new channel definitions.

Table 38 on page 436 shows the channel attributes for each type of channel. See
“Chapter 6. Channel attributes” on page 77 for details about the fields.

Chapter 30. Monitoring and controlling channels in MQSeries for AS/400 435
Panel choices
Table 38. Channel attribute fields per message channel type
Attribute field Sender Server Receiver Requester
Batch size U U U U
Channel name U U U U
Channel type U U U U
Connection name U U U
Context U U
Disconnect interval U U
Heartbeat interval U U U U
Long retry wait interval U U
Long retry count U U
Maximum message length U U U U
Message channel agent name U
Message exit user data U U U U
Message retry exit count U U
Message retry exit data U U
Message retry exit interval U U
Message retry exit name U U
Nonpersistent message speed U U U U
Receive exit U U U U
Receive exit user data U U U U
Security exit U U U U
Security exit user data U U U U
Send exit U U U U
Send exit user data U U U U
Sequence number wrap U U U U
Short retry wait interval U U
Short retry count U U
Transport type U U U U
Transmission queue U U
Message exit U U U U

2=Change
Use the Change option, or the CHGMQMCHL command, to change an existing
channel definition, except for the channel name. Simply type over the fields to be
changed in the channel definition panel, and then save the updated definition by
pressing Enter.

3=Copy
Use the Copy option, or the CPYMQMCHL command, to copy an existing channel.
The Copy panel enables you to define the new channel name. However, you
should restrict the characters used to those that are valid for MQSeries for AS/400
object names; see the MQSeries for AS/400 System Administration.

Press Enter on the Copy panel to display the details of current settings. You can
change any of the new channel settings. Save the new channel definition by
pressing Enter.

436 MQSeries Intercommunication

 Panel choices
4=Delete
Use the Delete option to delete the selected channel. A panel is displayed to
confirm or cancel your request.

5=Display
Use the Display option to display the current definitions for the channel. This
choice displays the panel with the fields showing the current values of the
parameters, and protected against user input.

8=Work with Status

The status column tells you whether the channel is active or inactive, and is
displayed continuously in the Work with MQM Channels panel. Use option 8
(Work with Status) to see more status information displayed. Alternatively, this can
be displayed from the command line with the WRKMQMCHST command. See
“Work with channel status” on page 432.
v Channel name
v Communication connection name
v In-doubt status of channel (where appropriate)
v Last sequence number
v Transmission queue name (where appropriate)
v The in-doubt identifier (where appropriate)
v The last committed sequence number
v Logical unit of work identifier

13=Ping
Use the Ping option to exchange a fixed data message with the remote end. This
gives some confidence to the system supervisor that the link is available and
functioning.

Ping does not involve the use of transmission queues and target queues. It uses
channel definitions, the related communication link, and the network setup.

It is available from sender and server channels, only. The corresponding channel is
started at the far side of the link, and performs the start up parameter negotiation.
Errors are notified normally.

The result of the message exchange is presented in the Ping panel for you, and is
the returned message text, together with the time the message was sent, and the
time the reply was received.

Ping with LU 6.2

When Ping is invoked in MQSeries for AS/400, it is run with the USERID of the
user requesting the function, whereas the normal way that a channel program is
run is for the QMQM USERID to be taken for channel programs. The USERID
flows to the receiving side and it must be valid on the receiving end for the LU 6.2
conversation to be allocated.

14=Start
The Start option is available for sender, server, and requester channels. It should
not be necessary where a channel has been set up with queue manager triggering.

| The Start option is also used for receiver channels that have a DISABLED or
| STOPPED status. Starting a receiver channel that is in DISABLED or STOPPED
| state resets the channel and allows it to be started from the remote channel.

Chapter 30. Monitoring and controlling channels in MQSeries for AS/400 437
Panel choices
When started, the sending MCA reads the channel definition file and opens the
transmission queue. A channel start-up sequence is executed, which remotely starts
the corresponding MCA of the receiver or server channel. When they have been
started, the sender and server processes await messages arriving on the
transmission queue and transmit them as they arrive.

When you use triggering, you will need to start the continuously running trigger
process to monitor the initiation queue. The STRMQMCHLI command can be used
for this.

At the far end of a channel, the receiving process may be started in response to a
channel startup from the sending end. The method of doing this is different for LU
6.2 and TCP/IP connected channels:
v LU 6.2 connected channels do not require any explicit action at the receiving end
of a channel.
v TCP connected channels require a listener process to be running continuously.
This process awaits channel startup requests from the remote end of the link and
starts the process defined in the channel definitions for that connection.
When the remote machine is an AS/400, you can use the STRMQMLSR
command for this.

Use of the Start option always causes the channel to re-synchronize, where
necessary.

For the start to succeed:

v Channel definitions, local and remote must exist. If there is no appropriate
channel definition for a receiver or server-connection channel, a default one is
created automatically if the channel is auto-defined. See “Channel
auto-definition exit program” on page 516.
v The transmission queue must exist, be enabled for GETs, and have no other
channels using it.
v MCAs, local and remote, must exist.
v The communication link must be available.
v The queue managers must be running, local and remote.
v The message channel must be inactive.

To transfer messages, remote queues and remote queue definitions must exist.

A message is returned to the panel confirming that the request to start a channel
has been accepted. For confirmation that the Start process has succeeded, check the
system log, or press F5 (refresh the screen).

15=End
Use the End option to request the channel to stop activity. The channel will not
send any more messages until the operator starts the channel again. (For
information about restarting stopped channels, see “Restarting stopped channels”
on page 69.)

You can select the type of stop you require if you press F4 before Enter. You can
choose IMMEDIATE, or CONTROLLED.

438 MQSeries Intercommunication

 Panel choices
Stop immediate
Normally, this option should not be used. It terminates the channel process. The
channel does not complete processing the current batch of messages, and cannot,
therefore, leave the channel in doubt. In general, it is recommended that the
operators use the controlled stop option.

Stop controlled
This choice requests the channel to close down in an orderly way; the current
batch of messages is completed, and the syncpoint procedure is carried out with
the other end of the channel.

16=Reset
The Reset option changes the message sequence number. Use it with care, and only
after you have used the Resolve option to resolve any in-doubt situations. This
option is available only at the sender or server channel. The first message starts the
new sequence the next time the channel is started.

17=Resolve
Use the Resolve option when messages are held in-doubt by a sender or server, for
example because one end of the link has terminated, and there is no prospect of it
recovering. The Resolve option accepts one of two parameters: BACKOUT or
COMMIT. Backout restores messages to the transmission queue, while Commit
discards them.

The channel program does not try to establish a session with a partner. Instead, it
determines the logical unit of work identifier (LUWID) which represents the
in-doubt messages. It then issues, as requested, either:
v BACKOUT to restore the messages to the transmission queue; or
v COMMIT to delete the messages from the transmission queue.

For the resolution to succeed:

v The channel must be inactive
v The channel must be in doubt
v The channel type must be sender or server
v The channel definition, local, must exist
v The queue manager must be running, local

Chapter 30. Monitoring and controlling channels in MQSeries for AS/400 439
Panel choices

440 MQSeries Intercommunication

Chapter 31. Preparing MQSeries for AS/400
This chapter describes the MQSeries for AS/400 preparations required before DQM
can be used. Communication preparations are described in “Chapter 32. Setting up
communication for MQSeries for AS/400” on page 449.

Before a channel can be started, the transmission queue must be defined as

described in this chapter, and must be included in the message channel definition.

In addition, where needed, the triggering arrangement must be prepared with the
definition of the necessary processes and queues.

Creating a transmission queue

You define a local queue with the Usage field attribute set to *TMQ, for each
sending message channel.

If you want to make use of remote queue definitions, use the same command to
create a queue of type *RMT, and Usage of *NORMAL.

To create a transmission queue, use the CRTMQMQ command from the command
line to present you with the first queue creation panel; see Figure 103.

Create MQM Queue (CRTMQMQ)

Type choices, press Enter.

Queue name . . . . . . . . . . .

Queue type . . . . . . . . . . . ____ *ALS, *LCL, *MDL, *RMT

Message Queue Manager name . . . *DFT________________________________

_____

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
+

Figure 103. Create a queue (1)

Type the name of the queue and specify the type of queue that you wish to create:
Local, Remote, or Alias. For a transmission queue, specify Local (*LCL) on this
panel and press Enter.

© Copyright IBM Corp. 1993, 2000 441

Creating a transmission queue
You are presented with the second page of the Create MQM Queue panel; see
Figure 104.

Create MQM Queue (CRTMQMQ)

Type choices, press Enter.

Queue name . . . . . . . . . . . > HURS.2.HURS.PRIORIT

Queue type . . . . . . . . . . . > *LCL *ALS, *LCL, *MDL, *RMT

Message Queue Manager name . . . *DFT
Replace . . . . . . . . . . . . *NO *NO, *YES
Text 'description' . . . . . . . ' '
Put enabled . . . . . . . . . . *YES *SYSDFTQ, *NO, *YES
Default message priority . . . . 0 0-9, *SYSDFTQ
Default message persistence . . *NO *SYSDFTQ, *NO, *YES
Process name . . . . . . . . . . ' '
Triggering enabled . . . . . . . *NO *SYSDFTQ, *NO, *YES
Get enabled . . . . . . . . . . *YES *SYSDFTQ, *NO, *YES
Sharing enabled . . . . . . . . *YES *SYSDFTQ, *NO, *YES

More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 104. Create a queue (2)

Change any of the default values shown. Press page down to scroll to the next
screen; see Figure 105.

Create MQM Queue (CRTMQMQ)

Type choices, press Enter.

Default share option . . . . . . *YES *SYSDFTQ, *NO, *YES

Message delivery sequence . . . *PTY *SYSDFTQ, *PTY, *FIFO
Harden backout count . . . . . . *NO *SYSDFTQ, *NO, *YES
Trigger type . . . . . . . . . . *FIRST *SYSDFTQ, *FIRST, *ALL...
Trigger depth . . . . . . . . . 1 1-999999999, *SYSDFTQ
Trigger message priority . . . . 0 0-9, *SYSDFTQ
Trigger data . . . . . . . . . . ' '
Retention interval . . . . . . . 999999999 0-999999999, *SYSDFTQ
Maximum queue depth . . . . . . 5000 1-24000, *SYSDFTQ
Maximum message length . . . . . 4194304 0-4194304, *SYSDFTQ
Backout threshold . . . . . . . 0 0-999999999, *SYSDFTQ
Backout requeue queue . . . . . ' '
Initiation queue . . . . . . . . ' '

More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 105. Create a queue (3)

Type *TMQ, for transmission queue, in the Usage field of this panel, and change any
of the default values shown in the other fields.

442 MQSeries Intercommunication

 Creating a transmission queue

Create MQM Queue (CRTMQMQ)

Type choices, press Enter.

Usage . . . . . . . . . . . . . *TMQ *SYSDFTQ, *NORMAL, *TMQ

Queue depth high threshold . . . 80 0-100, *SYSDFTQ
Queue depth low threshold . . . 20 0-100, *SYSDFTQ
Queue full events enabled . . . *YES *SYSDFTQ, *NO, *YES
Queue high events enabled . . . *YES *SYSDFTQ, *NO, *YES
Queue low events enabled . . . . *YES *SYSDFTQ, *NO, *YES
Service interval . . . . . . . . 999999999 0-999999999, *SYSDFTQ
Service interval events . . . . *NONE *SYSDFTQ, *HIGH, *OK, *NONE
Distribution list support . . . *NO *SYSDFTQ, *NO, *YES
Cluster Name . . . . . . . . . . *SYSDFTQ
Cluster Name List . . . . . . . *SYSDFTQ
Default Binding . . . . . . . . *SYSDFTQ *SYSDFTQ, *OPEN, *NOTFIXED

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 106. Create a queue (4)

When you are satisfied that the fields contain the correct data, press Enter to create
the queue.

Triggering channels
An overview of triggering is given in “Triggering channels” on page 20, while it is
described in depth in the MQSeries Application Programming Guide. This section
provides you with information specific to MQSeries for AS/400.

Triggering in MQSeries for AS/400 is implemented with the channel initiator

process, which is started with the STRMQMCHLI command that specifies the
name of the initiation queue. For example:
STRMQMCHLI QNAME(MYINITQ)

You need to set up the transmission queue for the channel specifying TRIGGER
and specifying the channel name in the TRIGDATA field: For example:
| CRTMQMQ QNAME(MYXMITQ) QTYPE(*LCL) MQMNAME(MYQMGR) +
| PRCNAME(MYPROCESS) TRGENBL(*YES) INITQNAME(MYINITQ) +
| USAGE(*TMQ)

Then define an initiation queue.

| CRTMQMQ QNAME(MYINITQ) MQMNAME(MYQMGR)

Next you define a process in MQSeries for AS/400 naming the MCA sender
program, as the program to be triggered when messages arrive on the transmission
queue. Type CRTMQMPRC on the command line to display the Create Process
panel. Alternatively, select F6 (Create) from the Work with MQM Process panel.
See Figure 107 on page 444 for the first page of the Create Process panel. The
MQSeries for AS/400 System Administration book contains details of defining
processes to be triggered.

Chapter 31. Preparing MQSeries for AS/400 443

Triggering channels

Create MQM Process (CRTMQMPRC)

Type choices, press Enter.

Process Name . . . . . . . . . . _______________________________________

Message Queue Manager name . . . *DFT___________________________________

Replace . . . . . . . . . . . . *NO *NO, *YES

Text 'description' . . . . . . . > 'Triggers hursley.to.hursley.normal '
Application type . . . . . . . . *OS400
Application identifier . . . . . > 'AMQRMCLA

User data . . . . . . . . . . . > *SYSDFTPRC

More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 107. Create process (1)

1. Type the name of the process definition in the field provided.

2. Enter a description in the Text ’description’ field.
3. Set Application type to *OS400.
4. Set Application identifier to AMQRMCLA.
5. Set User data to the channel name so as to associate this definition with the
transmission queue belonging to the channel.
6. Page down to show the second page (see Figure 108 on page 445) and insert
any environment data.

444 MQSeries Intercommunication

 Channel programs

Create MQM Process (CRTMQMPRC)

Type choices, press Enter.

Environment data . . . . . . . . *SYSDFTPRC___________________________

________________________________________________________________________
______________

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 108. Create process (2)

Channel programs
There are different types of channel programs (MCAs) available for use at the
channels. The names are contained in the following table.
Table 39. Program and transaction names
Program name Direction of connection Communication
| AMQCRSTA Inbound TCP
AMQCRS6A Inbound LU 6.2
AMQRMCLA Outbound Any

Chapter 31. Preparing MQSeries for AS/400 445

 Channel programs

Channel states on OS/400

Channel states are displayed on the Work with Channels panel (described in
Figure 96 on page 430). There are some differences between the names of channel
states on different versions of MQSeries for AS/400. In the following table, the
state names shown for V4R2 correspond to the channel states described in
Figure 30 on page 63. As shown in the table, some of these states have different
| names, or do not exist for earlier versions.
| Table 40. Channel states on OS/400
| State name State name Meaning
| (V3R6) (V3R2, V3R7,
| V4R2, V5R1)
| - STARTING Channel is ready to begin negotiation with target
| MCA
| BINDING BINDING Establishing a session and initial data exchange
| REQUESTING REQUESTING Requester channel initiating a connection
| READY RUNNING Transferring or ready to transfer
| PAUSED PAUSED Waiting for message-retry interval
| CLOSING STOPPING Establishing whether to retry or stop
| RETRYING RETRYING Waiting until next retry attempt
| DISABLED STOPPED Channel stopped because of an error or because an
| end-channel command is issued
| STOPPED INACTIVE Channel ended processing normally or channel never
| started
| - *None No state (for server-connection channels only)
| Note: The state *None applies only to V3R2 and V3R7.
|
|

446 MQSeries Intercommunication

 Other things to consider

Other things to consider

Here are some other topics that you should consider when preparing MQSeries for
distributed queue management.

Undelivered-message queue
It is advisable that you have an application available to process the messages
arriving on the undelivered-message queue (also known as the dead-letter queue
or DLQ). The program could be triggered, or run at regular intervals. For more
details, see the MQSeries for AS/400 System Administration and the MQSeries
Application Programming Guide.

Queues in use
MCAs for receiver channels may keep the destination queues open even when
messages are not being transmitted; this results in the queues appearing to be “in
use”.

Maximum number of channels

| You can specify the maximum number of channels allowed in your system and the
| maximum number that can be active at one time. You do this in the qm.ini file in
| directory QIBM/UserData/mqm/qmgrs/queue manager name. See “Appendix D.
| Configuration file stanzas for distributed queuing” on page 637.

Multiple message channels per transmission queue

It is possible to define more than one channel per transmission queue, but only
one of these channels can be active at any one time. This is recommended for the
provision of alternative routes between queue managers for traffic balancing and
link failure corrective action.

Security of MQSeries for AS/400 objects

This section deals with remote messaging aspects of security.

You need to provide users with authority to make use of the MQSeries for AS/400
facilities, and this is organized according to actions to be taken with respect to
objects and definitions. For example:
v Queue managers can be started and stopped by authorized users
v Applications need to connect to the queue manager, and have authority to make
use of queues
v Message channels need to be created and controlled by authorized users

Chapter 31. Preparing MQSeries for AS/400 447

Other things to consider
The message channel agent at a remote site needs to check that the message being
delivered has derived from a user with authority to do so at this remote site. In
addition, as MCAs can be started remotely, it may be necessary to verify that the
remote processes trying to start your MCAs are authorized to do so. There are
three possible ways for you to deal with this:
1. Decree in the channel definition that messages must contain acceptable context
authority, otherwise they will be discarded.
2. Implement user exit security checking to ensure that the corresponding message
channel is authorized. The security of the installation hosting the corresponding
channel ensures that all users are properly authorized, so that you do not need
to check individual messages.
3. Implement user exit message processing to ensure that individual messages are
vetted for authorization.

Here are some facts about the way MQSeries for AS/400 operates security:
v Users are identified and authenticated by OS/400
v Queue manager services invoked by applications are run with the authority of
the queue manager user profile, but in the user’s process
v Queue manager services invoked by user commands are run with the authority
of the queue manager user profile

System extensions and user-exit programs

A facility is provided in the channel definition to allow extra programs to be run at
defined times during the processing of messages. These programs are not supplied
with MQSeries for AS/400, but may be provided by each installation according to
local requirements.

In order to run, such programs must have predefined names and be available on
call to the channel programs. The names of the exit programs are included in the
message channel definitions.

There is a defined control block interface for handing over control to these
programs, and for handling the return of control from these programs.

The precise places where these programs are called, and details of control blocks
and names, are to be found in “Part 7. Further intercommunication considerations”
on page 503.

448 MQSeries Intercommunication

 Chapter 32. Setting up communication for MQSeries for
AS/400
DQM is a remote queuing facility for MQSeries for AS/400. It provides channel
control programs for the MQSeries for AS/400 queue manager which form the
interface to communication links, controllable by the system operator. The channel
definitions held by distributed-queuing management use these communication
links.

When a distributed-queuing management channel is started, it tries to use the

connection specified in the channel definition. For this to succeed, it is necessary
for the connection to be defined and available. This chapter explains how to do
this.

Deciding on a connection
There are two forms of communication between MQSeries for AS/400 systems:
v AS/400 TCP
For TCP, a host address may be used, and these connections are set up as
described in the OS/400 Communication Configuration Reference.
| In the TCP environment, each distributed service is allocated a unique TCP
| address which may be used by remote machines to access the service. The TCP
| address consists of a host name/number and a port number. All queue
| managers will use such a number to communicate with each other via TCP.
v AS/400 SNA (LU 6.2)
This form of communication requires the definition of an AS/400 SNA logical
unit type 6.2 (LU 6.2) that provides the physical link between the AS/400
serving the local queue manager and the system serving the remote queue
manager. Refer to the OS/400 Communication Configuration Reference for details on
configuring communications in OS/400.

Defining a TCP connection

The channel definition contains a field, CONNECTION NAME, that contains either
the TCP network address of the target, in dotted decimal form (for example
9.20.9.30) or the host name (for example AS4HUR1). If the CONNECTION NAME
is a host name, a name server or the AS/400 host table is used to convert the host
name into a TCP host address.

| A port number is required for a complete TCP address; if this is not supplied, the
| default port number 1414 is used. On the initiating end of a connection (sender,
| requester, and server channel types) it is possible to provide an optional port
| number for the connection, for example:
Connection name 9.20.9.30 (1555)

In this case the initiating end will attempt to connect to a receiving program at
port 1555.

© Copyright IBM Corp. 1993, 2000 449

 Defining a TCP connection
Receiving on TCP
Receiving channel programs are started in response to a startup request from the
sending channel. To do this, a listener program has to be started to detect incoming
network requests and start the associated channel. You start this listener program
with the STRMQMLSR command.

| You can start more than one listener for each queue manager. By default, the
| STRMQMLSR command uses port 1414 but you can override this. To override the
| default setting, add the following statements to the qm.ini file of the selected
| queue manager (in this example, the listener is required to use port 2500):
| TCP:
| Port=2500

| The qm.ini file is located in this IFS directory:

| /QIBM/UserData/mqm/qmgrs/queue manager name.

| This new value is read only when the TCP listener is started. If you have a listener
| already running, this change is not be seen by that program. To use the new value,
| stop the listener and issue the STRMQMLSR command again. Now, whenever you
| use the STRMQMLSR command, the listener defaults to the new port.

| Alternatively, you can specify a different port number on the STRMQMLSR

| command. For example:
| STRMQMLSR MQMNAME(queue manager name) PORT(2500)

| This change makes the listener default to the new port for the duration of the
| listener job.

Using the TCP SO_KEEPALIVE option

| If you want to use the SO_KEEPALIVE option (as discussed in “Checking that the
| other end of the channel is still available” on page 66) you must add the following
| entry to your queue manager configuration file (qm.ini in the IFS directory,
| /QIBM/UserData/mqm/qmgrs/queue manager name):
| TCP:
| KeepAlive=yes

| You must then issue the following command:

CFGTCP

Select option 3 (Change TCP Attributes). You can now specify a time interval in
minutes. You can specify a value in the range 1 through 40320 minutes; the default
is 120.

Using the TCP listener backlog option

When receiving on TCP, a maximum number of outstanding connection requests is
set. This can be considered a backlog of requests waiting on the TCP port for the
listener to accept the request.

The default listener backlog value on AS/400 is 255. If the backlog reaches this
value, the TCP connection is rejected and the channel will not be TCP: able to start.

For MCA channels, this results in the channel going into a RETRY state and
retrying the connection at a later time.

For client connections, the client receives an MQRC_Q_MGR_NOT_AVAILABLE

reason code from MQCONN and should retry the connection at a later time.

450 MQSeries Intercommunication

 Defining a TCP connection
However, to avoid this error, you can add an entry in the qm.ini file:
ListenerBacklog = n

This overrides the default maximum number of outstanding requests (255) for the
TCP listener.

Note: Some operating systems support a larger value than the default. If necessary,
this can be used to avoid reaching the connection limit.

Defining an LU 6.2 connection

| In MQSeries for AS/400 V5.1, a mode name, TP name, and connection name of a
| fully-qualified LU 6.2 connection can be used.

For other versions of MQSeries for AS/400, a communications side information

(CSI) object is required to define the LU 6.2 communications details for the sending
end of a message channel. It is referred to in the CONNECTION NAME field of
the Sender or Server channel definition for LU 6.2 connections. Further information
on the communications side object is available in the AS/400 APPC Communications
Programmer’s Guide.

The initiated end of the link must have a routing entry definition to complement
this CSI object. Further information on managing work requests from remote
LU 6.2 systems is available in the AS/400 Programming: Work Management Guide.

See the Multiplatform APPC Configuration Guide and the following table for
information.
Table 41. Settings on the local OS/400 system for a remote queue manager platform
Remote platform TPNAME
OS/390 without CICS The same as in the corresponding side information on the
remote queue manager.
OS/390 using CICS CKRC relates to a sender channel on the OS/400 system.
CKSV relates to a requester channel on the OS/400 system.
CKRC relates to a server channel on the OS/400 system.
OS/400 The same as the compare value in the routing entry on the
OS/400 system.
OS/2 As specified in the OS/2 Run Listener command, or
defaulted from the OS/2 queue manager configuration file.
Digital OVMS As specified in the Digital OVMS Run Listener command.
Tandem NSK The same as the TPNAME specified in the receiver-channel
definition.
| Other UNIX systems The invokable Transaction Program defined in the remote
| LU 6.2 configuration.
Windows NT As specified in the Windows NT Run Listener command, or
the invokable Transaction Program that was defined using
TpSetup on Windows NT.

If you have more than one queue manager on the same machine, ensure that the
TPnames in the channel definitions are unique.

Chapter 32. Setting up communication for MQSeries for AS/400 451

 Defining an LU 6.2 connection
Initiating end (Sending)
| Use the CRTMQMCHL command to define a channel of transport type *LU62. For
| versions previous to MQSeries for AS/400 V5.1, define the name of the CSI object
| that this channel will use in the CONNECTION NAME field. (See “Creating a
| channel” on page 426 for details of how to do this.) Use of the CSI object is
| optional in MQSeries for AS/400 V5.1.

The initiating end panel is shown in Figure Figure 109. You press F10 from the first
panel displayed to obtain the complete panel as shown.

Create Comm Side Information (CRTCSI)

Type choices, press Enter.

Side information . . . . . . . . > WINSDOA1 Name

Library . . . . . . . . . . . > QSYS Name, *CURLIB
Remote location . . . . . . . . > WINSDOA1 Name
Transaction program . . . . . . > MQSERIES

Text 'description' . . . . . . . *BLANK

Additional Parameters

Device . . . . . . . . . . . . . *LOC Name, *LOC

Local location . . . . . . . . . *LOC Name, *LOC, *NETATR
Mode . . . . . . . . . . . . . . JSTMOD92 Name, *NETATR
Remote network identifier . . . *LOC Name, *LOC, *NETATR, *NONE
Authority . . . . . . . . . . . *LIBCRTAUT Name, *LIBCRTAUT, *CHANGE...

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 109. LU 6.2 communication setup panel - initiating end

Complete the initiating end fields as follows:

Side information
Give this definition a name that will be used to store the side information
object to be created, for example, WINSDOA1.

Note: For LU 6.2, the link between the message channel definition and the
communication connection is the Connection name field of the
message channel definition at the sending end. This field contains
the name of the CSI object.
Library
The name of the library where this definition will be stored.
The CSI object must be available in a library accessible to the program
serving the message channel, for example, QSYS, QMQM, and QGPL.
If the name is incorrect, missing, or cannot be found then an error will
occur on channel start up.
Remote location
Specifies the remote location name with which your program
communicates.

452 MQSeries Intercommunication

 Defining an LU 6.2 connection
In short, this required parameter contains the logical unit name of the
partner at the remote system, as defined in the device description that is
used for the communication link between the two systems.
The Remote location name can be found by issuing the command
DSPNETA on the remote system and seeing the default local location
name.
Transaction program
Specifies the name (up to 64 characters) of the transaction program on the
remote system to be started. It may be a transaction process name, a
program name, the channel name, or a character string that matches the
Compare value in the routing entry.
This is a required parameter.

Note: To specify SNA service transaction program names, enter the

hexadecimal representation of the service transaction program name.
For example, to specify a service transaction program name whose
hexadecimal representation is 21F0F0F1, you would enter
X'21F0F0F1'.

More information on SNA service transaction program names is in the

SNA Transaction Programmer’s Reference manual for LU Type 6.2.

| If the receiving end is another OS/400 system, the Transaction program

| name is used to match the CSI object at the sending end with the routing
| entry at the receiving end. This should be unique for each queue manager
| on the target OS/400 system. (See the Program to call parameter under
| “Initiated end (Receiver)” on page 455.) See also the Comparison data:
| compare value parameter in the Add Routing Entry panel.
Text description
A description (up to 50 characters) to remind you of the intended use of
this connection.
Device
Specifies the name of the device description used for the remote system.
The possible values are:
*LOC The device is determined by the system.
Device-name
Specify the name of the device that is associated with the remote
location.
Local location
Specifies the local location name. The possible values are:
*LOC The local location name is determined by the system.
*NETATR
The LCLLOCNAME value specified in the system network
attributes is used.
Local-location-name
Specify the name of your location. Specify the local location if you
want to indicate a specific location name for the remote location.
The location name can be found by using the DSPNETA command.

Chapter 32. Setting up communication for MQSeries for AS/400 453

Defining an LU 6.2 connection
Mode Specifies the mode used to control the session. This name is the same as
the Common Programming Interface (CPI)- Communications Mode_Name.
The possible values are:
*NETATR
The mode in the network attributes is used.
BLANK
Eight blank characters are used.
Mode-name
Specify a mode name for the remote location.

Note: Because the mode determines the transmission priority of the

communications session, it may be useful to define different modes
depending on the priority of the messages being sent; for example
MQMODE_HI, MQMODE_MED, and MQMODE_LOW. (You can
have more than one CSI pointing to the same location.)
Remote network identifier
Specifies the remote network identifier used with the remote location. The
possible values are:
*LOC The remote network ID for the remote location is used.
*NETATR
The remote network identifier specified in the network attributes is
used.
*NONE
The remote network has no name.
Remote-network-id
Specify a remote network ID. Use the DSPNETA command at the
remote location to find the name of this network ID. It is the ‘local
network ID’ at the remote location.
Authority
Specifies the authority you are giving to users who do not have specific
authority to the object, who are not on an authorization list, and whose
group profile has no specific authority to the object. The possible values
are:
*LIBCRTAUT
Public authority for the object is taken from the CRTAUT
parameter of the specified library. This value is determined at
create time. If the CRTAUT value for the library changes after the
object is created, the new value does not affect existing objects.
*CHANGE
Change authority allows the user to perform basic functions on the
object, however, the user cannot change the object. Change
authority provides object operational authority and all data
authority.
*ALL The user can perform all operations except those limited to the
owner or controlled by authorization list management authority.
The user can control the object’s existence and specify the security
for the object, change the object, and perform basic functions on
the object. The user can change ownership of the object.

454 MQSeries Intercommunication

 Defining an LU 6.2 connection
*USE Use authority provides object operational authority and read
authority.
*EXCLUDE
Exclude authority prevents the user from accessing the object.
Authorization-list
Specify the name of the authorization list whose authority is used
for the side information.

Initiated end (Receiver)

Use the CRTMQMCHL command to define the receiving end of the message
channel link with transport type *LU62. Leave the CONNECTION NAME field
blank and ensure that the corresponding details match the sending end of the
channel. (See “Creating a channel” on page 426 for details of how to do this.)

To enable the initiating end to start the receiving channel, add a routing entry to a
subsystem at the initiated end. The subsystem must be the one that allocates the
APPC device used in the LU 6.2 sessions and, therefore, it must have a valid
communications entry for that device. The routing entry calls the program that
starts the receiving end of the message channel.

Use the OS/400 commands (for example, ADDRTGE) to define the end of the link
that is initiated by a communication session.

The initiated end panel is shown in Figure Figure 110.

Add Routing Entry (ADDRTGE)

Type choices, press Enter.

Subsystem description . . . . . QCMN Name

Library . . . . . . . . . . . *LIBL Name, *LIBL, *CURLIB
Routing entry sequence number . 1 1-9999
Comparison data:
Compare value . . . . . . . . MQSERIES

Starting position . . . . . . 37 1-80

Program to call . . . . . . . . AMQCRC6A Name, *RTGDTA
Library . . . . . . . . . . . QMQMBW Name, *LIBL, *CURLIB
Class . . . . . . . . . . . . . *SBSD Name, *SBSD
Library . . . . . . . . . . . *LIBL Name, *LIBL, *CURLIB
Maximum active routing steps . . *NOMAX 0-1000, *NOMAX
Storage pool identifier . . . . 1 1-10

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 110. LU 6.2 communication setup panel - initiated end

Subsystem description
The name of your subsystem where this definition resides. Use the OS/400
WRKSBSD command to view and update the appropriate subsystem
description for the routing entry.

Chapter 32. Setting up communication for MQSeries for AS/400 455

 Defining an LU 6.2 connection
Routing entry sequence number
A unique number in your subsystem to identify this communication
definition. You can use values in the range 1 to 9999.
Comparison data: Compare value
A text string to compare with that received when the session is started by
a Transaction program parameter, as shown in Figure 109 on page 452. The
character string is derived from the Transaction program field of the sender
CSI.
Comparison data: Starting position
The character position in the string where the comparison is to start.

Note: The starting position field is the character position in the string for
comparison, and this is always 37.
Program to call
| The name of the program that runs the inbound message program to be
| called to start the session.
| The program, AMQCRC6A, is called for the default queue manager. This is
| a program supplied with MQSeries for AS/400 that sets up the
| environment and then calls AMQCRS6A.
| For additional queue managers:
| v Each queue manager has a specific LU 6.2 invokable program located in
| its library. This program is called AMQCRC6B and is automatically
| generated when the queue manager is created.
| v Each queue manager requires a specific routing entry with unique
| routing data to be added. This routing data should match the
| Transaction program name supplied by the requesting system (see
| “Initiating end (Sending)” on page 452).

| An example of this is shown in Figure111:

Display Routing Entries

System: MY400
Subsystem description: QCMN Status: ACTIVE

Type options, press Enter.

5=Display details

Start
Opt Seq Nbr Program Library Compare Value Pos
10 *RTGDTA 'QZSCSRVR' 37
20 *RTGDTA 'QZRCSRVR' 37
30 *RTGDTA 'QZHQTRG' 37
50 *RTGDTA 'QVPPRINT' 37
60 *RTGDTA 'QNPSERVR' 37
70 *RTGDTA 'QNMAPINGD' 37
80 QNMAREXECD QSYS 'AREXECD' 37
90 AMQCRC6A QMQMBW 'MQSERIES' 37
100 *RTGDTA 'QTFDWNLD' 37
150 *RTGDTA 'QMFRCVR' 37

F3=Exit F9=Display all detailed descriptions F12=Cancel

Figure 111. LU 6.2 communication setup panel - initiated end

456 MQSeries Intercommunication

 Defining an LU 6.2 connection
| In Figure 111 sequence number 90 represents the default queue manager
| and provides compatibility with configurations from previous releases (that
| is, V3R2, V3R6, V3R7, and V4R2) of MQSeries for AS/400. These releases
| allow one queue manager only. Sequence numbers 92 and 94 represent two
| additional queue managers called ALPHA and BETA that are created with
| libraries QMALPHA and QMBETA.

| Note: You can have more than one routing entry for each queue manager
| by using different routing data. This gives the option of different job
| priorities depending on the classes used.
| Class The name and library of the class used for the steps started through this
routing entry. The class defines the attributes of the routing step’s running
environment and specifies the job priority. An appropriate class entry must
be specified. Use, for example, the WRKCLS command to display existing
classes or to create a new class. Further information on managing work
requests from remote LU 6.2 systems is available in the AS/400
Programming: Work Management Guide.

| Note on Work Management

| The AMQCRS6A job will not be able to take advantage of the normal AS/400 work
| management features that are documented in the MQSeries for AS/400 V5.1 System
| Administration book because it is not started in the same way as other MQSeries
| jobs. To change the run-time properties of the LU62 receiver jobs, you can do one
| of the following:
| v Alter the class description that is specified on the routing entry for the
| AMQCRS6A job
| v Change the job description on the communications entry
| See the AS/400 Programming: Work Management Guide for more information about
| configuring Communication Jobs.

Chapter 32. Setting up communication for MQSeries for AS/400 457

DQM in MQSeries for AS/400

458 MQSeries Intercommunication

 Chapter 33. Example configuration - IBM MQSeries for AS/400
This chapter gives an example of how to set up communication links from
MQSeries for AS/400 to MQSeries products on the following platforms:
v OS/2
v Windows NT
v AIX
| v Digital UNIX
v HP-UX
v AT&T GIS UNIX8
v Sun Solaris
v OS/390 or MVS/ESA without CICS
v VSE/ESA

First it describes the parameters needed for an LU 6.2 connection, then it describes
“Establishing an LU 6.2 connection” on page 464 and “Establishing a TCP
connection” on page 469.

Once the connection is established, you need to define some channels to complete
the configuration. This is described in “MQSeries for AS/400 configuration” on
page 471.

See “Chapter 7. Example configuration chapters in this book” on page 97 for

background information about this chapter and how to use it.

Configuration parameters for an LU 6.2 connection

Table 42 on page 460 presents a worksheet listing all the parameters needed to set
up communication from OS/400 to one of the other MQSeries platforms. The
worksheet shows examples of the parameters, which have been tested in a
working environment, and leaves space for you to fill in your own values. An
explanation of the parameter names follows the worksheet. Use the worksheet in
this chapter in conjunction with the worksheet in the chapter for the platform to
which you are connecting.

Configuration worksheet
Use the following worksheet to record the values you will use for this
configuration. Where numbers appear in the Reference column they indicate that
the value must match that in the appropriate worksheet elsewhere in this book.
The examples that follow in this chapter refer back to the values in the ID column
of this table. The entries in the Parameter Name column are explained in
“Explanation of terms” on page 462.

8. This platform has become NCR UNIX SVR4 MP-RAS, R3.0

© Copyright IBM Corp. 1993, 2000 459

OS/400 and LU 6.2
Table 42. Configuration worksheet for SNA on an AS/400 system
ID Parameter Name Reference Example Used User Value
Definition for local node
«1¬ Local network ID NETID
«2¬ Local control point name AS400PU
«3¬ LU name AS400LU
«4¬ LAN destination address 10005A5962EF
«5¬ Subsystem description QCMN
«6¬ Line description TOKENRINGL
«7¬ Resource name LIN041
«8¬ Local Transaction Program name MQSERIES
Connection to an OS/2 system

The values in this section must match those used in Table 14 on page 138, as indicated.
«9¬ Network ID «2¬ NETID
«10¬ Control point name «3¬ OS2PU
«11¬ LU name «6¬ OS2LU
«12¬ Controller description OS2PU
«13¬ Device OS2LU
«14¬ Side information OS2CPIC
«15¬ Transaction Program «8¬ MQSERIES
«16¬ LAN adapter address «10¬ 10005AFC5D83
«17¬ Mode «17¬ #INTER
Connection to a Windows NT system

The values in this section must match those used in Table 16 on page 170, as indicated.
«9¬ Network ID «2¬ NETID
«10¬ Control point name «3¬ WINNTCP
«11¬ LU name «5¬ WINNTLU
«12¬ Controller description WINNTCP
«13¬ Device WINNTLU
«14¬ Side information NTCPIC
«15¬ Transaction Program «7¬ MQSERIES
«16¬ LAN adapter address «9¬ 08005AA5FAB9
«17¬ Mode «17¬ #INTER
Connection to an AIX system

The values in this section must match those used in Table 20 on page 197, as indicated.
«9¬ Network ID «1¬ NETID
«10¬ Control point name «2¬ AIXPU
«11¬ LU name «4¬ AIXLU
«12¬ Controller description AIXPU
«13¬ Device AIXLU
«14¬ Side information AIXCPIC
«15¬ Transaction Program «6¬ MQSERIES
«16¬ LAN adapter address «8¬ 123456789012
«17¬ Mode «14¬ #INTER
Connection to an HP-UX system

The values in this section must match those used in Table 23 on page 219, as indicated.

460 MQSeries Intercommunication

 OS/400 and LU 6.2
Table 42. Configuration worksheet for SNA on an AS/400 system (continued)
ID Parameter Name Reference Example Used User Value
«9¬ Network ID «4¬ NETID
«10¬ Control point name «2¬ HPUXPU
«11¬ LU name «5¬ HPUXLU
«12¬ Controller description HPUXPU
«13¬ Device HPUXLU
«14¬ Side information HPUXCPIC
«15¬ Transaction Program «7¬ MQSERIES
«16¬ LAN adapter address «8¬ 100090DC2C7C
«17¬ Mode «17¬ #INTER
Connection to an AT&T GIS UNIX system

The values in this section must match those used in Table 25 on page 243, as indicated.
«9¬ Network ID «2¬ NETID
«10¬ Control point name «3¬ GISPU
«11¬ LU name «4¬ GISLU
«12¬ Controller description GISPU
«13¬ Device GISLU
«14¬ Side information GISCPIC
«15¬ Transaction Program «5¬ MQSERIES
«16¬ LAN adapter address «8¬ 10007038E86B
«17¬ Mode «15¬ #INTER
Connection to a Sun Solaris system

The values in this section must match those used in Table 27 on page 257, as indicated.
«9¬ Network ID «2¬ NETID
«10¬ Control point name «3¬ SOLARPU
«11¬ LU name «7¬ SOLARLU
«12¬ Controller description SOLARPU
«13¬ Device SOLARLU
«14¬ Side information SOLCPIC
«15¬ Transaction Program «8¬ MQSERIES
«16¬ LAN adapter address «5¬ 08002071CC8A
«17¬ Mode «17¬ #INTER
Connection to an OS/390 or MVS/ESA system without CICS

The values in this section must match those used in Table 36 on page 396, as indicated.
«9¬ Network ID «2¬ NETID
«10¬ Control point name «3¬ MVSPU
«11¬ LU name «4¬ MVSLU
«12¬ Controller description MVSPU
«13¬ Device MVSLU
«14¬ Side information MVSCPIC
«15¬ Transaction Program «7¬ MQSERIES
«16¬ LAN adapter address «8¬ 400074511092
«17¬ Mode «6¬ #INTER
Connection to a VSE/ESA system

The values in this section must match those used in Table 44 on page 485, as indicated.

Chapter 33. Example configuration - IBM MQSeries for AS/400 461

OS/400 and LU 6.2
Table 42. Configuration worksheet for SNA on an AS/400 system (continued)
ID Parameter Name Reference Example Used User Value
«9¬ Network ID «1¬ NETID
«10¬ Control point name «2¬ VSEPU
«11¬ LU name «3¬ VSELU
«12¬ Controller description VSEPU
«13¬ Device VSELU
«14¬ Side information VSECPIC
«15¬ Transaction Program «4¬ MQ01 MQ01
«16¬ LAN adapter address «5¬ 400074511092
«17¬ Mode #INTER

Explanation of terms
«1¬ «2¬ «3¬
See “How to find network attributes” on page 463 for the details of how to
find the configured values.
«4¬ LAN destination address
The hardware address of the AS/400 system token-ring adapter. You can
find the value using the command DSPLIND Line description («6¬).
«5¬ Subsystem description
This is the name of any OS/400 subsystem that will be active while using
the queue manager. The name QCMN has been used because this is the
OS/400 communications subsystem.
«6¬ Line description
If this has been specified it is indicated in the Description field of the
resource Resource name. See “How to find the value of Resource name” on
page 463 for details. If the value is not specified you will need to create a
line description.
«7¬ Resource name
See “How to find the value of Resource name” on page 463 for details of
how to find the configured value.
«8¬ Local Transaction Program name
MQSeries applications trying to converse with this workstation will specify
a symbolic name for the program to be run at the receiving end. This will
have been defined on the channel definition at the sender. For simplicity,
wherever possible use a transaction program name of MQSERIES, or in the
case of a connection to VSE/ESA, where the length is limited to 4 bytes,
use MQTP.
See Table 41 on page 451 for more information.
«12¬ Controller description
This is an alias for the Control Point name (or Node name) of the partner
system. For convenience we have used the actual name of the partner in
this example.
«13¬ Device
This is an alias for the LU of the partner system. For convenience we have
used the LU name of the partner in this example.

462 MQSeries Intercommunication

 OS/400 and LU 6.2
«14¬ Side information
This is the name given to the CPI-C side information profile. You specify
your own 8-character name for this.

How to find network attributes

The local node has been partially configured as part of the OS/400 installation. To
display the current network attributes enter the command DSPNETA.

If you need to change these values use the command CHGNETA. An IPL may be
required to apply your changes.

Display Network Attributes

System: AS400PU
Current system name . . . . . . . . . . . . . . : AS400PU
Pending system name . . . . . . . . . . . . . :
Local network ID . . . . . . . . . . . . . . . . : NETID
Local control point name . . . . . . . . . . . . : AS400PU
Default local location . . . . . . . . . . . . . : AS400LU
Default mode . . . . . . . . . . . . . . . . . . : BLANK
APPN node type . . . . . . . . . . . . . . . . . : *ENDNODE
Data compression . . . . . . . . . . . . . . . . : *NONE
Intermediate data compression . . . . . . . . . : *NONE
Maximum number of intermediate sessions . . . . : 200
Route addition resistance . . . . . . . . . . . : 128
Server network ID/control point name . . . . . . : NETID NETCP

More...
Press Enter to continue.

F3=Exit F12=Cancel

Check that the values for Local network ID («1¬), Local control point name («2¬),
and Default local location («3¬), correspond to the values on your worksheet.

How to find the value of Resource name

Type WRKHDWRSC TYPE(*CMN) and press Enter. The Work with Communication
Resources panel is displayed. The value for Resource name is found as the
Token-Ring Port. It is LIN041 in this example.

Chapter 33. Example configuration - IBM MQSeries for AS/400 463

OS/400 and LU 6.2

Work with Communication Resources

System: AS400PU
Type options, press Enter.
2=Edit 4=Remove 5=Work with configuration description
7=Add configuration description ...

Configuration
Opt Resource Description Type Description
CC02 2636 Comm Processor
LIN04 2636 LAN Adapter
LIN041 TOKENRINGL 2636 Token-Ring Port

Bottom
F3=Exit F5=Refresh F6=Print F11=Display resource addresses/statuses
F12=Cancel F23=More options

Establishing an LU 6.2 connection

This section describes how to establish an LU 6.2 connection.

Local node configuration

To configure the local node, you need to:
1. Create a line description
2. Add a routing entry

Creating a line description

1. If the line description has not already been created use the command
CRTLINTRN.
2. Specify values for Line description («6¬) and Resource name («7¬).

Create Line Desc (Token-Ring) (CRTLINTRN)

Type choices, press Enter.

Line description . . . . . . . . TOKENRINGL Name

Resource name . . . . . . . . . LIN041 Name, *NWID
NWI type . . . . . . . . . . . . *FR *FR, *ATM
Online at IPL . . . . . . . . . *YES *YES, *NO
Vary on wait . . . . . . . . . . *NOWAIT *NOWAIT, 15-180 (1 second)
Maximum controllers . . . . . . 40 1-256
Attached NWI . . . . . . . . . . *NONE Name, *NONE

Bottom
F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel
F13=How to use this display F24=More keys
Parameter LIND required. +

464 MQSeries Intercommunication

 OS/400 and LU 6.2
Adding a routing entry
1. Type the command ADDRTGE and press Enter.

Add Routing Entry (ADDRTGE)

Type choices, press Enter.

Subsystem description . . . . . QCMN Name

Library . . . . . . . . . . . *LIBL Name, *LIBL, *CURLIB
Routing entry sequence number . 1 1-9999
Comparison data:
Compare value . . . . . . . . 'MQSERIES'

Starting position . . . . . . 37 1-80

Program to call . . . . . . . . AMQCRC6A Name, *RTGDTA
Library . . . . . . . . . . . QMQMBW Name, *LIBL, *CURLIB
Class . . . . . . . . . . . . . *SBSD Name, *SBSD
Library . . . . . . . . . . . *LIBL Name, *LIBL, *CURLIB
Maximum active routing steps . . *NOMAX 0-1000, *NOMAX
Storage pool identifier . . . . 1 1-10

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
Parameter SBSD required. +

2. Specify your value for Subsystem description («5¬), and the values shown here
for Routing entry sequence number, Compare value («8¬), Starting position,
Program to call, and the Library containing the program to call.
3. Type the command STRSBS subsystem description («5¬) and press Enter.

Connection to partner node

This example is for a connection to an OS/2 system, but the steps are the same for
other nodes. The steps are:
1. Create a controller description.
2. Create a device description.
3. Create CPI-C side information.
4. Add a communications entry for APPC.
5. Add a configuration list entry.

Creating a controller description

1. At a command line type CRTCTLAPPC and press Enter.

Chapter 33. Example configuration - IBM MQSeries for AS/400 465

OS/400 and LU 6.2

Create Ctl Desc (APPC) (CRTCTLAPPC)

Type choices, press Enter.

Controller description . . . . . OS2PU Name

Link type . . . . . . . . . . . *LAN *FAX, *FR, *IDLC,
*LAN...
Online at IPL . . . . . . . . . *NO *YES, *NO

Bottom
F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel
F13=How to use this display F24=More keys
Parameter CTLD required. +

2. Specify a value for Controller description («12¬), set Link type to *LAN, and set
Online at IPL to *NO.
3. Press Enter twice, followed by F10.

Create Ctl Desc (APPC) (CRTCTLAPPC)

Type choices, press Enter.

Controller description . . . . . > OS2PU Name

Link type . . . . . . . . . . . > *LAN *FAX, *FR, *IDLC, *LAN...
Online at IPL . . . . . . . . . > *NO *YES, *NO
APPN-capable . . . . . . . . . . *YES *YES, *NO
Switched line list . . . . . . . TOKENRINGL Name
+ for more values
Maximum frame size . . . . . . . *LINKTYPE 265-16393, 256, 265, 512...
Remote network identifier . . . NETID Name, *NETATR, *NONE, *ANY
Remote control point . . . . . . OS2PU Name, *ANY
Exchange identifier . . . . . . 00000000-FFFFFFFF
Initial connection . . . . . . . *DIAL *DIAL, *ANS
Dial initiation . . . . . . . . *LINKTYPE *LINKTYPE, *IMMED, *DELAY
LAN remote adapter address . . . 10005AFC5D83 000000000001-FFFFFFFFFFFF
APPN CP session support . . . . *YES *YES, *NO
APPN node type . . . . . . . . . *ENDNODE *ENDNODE, *LENNODE...
APPN transmission group number 1 1-20, *CALC
More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

4. Specify values for Switched line list («6¬), Remote network identifier («9¬),
Remote control point («10¬), and LAN remote adapter address («16¬).
5. Press Enter.

Creating a device description

1. Type the command CRTDEVAPPC and press Enter.

466 MQSeries Intercommunication

 OS/400 and LU 6.2

Create Device Desc (APPC) (CRTDEVAPPC)

Type choices, press Enter.

Device description . . . . . . . OS2LU Name

Remote location . . . . . . . . OS2LU Name
Online at IPL . . . . . . . . . *YES *YES, *NO
Local location . . . . . . . . . AS400LU Name, *NETATR
Remote network identifier . . . NETID Name, *NETATR, *NONE
Attached controller . . . . . . OS2PU Name
Mode . . . . . . . . . . . . . . *NETATR Name, *NETATR
+ for more values
Message queue . . . . . . . . . QSYSOPR Name, QSYSOPR
Library . . . . . . . . . . . *LIBL Name, *LIBL, *CURLIB
APPN-capable . . . . . . . . . . *YES *YES, *NO
Single session:
Single session capable . . . . *NO *NO, *YES
Number of conversations . . . 1-512

Bottom
F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel
F13=How to use this display F24=More keys
Parameter DEVD required. +

2. Specify values for Device description («13¬), Remote location («11¬), Local
location («3¬), Remote network identifier («9¬), and Attached controller
(«12¬).

Note: You can avoid having to create controller and device descriptions manually
by taking advantage of OS/400’s auto-configuration service. Consult the
OS/400 documentation for details.

Creating CPI-C side information

1. Type CRTCSI and press F10.

Create Comm Side Information (CRTCSI)

Type choices, press Enter.

Side information . . . . . . . . OS2CPIC Name

Library . . . . . . . . . . . *CURLIB Name, *CURLIB
Remote location . . . . . . . . OS2LU Name
Transaction program . . . . . . MQSERIES

Text 'description' . . . . . . . *BLANK

Additional Parameters

Device . . . . . . . . . . . . . *LOC Name, *LOC

Local location . . . . . . . . . AS400LU Name, *LOC, *NETATR
Mode . . . . . . . . . . . . . . #INTER Name, *NETATR
Remote network identifier . . . NETID Name, *LOC, *NETATR, *NONE
Authority . . . . . . . . . . . *LIBCRTAUT Name, *LIBCRTAUT, *CHANGE...

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
Parameter CSI required.

2. Specify values for Side information («14¬), Remote location («11¬), Transaction
program («15¬), Local location («3¬), Mode, and Remote network identifier
(«9¬).
3. Press Enter.

Chapter 33. Example configuration - IBM MQSeries for AS/400 467

OS/400 and LU 6.2
Adding a communications entry for APPC
1. At a command line type ADDCMNE and press Enter.

Add Communications Entry (ADDCMNE)

Type choices, press Enter.

Subsystem description . . . . . QCMN Name

Library . . . . . . . . . . . *LIBL Name, *LIBL, *CURLIB
Device . . . . . . . . . . . . . OS2LU Name, generic*, *ALL...
Remote location . . . . . . . . Name
Job description . . . . . . . . *USRPRF Name, *USRPRF, *SBSD
Library . . . . . . . . . . . Name, *LIBL, *CURLIB
Default user profile . . . . . . *NONE Name, *NONE, *SYS
Mode . . . . . . . . . . . . . . *ANY Name, *ANY
Maximum active jobs . . . . . . *NOMAX 0-1000, *NOMAX

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
Parameter SBSD required.

2. Specify values for Subsystem description («5¬) and Device («13¬), and press
Enter.

Adding a configuration list entry

1. Type ADDCFGLE *APPNRMT and press F4.

Add Configuration List Entries (ADDCFGLE)

Type choices, press Enter.

Configuration list type . . . . > *APPNRMT *APPNLCL, *APPNRMT...

APPN remote location entry:
Remote location name . . . . . OS2LU Name, generic*, *ANY
Remote network identifier . . NETID Name, *NETATR, *NONE
Local location name . . . . . AS400LU Name, *NETATR
Remote control point . . . . . OS2PU Name, *NONE
Control point net ID . . . . . NETID Name, *NETATR, *NONE
Location password . . . . . . *NONE
Secure location . . . . . . . *NO *YES, *NO
Single session . . . . . . . . *NO *YES, *NO
Locally controlled session . . *NO *YES, *NO
Pre-established session . . . *NO *YES, *NO
Entry 'description' . . . . . *BLANK
Number of conversations . . . 10 1-512
+ for more values

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

2. Specify values for Remote location name («11¬), Remote network identifier
(«9¬), Local location name («3¬), Remote control point («10¬), and Control
point net ID («9¬).
3. Press Enter.

468 MQSeries Intercommunication

 OS/400 and LU 6.2
What next?
The LU 6.2 connection is now established. You are ready to complete the
configuration. Go to “MQSeries for AS/400 configuration” on page 471.

Establishing a TCP connection

If TCP is already configured there are no extra configuration tasks. The following
panels guide you through the steps that may be required if TCP/IP is not
configured.

Adding a TCP/IP interface

1. At a command line type ADDTCPIFC and press Enter.

Add TCP/IP Interface (ADDTCPIFC)

Type choices, press Enter.

Internet address . . . . . . . . 19.22.11.55

Line description . . . . . . . . TOKENRINGL Name, *LOOPBACK
Subnet mask . . . . . . . . . . 255.255.0.0
Type of service . . . . . . . . *NORMAL *MINDELAY, *MAXTHRPUT..
Maximum transmission unit . . . *LIND 576-16388, *LIND
Autostart . . . . . . . . . . . *YES *YES, *NO
PVC logical channel identifier 001-FFF
+ for more values
X.25 idle circuit timeout . . . 60 1-600
X.25 maximum virtual circuits . 64 0-64
X.25 DDN interface . . . . . . . *NO *YES, *NO
TRLAN bit sequencing . . . . . . *MSB *MSB, *LSB

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

2. Specify this machine’s Internet address and Line description, and a Subnet
mask.
3. Press Enter.

Adding a TCP/IP loopback interface

1. At a command line type ADDTCPIFC and press Enter.

Chapter 33. Example configuration - IBM MQSeries for AS/400 469

OS/400 and TCP

Add TCP Interface (ADDTCPIFC)

Type choices, press Enter.

Internet address . . . . . . . . 127.0.0.1

Line description . . . . . . . . *LOOPBACK Name, *LOOPBACK
Subnet mask . . . . . . . . . . 255.0.0.0
Type of service . . . . . . . . *NORMAL *MINDELAY, *MAXTHRPUT..
Maximum transmission unit . . . *LIND 576-16388, *LIND
Autostart . . . . . . . . . . . *YES *YES, *NO
PVC logical channel identifier 001-FFF
+ for more values
X.25 idle circuit timeout . . . 60 1-600
X.25 maximum virtual circuits . 64 0-64
X.25 DDN interface . . . . . . . *NO *YES, *NO
TRLAN bit sequencing . . . . . . *MSB *MSB, *LSB

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

2. Specify the values for Internet address, Line description, and Subnet mask.

Adding a default route

1. At a command line type ADDTCPRTE and press Enter.

Add TCP Route (ADDTCPRTE)

Type choices, press Enter.

Route destination . . . . . . . *DFTROUTE

Subnet mask . . . . . . . . . . *NONE
Type of service . . . . . . . . *NORMAL *MINDELAY, *MAXTHRPUT.
Next hop . . . . . . . . . . . . 19.2.3.4
Maximum transmission unit . . . 576 576-16388, *IFC

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
Command prompting ended when user pressed F12.

2. Fill in with values appropriate to your network and press Enter to create a
default route entry.

What next?
The TCP connection is now established. You are ready to complete the
configuration. Go to “MQSeries for AS/400 configuration” on page 471.

470 MQSeries Intercommunication

 OS/400 configuration

MQSeries for AS/400 configuration

Start the TCP channel listener using the command STRMQMLSR.

Start any sender channel using the command STRMQMCHL

CHLNAME(channel_name).

Use the WRKMQMQ command to display the MQSeries configuration menu.

Note: AMQ* errors are placed in the log relating to the job that found the error.
Use the WRKACTJOB command to display the list of jobs. Under the
subsystem name QSYSWRK, locate the job and enter 5 against it to work
with that job. MQSeries logs are prefixed ‘AMQ’.

Basic configuration
1. First you need to create a queue manager. To do this, type CRTMQM and press
Enter.

Create Message Queue Manager (CRTMQM)

Type choices, press Enter.

Message Queue Manager name . . .

Text 'description' . . . . . . . *BLANK

Trigger interval . . . . . . . . 999999999 0-999999999

Undelivered message queue . . . *NONE

Default transmission queue . . . *NONE

Maximum handle limit . . . . . . 256 1-999999999

Maximum uncommitted messages . . 1000 1-10000
Default Queue manager . . . . . *NO *YES, *NO

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

2. In the Message Queue Manager name field, type AS400. In the Undelivered
message queue field, type DEAD.LETTER.QUEUE.
3. Press Enter.
4. Now start the queue manager by entering STRMQM MQMNAME(AS400).
5. Create the undelivered message queue using the following parameters. (For
details and an example refer to “Defining a queue” on page 475.)
Local Queue
Queue name : DEAD.LETTER.QUEUE
Queue type : *LCL

Channel configuration
This section details the configuration to be performed on the OS/400 queue
manager to implement the channel described in Figure 32 on page 97.

Chapter 33. Example configuration - IBM MQSeries for AS/400 471

OS/400 configuration
Examples are given for connecting MQSeries for AS/400 and MQSeries for OS/2
Warp. If you wish connect to another MQSeries product, use the appropriate
values from the table in place of those for OS/2.
Notes:
1. The words in bold are user-specified and reflect the names of MQSeries objects
used throughout these examples. If you change the names used here, ensure
that you also change the other references made to these objects throughout this
book. All others are keywords and should be entered as shown.
2. The MQSeries channel ping command (PNGMQMCHL) runs interactively,
whereas starting a channel causes a batch job to be submitted. If a channel ping
completes successfully but the channel will not start, this indicates that the
network and MQSeries definitions are probably correct, but that the OS/400
environment for the batch job is not. For example, make sure that QSYS2 is
included in the system portion of the library list and not just your personal
library list.

For details and examples of how to create the objects listed refer to “Defining a
queue” on page 475 and “Defining a channel” on page 476.
Table 43. Configuration worksheet for MQSeries for AS/400
ID Parameter Name Reference Example Used User Value
Definition for local node
«A¬ Queue Manager Name AS400
«B¬ Local queue name AS400.LOCALQ
Connection to MQSeries for OS/2 Warp

The values in this section of the table must match those used in Table 15 on page 164, as indicated.
«C¬ Remote queue manager name «A¬ OS2
«D¬ Remote queue name OS2.REMOTEQ
«E¬ Queue name at remote system «B¬ OS2.LOCALQ
«F¬ Transmission queue name OS2
«G¬ Sender (SNA) channel name AS400.OS2.SNA
«H¬ Sender (TCP) channel name AS400.OS2.TCP
«I¬ Receiver (SNA) channel name «G¬ OS2.AS400.SNA
«J¬ Receiver (TCP) channel name «H¬ OS2.AS400.TCP
Connection to MQSeries for Windows NT

The values in this section of the table must match those used in Table 17 on page 185, as indicated.
«C¬ Remote queue manager name «A¬ WINNT
«D¬ Remote queue name WINNT.REMOTEQ
«E¬ Queue name at remote system «B¬ WINNT.LOCALQ
«F¬ Transmission queue name WINNT
«G¬ Sender (SNA) channel name AS400.WINNT.SNA
«H¬ Sender (TCP/IP) channel name AS400.WINNT.TCP
«I¬ Receiver (SNA) channel name «G¬ WINNT.AS400.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ WINNT.AS400.TCP
Connection to MQSeries for AIX

The values in this section of the table must match those used in Table 21 on page 211, as indicated.
«C¬ Remote queue manager name AIX
«D¬ Remote queue name AIX.REMOTEQ

472 MQSeries Intercommunication

 OS/400 configuration
Table 43. Configuration worksheet for MQSeries for AS/400 (continued)
ID Parameter Name Reference Example Used User Value
«E¬ Queue name at remote system «B¬ AIX.LOCALQ
«F¬ Transmission queue name AIX
«G¬ Sender (SNA) channel name AS400.AIX.SNA
«H¬ Sender (TCP/IP) channel name AS400.AIX.TCP
«I¬ Receiver (SNA) channel name «G¬ AIX.AS400.SNA
«J¬ Receiver (TCP) channel name «H¬ AIX.AS400.TCP
| Connection to MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| The values in this section of the table must match those used in Table 22 on page 216, as indicated.
| «C¬ Remote queue manager name DECUX
| «D¬ Remote queue name DECUX.REMOTEQ
| «E¬ Queue name at remote system «B¬ DECUX.LOCALQ
| «F¬ Transmission queue name DECUX
| «H¬ Sender (TCP) channel name DECUX.AS400.TCP
| «J¬ Receiver (TCP) channel name «H¬ AS400.DECUX.TCP
Connection to MQSeries for HP-UX

The values in this section of the table must match those used in Table 24 on page 239, as indicated.
«C¬ Remote queue manager name HPUX
«D¬ Remote queue name HPUX.REMOTEQ
«E¬ Queue name at remote system «B¬ HPUX.LOCALQ
«F¬ Transmission queue name HPUX
«G¬ Sender (SNA) channel name AS400.HPUX.SNA
«H¬ Sender (TCP) channel name AS400.HPUX.TCP
«I¬ Receiver (SNA) channel name «G¬ HPUX.AS400.SNA
«J¬ Receiver (TCP) channel name «H¬ HPUX.AS400.TCP
Connection to MQSeries for AT&T GIS UNIX

The values in this section of the table must match those used in Table 26 on page 253, as indicated.
«C¬ Remote queue manager name GIS
«D¬ Remote queue name GIS.REMOTEQ
«E¬ Queue name at remote system «B¬ GIS.LOCALQ
«F¬ Transmission queue name GIS
«G¬ Sender (SNA) channel name AS400.GIS.SNA
«H¬ Sender (TCP) channel name AS400.GIS.TCP
«I¬ Receiver (SNA) channel name «G¬ GIS.AS400.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ GIS.AS400.TCP
Connection to MQSeries for Sun Solaris

The values in this section of the table must match those used in Table 28 on page 272, as indicated.
«C¬ Remote queue manager name SOLARIS
«D¬ Remote queue name SOLARIS.REMOTEQ
«E¬ Queue name at remote system «B¬ SOLARIS.LOCALQ
«F¬ Transmission queue name SOLARIS
«G¬ Sender (SNA) channel name AS400.SOLARIS.SNA
«H¬ Sender (TCP/IP) channel name AS400.SOLARIS.TCP
«I¬ Receiver (SNA) channel name «G¬ SOLARIS.AS400.SNA
«J¬ Receiver (TCP/IP) channel name «H¬ SOLARIS.AS400.TCP

Chapter 33. Example configuration - IBM MQSeries for AS/400 473

OS/400 configuration
Table 43. Configuration worksheet for MQSeries for AS/400 (continued)
ID Parameter Name Reference Example Used User Value
Connection to MQSeries for OS/390 without CICS

The values in this section of the table must match those used in Table 37 on page 406, as indicated.
«C¬ Remote queue manager name MVS
«D¬ Remote queue name MVS.REMOTEQ
«E¬ Queue name at remote system «B¬ MVS.LOCALQ
«F¬ Transmission queue name MVS
«G¬ Sender (SNA) channel name AS400.MVS.SNA
«H¬ Sender (TCP) channel name AS400.MVS.TCP
«I¬ Receiver (SNA) channel name «G¬ MVS.AS400.SNA
«J¬ Receiver (TCP) channel name «H¬ MVS.AS400.TCP
Connection to MQSeries for VSE/ESA

The values in this section of the table must match those used in Table 45 on page 490, as indicated.
«C¬ Remote queue manager name VSE
«D¬ Remote queue name VSE.REMOTEQ
«E¬ Queue name at remote system «B¬ VSE.LOCALQ
«F¬ Transmission queue name VSE
«G¬ Sender channel name AS400.VSE.SNA
«I¬ Receiver channel name «G¬ VSE.AS400.SNA

MQSeries for AS/400 sender-channel definitions using SNA

Local Queue
Queue name : OS2 «F¬
Queue type : *LCL
Usage : *TMQ

Remote Queue
Queue name : OS2.REMOTEQ «D¬
Queue type : *RMT
Remote queue : OS2.LOCALQ «E¬
Remote Queue Manager : OS2 «C¬
Transmission queue : OS2 «F¬

Sender Channel
Channel Name : AS400.OS2.SNA «G¬
Channel Type : *SDR
Transport type : *LU62
Connection name : OS2CPIC «14¬
Transmission queue : OS2 «F¬

MQSeries for AS/400 receiver-channel definitions using SNA

Local Queue
Queue name : AS400.LOCALQ «B¬
Queue type : *LCL

Receiver Channel
Channel Name : OS2.AS400.SNA «I¬
Channel Type : *RCVR
Transport type : *LU62

474 MQSeries Intercommunication

 OS/400 configuration
MQSeries for AS/400 sender-channel definitions using TCP
Local Queue
Queue name : OS2 «F¬
Queue type : *LCL
Usage : *TMQ

Remote Queue
Queue name : OS2.REMOTEQ «D¬
Queue type : *RMT
Remote queue : OS2.LOCALQ «E¬
Remote Queue Manager : OS2 «C¬
Transmission queue : OS2 «F¬

Sender Channel
Channel Name : AS400.OS2.TCP «H¬
Channel Type : *SDR
Transport type : *TCP
Connection name : os2.tcpip.hostname
Transmission queue : OS2 «F¬

MQSeries for AS/400 receiver-channel definitions using TCP

Local Queue
Queue name : AS400.LOCALQ «B¬
Queue type : *LCL

Receiver Channel
Channel Name : OS2.AS400.TCP «J¬
Channel Type : *RCVR
Transport type : *TCP

Defining a queue
Type CRTMQMQ on the command line.

Create MQM Queue (CRTMQMQ)

Type choices, press Enter.

Queue name . . . . . . . . . . .

Queue type . . . . . . . . . . . *ALS, *LCL, *RMT

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
Parameter QNAME required.

Fill in the two fields of this panel and press Enter. This causes another panel to
appear, with entry fields for the other parameters you have. Defaults can be taken
for all other queue attributes.

Chapter 33. Example configuration - IBM MQSeries for AS/400 475

OS/400 configuration
Defining a channel
Type CRTMQMCHL on the command line.

Create MQM Channel (CRTMQMCHL)

Type choices, press Enter.

Channel name . . . . . . . . . .
Channel type . . . . . . . . . . *RCVR, *SDR, *SVR, *RQSTR

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
Parameter CHLNAME required.

Fill in the two fields of this panel and press Enter. Another panel is displayed on
which you can specify the values for the other parameters given earlier. Defaults
can be taken for all other channel attributes.

476 MQSeries Intercommunication

Chapter 34. Message channel planning example for OS/400
This chapter provides a detailed example of how to connect two OS/400 queue
managers together so that messages can be sent between them. The example
illustrates the preparations needed to allow an application using queue manager
QM1 to put messages on a queue at queue manager QM2. An application running
on QM2 can retrieve these messages, and send responses to a reply queue on QM1.

The example illustrates the use of TCP/IP connections. The example assumes that
channels are to be triggered to start when the first message arrives on the
transmission queue they are servicing. You must start the channel initiator in order
for triggering to work. To do this, use the STRMQMCHLI command.

This example uses SYSTEM.CHANNEL.INITQ as the initiation queue. This queue

is already defined by MQSeries. You can use a different initiation queue, but you
will have to define it yourself and specify the name of the queue when you start
the channel initiator.

What the example shows

The example uses the MQSeries for AS/400 command language.

Application Queue manager 'QM1' Queue manager 'QM2' Application

Payroll Query
Payroll
query Queue remote 'PAYROLL.QUERY' processing
message
Channel
Query
Queue transmission 'QM2' QM1.TO.QM2 Queue local 'PAYROLL'
message

Reply
'SYSTEM.CHANNEL.INITQ' Queue transmission 'QM1'
message

Reply
Queue local 'PAYROLL.REPLY' QM2.TO.QM1 'SYSTEM.CHANNEL.INITQ'
message

Figure 112. The message channel example for MQSeries for AS/400

It involves a payroll query application connected to queue manager QM1 that

sends payroll query messages to a payroll processing application running on queue
manager QM2. The payroll query application needs the replies to its queries sent
back to QM1. The payroll query messages are sent from QM1 to QM2 on a
sender-receiver channel called QM1.TO.QM2, and the reply messages are sent back
from QM2 to QM1 on another sender-receiver channel called QM2.TO.QM1. Both
of these channels are triggered to start as soon as they have a message to send to
the other queue manager.

The payroll query application puts a query message to the remote queue
“PAYROLL.QUERY” defined on QM1. This remote queue definition resolves to the

© Copyright IBM Corp. 1993, 2000 477

 Planning example for OS/400
local queue “PAYROLL” on QM2. In addition, the payroll query application
specifies that the reply to the query is sent to the local queue “PAYROLL.REPLY”
on QM1. The payroll processing application gets messages from the local queue
“PAYROLL” on QM2, and sends the replies to wherever they are required; in this
case, local queue “PAYROLL.REPLY” on QM1.

Both queue managers are assumed to be running on OS/400. In the example

definitions, QM1 has a host address of 9.20.9.31 and is listening on port 1411, and
QM2 has a host address of 9.20.9.32 and is listening on port 1412. The example
assumes that these are already defined on your OS/400 system, and are available
for use.

| The object definitions that need to be created on QM1 are:

| v Remote queue definition, PAYROLL.QUERY
| v Transmission queue definition, QM2 (default=remote queue manager name)
| v Process definition, QM1.TO.QM2.PROCESS (not needed for MQSeries for
| AS/400 V5.1)
| v Sender channel definition, QM1.TO.QM2
| v Receiver channel definition, QM2.TO.QM1
| v Reply-to queue definition, PAYROLL.REPLY

| The object definitions that need to be created on QM2 are:

| v Local queue definition, PAYROLL
| v Transmission queue definition, QM1 (default=remote queue manager name)
| v Process definition, QM2.TO.QM1.PROCESS (not needed for MQSeries for
| AS/400 V5.1)
| v Sender channel definition, QM2.TO.QM1
| v Receiver channel definition, QM1.TO.QM2

The connection details are supplied in the CONNAME attribute of the sender
channel definitions.

You can see a diagram of the arrangement in Figure 112 on page 477.

Queue manager QM1 example

The following object definitions allow applications connected to queue manager
QM1 to send request messages to a queue called PAYROLL on QM2, and to receive
replies on a queue called PAYROLL.REPLY on QM1.

All the object definitions have been provided with the TEXT attributes. The other
attributes supplied are the minimum required to make the example work. The
attributes that are not supplied take the default values for queue manager QM1.

Run the following commands on queue manager QM1:

Remote queue definition
The CRTMQMQ command with the following attributes:

QNAME ‘PAYROLL.QUERY’
QTYPE *RMT
TEXT ‘Remote queue for QM2’
PUTENBL *YES
TMQNAME ‘QM2’ (default = remote queue manager name)
RMTQNAME ‘PAYROLL’
RMTMQMNAME ‘QM2’

478 MQSeries Intercommunication

 Planning example for OS/400
Note: The remote queue definition is not a physical queue, but a means of
directing messages to the transmission queue, QM2, so that they can
be sent to queue manager QM2.
Transmission queue definition
The CRTMQMQ command with the following attributes:

QNAME QM2
QTYPE *LCL
TEXT ‘Transmission queue to QM2’
USAGE *TMQ
PUTENBL *YES
GETENBL *YES
TRGENBL *YES
TRGTYPE *FIRST
INITQNAME SYSTEM.CHANNEL.INITQ
PRCNAME QM1.TO.QM2.PROCESS

When the first message is put on this transmission queue, a trigger

message is sent to the initiation queue, SYSTEM.CHANNEL.INITQ. The
channel initiator gets the message from the initiation queue and starts the
channel identified in the named process.
Process definition
The CRTMQMPRC command with the following attributes:

PRCNAME QM1.TO.QM2.PROCESS
TEXT ‘Process for starting channel’
APPTYPE *OS400
APPID ‘AMQRMCLA’
USRDATA QM1.TO.QM2

The channel initiator uses this process information to start channel

| QM1.TO.QM2.

| Note: From MQSeries for AS/400 V5.1 onwards, the need for a process
| definition can be eliminated by specifying the channel name in the
| TRIGDATA attribute of the transmission queue.
| Sender channel definition
The CRTMQMCHL command with the following attributes:

CHLNAME QM1.TO.QM2
CHLTYPE *SDR
TRPTYPE *TCP
TEXT ‘Sender channel to QM2’
TMQNAME QM2
CONNAME ‘9.20.9.32(1412)’

Chapter 34. Message channel planning example for OS/400 479

Planning example for OS/400
Receiver channel definition
The CRTMQMCHL command with the following attributes:

CHLNAME QM2.TO.QM1
CHLTYPE *RCVR
TRPTYPE *TCP
TEXT ‘Receiver channel from QM2’

Reply-to queue definition

The CRTMQMQ command with the following attributes:

QNAME PAYROLL.REPLY
QTYPE *LCL
TEXT ‘Reply queue for replies to query messages sent to QM2’
PUTENBL *YES
GETENBL *YES

The reply-to queue is defined as PUT(ENABLED). This ensures that reply

messages can be put to the queue. If the replies cannot be put to the
reply-to queue, they are sent to the dead-letter queue on QM1 or, if this
queue is not available, remain on transmission queue QM1 on queue
manager QM2. The queue has been defined as GET(ENABLED) to allow
the reply messages to be retrieved.

Queue manager QM2 example

The following object definitions allow applications connected to queue manager
QM2 to retrieve request messages from a local queue called PAYROLL, and to put
replies to these request messages to a queue called PAYROLL.REPLY on queue
manager QM1.

You do not need to provide a remote queue definition to enable the replies to be
returned to QM1. The message descriptor of the message retrieved from local
queue PAYROLL contains both the reply-to queue and the reply-to queue manager
names. Therefore, as long as QM2 can resolve the reply-to queue manager name to
that of a transmission queue on queue manager QM2, the reply message can be
sent. In this example, the reply-to queue manager name is QM1 and so queue
manager QM2 simply requires a transmission queue of the same name.

All the object definitions have been provided with the TEXT attribute and are the
minimum required to make the example work. The attributes that are not supplied
take the default values for queue manager QM2.

Run the following commands on queue manager QM2:

Local queue definition
The CRTMQMQ command with the following attributes:

QNAME PAYROLL
QTYPE *LCL
TEXT ‘Local queue for QM1 payroll details’
PUTENBL *YES
GETENBL *YES

This queue is defined as PUT(ENABLED) and GET(ENABLED) for the

same reason as the reply-to queue definition on queue manager QM1.

480 MQSeries Intercommunication

 Planning example for OS/400
Transmission queue definition
The CRTMQMQ command with the following attributes:

QNAME QM1
QTYPE *LCL
TEXT ‘Transmission queue to QM1’
USAGE *TMQ
PUTENBL *YES
GETENBL *YES
TRGENBL *YES
TRGTYPE *FIRST
INITQNAME SYSTEM.CHANNEL.INITQ
PRCNAME QM2.TO.QM1.PROCESS

When the first message is put on this transmission queue, a trigger

message is sent to the initiation queue, SYSTEM.CHANNEL.INITQ. The
channel initiator gets the message from the initiation queue and starts the
channel identified in the named process.
Process definition
The CRTMQMPRC command with the following attributes:

PRCNAME QM2.TO.QM1.PROCESS
TEXT ‘Process for starting channel’
APPTYPE *OS400
APPID ‘AMQRMCLA’
USRDATA QM2.TO.QM1

The channel initiator uses this process information to start channel

| QM2.TO.QM1.

| Note: For MQSeries for AS/400 V5.1, the need for a process definition can
| be eliminated by specifying the channel name in the TRIGDATA
| attribute of the transmission queue.
| Sender channel definition
The CRTMQMCHL command with the following attributes:

CHLNAME QM2.TO.QM1
CHLTYPE *SDR
TRPTYPE *TCP
TEXT ‘Sender channel to QM1’
TMQNAME QM1
CONNAME ‘9.20.9.31(1411)’

Receiver channel definition

The CRTMQMCHL command with the following attributes:

CHLNAME QM1.TO.QM2
CHLTYPE *RCVR
TRPTYPE *TCP
TEXT ‘Receiver channel from QM1’

Chapter 34. Message channel planning example for OS/400 481

Planning example for OS/400

Running the example

When you have created the required objects, you must:
v Start the channel initiator for both queue managers
v Start the listener for both queue managers

The applications can then send messages to each other. The channels are triggered
to start by the first message arriving on each transmission queue, so you do not
need to issue the STRMQMCHL command.

For details about starting a channel initiator and a listener see “Chapter 30.
Monitoring and controlling channels in MQSeries for AS/400” on page 423.

Expanding this example

This example can be expanded by:
v Adding more queue, process, and channel definitions to allow other applications
to send messages between the two queue managers.
v Adding user exit programs on the channels to allow for link encryption, security
checking, or additional message processing.
v Using queue manager aliases and reply-to queue aliases to understand more
about how these can be used in the organization of your queue manager
network.

For a version of this example that uses MQSC commands, see “Chapter 25.
Message channel planning example for OS/390” on page 345.

482 MQSeries Intercommunication

Part 6. DQM in MQSeries for VSE/ESA
Chapter 35. Example configuration - MQSeries Configuring channels. . . . . . . . . . 490
for VSE/ESA . . . . . . . . . . . . . 485 MQSeries for VSE/ESA sender-channel
Configuration parameters for an LU 6.2 connection 485 definitions . . . . . . . . . . . . 492
Configuration worksheet . . . . . . . . 485 MQSeries for VSE/ESA receiver-channel
Explanation of terms . . . . . . . . . . 487 definitions . . . . . . . . . . . . 493
Establishing an LU 6.2 connection . . . . . . 488 Defining a local queue . . . . . . . . . 493
Defining a connection . . . . . . . . . 488 Defining a remote queue . . . . . . . . 495
Defining a session . . . . . . . . . . . 488 Defining a SNA LU 6.2 sender channel . . . . 497
Installing the new group definition . . . . . 489 Defining a SNA LU6.2 receiver channel. . . . 498
What next? . . . . . . . . . . . . . 489 Defining a TCP/IP sender channel . . . . . 500
Establishing a TCP connection. . . . . . . . 490 Defining a TCP receiver channel . . . . . . 501
MQSeries for VSE/ESA configuration . . . . . 490

This part of the book describes an example configuration for MQSeries for
VSE/ESA.

© Copyright IBM Corp. 1993, 2000 483

DQM in MQSeries for VSE/ESA

484 MQSeries Intercommunication

 Chapter 35. Example configuration - MQSeries for VSE/ESA
This chapter gives an example of how to set up communication links from
MQSeries for VSE/ESA to MQSeries products on the following platforms:
v OS/2
v Windows NT
v AIX
| v Digital UNIX
v HP-UX
v AT&T GIS UNIX9
v Sun Solaris
v OS/400
v OS/390 or MVS/ESA without CICS

It describes the parameters needed for an LU 6.2 and TCP connection. Once the
connection is established, you need to define some channels to complete the
configuration. This is described in “MQSeries for VSE/ESA configuration” on
page 490.

Configuration parameters for an LU 6.2 connection

Table 44 presents a worksheet listing all the parameters needed to set up
communication from VSE/ESA to one of the other MQSeries platforms. The
worksheet shows examples of the parameters, which have been tested in a
working environment, and leaves space for you to fill in your own values. An
explanation of the parameter names follows the worksheet. Use the worksheet in
this chapter in conjunction with the worksheet in the chapter for the platform to
which you are connecting.

Configuration worksheet
Use the following worksheet to record the values you will use for this
configuration. Where numbers appear in the Reference column they indicate that
the value must match that in the appropriate worksheet elsewhere in this book.
The examples that follow in this chapter refer back to the values in the ID column
of this table. The entries in the Parameter Name column are explained in
“Explanation of terms” on page 487.
Table 44. Configuration worksheet for VSE/ESA using APPC
ID Parameter Name Reference Example Used User Value
Definition for local node
«1¬ Network ID NETID
«2¬ Node name VSEPU
«3¬ Local LU name VSELU
«4¬ Local Transaction Program name MQ01 MQ01
«5¬ LAN destination address 400074511092
Connection to an OS/2 system

The values in this section of the table must match those used in the table for OS/2, as indicated.

9. This platform has become NCR UNIX SVR4 MP-RAS, R3.0

© Copyright IBM Corp. 1993, 2000 485

VSE/ESA and LU 6.2
Table 44. Configuration worksheet for VSE/ESA using APPC (continued)
ID Parameter Name Reference Example Used User Value
«6¬ Connection name OS2
«7¬ Group name EXAMPLE
«8¬ Session name OS2SESS
«9¬ Netname «6¬ OS2LU
Connection to a Windows NT system

The values in this section of the table must match those used in the table for Windows NT, as indicated.
«6¬ Connection name WNT
«7¬ Group name EXAMPLE
«8¬ Session name WNTSESS
«9¬ Netname «5¬ WINNTLU
Connection to an AIX system

The values in this section of the table must match those used in the table for AIX, as indicated.
«6¬ Connection name AIX
«7¬ Group name EXAMPLE
«8¬ Session name AIXSESS
«9¬ Netname «4¬ AIXLU
Connection to an HP-UX system

The values in this section of the table must match those used in the table for HP-UX, as indicated.
«6¬ Connection name HPUX
«7¬ Group name EXAMPLE
«8¬ Session name HPUXSESS
«9¬ Netname «5¬ HPUXLU
Connection to an AT&T GIS UNIX system

The values in this section of the table must match those used in the table for GIS UNIX, as indicated.
«6¬ Connection name GIS
«7¬ Group name EXAMPLE
«8¬ Session name GISSESS
«9¬ Netname «4¬ GISLU
Connection to a Sun Solaris system

The values in this section of the table must match those used in the table for Sun Solaris, as indicated.
«6¬ Connection name SOL
«7¬ Group name EXAMPLE
«8¬ Session name SOLSESS
«9¬ Netname «7¬ SOLARLU
Connection to an AS/400 system

The values in this section of the table must match those used in the table for AS/400, as indicated.
«6¬ Connection name AS4
«7¬ Group name EXAMPLE
«8¬ Session name AS4SESS
«9¬ Netname «3¬ AS400LU
Connection to an OS/390 or MVS/ESA system without CICS

The values in this section of the table must match those used in the table for OS/390, as indicated.
«6¬ Connection name MVS

486 MQSeries Intercommunication

 VSE/ESA and LU 6.2
Table 44. Configuration worksheet for VSE/ESA using APPC (continued)
ID Parameter Name Reference Example Used User Value
«7¬ Group name EXAMPLE
«8¬ Session name MVSSESS
«9¬ Netname «4¬ MVSLU

Explanation of terms
«1¬ Network ID
This is the unique ID of the network to which you are connected. Your
system administrator will tell you this value.
«2¬ Node name
This is the name of the SSCP which owns the CICS/VSE region.
«3¬ Local LU name
This is the unique VTAM APPLID of this CICS/VSE region.
«4¬ Transaction Program name
MQSeries applications trying to converse with this queue manager will
specify a transaction name for the program to be run at the receiving end.
This will have been defined on the channel definition at the sender.
MQSeries for VSE/ESA uses a name of MQ01.
«5¬ LAN destination address
This is the LAN destination address that your partner nodes will use to
communicate with this host. It is usually the address of the 3745 on the
same LAN as the partner node.
«6¬ Connection name
This is a 4-character name by which each connection will be individually
known in CICS RDO.
«7¬ Group name
You choose your own 8-character name for this value. Your system may
already have a group defined for connections to partner nodes. Your
system administrator will give you a value to use.
«8¬ Session name
This is an 8-character name by which each session will be individually
known. For clarity we use the connection name, concatenated with ’SESS’.
«9¬ Netname
This is the LU name of the MQSeries queue manager on the system with
which you are setting up communication.

Chapter 35. Example configuration - MQSeries for VSE/ESA 487

Establishing a connection

Establishing an LU 6.2 connection

This example is for a connection to an OS/2 system. The steps are the same
whatever platform you are using; change the values as appropriate.

Defining a connection
1. At a CICS command line type CEDA DEF CONN(connection name)
GROUP(group name) (where connection name is «6¬ and group name is «7¬). For
example:
CEDA DEF CONN(OS2) GROUP(EXAMPLE)
2. Press Enter to define a connection to CICS.

DEF CONN(OS2) GROUP(EXAMPLE)

OVERTYPE TO MODIFY
CEDA DEFine
Connection : OS2
Group : EXAMPLE
DEscription ==>
CONNECTION IDENTIFIERS
Netname ==> OS2LU
INDsys ==>
REMOTE ATTRIBUTES
REMOTESystem ==>
REMOTEName ==>
CONNECTION PROPERTIES
ACcessmethod ==> Vtam Vtam | IRc | INdirect | Xm
Protocol ==> Appc Appc | Lu61
SInglesess ==> No No | Yes
DAtastream ==> User User | 3270 | SCs | STrfield | Lms
RECordformat ==> U U | Vb
OPERATIONAL PROPERTIES
+ AUtoconnect ==> Yes No | Yes | All
I New group EXAMPLE created.

DEFINE SUCCESSFUL TIME: 16.49.30 DATE: 96.054

PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

3. On the panel change the Netname field in the CONNECTION IDENTIFIERS

section to be the LU name («9¬) of the target system.
4. In the CONNECTION PROPERTIES section set the ACcessmethod field to Vtam
and the Protocol to Appc.
5. Press Enter to make the change.

Defining a session
1. At a CICS command line type CEDA DEF SESS(session name)
GROUP(group name) (where session name is «8¬ and group name is «7¬). For
example:
CEDA DEF SESS(OS2SESS) GROUP(EXAMPLE)
2. Press Enter to define a session for the connection.

488 MQSeries Intercommunication

 Establishing a connection

DEF SESS(OS2SESS) GROUP(EXAMPLE)

OVERTYPE TO MODIFY
CEDA DEFine
Sessions ==> OS2SESS
Group ==> EXAMPLE
DEscription ==>
SESSION IDENTIFIERS
Connection ==> OS2
SESSName ==>
NETnameq ==>
MOdename ==> #INTER
SESSION PROPERTIES
Protocol ==> Appc Appc | Lu61
MAximum ==> 008 , 004 0-999
RECEIVEPfx ==>
RECEIVECount ==> 1-999
SENDPfx ==>
SENDCount ==> 1-999
SENDSize ==> 04096 1-30720
+ RECEIVESize ==> 04096 1-30720
S CONNECTION MUST BE SPECIFIED.

TIME: 14.23.19 DATE: 96.054

PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

3. In the SESSION IDENTIFIERS section of the panel specify the Connection name
(«6¬) in the Connection field and set the MOdename to #INTER.
4. In the SESSION PROPERTIES section set the Protocol to Appc and the
MAximum field to 008 , 004.

Installing the new group definition

1. At a CICS command line type CEDA INS GROUP(group name) «7¬.
2. Press Enter to install the new group definition.

Note: If this connection group is already in use you may get severe errors
reported. If this happens, take the existing connections out of service,
retry the above group installation, and then set the connections in service
using the following commands:
a. CEMT I CONN
b. CEMT S CONN(*) OUTS
c. CEDA INS GROUP(group name)
d. CEMT S CONN(*) INS

What next?
The LU 6.2 connection is now established. You are ready to complete the
configuration. Go to “MQSeries for VSE/ESA configuration” on page 490.

Chapter 35. Example configuration - MQSeries for VSE/ESA 489

TCP connection

Establishing a TCP connection

TCP connections do not require the configuration of additional profiles as does the
LU 6.2 protocol. Instead, MQSeries for VSE/ESA processes the MQSeries listener
program during MQSeries startup.

The MQSeries listener program waits for remote TCP connection requests. As these
are received, the listener starts the receiver MCA to process the remote connection.
When the remote connection is received from a client program, the receiver MCA
starts the MQSeries server program.

Note: There is one MQSeries server process for each client connection.

Provided that the MQSeries listener is active and TCP is active in a VSE partition,
TCP connections can be established.

MQSeries for VSE/ESA configuration

Configuring MQSeries for VSE/ESA involves the following tasks:
v Configuring channels
v Defining a local queue
v Defining a remote queue
v Defining a sender channel
v Defining a receiver channel

Configuring channels
Examples are given for connecting MQSeries for VSE/ESA and MQSeries for OS/2
Warp. If you wish connect to another MQSeries platform use the appropriate set of
values from the table in place of those for OS/2.

Note: The words in bold are user-specified and reflect the names of MQSeries
objects used throughout these examples. If you change the names used here,
ensure that you also change the other references made to these objects
throughout this book. All others are keywords and should be entered as
shown.

Refer to the sections “Defining a local queue” on page 493 and “Defining a remote
queue” on page 495 for details of how to create queue definitions, and “Defining a
SNA LU 6.2 sender channel” on page 497 and “Defining a SNA LU6.2 receiver
channel” on page 498 for details of how to create channels.
Table 45. Configuration worksheet for MQSeries for VSE/ESA
ID Parameter Name Reference Example Used User Value
Definition for local node
«A¬ Queue Manager Name VSE
«B¬ Local queue name VSE.LOCALQ
Connection to MQSeries for OS/2 Warp

The values in this section of the table must match those used in the worksheet table for OS/2, as indicated.
«C¬ Remote queue manager name «A¬ OS2
«D¬ Remote queue name OS2.REMOTEQ
«E¬ Queue name at remote system «B¬ OS2.LOCALQ
«F¬ Transmission queue name OS2
«G¬ Sender channel name VSE.OS2.SNA

490 MQSeries Intercommunication

 VSE/ESA configuration
Table 45. Configuration worksheet for MQSeries for VSE/ESA (continued)
ID Parameter Name Reference Example Used User Value
«I¬ Receiver channel name «G¬ OS2.VSE.SNA
Connection to MQSeries for Windows NT

The values in this section of the table must match those used in the worksheet table for Windows NT, as indicated.
«C¬ Remote queue manager name «A¬ WINNT
«D¬ Remote queue name WINNT.REMOTEQ
«E¬ Queue name at remote system «B¬ WINNT.LOCALQ
«F¬ Transmission queue name WINNT
«G¬ Sender channel name VSE.WINNT.SNA
«I¬ Receiver channel name «G¬ WINNT.VSE.SNA
Connection to MQSeries for AIX

The values in this section of the table must match those used in the worksheet table for AIX, as indicated.
«C¬ Remote queue manager name AIX
«D¬ Remote queue name AIX.REMOTEQ
«E¬ Queue name at remote system «B¬ AIX.LOCALQ
«F¬ Transmission queue name AIX
«G¬ Sender channel name VSE.AIX.SNA
«I¬ Receiver channel name «G¬ AIX.VSE.SNA
| Connection to MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| The values in this section of the table must match those used in the worksheet table for Digital UNIX, as indicated.
| «C¬ Remote queue manager name DECUX
| «D¬ Remote queue name DECUX.REMOTEQ
| «E¬ Queue name at remote system «B¬ DECUX.LOCALQ
| «F¬ Transmission queue name DECUX
| «H¬ Sender (TCP) channel name DECUX.VSE.TCP
| «I¬ Receiver channel name «J¬ VSE.DECUX.TCP
Connection to MQSeries for HP-UX

The values in this section of the table must match those used in the worksheet table for HP-UX, as indicated.
«C¬ Remote queue manager name HPUX
«D¬ Remote queue name HPUX.REMOTEQ
«E¬ Queue name at remote system «B¬ HPUX.LOCALQ
«F¬ Transmission queue name HPUX
«G¬ Sender channel name VSE.HPUX.SNA
«I¬ Receiver channel name «G¬ HPUX.VSE.SNA
Connection to MQSeries for AT&T GIS UNIX

The values in this section of the table must match those used in the worksheet table for GIS UNIX, as indicated.
«C¬ Remote queue manager name GIS
«D¬ Remote queue name GIS.REMOTEQ
«E¬ Queue name at remote system «B¬ GIS.LOCALQ
«F¬ Transmission queue name GIS
«G¬ Sender channel name VSE.GIS.SNA
«I¬ Receiver channel name «G¬ GIS.VSE.SNA
Connection to MQSeries for Sun Solaris

The values in this section of the table must match those used in the worksheet table for Sun Solaris, as indicated.

Chapter 35. Example configuration - MQSeries for VSE/ESA 491

VSE/ESA configuration
Table 45. Configuration worksheet for MQSeries for VSE/ESA (continued)
ID Parameter Name Reference Example Used User Value
«C¬ Remote queue manager name SOLARIS
«D¬ Remote queue name SOLARIS.REMOTEQ
«E¬ Queue name at remote system «B¬ SOLARIS.LOCALQ
«F¬ Transmission queue name SOLARIS
«G¬ Sender channel name VSE.SOLARIS.SNA
«I¬ Receiver channel name «G¬ SOLARIS.VSE.SNA
Connection to MQSeries for AS/400

The values in this section of the table must match those used in the worksheet table for AS/400, as indicated.
«C¬ Remote queue manager name AS400
«D¬ Remote queue name AS400.REMOTEQ
«E¬ Queue name at remote system «B¬ AS400.LOCALQ
«F¬ Transmission queue name AS400
«G¬ Sender channel name VSE.AS400.SNA
«I¬ Receiver channel name «G¬ AS400.VSE.SNA
Connection to MQSeries for OS/390 or MVS/ESA without CICS

The values in this section of the table must match those used in the worksheet table for OS/390, as indicated.
«C¬ Remote queue manager name MVS
«D¬ Remote queue name MVS.REMOTEQ
«E¬ Queue name at remote system «B¬ MVS.LOCALQ
«F¬ Transmission queue name MVS
«G¬ Sender channel name VSE.MVS.SNA
«I¬ Receiver channel name «G¬ MVS.VSE.SNA

For TCP, the sender channel name «G¬ and the receiver channel name «I¬, in the
preceding table, can be VSE.sys.tcp and sys.VSE.TCP respectively.

In both cases sys represents the remote system name, for example, OS2. Therefore,
in this case, «G¬ becomes VSE.OS2.TCP and «I¬ becomes OS2.VSE.TCP.

MQSeries for VSE/ESA sender-channel definitions

Local Queue
Object Type : L
Object Name : OS2 «F¬
Usage Mode: T (Transmission)

Remote Queue
Object Type : R
Object Name : OS2.REMOTEQ «D¬
Remote QUEUE Name : OS2.LOCALQ «E¬
Remote QM Name : OS2 «C¬
Transmission Name : OS2 «F¬

Sender Channel
Channel name : VSE.OS2.SNA «G¬
Channel type : S (Sender)
Transmission queue name : OS2 «F¬
Remote Task ID : MQTP
Connection name : OS2 «6¬

492 MQSeries Intercommunication

 VSE/ESA configuration
MQSeries for VSE/ESA receiver-channel definitions
Local Queue
Object type : QLOCAL
Object Name : VSE.LOCALQ «B¬
Usage Mode : N (Normal)

Receiver Channel
Channel name : OS2.VSE.SNA «I¬
Channel type : R (Receiver)

Defining a local queue

1. Run the MQSeries master terminal transaction MQMT.

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:50:25 *** Master Terminal Main Menu *** VSE1
MQMMTP A004
SYSTEM IS ACTIVE

1. Configuration

2. Operations

3. Monitoring

4. Browse Queue Records

Option:

Function completed - please enter a new request.

5686-A06 (C) Copyright IBM Corp. 1999 All Rights Reserved.
CLEAR/PF3 = Exit ENTER=Select

2. Select option 1 to configure.

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:52:21 *** Configuration Main Menu *** VSE1
MQMMCFG A004
SYSTEM IS ACTIVE

Maintenance Options :
1. Global System Definition
2. Queue Definitions
3. Channel Definitions

Display Options :
4. Global System Definition
5. Queue Definitions
6. Channel Definitions

Option:

Please enter one of the options listed.

5686-A06 (C) Copyright IBM Corp. 1999 All Rights Reserved.
ENTER = Process PF2 = Main Menu PF3 = Quit

Chapter 35. Example configuration - MQSeries for VSE/ESA 493

VSE/ESA configuration
3. Select option 2 to work with queue definitions.

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:55:12 Queue Main Options VSE1
MQMMQUE A004
SYSTEM IS ACTIVE

Default Q Manager : VSEP

Object Type: L L=Local Q, R=Remote Q, AQ=Alias Queue,

AM=Alias Manager,
AR=Alias Reply Q

Object Name: VSE.LOCALQ

ENTER NEEDED INFORMATION.

PF2=Main Config PF3 = Quit PF4/ENTER = Read PF5 = Add PF6 = Update
PF9 = List PF11= Reorg. PF12= Delete

4. Select an Object type of L and specify the name of the queue.

5. Press PF5.

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:56:10 Queue Definition Record VSE1
MQMMQUE QM - VSEP A004

LOCAL QUEUE DEFINITION

Object Name. . . . . . . . : VSE.LOCALQ

Description line 1 . . . . :
Description line 2 . . . . :

Put Enabled . . . . . . . : Y Y=Yes, N=No

Get Enabled . . . . . . . : Y Y=Yes, N=No

Default Inbound status . . : A Outbound .. : A A=Active,I=Inactive

Dual Update Queue . . . . .:

Automatic Reorganize (Y/N) : N

Record being added - Press ADD key again.

PF2=Main Config PF3 = Quit PF4/ENTER = Read PF5 = Add PF6 = Update
PF9 = List PF10= Queue PF11= Reorg. PF12= Delete

6. Press PF5 again.

494 MQSeries Intercommunication

 VSE/ESA configuration

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:57:26 Queue Extended Definition VSE1
MQMMQUE QM - VSEP A004
Object Name. . . . . . . . : VSE.LOCALQ
Physical Queue Information
Usage Mode . . . . . . . . : N N=Normal, T=Transmission
Share Mode . . . . . . . . : Y Y=Yes, N=No
Physical File Name . . . . : ** FILE NOT DEFINED
Maximum Values
Maximum Q Depth. . . . . . : 01000000 Global Lock Entries . : 00001000
Maximum Message Length . . : 01000000 Local Lock Entries. . : 00001000
Maximum Concurrent Accesses: 00000100 Checkpoint Threshold : 1000

Trigger Information
Trigger Enable . . . . . . : N Y=yes, N=No
Trigger Type . . . . . . : F=First, E=Every
Maximum Trigger Starts . . : 0001
Allow Restart of Trigger : N Y=Yes, N=No
Trans ID : Term ID:
Program ID : Channel Name:

***** File not found *****

PF2=Main Config PF3 = Quit PF4/ENTER = Read PF5 = Add PF6 = Update
PF9 = List PF10= Queue PF11= Reorg. PF12= Delete

7. Specify the name of a CICS file to store messages for this queue.
8. If you are creating a transmission queue, specify a Usage Mode of T, a Program
ID of MQPSEND, and a Channel Name<«G¬>.
For a normal queue specify a Usage Mode of N.
9. Press PF5 again.

Defining a remote queue

1. Run the MQSeries master terminal transaction MQMT.

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:50:25 *** Master Terminal Main Menu *** VSE1
MQMMTP A004
SYSTEM IS ACTIVE

1. Configuration

2. Operations

3. Monitoring

4. Browse Queue Records

Option:

Function completed - please enter a new request.

5686-A06 (C) Copyright IBM Corp. 1999 All Rights Reserved.
CLEAR/PF3 = Exit ENTER=Select

2. Select option 1 to configure.

Chapter 35. Example configuration - MQSeries for VSE/ESA 495

VSE/ESA configuration

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:52:21 *** Configuration Main Menu *** VSE1
MQMMCFG A004
SYSTEM IS ACTIVE

Maintenance Options :
1. Global System Definition
2. Queue Definitions
3. Channel Definitions

Display Options :
4. Global System Definition
5. Queue Definitions
6. Channel Definitions

Option:

Please enter one of the options listed.

5686-A06 (C) Copyright IBM Corp. 1999 All Rights Reserved.
ENTER = Process PF2 = Main Menu PF3 = Quit

3. Select option 2 to work with queue definitions.

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:59:30 Queue Main Options VSE1
MQMMQUE A004
SYSTEM IS ACTIVE

Default Q Manager : VSEP

Object Type: R L=Local Q, R=Remote Q, AQ=Alias Queue,

AM=Alias Manager,
AR=Alias Reply Q

Object Name: OS2.REMOTEQ

ENTER NEEDED INFORMATION.

PF2=Main Config PF3 = Quit PF4/ENTER = Read PF5 = Add PF6 = Update
PF9 = List PF11= Reorg. PF12= Delete

4. Select an Object type of R and specify the name of the queue.

5. Press PF5.

496 MQSeries Intercommunication

 VSE/ESA configuration

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

20:00:25 Queue Definition Record VSE1
MQMMQUE QM - VSEP A004

REMOTE QUEUE DEFINITION

Object Name. . . . . . . . : OS2.REMOTEQ

Description line 1 . . . . :
Description line 2 . . . . :

Put Enabled . . . . . . . : Y Y=Yes, N=No

Get Enabled . . . . . . . : Y Y=Yes, N=No

Remote Queue Name . . . . .: OS2.LOCALQ

Remote QM Name. . . . . . .: OS2
Transmission Q Name . . . .: OS2

Record being added - Press ADD key again.

PF2=Main Config PF3 = Quit PF4/ENTER = Read PF5 = Add PF6 = Update
PF9 = List PF10= Queue PF11= Reorg. PF12= Delete

6. Specify a remote queue name, remote queue manager name, and transmission
queue name.
7. Press PF5.

Defining a SNA LU 6.2 sender channel

1. Run the MQSeries master terminal transaction MQMT.

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:50:25 *** Master Terminal Main Menu *** VSE1
MQMMTP A004
SYSTEM IS ACTIVE

1. Configuration

2. Operations

3. Monitoring

4. Browse Queue Records

Option:

Function completed - please enter a new request.

5686-A06 (C) Copyright IBM Corp. 1999 All Rights Reserved.
CLEAR/PF3 = Exit ENTER=Select

2. Select option 1 to configure.

Chapter 35. Example configuration - MQSeries for VSE/ESA 497

VSE/ESA configuration

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:52:21 *** Configuration Main Menu *** VSE1
MQMMCFG A004
SYSTEM IS ACTIVE

Maintenance Options :
1. Global System Definition
2. Queue Definitions
3. Channel Definitions

Display Options :
4. Global System Definition
5. Queue Definitions
6. Channel Definitions

Option:

Please enter one of the options listed.

5686-A06 (C) Copyright IBM Corp. 1999 All Rights Reserved.
ENTER = Process PF2 = Main Menu PF3 = Quit

3. Select option 3 to work with channel definitions.

10/08/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZR02

14:05:20 Channel Record DISPLAY SYSA
MQMMCHN Last Check Point Last Update 19981006 SFCA
MSN 00000000 Time 11:28:28 Interv 000000 Create Date 19980616
Name : RB01.DC01.SDRC.5006
Protocol : L (L/T) Port : 0000 Type : R (S/R/C)
Partner : MA02

Allocation Retries Get Retries

Number of Retries: 00000000 Number of Retries : 00000000
Delay Time - fast: 00000000 Delay Time : 00000005
Delay Time - slow: 00000000

Max Messages per Batch : 000001 Max Transmission Size : 03200

Message Sequence Wrap : 999999 Max Message Size : 0010240

Mess Seq Req(Y/N): Y Convers Cap (Y/N): Y Split Msg(Y/N): N

Transmission Queue Name :

TP Name:
Checkpoint Values: Frequency: 0000 Time Span: 0000
Enable(Y/N) Y Dead Letter Store(Y/N) Y
Channel record displayed.
PF2 =Menu PF3 =Quit PF4 =Read PF5 =Add PF6=Update PF9 =List PF12 =Delete

4. Complete the parameter fields as indicated, specifically the fields Name<«G¬>,

Type, Partner, Transmission Queue Name<«F¬>, and TP Name.
All other parameters can be entered as shown.
Note that the default value for sequence number wrap is 999999, whereas for
Version 2 MQSeries products, this value defaults to 999999999.
5. Press PF5.

Defining a SNA LU6.2 receiver channel

1. Run the MQSeries master terminal transaction MQMT.

498 MQSeries Intercommunication

 VSE/ESA configuration

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:50:25 *** Master Terminal Main Menu *** VSE1
MQMMTP A004
SYSTEM IS ACTIVE

1. Configuration

2. Operations

3. Monitoring

4. Browse Queue Records

Option:

Function completed - please enter a new request.

5686-A06 (C) Copyright IBM Corp. 1999 All Rights Reserved.
CLEAR/PF3 = Exit ENTER=Select

2. Select option 1 to configure.

08/18/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

19:52:21 *** Configuration Main Menu *** VSE1
MQMMCFG A004
SYSTEM IS ACTIVE

Maintenance Options :
1. Global System Definition
2. Queue Definitions
3. Channel Definitions

Display Options :
4. Global System Definition
5. Queue Definitions
6. Channel Definitions

Option:

Please enter one of the options listed.

5686-A06 (C) Copyright IBM Corp. 1999 All Rights Reserved.
ENTER = Process PF2 = Main Menu PF3 = Quit

3. Select option 3 to work with channel definitions.

Chapter 35. Example configuration - MQSeries for VSE/ESA 499

VSE/ESA configuration

08/19/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

07:29:03 Channel Record DISPLAY MCHN
MQMMCHN Last Check Point Last Update 19980805 A004
MSN 00000149 Time 17:52:32 Interv 000000 Create Date 19980528
Name : OS2.VSE.SNA
Protocol : L (L/T) Port : 0000 Type : R (S/R/C)
Partner :

Allocation Retries Get Retries

Number of Retries: 00000000 Number of Retries : 00000000
Delay Time - fast: 00000000 Delay Time : 00000000
Delay Time - slow: 00000000

Max Messages per Batch : 000001 Max Transmission Size : 032000

Message Sequence Wrap : 999999 Max Message Size : 008192

Mess Seq Req(Y/N): Y Convers Cap (Y/N): Y Split Msg(Y/N): N

Transmission Queue Name :

TP Name:
Checkpoint Values: Frequency: 0000 Time Span: 0000
Enable(Y/N) Y Dead Letter Store(Y/N) Y
Channel record displayed.
PF2 =Menu PF3 =Quit PF4 =Read PF5 =Add PF6=Update PF9 =List PF12 =Delete

4. Complete the parameter fields as indicated, specifically the field Channel

name<«L¬>.
All other parameters can be entered as shown.
5. Press PF5.

Defining a TCP/IP sender channel

To define a TCP/IP sender channel, carry out the following procedure:
1. Run the MQSeries master terminal transaction MQMT.
2. Select option 1 to configure.
3. Select option 3 to work with channel definitions. The screen shown in
Figure 113 on page 501 is displayed:

500 MQSeries Intercommunication

 VSE/ESA configuration

07/16/1998 IBM MQSeries for VSE/ESA Version 2.1.0 IYBPZS01

08:03:53 Channel Record DISPLAY MCHN
MQMMCHN Last Check Point Last Update 00000000 A005
MSN 00000002 Time 07:10:22 Interv 000000 Create Date 19980528
Name : SD01_TCP_VSEP
Protocol : T (L/T) Port : 1414 Type : S (S/R/C)
Partner :

Allocation Retries Get Retries

Number of Retries: 00000000 Number of Retries : 00000000
Delay Time - fast: 00000000 Delay Time : 00000000
Delay Time - slow: 00000000

Max Messages per Batch : 000001 Max Transmission Size : 032000

Message Sequence Wrap : 999999 Max Message Size : 008192

Mess Seq Req(Y/N): Y Convers Cap (Y/N): Y Split Mssg(Y/N): N

Transmission Queue Name :

TP Name:
Checkpoint Values: Frequency: 0000 Time Span: 0000
Enable(Y/N) Y Dead Letter Store(Y/N) N
Channel record displayed.
PF2 =Menu PF3 =Quit PF4 =Read PF5 =Add PF6=Update PF9 =List PF12 =Delete

Figure 113. Channel configuration panel

4. Complete the parameter fields as follows:

v Channel name – «G¬ on the configuration worksheet.
v Partner – should contain the IP address of the remote host, for example,
1.20.33.444.
v Port – the port number must match the port number configured for the
remote host. This is configured in the global system definition of the remote
host. The default port number for MQSeries for VSE/ESA is 1414.
v Transmission queue name – «F¬ on the configuration worksheet.
v Protocol – enter T for TCP.
v Channel type – enter S for sender.
Notes:
a. The TP Name is not used by TCP channels.
b. Ensure that the parameter field values match the values of the receiver
channel definition of the same name on the remote host.
5. Press PF5 (Add) to add the new channel definition.

Defining a TCP receiver channel

To define a TCP receiver channel, carry out the following procedure:
1. Run the MQSeries master terminal transaction MQMT.
2. Select option 1 to configure.
3. Select option 3 to work with channel definitions. The screen shown in
Figure 113 is displayed.
4. Complete the parameter fields as follows:
v Channel name – «G¬ on the configuration worksheet.
v Protocol – enter T for TCP.
v Channel type – enter R for receiver.

Chapter 35. Example configuration - MQSeries for VSE/ESA 501

VSE/ESA configuration
Notes:
a. The Partner and Port are not required for a TCP receiver channel.
b. The TP Name is not used by TCP channels.
c. Ensure that the parameter field values match the values of the sender
channel definition of the same name on the remote host.
5. Press PF5 (Add) to add the new channel definition.

502 MQSeries Intercommunication

 Part 7. Further intercommunication considerations
Chapter 36. Channel-exit programs . . . . . 505 Usage notes . . . . . . . . . . . . . 551
What are channel-exit programs? . . . . . . . 505 C invocation. . . . . . . . . . . . . 552
Processing overview . . . . . . . . . . 506 COBOL invocation . . . . . . . . . . 552
Channel security exit programs . . . . . . 507 RPG invocation (ILE) . . . . . . . . . . 552
Channel send and receive exit programs . . . 512 RPG invocation (OPM) . . . . . . . . . 552
Channel message exit programs . . . . . . 514 System/390 assembler invocation. . . . . . 552
Channel message retry exit program. . . . . 516 MQXWAIT - Wait . . . . . . . . . . . . 553
Channel auto-definition exit program . . . . 516 Syntax. . . . . . . . . . . . . . . 553
Transport-retry exit program . . . . . . . 517 Parameters . . . . . . . . . . . . . 553
Writing and compiling channel-exit programs . . 518 C invocation. . . . . . . . . . . . . 554
MQSeries for OS/390 without CICS . . . . . 520 System/390 assembler invocation. . . . . . 554
MQSeries for OS/390 using CICS. . . . . . 521 MQ_TRANSPORT_EXIT - Transport retry exit . . 555
MQSeries for AS/400 . . . . . . . . . . 521 Syntax. . . . . . . . . . . . . . . 555
MQSeries for OS/2 Warp . . . . . . . . 522 Parameters . . . . . . . . . . . . . 555
Windows 3.1 client . . . . . . . . . . 524 Usage notes . . . . . . . . . . . . . 555
MQSeries for Windows NT server, MQSeries C invocation. . . . . . . . . . . . . 555
client for Windows NT, and MQSeries client for MQCD - Channel data structure . . . . . . . 556
Windows 95 and Windows 98 . . . . . . . 524 Fields . . . . . . . . . . . . . . . 558
MQSeries for Windows . . . . . . . . . 526 C declaration . . . . . . . . . . . . 580
MQSeries for AIX . . . . . . . . . . . 526 COBOL declaration . . . . . . . . . . 582
MQSeries for Compaq (DIGITAL) OpenVMS 528 PL/I declaration . . . . . . . . . . . 584
| MQSeries for DIGITAL UNIX (Compaq Tru64 ILE RPG declaration . . . . . . . . . . 585
| UNIX) . . . . . . . . . . . . . . . 529 OPM RPG declaration . . . . . . . . . 587
MQSeries for HP-UX . . . . . . . . . . 530 System/390 assembler declaration . . . . . 589
MQSeries for AT&T GIS UNIX . . . . . . 531 MQCXP - Channel exit parameter structure . . . 591
MQSeries for Sun Solaris . . . . . . . . 532 Fields . . . . . . . . . . . . . . . 591
MQSeries for SINIX and DC/OSx . . . . . 532 C declaration . . . . . . . . . . . . 601
MQSeries for Tandem NonStop Kernel . . . . 533 COBOL declaration . . . . . . . . . . 601
| Building and using channel exit functions 534 PL/I declaration . . . . . . . . . . . 602
Supplied channel-exit programs using DCE ILE RPG declaration . . . . . . . . . . 602
security services . . . . . . . . . . . . 537 OPM RPG declaration . . . . . . . . . 603
What do the DCE channel-exit programs do? 537 System/390 assembler declaration . . . . . 604
How do the DCE channel-exit programs work? 538 MQTXP - Transport-exit data structure . . . . . 605
How to use the DCE channel-exit programs . . 540 Fields . . . . . . . . . . . . . . . 605
Setup for DCE . . . . . . . . . . . 540 C declaration . . . . . . . . . . . . 608
The supplied exit code . . . . . . . . 541 MQXWD - Exit wait descriptor structure . . . . 609
Using DCE channel exits with the runmqlsr Fields . . . . . . . . . . . . . . . 609
listener program . . . . . . . . . . 542 C declaration . . . . . . . . . . . . 610
System/390 assembler declaration . . . . . 610
Chapter 37. Channel-exit calls and data
structures . . . . . . . . . . . . . . 543 Chapter 38. Problem determination in DQM . . 611
Data definition files . . . . . . . . . . . 544 Error message from channel control . . . . . . 611
MQ_CHANNEL_EXIT - Channel exit . . . . . 546 Ping . . . . . . . . . . . . . . . . 611
Syntax. . . . . . . . . . . . . . . 546 Dead-letter queue considerations . . . . . . . 612
Parameters . . . . . . . . . . . . . 546 Validation checks . . . . . . . . . . . . 612
Usage notes . . . . . . . . . . . . . 548 In-doubt relationship . . . . . . . . . . . 613
C invocation. . . . . . . . . . . . . 549 Channel startup negotiation errors . . . . . . 613
COBOL invocation . . . . . . . . . . 549 When a channel refuses to run . . . . . . . 613
PL/I invocation . . . . . . . . . . . 549 Triggered channels . . . . . . . . . . 614
RPG invocation (ILE) . . . . . . . . . . 549 Conversion failure. . . . . . . . . . . 615
RPG invocation (OPM) . . . . . . . . . 550 Network problems . . . . . . . . . . 615
System/390® assembler invocation . . . . . 550 Dial-up problems . . . . . . . . . . . 615
MQ_CHANNEL_AUTO_DEF_EXIT - Channel Retrying the link . . . . . . . . . . . . 615
auto-definition exit . . . . . . . . . . . 551 Retry considerations . . . . . . . . . . 615
Syntax. . . . . . . . . . . . . . . 551 Data structures . . . . . . . . . . . . . 616
Parameters . . . . . . . . . . . . . 551 User exit problems . . . . . . . . . . . 616

© Copyright IBM Corp. 1993, 2000 503

Further intercommunication considerations
Disaster recovery . . . . . . . . . . . . 616 Error logs on UNIX systems . . . . . . . 618
Channel switching. . . . . . . . . . . . 617 Error logs on DOS, Windows 3.1, and Windows
Connection switching. . . . . . . . . . . 617 95 and Windows 98 clients . . . . . . . . 618
Client problems . . . . . . . . . . . . 617 Error logs on OS/390. . . . . . . . . . 619
Terminating clients . . . . . . . . . . 617 Error logs on MQSeries for Windows . . . . 619
Error logs . . . . . . . . . . . . . . 618 Error logs on MQSeries for VSE/ESA . . . . 619
Error logs for OS/2 and Windows NT . . . . 618 | Error logs on MQSeries for Tandem NSK . . . 619

This part of the book is about creating installation-specific user-exit programs, and
solving problems with your MQSeries system. The description is not
platform-specific. Where some details apply only to certain platforms, this is made
clear. Most of the OS/390 information here applies equally to MVS/ESA.

504 MQSeries Intercommunication

Chapter 36. Channel-exit programs
This chapter discusses MQSeries channel-exit programs. This is product-sensitive
programming interface information. The following topics are covered:
v “What are channel-exit programs?”
v “Writing and compiling channel-exit programs” on page 518
v “Supplied channel-exit programs using DCE security services” on page 537

Message channel agents (MCAs) can also call data-conversion exits; these are
discussed in the MQSeries Application Programming Guide.

Note: Channel exit programs are not supported on DOS or VSE/ESA.

What are channel-exit programs?

Channel-exit programs are called at defined places in the processing carried out by
MCA programs.

Some of these user-exit programs work in complementary pairs. For example, if a

user-exit program is called by the sending MCA to encrypt the messages for
transmission, the complementary process must be functioning at the receiving end
to reverse the process.

The different types of channel-exit program are described below. Table 46 shows
the types of channel exit that are available for each channel type.
Table 46. Channel exits available for each channel type
Channel Type Message exit Message- Receive exit Security exit Send exit Auto- Transport-
retry exit definition exit retry exit
Sender U U U U U
channel
Server channel U U U U U
Cluster- U U U U U
sender channel
Receiver U U U U U U U
channel
Requester U U U U U U
channel
Cluster- U U U U U U
receiver
channel
Client- U U U
connection
channel
Server- U U U U
connection
channel
Notes:
1. The message-retry exit does not apply to MQSeries for OS/390 or MQSeries for Windows.
2. The auto-definition exit applies to V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT and
MQSeries for OS/390 (cluster-sender channels only).
3. The transport-retry exit applies to MQSeries for AIX V5.1 and MQSeries for Windows V2.0 only.

© Copyright IBM Corp. 1993, 2000 505

Channel-exit programs
If you are going to run channel exits on a client, you cannot use the MQSERVER
environment variable. Instead, create and reference a client channel definition table
as described in the MQSeries Clients book.

Processing overview
On startup, the MCAs exchange a startup dialog to synchronize processing. Then
they switch to a data exchange that includes the security exits; these must end
successfully for the startup phase to complete and to allow messages to be
transferred.

The security check phase is a loop, as shown in Figure 114.

E xit MCA MCA E xit

S e c u rity S e nd er- Comms R e ce iv e r- S e c u rity

S e rv e r lin k R equester

Local system Adjacent system

Figure 114. Security exit loop

During the message transfer phase, the sending MCA gets messages from a
transmission queue, calls the message exit, calls the send exit, and then sends the
message to the receiving MCA, as shown in Figure 115.

A p p lica tio n

MCA E xit

M e ss a ge
Q ueue tra n s m is s io n (get)

E xit

Comms
lin k Send

Figure 115. Example of a send exit at the sender end of message channel

506 MQSeries Intercommunication

 Channel-exit programs

MCA Exi t

C o mm s

l in k

Receive

App li ca t ion Exi t

Mess age

(put)

Queue Loc al

Figure 116. Example of a receive exit at the receiver end of message channel

The receiving MCA receives a message from the communications link, calls the
receive exit, calls the message exit, and then puts the message on the local queue,
as shown in Figure 116. (The receive exit can be called more than once before the
message exit is called.)

Channel security exit programs

You can use security exit programs to verify that the partner at the other end of a
channel is genuine.

Channel security exit programs are called at the following places in an MCA’s
processing cycle:
v At MCA initiation and termination.
v Immediately after the initial data negotiation is finished on channel startup. The
receiver or server end of the channel may initiate a security message exchange
with the remote end by providing a message to be delivered to the security exit
at the remote end. It may also decline to do so. The exit program is re-invoked
to process any security message received from the remote end.
v Immediately after the initial data negotiation is finished on channel startup. The
sender or requester end of the channel processes a security message received
from the remote end, or initiates a security exchange when the remote end
cannot. The exit program is re-invoked to process all subsequent security
messages that may be received.

A requester channel never gets called with MQXCC_INIT_SEC. The channel

notifies the server that it has a security exit program, and the server then has the
opportunity to initiate a security exit. If it does not have one, it sends a null
security flow to allow the requester to call its exit program.

Note: You are recommended to avoid sending zero-length security messages.

Chapter 36. Channel-exit programs 507

 Channel-exit programs
| V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT and
| the MQSeries client for Windows 95 and Windows 98 supply a security exit
| program that uses the DCE security services. See “Supplied channel-exit programs
| using DCE security services” on page 537.

Examples of the data exchanged by security-exit programs are illustrated in figures

117 through 120. These examples show the sequence of events that occur involving
the receiver’s security exit (left-hand column) and the sender’s security exit
(right-hand column). Successive rows in the figures represent the passage of time.
In some cases, the events at the receiver and sender are not correlated, and
therefore can occur at the same time or at different times. In other cases, an event
at one exit program results in a complementary event occurring later at the other
exit program. For example, in Figure 117 on page 509:
1. The receiver and sender are each invoked with MQXR_INIT, but these
invocations are not correlated and can therefore occur at the same time or at
different times.
2. The receiver is next invoked with MQXR_INIT_SEC, but returns MQXCC_OK
which requires no complementary event at the sender exit.
3. The sender is next invoked with MQXR_INIT_SEC. This is not correlated with
the invocation of the receiver with MQXR_INIT_SEC. The sender returns
MQXCC_SEND_SEC_MSG, which causes a complementary event at the
receiver exit.
4. The receiver is subsequently invoked with MQXR_SEC_MSG, and returns
MQXCC_SEND_SEC_MSG, which causes a complementary event at the sender
exit.
5. The sender is subsequently invoked with MQXR_SEC_MSG, and returns
MQXCC_OK which requires no complementary event at the receiver exit.

508 MQSeries Intercommunication

 Channel-exit programs

Receiver exit Sender exit

Invoked with MQXR INIT Invoked with MQXR INIT

Responds with MQXCC OK Responds with MQXCC OK

Invoked with MQXR INIT SEC

Responds with MQXCC OK

Invoked with MQXR INIT SEC

Responds with MQXCC SEND SEC MSG

Invoked with MQXR SEC MSG

Responds with MQXCC SEND SEC MSG

Invoked with MQXR SEC MSG

Responds with MQXCC OK

Message transfer begins

Figure 117. Sender-initiated exchange with agreement

Chapter 36. Channel-exit programs 509

Channel-exit programs

R e c e iv e r e x it S e n d e r e x it

In v o k e d w ith M Q X R IN IT In v o k e d w ith M Q X R IN IT

R e s p o n d s w ith M Q X C C O K R e s p o n d s w ith M Q X C C O K

In v o k e d w ith M Q X R IN IT S E C

R e s p o n d s w ith M Q X C C O K

In v o k e d w ith M Q X R IN IT S E C

R e s p o n d s w ith M Q X C C S E N D S E C M S G

In v o k e d w ith M Q X R S E C M S G

R e s p o n d s w ith M Q X C C O K

In v o k e d w ith M Q X R S E C M S G

R es po nds w ith M Q X C C S U P P R E S S F U N C T IO N

C ha n n e l c l o s e s

In v o k e d w ith M Q X R T E R M In v o k e d w ith M Q X R T E R M

R e s p o n d s w ith M Q X C C O K R e s p o n d s w ith M Q X C C O K

Figure 118. Sender-initiated exchange with no agreement

510 MQSeries Intercommunication

 Channel-exit programs

Receiver exit Sender exit

Invoked with MQXR INIT Invoked with MQXR INIT

Responds with MQXCC OK Responds with MQXCC OK

Invoked with MQXR INIT SEC

Responds with MQXCC SEND SEC MSG

Invoked with MQXR SEC MSG

Responds with MQXCC SEND SEC MSG

Invoked with MQXR SEC MSG

Responds with MQXCC OK

Message transfer begins

Invoked with MQXR TERM Invoked with MQXR TERM

Responds with MQXCC OK Responds with MQXCC OK

Figure 119. Receiver-initiated exchange with agreement

Receiver exit Sender exit

Invoked with MQXR_INIT Invoked with MQXR_INIT

Responds with MQXCC_OK Responds with MQXCC_OK

Invoked with MQXR_INIT_SEC

Responds with MQXCC_SEND_SEC_MSG

Invoked with MQXR_SEC_MSG

Responds with MQXCC_OK

Invoked with MQXR_SEC_MSG

Responds with MQXCC_SUPRESS_FUNCTION

Channel closes

Figure 120. Receiver-initiated exchange with no agreement

Chapter 36. Channel-exit programs 511

 Channel-exit programs
The channel security exit program is passed an agent buffer containing the security
data, excluding any transmission headers, generated by the security exit. This may
be any suitable data so that either end of the channel is able to perform security
validation.

The security exit program at both the sending and receiving end of the message
channel may return one of four response codes to any call:
v Security exchange ended with no errors
v Suppress the channel and close down
v Send a security message to the corresponding security exit at the remote end
v Send a security message and demand a reply (this does not apply on OS/390
when using CICS)
Notes:
1. The channel security exits usually work in pairs. When you define the
appropriate channels, make sure that compatible exit programs are named for
both ends of the channel.
| 2. In OS/400, security exit programs that have been compiled with “Use adopted
| authority” (USEADPAUT=*YES) have the ability to adopt QMQM or
| QMQMADM authority. Take care that the exit does not exploit this feature to
| pose a security risk to your system.

Channel send and receive exit programs

| You can use the send and receive exits to perform tasks such as data compression
| and decompression. In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp,
| Sun Solaris, and Windows NT, and with MQSeries clients, you can specify a list of
| send and receive exit programs to be run in succession.

Channel send and receive exit programs are called at the following places in an
MCA’s processing cycle:
v The send and receive exit programs are called for initialization at MCA initiation
and for termination at MCA termination.
v The send exit program is invoked at either end of the channel, immediately
before a transmission is sent over the link.
v The receive exit program is invoked at either end of the channel, immediately
after a transmission has been taken from the link.

Note: For MQSeries for OS/390 using CICS, only the security exit is called at
MCA initiation; other exits are called with the ExitReason parameter set to
MQXR-INIT when the first message is sent across the channel.

There may be many transmissions for one message transfer, and there could be
many iterations of the send and receive exit programs before a message reaches the
message exit at the receiving end.

The channel send and receive exit programs are passed an agent buffer containing
the transmission data as sent or received from the communications link. For send
exit programs, the first eight bytes of the buffer are reserved for use by the MCA,
and must not be changed. If the program returns a different buffer, then these first
eight bytes must exist in the new buffer. The format of data presented to the exit
programs is not defined.

A good response code must be returned by send and receive exit programs. Any
other response will cause an MCA abnormal end (abend).

512 MQSeries Intercommunication

 Channel-exit programs
Note: Do not issue an MQGET, MQPUT, or MQPUT1 call within syncpoint from a
send or receive exit.

V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT and
the MQSeries client for Windows 95 and Windows 98 supply send and receive exit
programs that use the DCE encryption security services. See “Supplied channel-exit
programs using DCE security services” on page 537.
Notes:
1. Send and receive exits usually work in pairs. For example a send exit may
compress the data and a receive exit decompress it, or a send exit may encrypt
the data and a receive exit decrypt it. When you define the appropriate
channels, make sure that compatible exit programs are named for both ends of
the channel.
2. Channel send and receive exits may be called for message segments other than
for application data, for example, status messages. They are not called during
the startup dialog, nor the security check phase.
3. Although message channels send messages in one direction only,
channel-control data flows in both directions, and these exits are available in
both directions, also. However, some of the initial channel startup data flows
are exempt from processing by any of the exits.
4. There are circumstances in which send and receive exits could be invoked out
of sequence; for example, if you are running a series of exit programs or if you
are also running security exits. Then, when the receive exit is first called upon
to process data, it may receive data that has not passed through the
corresponding send exit. If the receive exit were just to perform the operation,
for example decompression, without first checking that it was really required,
the results would be unexpected.
You should code your send and receive exits in such a way that the receive exit
can check that the data it is receiving has been processed by the corresponding
send exit. The recommended way to do this is to code your exit programs so
that:
v The send exit sets the value of the ninth byte of data to 0 and shifts all the
data along one byte, before performing the operation. (The first eight bytes
are reserved for use by the MCA.)
v If the receive exit receives data that has a 0 in byte 9, it knows that the data
has come from the send exit. It removes the 0, performs the complementary
operation, and shifts the resulting data back by one byte.
v If the receive exit receives data that has something other than 0 in byte 9, it
assumes that the send exit has not run, and sends the data back to the caller
unchanged.

| When using security exits, if the channel is ended by the security exit it is
| possible that a send exit may be called without the corresponding receive exit.
| One way to prevent this from being a problem is to code the security exit to set
| a flag, in MQCD.SecurityUserData or MQCD.SendUserData, for example, when
| the exit decides to end the channel. Then the send exit should check this field,
| and process the data only if the flag is not set. This prevents the send exit from
| unnecessarily altering the data, and thus prevents any conversion errors that
| could occur if the security exit received altered data.
5. In the case of MQI channels for clients, byte 10 of message data identifies the
API call in use when the send or receive exit is called. This is useful for
identifying which channel flows include user data and may require processing
such as encryption or digital signing.

Chapter 36. Channel-exit programs 513

Channel-exit programs
Table 47 shows the data that appears in byte 10 of the channel flow when an
API call is being processed.

Note: These are not the only values of this byte. There are other reserved
values.
Table 47. Identifying API calls
API call Value of byte 10
MQCONN request (5a, 5b) X’81’
MQCONN reply (5a, 5b) X’91’
MQDISC request (5a) X’82’
MQDISC reply (5a) X’92’
MQOPEN request (5c) X’83’
MQOPEN reply (5c) X’93’
MQCLOSE request X’84’
MQCLOSE reply X’94’
MQGET request (5d) X’85’
MQGET reply (5d) X’95’
MQPUT request (5d) X’86’
MQPUT reply (5d) X’96’
MQPUT1 request (5d) X’87’
MQPUT1 reply (5d) X’97’
MQSET request X’88’
MQSET reply X’98’
MQINQ request X’89’
MQINQ reply X’99’
MQCMIT request X’8A’
MQCMIT reply X’9A’
MQBACK request X’8B’
MQBACK reply X’9B’
Notes:
a. The connection between the client and server is initiated by the client application using
MQCONN. Therefore, for this command in particular, there will be several other
network flows. This also applies to MQDISC that terminates the network connection.
b. MQCONNX is treated in the same way as MQCONN for the purposes of the
client-server connection.
c. If a large distribution list is opened, there may be more than one network flow per
MQOPEN call in order to pass all of the required data to the SVRCONN MCA.
d. If the message data exceeds the transmission segment size, there may be a large
number of network flows per single API call.

Channel message exit programs

You can use the channel message exit for the following:
v Encryption on the link
v Validation of incoming user IDs
v Substitution of user IDs according to local policy
v Message data conversion

514 MQSeries Intercommunication

 Channel-exit programs
v Journaling
v Reference message handling

| In V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT, you can specify a list of message exit programs to be run in
| succession.

Channel message exit programs are called at the following places in an MCA’s
processing cycle:
v At MCA initiation and termination
v Immediately after a sending MCA has issued an MQGET call
v Before a receiving MCA issues an MQPUT call

The message exit is passed an agent buffer containing the transmission queue
header, MQXQH, and the application message text as retrieved from the queue.
(The format of MQXQH is given in the MQSeries Application Programming Reference
book.) If you use reference messages, that is messages that contain only a header
which points to some other object that is to be sent, the message exit recognizes
the header, MQRMH. It identifies the object, retrieves it in whatever way is
appropriate appends it to the header, and passes it to the MCA for transmission to
the receiving MCA. At the receiving MCA, another message exit recognizes that
this is a reference message, extracts the object, and passes the header on to the
destination queue. See the MQSeries Application Programming Guide for more
information about reference messages and some sample message exits that handle
them.

Message exits can return the following responses:

v Send the message (GET exit). The message may have been changed by the exit.
(This returns MQXCC_OK.)
v Put the message on the queue (PUT exit). The message may have been changed
by the exit. (This returns MQXCC_OK.)
v Do not process the message. The message is placed on the dead-letter queue
(undelivered message queue) by the MCA.
v Close the channel.
v Bad return code, which causes the MCA to abend.
Notes:
1. Message exits are called just once for every complete message transferred, even
when the message is split into parts.
2. In UNIX systems, if you provide a message exit for any reason the automatic
conversion of user IDs to lowercase characters does not operate. See “User IDs
on UNIX systems, Digital OpenVMS” on page 120.
3. An exit runs in the same thread as the MCA itself. It also runs inside the same
unit of work (UOW) as the MCA because it uses the same connection handle.
Therefore, any calls made under syncpoint are committed or backed out by the
channel at the end of the batch. For example, one channel message exit
program can send notification messages to another and these messages will
only be committed to the queue when the batch containing the original
message is committed.
Therefore, it is possible to issue syncpoint MQI calls from a channel message
exit program.

Chapter 36. Channel-exit programs 515

 Channel-exit programs
| V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT
| supplies a message exit program that uses the DCE security services. See
| “Supplied channel-exit programs using DCE security services” on page 537.

Channel message retry exit program

The channel message-retry exit is called when an attempt to open the target queue
is unsuccessful. You can use the exit to determine under which circumstances to
retry, how many times to retry, and how frequently. (This exit is not available on
MQSeries for OS/390 or MQSeries for Windows.)

This exit is also called at the receiving end of the channel at MCA initiation and
termination.

The channel message-retry exit is passed an agent buffer containing the

transmission queue header, MQXQH, and the application message text as retrieved
from the queue. The format of MQXQH is given in the MQSeries Application
Programming Reference book.

The exit is invoked for all reason codes; the exit determines for which reason codes
it wants the MCA to retry, for how many times, and at what intervals. (The value
of the message-retry count set when the channel was defined is passed to the exit
in the MQCD, but the exit can ignore this.)

The MsgRetryCount field in MQCXP is incremented by the MCA each time the exit
is invoked, and the exit returns either MQXCC_OK with the wait time contained in
the MsgRetryInterval field of MQCXP, or MQXCC_SUPPRESS_FUNCTION. Retries
continue indefinitely until the exit returns MQXCC_SUPPRESS_FUNCTION in the
ExitResponse field of MQCXP. See “MQCXP - Channel exit parameter structure” on
page 591 for information about the action taken by the MCA for these completion
codes.

| If all the retries are unsuccessful, the message is written to the dead-letter queue. If
| there is no dead-letter queue available, the channel stops.

If you do not define a message-retry exit for a channel and a failure occurs that is
likely to be temporary, for example MQRC_Q_FULL, the MCA uses the
message-retry count and message-retry intervals set when the channel was defined.
If the failure is of a more permanent nature and you have not defined an exit
program to handle it, the message is written to the dead-letter queue.

Channel auto-definition exit program

| The channel auto-definition exit can be called when a request is received to start a
| receiver or server-connection channel but no channel definition exists. The exit
| applies to V5.1 of MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and
| Windows NT. You can use it to modify the supplied default definition for an
| automatically defined receiver or server-connection channel,
| SYSTEM.AUTO.RECEIVER or SYSTEM.AUTO.SVRCON. See “Auto-definition of
| channels” on page 60 for a description of how channel definitions can be created
| automatically.

| The channel auto-definition exit can also be called when a request is received to
| start a cluster-sender channel. It can be called for cluster-sender and
| cluster-receiver channels to allow definition modification for this instance of the
| channel. In this case, the exit applies to MQSeries for OS/390 as well as V5.1 of

516 MQSeries Intercommunication

 Channel-exit programs
| MQSeries for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT. For
| more information about this, see the MQSeries Administration Interface Programming
| Guide and Reference book.

As with other channel exits, the parameter list is:

MQ_CHANNEL_AUTO_DEF_EXIT (ChannelExitParms, ChannelDefinition)

ChannelExitParms are described in “MQCXP - Channel exit parameter structure” on

page 591. ChannelDefinition is described in “MQCD - Channel data structure” on
page 556.

MQCD contains the values that are used in the default channel definition if they
are not altered by the exit. The exit may modify only a subset of the fields; see
“MQ_CHANNEL_AUTO_DEF_EXIT - Channel auto-definition exit” on page 551.
However, attempting to change other fields does not cause an error.

The channel auto-definition exit returns a response of either MQXCC_OK or

MQXCC-SUPPRESS_FUNCTION. If neither of these is returned, the MCA
continues processing as though MQXCC-SUPPRESS_FUNCTION were returned.
That is, the auto-definition is abandoned, no new channel definition is created and
the channel cannot start.

Transport-retry exit program

| The transport-retry exit applies to MQSeries for AIX, V5.1 and MQSeries for
| Windows V2.0 and is supported on UDP only. It allows you to write a C-language
| retry exit. The exit allows your application to suspend data being sent on a channel
| when communication is not possible (for example, when a mobile user is traveling
| through a tunnel or is temporarily out of range of a transmitter).

The transport-retry exit can be associated with a monitor program that can assess
whether the IP connection is available for sending data. The exit has to be built
into a library that is included in the path in which you are operating.

The exit is normally called before a datagram is about to be sent but is also called
to provide other useful signals.

The retry exit is called under five different conditions:

v When the MQSeries channel is first initialized; the ExitReason variable is set to a
value of MQXR_INIT.
v When the MQSeries channel is shut down; the ExitReason variable is set to a
value of MQXR_TERM.
v Before each datagram is sent; the ExitReason variable is set to a value of
MQXR_RETRY.
v When the end of a batch of messages occurs; the ExitReason variable is set to a
value of MQXR_END_BATCH.
v When an information datagram is received from the remote end of the link; the
ExitReason variable is set to a value of MQXR_ACK_RECEIVED.

If you want to postpone sending a datagram in response to an ExitReason of

MQXR_RETRY, you need to block returning from the exit until it is safe to send
the datagram. In all other cases, the return from the exit should be immediate.

There are three possible return codes that can be set when returning from the exit:
v MQXCC_OK — this is the normal response.

Chapter 36. Channel-exit programs 517

 Channel-exit programs
v MQXCC_CLOSE_CHANNEL — in response to an ExitReason of MQXR_RETRY,
this will cause the channel to be closed.
v MQXCC_REQUEST_ACK — in response to an ExitReason of MQXR_RETRY,
this will cause the datagram about to be sent to be modified so that it requests
the remote end of the link to send an information datagram back to indicate that
the node can be reached. If this datagram arrives the exit will be invoked again
with an ExitReason of MQXR_ACK_RECEIVED. You can set this return code on
or off by using the PSEUDO_ACK parameter in the qm.ini file.

Note: If the datagram fails to arrive at the remote node, for any reason, you
must repeat the request on the next datagram that is sent.

The transport-retry exit name can be defined by the user, who can also change the
name of the library that contains the exit. You configure the retry exit by editing
the qm.ini file. A qm.ini file exists on both MQSeries for AIX V5.1 and MQSeries
for Windows V2.0. For more information about editing these files, see the MQSeries
System Administration book.

Writing and compiling channel-exit programs

Channel exits must be named in the channel definition. You can do this when you
first define the channels, or you can add the information later using, for example,
the MQSC command ALTER CHANNEL. You can also give the channel exit names
in the MQCD channel data structure. The format of the exit name depends on your
MQSeries platform; see “MQCD - Channel data structure” on page 556 or the
MQSeries Command Reference book for information.

If the channel definition does not contain a user-exit program name, the user exit is
not called.

The channel auto-definition exit is the property of the queue manager, not the
individual channel. In order for this exit to be called, it must be named in the
queue manager definition. To alter a queue manager definition, use the MQSC
command ALTER QMGR.

User exits and channel-exit programs are able to make use of all MQI calls, except
as noted in the sections that follow. To get the connection handle, an MQCONN
must be issued, even though a warning, MQRC_ALREADY_CONNECTED, is
returned because the channel itself is connected to the queue manager.

| For exits on client-connection channels, the queue manager to which the exit tries
| to connect, depends on how the exit was linked. If the exit was linked with
| MQM.LIB (or QMQM/LIBMQM on OS/400) and you do not specify a queue
| manager name on the MQCONN call, the exit will try to connect to the default
| queue manager on your system. If the exit was linked with MQM.LIB (or
| QMQM/LIBMQM on OS/400) and you specify the name of the queue manager
| that was passed to the exit through the QMgrName field of MQCD, the exit tries
| to connect to that queue manager. If the exit was linked with MQIC.LIB or any
| other library, the MQCONN call will fail whether you specify a queue manager
| name or not.

Note: You are recommended to avoid issuing the following MQI calls in
channel-exit programs:
v MQCMIT
v MQBACK
v MQBEGIN

518 MQSeries Intercommunication

 Channel-exit programs
An exit runs in the same thread as the MCA itself and uses the same connection
handle. So, it runs inside the same UOW as the MCA and any calls made under
syncpoint are committed or backed out by the channel at the end of the batch.

Therefore, a channel message exit could send notification messages that will only
be committed to that queue when the batch containing the original message is
committed. So, it is possible to issue syncpoint MQI calls from a channel message
exit.

Channel-exit programs should not modify the Channel data structure (MQCD).
They can actually change the BatchSize parameter and a security exit can set the
MCAUserIdentifier parameter, but ChannelType and ChannelName must not be
changed.

Also, for programs written in C, non-reentrant C library function should not be

used in a channel-exit program.

All exits are called with a channel exit parameter structure (MQCXP), a channel
definition structure (MQCD), a prepared data buffer, data length parameter, and
buffer length parameter. The buffer length must not be exceeded:
v For message exits, you should allow for the largest message required to be sent
across the channel, plus the length of the MQXQH structure.
v For send and receive exits, the largest buffer you should allow for is as follows:
LU 6.2:
OS/2 64 KB
Others 32 KB

TCP:
AS/400 16 KB
Others 32 KB

UDP:
32 KB

NetBIOS:
DOS 4 KB
Others 64 KB

SPX:
64 KB

Note: Receive exits on sender channels and sender exits on receiver channels
use 2 KB buffers for TCP.
v For security exits, the distributed queuing facility allocates a buffer of 4000
bytes.
v On OS/390 using CICS, all exits use the maximum transmission length for the
channel, defined in the channel definition.

It is permissible for the exit to return an alternate buffer, together with the relevant
| parameters. See “MQ_CHANNEL_EXIT - Channel exit” on page 546 for call details.

| Note: Before using a channel-exit program for the first time on V5.1 of MQSeries
| for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT, you
| should relink it with threaded libraries to make it thread-safe.

Chapter 36. Channel-exit programs 519

 Channel-exit programs
| MQSeries for OS/390 without CICS
The exits are invoked as if by an OS/390 LINK, in:
v Non-authorized problem program state
v Primary address space control mode
v Non-cross-memory mode
v Non-access register mode
v 31-bit addressing mode

The link-edited modules must be placed in the data set specified by the CSQXLIB
DD statement of the channel initiator address space procedure; the names of the
load modules are specified as the exit names in the channel definition.

When writing channel exits for OS/390 without CICS, the following rules apply:
v Exits must be written in assembler or C; if C is used, it must conform to the C
systems programming environment for system exits, described in the OS/390
C/C++ Programming Guide.
v Exits are loaded from the non-authorized libraries defined by a CSQXLIB DD
statement. Providing CSQXLIB has DISP=SHR, exits can be updated while the
channel initiator is running, with the new version used when the channel is
restarted.
v Exits must be reentrant, and capable of running anywhere in virtual storage.
v Exits must reset the environment, on return, to that at entry.
v Exits must free any storage obtained, or ensure that it will be freed by a
subsequent exit invocation.
For storage that is to persist between invocations, use the OS/390 STORAGE
service; there is no suitable service in C.
v All MQI calls except MQCMIT/CSQBCMT and MQBACK/CSQBBAK are
allowed. They must be contained between MQCONN (with a blank queue
manager name) and MQDISC, although not necessarily in the same exit
invocation. If these calls are used, the exit must be link-edited with the stub
CSQXSTUB.
The exception to this rule is that security channel exits may issue commit and
backout MQI calls. To do this, code the verbs CSQXCMT and CSQXBAK in
place of MQCMIT/CSQBCMT and MQBACK/CSQBBAK.
v Exits should not use any system services that could cause a wait, because this
would severely impact the handling of some or all of the other channels. Many
channels are run under a single TCB typically, if you do something in an exit
that causes a wait and you do not use MQXWAIT, it will cause all these
channels to wait. This will not give any functional problems, but might have an
adverse effect on performance. Most SVCs involve waits, so you should avoid
them, except for the following:
– GETMAIN/FREEMAIN/STORAGE
– LOAD/DELETE
In general, therefore, SVCs, PCs, and I/O should be avoided. Instead, the
MQXWAIT call should be used.
v Exits should not issue ESTAEs or SPIEs, apart from in any subtasks they attach.
This is because their error handling might interfere with the error handling
performed by MQSeries. This means that MQSeries might not be able to recover
from an error, or that your exit program might not receive all the error
information.

520 MQSeries Intercommunication

 Channel-exit programs
v The MQXWAIT call (see “MQXWAIT - Wait” on page 553) provides a wait
service that allows waiting for I/O and other events; if this service is used, exits
must not use the linkage stack.
For I/O and other facilities that do not provide non-blocking facilities or an ECB
to wait on, a separate subtask should be ATTACHed, and its completion waited
for by MQXWAIT; because of the overhead that this technique incurs, it is
recommended that this be used only by the security exit.
v The MQDISC MQI call will not cause an implicit commit to occur within the exit
program. A commit of the channel process is performed only when the channel
protocol dictates.

The following exit samples are provided with MQSeries for OS/390:
CSQ4BAX0
This sample is written in assembler, and illustrates the use of MQXWAIT.
CSQ4BCX1 and CSQ4BCX2
These samples are written in C and illustrate how to access the parameters.

MQSeries for OS/390 using CICS

In MQSeries for OS/390 using CICS, an exit program must be written in
Assembler, C, COBOL, or PL/I. In CICS, the exits are invoked with EXEC CICS
LINK with the parameters passed by pointers (addresses) in the CICS
communication area (COMMAREA). The exit programs, named in the channel
definitions, reside in a library in the DFHRPL concatenation. They must be defined
in the CICS system definition file CSD, and must be enabled.

User-exit programs can also make use of CICS API calls, but you should not issue
syncpoints because the results could influence units of work declared by the MCA.

Do not update any resources controlled by a resource manager other than

MQSeries for OS/390, including those controlled by CICS Transaction Server for
OS/390.

Any non-MQSeries for OS/390 resources updated by an exit are committed, or

backed out, at the next syncpoint issued by the channel program. If a sender is
unable to synchronize with its partner, these CICS Transaction Server for OS/390
resources are backed out even though MQSeries for OS/390 resources are held
in-doubt until the next opportunity to re-synchronize.

MQSeries for AS/400

| The exit is a program object written in the C/400®, ILE COBOL/400® or ILE
| RPG/400® language. The exit program names and their libraries are named in the
| channel definition.

| Observe the following conditions when creating and compiling an exit program:
| v The program must be made thread safe and created with the C/400, ILE
| RPG/400, or ILE COBOL/400 compiler. For ILE RPG you must specify the
| THREAD(*SERIALIZE) control specification, and for ILE COBOL you must
| specify SERIALIZE for the THREAD option of the PROCESS statement. The
| programs must also be bound to the threaded MQSeries libraries:
| QMQM/LIBMQM_R in the case of C/400 and ILE RPG/400, and AMQ0STUB_R
| in the case of ILE COBOL/400. For additional information about making RPG or
| COBOL applications thread safe, refer to the appropriate Programmer’s Guide
| for the language.

Chapter 36. Channel-exit programs 521

 Channel-exit programs
| v MQSeries for AS/400 requires that the exit programs are enabled for teraspace
| support. (Teraspace is a form of shared memory introduced in OS/400 V4R4.) In
| the case of the ILE RPG and COBOL compilers, any programs compiled on
| OS/400 V4R4 or later are so enabled. In the case of C, the programs must be
| compiled with the TERASPACE(*YES *TSIFC) options specified on CRTCMOD
| or CRTBNDC commands.
| v An exit returning a pointer to its own buffer space must ensure that the object
| pointed to exists beyond the timespan of the channel-exit program. In other
| words, the pointer cannot be the address of a variable on the program stack, nor
| of a variable in the program heap. Instead, the pointer must be obtained from
| the system. An example of this is a user space created in the user exit. To ensure
| that any data area allocated by the channel-exit program is still available for the
| MCA when the program ends, the channel exit must run in the caller’s
| activation group or a named activation group. Do this by setting the ACTGRP
| parameter on CRTPGM to a user-defined value or *CALLER. If the program is
| created in this way, the channel-exit program can allocate dynamic memory and
| pass a pointer to this memory back to the MCA.

| MQSeries for OS/2 Warp

| The exit is a DLL that must be written in C. To ensure that it can be loaded when
| required, specify the full path name in the DEFINE CHANNEL command, or if
| you are using Version 5.1, enter the path name in the ExitPath stanza of the
| QM.INI file. The value in the ExitPath stanza of the QM.INI file defaults to
| c:\mqm\exits. You can change this value in QM.INI or you can override it by
| specifying a full path name on the DEFINE CHANNEL command.

Define a dummy MQStart() routine in the exit and specify MQStart as the entry
point in the shared library. Figure 121 shows how to set up entry to your program:

#include <cmqc.h>
#include <cmqxc.h>

void MQStart() {;} /* dummy entry point - for consistency only */

void MQENTRY ChannelExit ( PMQVOID pChannelExitParms,
PMQVOID pChannelDefinition,
PMQLONG pDataLength,
PMQLONG pAgentBufferLength,
PMQVOID pAgentBuffer,
PMQLONG pExitBufferLength,
PMQPTR pExitBufferAddr)
{
... Insert code here
}

Figure 121. Sample source code for a channel exit on OS/2

Figure 122 on page 523 shows a sample definition file that gives the entry point to
the exit program.

522 MQSeries Intercommunication

 Channel-exit programs
LIBRARY csqos2it INITINSTANCE TERMINSTANCE

PROTMODE

DESCRIPTION 'channel exit '

CODE SHARED LOADONCALL

DATA NONSHARED MULTIPLE

HEAPSIZE 4096
STACKSIZE 8192

EXPORTS
csqos2it;

Figure 122. Sample DEF file for a channel exit on OS/2

Use a make file like the one shown in Figure 123 to compile and link your
program to create the DLL.

# MAKE FILE TO CREATE AN MQSERIES EXIT

# Make File Creation run in directory:

# D:\EXIT;

.SUFFIXES:

.SUFFIXES: .c .cpp .cxx

CSQOS2IT.DLL: \
csqos2it.OBJ \
MAKEOS2
ICC.EXE @<<
/Fe"CSQOS2IT.DLL" mqm.lib csqos2it.def
csqos2it.OBJ
<<
IMPLIB CSQOS2IT.LIB CSQOS2IT.DLL

{.}.c.obj:
ICC.EXE /Ge- /G5 /C .\$*.c

{.}.cpp.obj:
ICC.EXE /Ge- /G5 /C .\$*.cpp

{.}.cxx.obj:
ICC.EXE /Ge- /G5 /C .\$*.cxx

!include MAKEOS2.DEP

Figure 123. Sample make file for a channel exit on OS/2

Chapter 36. Channel-exit programs 523

 Channel-exit programs
Windows 3.1 client
| The exit is a DLL that must be written in C. It must be placed in a directory
| pointed to by LIBPATH to ensure it can be loaded when required. Define a dummy
| MQStart() routine in the exit and specify MQStart as the entry point in the shared
| library. Figure 124 shows how to set up an entry to your program:

#include <cmqc.h>
#include <cmqxc.h>

void MQStart() {;} /* dummy entry point - for consistency only */

void MQENTRY ChannelExit ( PMQVOID pChannelExitParms,
PMQVOID pChannelDefinition,
PMQLONG pDataLength,
PMQLONG pAgentBufferLength,
PMQVOID pAgentBuffer,
PMQLONG pExitBufferLength,
PMQPTR pExitBufferAddr)
{
... Insert code here
}

Figure 124. Sample source code for a channel exit on Windows 3.1

MQSeries for Windows NT server, MQSeries client for

Windows NT, and MQSeries client for Windows 95 and
Windows 98
| The exit is a DLL that must be written in C.
v On MQSeries for Windows NT server, use the Control Service Manager User
Interface snap-in within the Microsoft Management Console (MMC) in order to
ensure that the DLL can be loaded when required. Specify the full path name on
the DEFINE CHANNEL command or enter the path name in the ExitPath of the
registry entry.
If the exit is on a Windows NT client, specify the path name in the
ClientExitPath stanza of the registry file.
The default exit path is c:\WINNT\Profiles\All Users\Application
Data\MQSeries\EXITS. You can change this value or you can override it by
specifying a full path name on the DEFINE CHANNEL command.
v On MQSeries client for Windows 95 and Windows 98, specify the path name in
the ExitPath stanza of the MQS.INI file You can change this value or you can
override it by specifying a full path name on the DEFINE CHANNEL command.

Define a dummy MQStart() routine in the exit and specify MQStart as the entry
point in the library. Figure 125 on page 525 shows how to set up an entry to your
program:

524 MQSeries Intercommunication

 Channel-exit programs
#include <cmqc.h>
#include <cmqxc.h>

void MQStart() {;} /* dummy entry point - for consistency only */

void MQENTRY ChannelExit ( PMQCXP pChannelExitParms,
PMQCD pChannelDefinition,
PMQLONG pDataLength,
PMQLONG pAgentBufferLength,
PMQVOID pAgentBuffer,
PMQLONG pExitBufferLength,
PMQPTR pExitBufferAddr)
{
... Insert code here
}

Figure 125. Sample source code for a channel exit on Windows NT, Windows 95, or
Windows 98

In order to access the fields pointed to by pChannelExitParms and

pChannelDefinition you need to insert the following lines in your exit program:
.
.
.

/*
. Variable definitions */
.
.

PMQCXP pParms;
. PMQCD pChDef;
.
.

/*
. Code */
.
.

pParms = (PMQCXP)pChannelExitParms;
pChDef = (PMQCD)pChannelDefinition;

The pointers pParms and pChDef can then be dereferenced to access individual
fields.

When writing channel exits for these products using Visual C++, you should do
the following:
v Add MQMVX.LIB to project as a source file10.
v Change the box labelled “Use Run-Time Library” from “Multithreaded” to
“Multithreaded using DLL” in the project settings under C/C++ code
generation.
v Do not change the box labelled “Entry-Point Symbol”. This box can be found in
the project settings, under the Link tab, when you select Category and then
Output.
v Write your own .DEF file; an example of this is shown in Figure 126 on page 526.

10. MQMVX.LIB is used for data conversion and is not available on client products.

Chapter 36. Channel-exit programs 525

 Channel-exit programs
LIBRARY exit

PROTMODE

DESCRIPTION 'Provides Retry and Channel exits'

CODE SHARED LOADONCALL

DATA NONSHARED MULTIPLE

HEAPSIZE 4096
STACKSIZE 8192

EXPORTS Retry

Figure 126. Sample DEF file for Windows NT, Windows 95, Windows 98, or Windows

MQSeries for Windows

The exit is a DLL that must be written in C. To ensure that it can be loaded when
required, specify the full path name on the DEFINE CHANNEL command.
Figure 127 shows how to set up an entry to your program:

#include <cmqc.h>
#include <cmqxc.h>

void MQENTRY ChannelExit ( PMQVOID pChannelExitParms,

PMQVOID pChannelDefinition,
PMQLONG pDataLength,
PMQLONG pAgentBufferLength,
PMQVOID pAgentBuffer,
PMQLONG pExitBufferLength,
PMQPTR pExitBufferAddr)
{
... Insert code here
}

Figure 127. Sample source code for a channel exit on Windows

When writing channel exits for MQSeries for Windows using Visual C++, you
should do the following:
v Change the box labelled “Use Run-Time Library” from “Multithreaded” to
“Multithreaded using DLL” in the project settings under C/C++ code
generation.
v Do not change the box labelled “Entry-Point Symbol”. This box can be found in
the project settings, under the Link tab, when you select Category and then
Output.
v Write your own .DEF file; an example of this is shown in Figure 126.

MQSeries for AIX

Note: Before you use an existing user exit for the first time on MQSeries for AIX,
V5.1, you must recompile it to enable it to take advantage of thread-safe
system calls. If your user exits use thread-unsafe system calls, you will need
to modify them before using them on this platform.

| The exit is a dynamically loaded object that must be written in C. To ensure that it
| can be loaded when required, specify the full path name in the DEFINE
| CHANNEL command or enter the path name in the ExitPath stanza of the QM.INI
| file. If the exit is on an AIX client, specify the path name in the ClientExitPath

526 MQSeries Intercommunication

 Channel-exit programs
| stanza of the MQS.INI file. The value in the ExitPath stanza of the QM.INI file or
| the ClientExitPath stanza of the MQS.INI file defaults to /var/mqm/exits. You can
| change this value or you can override it by specifying a full path name on the
| DEFINE CHANNEL command.

Define a dummy MQStart() routine in the exit and specify MQStart as the entry
point in the module. Figure 128 shows how to set up an entry to your program:

#include <cmqc.h>
#include <cmqxc.h>

void MQStart() {;} /* dummy entry point - for consistency only */

void MQENTRY ChannelExit ( PMQVOID pChannelExitParms,
PMQVOID pChannelDefinition,
PMQLONG pDataLength,
PMQLONG pAgentBufferLength,
PMQVOID pAgentBuffer,
PMQLONG pExitBufferLength,
PMQPTR pExitBufferAddr)
{
... Insert code here
}

Figure 128. Sample source code for a channel exit on AIX

Figure 129 shows the compiler and loader commands for channel-exit programs on
AIX.

$ cc -c exit.c
$ ld -o exit exit.o -bE:exit.exp -H512 -T512 -e MQStart -bM:SRE
$ cp exit /usr/xmp/lib # (or wherever you require)

Figure 129. Sample compiler and loader commands for channel exits on AIX

Chapter 36. Channel-exit programs 527

 Channel-exit programs
Figure 131 shows a sample make file that can be used to build an MQSeries exit
program, and Figure 130 shows a sample export file for this make file.

#!
csqaixit
MQStart

Figure 130. Sample export file for AIX

# MAKE FILE TO BUILD AN MQSERIES EXIT ON AIX

MQIDIR = /usr/mqm
MQILIBDIR = $(MQIDIR)/lib
MQIINCDIR = $(MQIDIR)/inc

LIBEXIT = -lmqm

CFLAGS = -g -bloadmap:muck

ALL : CSQAIXIT

csqaixit: csqaixit.o
xlc -L $(MQILIBDIR) $(LIBEXIT) csqaixit.o -o csqaixit \
-bE:csqaixit.exp -H512 -T512 -e MQStart -bM:SRE

csqaixit.o : csqaixit.c
xlc -c csqaixit.c \
-I $(MQIINCDIR)

Figure 131. Sample make file for AIX

MQSeries for Compaq (DIGITAL) OpenVMS

| The user exit is a dynamically loaded image that can be shared, with its name
| taken from the format of the message. It must be written in C. The object’s name
| must be in uppercase, for example MYFORMAT. The shareable image must be placed
| in sys$share or a location defined by a logical name at executive level for it to be
| loaded.

User exits must be installed as known images. Figure 132 shows how to set up an
entry to your program:

#include <cmqc.h>
#include <cmqxc.h>

void MQStart() {;} /* dummy entry point */

void MQENTRY ChannelExit ( PMQVOID pChannelExitParms,
PMQVOID pChannelDefinition,
PMQLONG pDataLength,
PMQLONG pAgentBufferLength,
PMQVOID pAgentBuffer,
PMQLONG pExitBufferLength,
PMQPTR pExitBufferAddr)
{
... Insert code here
}

Figure 132. Sample source code for a channel exit on Digital OVMS

528 MQSeries Intercommunication

 Channel-exit programs
In the example, MQSTART is the initialization routine entry point for the
MYFORMAT shareable image. The names of the routines that are called by the exit
must be made universal.
$ CC /INCLUDE_DIRECTORY=MQS_INCLUDE exitname.C
$ LINK /SHARE=SYS$SHARE:[SYSLIB]MYFORMAT exitname.OBJ,MYFORMAT/OPTIONS

The contents of MYFORMAT.OPT vary depending on what platform you are

working on:

On AXP:
SYS$SHARE:MQM/SHAREABLE
SYMBOL_VECTOR=(MQSTART=PROCEDURE)

On VAX:
SYS$SHARE:MQM/SHAREABLE
UNIVERSAL=MQSTART

If you are using threaded applications linked with the pthread library, you must
also build a second copy of the exit with the thread options and libraries:
$ CC /INCLUDE_DIRECTORY=MQS_INCLUDE exitname.C
$ LINK /SHARE=SYS$SHARE:MYFORMAT exitname.OBJ,MYFORMAT/OPTIONS

Again, the contents of MYFORMAT.OPT vary depending on what platform you are
working on:

On AXP:
SYS$SHARE:MQM_R/SHAREABLE
SYS$SHARE:CMA$OPEN_RTL.EXE/SHAREABLE
SYMBOL_VECTOR’-(MQSTART=PROCEDURE)

On VAX:
SYS$SHARE:MQM_R/SHAREABLE
SYS$SHARE:CMA$OPEN_RTL.EXE/SHAREABLE
UNIVERSAL=MQSTART

| MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX)

| The exit is a dynamically loaded object that must be written in C. To ensure that it
| can be loaded when required, link and copy the exit to the /usr/lib directory.
| Define a dummy MQStart() routine in the exit and specify MQStart as the entry
| point in the module. Figure 133 on page 530 shows how to set up an entry to your
| program:
|

Chapter 36. Channel-exit programs 529

 Channel-exit programs
#include <cmqc.h>
#include <cmqxc.h>

void MQStart() {;} /* dummy entry point - for consistency only */

void MQENTRY ChannelExit ( PMQVOID pChannelExitParms,
PMQVOID pChannelDefinition,
PMQLONG pDataLength,
PMQLONG pAgentBufferLength,
PMQVOID pAgentBuffer,
PMQLONG pExitBufferLength,
PMQPTR pExitBufferAddr)
{
... Insert code here
}

Figure 133. Sample source code for a channel exit on DIGITAL UNIX

| Figure 134 shows the compiler and loader commands for channel-exit programs on
| DIGITAL UNIX.
|
$ cc -stdl -c -I/opt/mqm/inc exit.c
$ ld -o exit exit.o -shared -L/opt/mqm/lib -lmqm -e MQStart -lc
$ cp exit /usr/lib

Figure 134. Sample compiler and loader commands for channel exits on DIGITAL UNIX

| MQSeries for HP-UX

Note: Before you use an existing user exit for the first time on MQSeries for
HP-UX, V5.1, you must recompile it to enable it to take advantage of
thread-safe system calls. If your user exits use thread-unsafe system calls,
you will need to modify them before using them on this platform.

| The exit is a dynamically loaded object that must be written in C. To ensure that it
| can be loaded when required, specify the full path name in the DEFINE
| CHANNEL command or enter the path name in the ExitPath stanza of the QM.INI
| file. If the exit is on an HP-UX client, specify the path name in the ClientExitPath
| stanza of the MQS.INI file. The value in the ExitPath stanza of the QM.INI file or
| the ClientExitPath stanza of the MQS.INI file defaults to /var/mqm/exits. You can
| change this value or you can override it by specifying a full path name on the
| DEFINE CHANNEL command.

Define a dummy MQStart() routine in the exit and specify MQStart as the entry
point in the module. Figure 135 on page 531 shows how to set up an entry to your
program:

530 MQSeries Intercommunication

 Channel-exit programs
#include <cmqc.h>
#include <cmqxc.h>

void MQStart() {;} /* dummy entry point - for consistency only */

void MQENTRY ChannelExit ( PMQVOID pChannelExitParms,
PMQVOID pChannelDefinition,
PMQLONG pDataLength,
PMQLONG pAgentBufferLength,
PMQVOID pAgentBuffer,
PMQLONG pExitBufferLength,
PMQPTR pExitBufferAddr)
{
... Insert code here
}

Figure 135. Sample source code for a channel exit on HP-UX

Figure 136 shows the compiler and loader commands for channel-exit programs on
HP-UX.

$ cc -c +z exit.c
$ ld -o exit exit.o +b : -c exit.exp +I MQStart -b
$ cp exit /usr/xmp/lib # (or wherever you require)

Figure 136. Sample compiler and loader commands for channel exits on HP-UX

MQSeries for AT&T GIS UNIX

| The exit is a dynamically loaded object that must be written in C. Specify the full
| path name in the DEFINE CHANNEL command. Define a dummy MQStart()
| routine in the exit and specifyMQStart as the entry point in the module.
| Figure 137shows how to set up an entry to your program:

#include <cmqc.h>
#include <cmqxc.h>

void MQStart() {;} /* dummy entry point */

void MQENTRY ChannelExit ( PMQVOID pChannelExitParms,
PMQVOID pChannelDefinition,
PMQLONG pDataLength,
PMQLONG pAgentBufferLength,
PMQVOID pAgentBuffer,
PMQLONG pExitBufferLength,
PMQPTR pExitBufferAddr)
{
... Insert code here
}

Figure 137. Sample source code for a channel exit on AT&T GIS UNIX

Figure 138 on page 532 shows the compiler and loader commands for channel-exit
programs on AT&T GIS UNIX11.

11. This platform has become NCR UNIX SVR4 MP-RAS, R3.0

Chapter 36. Channel-exit programs 531

 Channel-exit programs
$ cc -c PIC exit.c
$ ld -o exit -G exit.o
$ cp exit /usr/xmp/lib # (or wherever you require)

Figure 138. Sample compiler and loader commands for channel exits on AT&T GIS UNIX

MQSeries for Sun Solaris

Note: Before you use an existing user exit for the first time on MQSeries for Sun
Solaris, V5.1, you must recompile it to enable it to take advantage of
thread-safe system calls. If your user exits use thread-unsafe system calls,
you will need to modify them before using them on this platform. If you
have DCE installed, your channel exits must be threaded with DCE
threading. If you do not have DCE installed, your channel exits must be
threaded with Posix V10 threading.

| The exit is a dynamically loaded object that must be written in C. To ensure that it
| can be loaded when required, specify the full path name in the DEFINE
| CHANNEL command or enter the path name in the ExitPath stanza of the QM.INI
| file. If the exit is on a Sun Solaris client, specify the path name in the
| ClientExitPath stanza of the MQS.INI file. The value in the ExitPath stanza of the
| QM.INI file or the ClientExitPath stanza of the MQS.INI file defaults to
| /var/mqm/exits. You can change this value or you can override it by specifying a
| full path name on the DEFINE CHANNEL command.

Define a dummy MQStart() routine in the exit and specify MQStart as the entry
point in the module. Figure 139 shows how to set up an entry to your program:

#include <cmqc.h>
#include <cmqxc.h>

void MQStart() {;} /* dummy entry point */

void MQENTRY ChannelExit ( PMQVOID pChannelExitParms,
PMQVOID pChannelDefinition,
PMQLONG pDataLength,
PMQLONG pAgentBufferLength,
PMQVOID pAgentBuffer,
PMQLONG pExitBufferLength,
PMQPTR pExitBufferAddr)
{
... Insert code here
}

Figure 139. Sample source code for a channel exit on Sun Solaris

Figure 140 shows the compiler and loader commands for channel-exit programs on
Sun Solaris.

$ cc -c -KPIC exit.c
$ ld -G exit.o -o exit
$ cp exit /usr/xmp/lib # (or wherever you require)

Figure 140. Sample compiler and loader commands for channel exits on Sun Solaris

MQSeries for SINIX and DC/OSx

| The exit is a dynamically loaded object that must be written in C. Specify the full
| path name in the DEFINE CHANNEL command. Define a dummy MQStart()

532 MQSeries Intercommunication

 Channel-exit programs
| routine in the exit and specify MQStart as the entry point in the module. Figure 141
| shows how to set up an entry to your program:

#include <cmqc.h>
#include <cmqxc.h>

void MQStart() {;} /* dummy entry point */

void MQENTRY ChannelExit ( PMQVOID pChannelExitParms,
PMQVOID pChannelDefinition,
PMQLONG pDataLength,
PMQLONG pAgentBufferLength,
PMQVOID pAgentBuffer,
PMQLONG pExitBufferLength,
PMQPTR pExitBufferAddr)
{
... Insert code here
}

Figure 141. Sample source code for a channel exit on SINIX and DC/OSx

Figure 142 shows the compiler and loader commands for channel-exit programs on
SINIX and DC/OSx.

$ cc -Kpic exit.c -G -o exit -lmqm -lmqmcs

$ cp exit /opt/mqm/lib # (or wherever you require)

Figure 142. Sample compiler and loader commands for channel exits on SINIX and DC/OSx

For DC/OSx, version cd087 and later, append the following to the cc line:
-liconv -lresolv

For earlier versions of DC/OSx, append the following to the cc line:

-liconv

MQSeries for Tandem NonStop Kernel

| MQSeries for Tandem NonStop Kernel supports a single, statically bound
| channel-exit program, whose entry point is MQ_CHANNEL_EXIT(). The exit must
| be written in C. MQSeries for Tandem NonStop Kernel provides a stub function for
| this exit that acts as a placeholder for user-supplied exit code. In the supplied stub
| function, the ExitResponse field in MQCXP (channel exit parameter structure) is set
| to MQXCC_CLOSE_CHANNEL, which causes the MCA to close the channel. No
| other fields in MQCXP are modified.

You replace the supplied stub function in the MCA executable images with your
own user exit code using the Tandem BIND utility BEXITE. Only the Tandem
Common Runtime Environment (CRE) interface for the WIDE memory model is
supported.

In MQSeries for Tandem NonStop Kernel, there is a single entry point for all
channel exits. In other MQSeries Version 2 products, there are entry points specific
to each channel type and function. It is possible to use channel-exit programs
written for other MQSeries Version 2 products by calling those programs from
MQ_CHANNEL_EXIT(). To determine the type of exit being called, examine the
ExitId field of MQCXP, then extract the associated exit-program name from the
MsgExit, MsgRetryExit, ReceiveExit, SendExit, or SecurityExit field of MQCD.

The channel attributes that define the names of user exits are:

Chapter 36. Channel-exit programs 533

 Channel-exit programs
v Security exit name (SCYEXIT)
v Message-retry exit name (MREXIT)
v Message exit name (MSGEXIT)
v Send exit name (SENDEXIT)
v Receive exit name (RCVEXIT)

If these channel attributes are left blank, the channel user exit is not invoked. If
any of the channel attributes is nonblank, the MQ_CHANNEL_EXIT() user exit
program is invoked for the corresponding function. Note that the text-string value
of the channel attribute is not used to determine the name of the user exit
program, since only a single entry point, MQ_CHANNEL_EXIT(), is supported in
MQSeries for Tandem NonStop Kernel. However, the values of these channel
attributes are passed to MQ_CHANNEL_EXIT() in the MQCD (channel data)
structure. The function of the channel exit (that is, whether the exit corresponds to
a Message, Message-retry, Receive, Security or Send Exit) is passed to
MQ_CHANNEL_EXIT() in the ExitId field of the MQCXP (Channel Exit
Parameters) structure.

MQSeries for Tandem NonStop Kernel does not support the following channel
attributes:
v CICS Profile Name
v Sequential delivery
v Target system identifier
v Transaction identifier
v Maximum transmission size

| Building and using channel exit functions

| Dynamically bound libraries are not supported by MQSeries for Tandem NSK.
| Channel exits (and data-conversion exits) are implemented by including statically
| bound stub functions in the MQSeries libraries and executables which can be
| replaced using the REPLACE bind option.

| A channel exit function must be written in C, must be called CHANNELEXIT (see

| sample MQSVCHX), and can be bound into the chosen executable (or library)
| using the TACL macro BEXITE.

| Note: This procedure modifies the target executable. Therefore, you are
| recommended to make a backup copy of the target executable or library
| before using the macro.

| The function CHANNELEXIT must handle each of the possible exit calls (security,
| message-retry, message, send, and receive). You may write your own functions to
| do this.

| Use the TACL macro BCHXALL to bind the data conversion exit into all required
| MQSeries processes. For example:
| BCHXALL source-exit-file-or-library

| Sample channel exit:

| /********************************************************************/
| /* */
| /* Program name: MQSVCHXE */
| /* */
| /* Description: Sample C skeleton of a Channel Exit controlling */
| /* function */
| /* */
| /* Statement: Licensed Materials - Property of IBM */

534 MQSeries Intercommunication

 Channel-exit programs
| /* */
| /* 33H2205, 5622-908 */
| /* 33H2267, 5765-623 */
| /* 29H0990, 5697-176 */
| /* (C) Copyright IBM Corp. 1994, 1995 */
| /* */
| /********************************************************************/
| /* */
| /* Function: */
| /* */
| /* MQSVCHXE is a sample C skeleton of a Channel Exit controlling */
| /* function */
| /* */
| /* The function controls the calls to user-defined channel exits */
| /* */
| /* */
| /* Once complete the code should be compiled into a loadable */
| /* object, the name of the object should be the name of the */
| /* format to be converted. Instructions on how to do this are */
| /* contained in the README file in the current directory. */
| /* */
| /********************************************************************/
| /* */
| /* MQSVFCXE takes the parameters defined for a Data Conversion */
| /* exit routine in the CMQXC.H header file. */
| /* */
| /********************************************************************/
| #include <cmqc.h> /* For MQI datatypes */
| #include <cmqxc.h> /* For MQI exit-related definitions */
| #include <amqsvmht.h> /* For sample macro definitions */
|
| /********************************************************************/
| /* Insert the function prototypes for the functions produced by */
| /* the data conversion utility program. */
| /********************************************************************/
|
| MQDATACONVEXIT CHANNELEXIT;
|
| /********************************************************************/
| /* On some Unix systems, the name of this function is not important */
| /* as it is not actually used to call the conversion exit but it */
| /* must be an exported symbol or the entry point to the module. On */
| /* the TANDEM NSK this function MUST be called CHANNELEXIT */
| /********************************************************************/
| void
| MQENTRY CHANNELEXIT(
| PMQVOID pChannelExitParms, /* Channel exit parameter block */
| PMQVOID pChannelDefinition, /* Channel definition */
| PMQLONG pDataLength, /* Length of data */
| PMQLONG pAgentBufferLength, /* Length of agent buffer */
| PMQVOID pAgentBuffer, /* Agent buffer */
| PMQLONG pExitBufferLength, /* Length of exit buffer */
| PMQPTR pExitBufferAddr) /* Address of exit buffer */
| {
| PMQCXP pCEP = pChannelExitParms;
| PMQCD pCD = pChannelDefinition;
| MQLONG ExitId = pCEP->ExitId;
| MQLONG ExitReason = pCEP->ExitReason;
|
| pCEP->ExitResponse = MQXCC_OK ;
|
| /* Call the handling function according to the ExitId */
| /* By default, there are no exits. If there are, then */
| /* this function will have been replaced by a bind */
|
| switch (ExitId)
| {

Chapter 36. Channel-exit programs 535

 Channel-exit programs
| case MQXT_CHANNEL_SEC_EXIT:
| if (strlen(pCD->SecurityExit) == 0)
| {
| pCEP->ExitResponse = MQXCC_SUPPRESS_FUNCTION ;
| }
| else
| {
| /* Call the security exit function here */
| }
| break;
| case MQXT_CHANNEL_MSG_EXIT:
| /* Call the channel message exit function here */
| if (strlen(pCD->MsgExit) == 0)
| {
| pCEP->ExitResponse = MQXCC_SUPPRESS_FUNCTION ;
| }
| else
| {
| /* Call the message exit function here */
| }
| break;
| case MQXT_CHANNEL_SEND_EXIT:
| /* Call the channel send exit function here */
| if (strlen(pCD->SendExit) == 0)
| {
| pCEP->ExitResponse = MQXCC_SUPPRESS_FUNCTION ;
| }
| else
| {
| /* Call the send exit function here */
| }
| break;
| case MQXT_CHANNEL_RCV_EXIT:
| /* Call the channel receive exit function here */
| if (strlen(pCD->ReceiveExit) == 0)
| {
| pCEP->ExitResponse = MQXCC_SUPPRESS_FUNCTION ;
| }
| else
| {
| /* Call the receive exit function here */
| }
| break;
| case MQXT_CHANNEL_MSG_RETRY_EXIT:
| /* Call the channel retry exit function here */
| if (strlen(pCD->MsgRetryExit) == 0)
| {
| pCEP->ExitResponse = MQXCC_SUPPRESS_FUNCTION ;
| }
| else
| {
| /* Call the message retry exit function here */
| }
| break;
| default:
| /* if the exit isn't recognized, stop it from being called again */
| pCEP->ExitResponse = MQXCC_SUPPRESS_EXIT ;
| break;
| }
| return;
| }
| /********************************************************************/
| /* */
| /* END OF MQSVCHXE */
| /* */
| /********************************************************************/

536 MQSeries Intercommunication

 Channel-exit programs
|
Supplied channel-exit programs using DCE security services
V5.1 of MQSeries for AIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT
supply channel-exit programs for the security exit, the message exit, and the send
and receive exits. The MQSeries client for Windows 95 and Windows 98 supplies
channel-exit programs for the security exit and the send and receive exits. These
programs take advantage of the Distributed Computing Environment (DCE)
security services and encryption facilities. Before using the supplied exit programs
from an MQSeries client for Windows 95 and Windows 98, see the note under
“How to use the DCE channel-exit programs” on page 540.

The programs are supplied in source and object format. You can use the objects as
they stand, or can use the source as the basis for creating your own user-exit
programs. You should bear in mind that whereas the objects are supplied as
working programs, the source code does not include any provision for tracing or
error handling. If you chose to modify and use the source code, you should add
your own tracing and error-handling routines.

The object has two entry points:

DCE_SEC_SCY_CHANNELEXIT
For the security exit, which can be used to access authentication services.
DCE_SEC_SRM_CHANNELEXIT
For the send, receive, and message exits, which can be used to access data
encryption services.

What do the DCE channel-exit programs do?

The supplied channel-exit programs address the Distributed Computing
Environment (DCE) considerations for security in the areas of data encryption, and
of authentication of a partner system when establishing a session. For a particular
channel, each exit program has an associated DCE principal (similar to a user ID). A
connection between two exit programs is an association between the two
principals.

A secure connection between two security exit programs, one for the sending MCA
and one for the receiving MCA, is established after the underlying session has
been established. The sequence of operations is as follows:
1. Each program is associated with a particular principal, for example due to an
explicit DCE Login.
2. The program that initiates the secure connection, that is the first program to get
control after the MCA session has been established, is known as the Context
Initiator. The context initiator requests a secure connection with the named
partner from the DCE security server and receives a token. The token (called
token1 in Figure 143 on page 538) is sent, using the already established
underlying session, to the partner program.
3. The partner program (known as the Context Acceptor) passes token1 to the DCE
security server, which verifies that the Context Initiator is authentic. For mutual
authentication, as implemented by the supplied security exit, the DCE security
server also generates a second token (called token2 in Figure 143 on page 538),
which the Context Acceptor returns to the Context Initiator using the
underlying session.
4. The Context Initiator uses token2 to verify that the Context Acceptor is
authentic.
At this stage, if both applications are satisfied with the authenticity of the
partner’s token, then the secure (authenticated) connection is established.

Chapter 36. Channel-exit programs 537

Channel-exit programs
5. The token exchange described above establishes a Security Context for each
security exit program. This context enables the subsequent send, receive, and
message exits to encrypt and decrypt data passed on the connection.
DCE Security provides an API to ‘seal’ and ‘unseal’ data and hence to
selectively protect specified elements of a datastream. The supplied message,
send, and receive exits encrypt and decrypt messages using these DCE Security
API calls.

NODE name1 Flow NODE name2

gss_acquire_cred(name1)
gss_init_sec_context
(name2) ->token1
INIT_SEC(token1)
gss_accept_sec_context
(token1) ->token2
ACC_SEC(token2)
gss_init_sec_context
(name2)

Above two flows can be repeated, if required by GSS.

When satisfied, proceed to other data transfer.

Figure 143. Security exit flows

Clearly the encryption algorithm used by the send exit must match the decryption
algorithm used by the receive exit. The supplied send, receive, and message exits
use the gss_seal() and gss_unseal() calls to encrypt and decrypt data. The qop_req
parameter on the gss_seal() call is set to GSS_C_QOP_DEFAULT. The encryption
provided by DCE depends on the DCE product installed. The supplied encrypting
exits work correctly only when used with US-domestic DCE products supporting
DES encryption. See the MQSeries Planning Guide for information about which DCE
products are supported.

The send, receive, and message exits are all used for encryption. The difference is
that the message exit encrypts only the content of the message, whereas the send
and receive exits also encrypt the message headers. Therefore, the message exit
offers slightly better performance but at the expense of unencrypted header data.

How do the DCE channel-exit programs work?

The supplied code implements a security exit and message, send, and receive exits.
Note that the message exit does not encrypt the MQSeries header. The security exit
provides mutual (two-way) authentication. The message, send, and receive exits
provide encryption facilities based on a key managed by the security context set
up by the security exit. Therefore, the message, send, and receive exits will not
work unless the security exit has been called previously.

The code interfaces to DCE through the DCE GSS API provided as part of OSF
DCE 1.1. This API provides a superset of the standard GSS API calls as specified in
Internet RFCs 1508 and 1509. Some DCE-specific GSS calls have been added to the
API by OSF.

The principal of an MQSeries system that has a queue manager is the queue
manager name.

538 MQSeries Intercommunication

 Channel-exit programs
An MQSeries client does not have a queue manager. The principal used for a client
is as follows:
v On Sun Solaris, AIX, HP-UX, Windows NT, Windows 95, and Windows 98
clients:
– If the login user ID of the user who started the MQSeries client application
can be obtained and is defined as a principal to DCE, this user ID is used.
– If the login user ID of the user who started the MQSeries client application
cannot be obtained or is not defined to DCE, and a DCE default login context
exists, the DCE default credential is used.

Note: When a principal logs in to DCE, a default login context is established.

In this case the principal used in association with the DCE default
credential is that of the principal logged in to DCE.
– If the login user ID of the user who started the MQSeries client application
cannot be obtained or is not defined to DCE, and no DCE default login
context exists, there is no principal name available and the security exit rejects
the attempt to start the channel.
v On OS/2 clients, user IDs cannot be used as principals.
– If a principal has logged in to DCE, the name of this logged in principal is
used.
– If a principal has not logged in to DCE, and a DCE default login context
exists, the DCE default credential is used.
– If a principal has not logged in to DCE, and no DCE default login context
exists, there is no principal name available and the security exit rejects the
attempt to start the channel.

It is important that queue manager names or user IDs that are to be used as DCE
principals are syntactically acceptable to DCE; see your DCE documentation for
information about valid DCE principal names. If the name is to be used only
within the local cell directory, the only mismatch between the allowable characters
in a queue manager name and the allowable characters in a principal name is that
a principal name cannot contain a ‘/’. If there is any likelihood that the name will
also need to be reflected in a global directory, you are recommended to restrict
principal names to alphanumeric characters. As with any DCE principal, when you
create it you must define it to the DCE security server and must also put an entry
for it in the relevant keytable file. Therefore, when you delete a queue manager
that is also a DCE principal you must remember to delete both its entries.

Remote queue manager names are transferred across a channel at channel

initialization. When the security exit is called, if the remote MQSeries system is not
a client, the remote queue manager name (which is also the remote principal) is
passed to the security exit in the MQSeries MQCXP parameter list. The initiator
exit uses the name provided. If the channel is being established between an
MQSeries client and an MQSeries server, the client always initiates the first
security flow. In all cases, the initiator exit’s remote principal name is a queue
manager name.

The flows shown in Figure 143 on page 538 occur to establish the security context.
As a part of these flows the initiator’s principal is transferred to the acceptor.

It is possible to establish multiple security contexts between the same pair of

principals, and hence to allow parallel channels to use the security exit.

Chapter 36. Channel-exit programs 539

Channel-exit programs
You can set up restricted channels. The system administrator supplies a value in the
Channel Security Exit User Data when defining this end of the channel. The
presence of this value causes the security exit to check the remote principal name.
If this check shows a mismatch the channel is not established. Note that the remote
principals (queue manager names and default DCE principals) may be longer than
the 32 characters allowed in the Channel Security Exit User Data. Only the first 32
characters of the remote principal are considered significant.

If the MCA forms part of an MQSeries server system connected to a client, the
security exchange will have caused the client principal to flow to the server. If the
value is valid with regard to the optional restricted-channel check and the
MCAUserIdentifier variable is not already defined, the client principal is copied
into the server’s MCAUserIdentifier variable. Note that client principals may be
longer than the 12-character MCAUserIdentifier. Only the first 12 characters of
such a remote principal are copied.

Thus the first 12 characters of the MQSeries client’s DCE principal name can
become the user identifier to be used by the server’s MCA for authorization for
that client to access MQSeries resources. The server system must be set up
appropriately to allow this to work.

How to use the DCE channel-exit programs

Do not run the supplied DCE message exit in combination with the supplied DCE
send and receive exits on the same channel.

To use the supplied channel-exit programs you need to install DCE and define
some channels. For installation information, see the Quick Beginnings book for your
platform:
v The MQSeries for AIX, V5.1 Quick Beginnings book.
v The MQSeries for HP-UX, V5.1 Quick Beginnings book.
v The MQSeries for Sun Solaris, V5.1 Quick Beginnings book.
v The MQSeries for OS/2 Warp, V5.1 Quick Beginnings book.
v The MQSeries for Windows NT, V5.1 Quick Beginnings book.

Note: Using IBM DCE for Windows 95 V1, you cannot use the supplied DCE
security exit from a Windows 95 client connected to an MQSeries for HP-UX
server or an MQSeries for Sun Solaris server. Nor can you use the supplied
send and receive exits from a Windows 95 client when using IBM DCE for
Windows 95 V1.

Setup for DCE

The supplied channel-exit programs are intended for use between systems
operating within a single DCE cell. The setup of a DCE cell is described in the
documentation provided with the DCE packages for the platforms incorporated in
the cell. The exit programs operate the same way whether they are running on a
system with a DCE security client installed or with a DCE security server installed.

Once the DCE cell has been configured, it is necessary to define the principals that
the exit is going to use to DCE. DCE setup samples are provided on all the
supported platforms. The samples are primarily intended for setting up DCE for
the DCE Names installable component. They also contain comments indicating
how they can be modified to set up the DCE security principals instead of, or as
well as, the Names principal.

540 MQSeries Intercommunication

 Channel-exit programs
Each DCE security principal has its own keytable. On UNIX systems that support
DCE security, the keytable is a file within the directory /var/mqm/dce/keytabs.
On OS/2, Windows NT, Windows 95, and Windows 98 it is a file within the
directory \MQM\DCE\KEYTABS, where MQM is the name of your work path.

When the supplied channel-exit programs are called for a particular principal, they
look in a keytable file that has the same name as the principal itself. Therefore, the
keytable file for a particular principal must have the same name as that principal.

The use of separate keytables for each principal is recommended in the OSF DCE
literature. On systems that support file access controls (UNIX systems and
Windows NT) keytable access should be limited to:
v Superuser/administrator: no restriction
v Other user IDs:
– read only access, given only to the user IDs under which the processes that
call the security exits run, and only to the relevant keytables.

In the case of queue manager MQSeries systems, the processes that interface to the
security exits at the sending end of the channel are runmqchl (and runmqchi on
OS/2 and Windows NT). amqcrsta, amqcrs6a or runmqlsr interface to the security
exits at the receiving end of the channel. On most systems these all run under the
mqm user ID; in this case, non-supervisor/administrator access to the keytables
relating to queue manager principals should be restricted to read access for the
mqm user ID.

On client systems the user ID under which the security exit is called is the user ID
under which the client application runs (often the login user ID of the user of the
client system). Again, non-supervisor/administrator access to the relevant keytable
should be restricted to read access by that user ID only.

The supplied exit code

The supplied exit code is in two formats: object and source.

Object: The object is called amqrdsc0 on UNIX systems and amqrdsc0.DLL on

OS/2, Windows NT, Windows 95, and Windows 98. It is installed as a standard
part of the MQSeries product for your platform and is loaded as a standard user
exit. If you wish to run the supplied security channel exit to make use of
authentication services then in your definition of the channel, specify:
SCYEXIT('<path>amqrdsc0(DCE_SEC_SCY_CHANNELEXIT)')

If you also wish to use the message exit to support data encryption, then in your
definition of the channel, specify:
MSGEXIT('<path>amqrdsc0(DCE_SEC_SRM_CHANNELEXIT)')

Or you can use the send and receive exits to support data encryption by specifying
the following in your definition of the channel:
SENDEXIT('<path>amqrdsc0(DCE_SEC_SRM_CHANNELEXIT)')
RCVEXIT('<path>amqrdsc0(DCE_SEC_SRM_CHANNELEXIT)')

<path> is the path to the directory containing the exit.

See page 520 through page 533 for information about how to call user exits on the
platform you are using.

Chapter 36. Channel-exit programs 541

Channel-exit programs
Source: The exit source file is called amqsdsc0.c. It can be found in
<mqmtop>/samp on UNIX systems and in <bootdrive>:\mqm\tools\c\samples on
OS/2, Windows NT, Windows 95, and Windows 98. If you choose to modify the
source versions, rather than running the objects as they stand, you will need to
recompile the modified source. It is compiled and linked in the same way as any
other channel exit for the platform concerned, except that DCE headers need to be
accessed at compile time, and the DCE libraries, together with any recommended
associated libraries, need to be accessed at link time. Refer to the documentation
for the DCE product for the platform you are using, to find out about the DCE and
associated libraries.
OS/2
icc /DIBMOS2 /DINTEL80x86 /Fe amqsdsc0.dll /I \
c:\mqclient\tools\c\include /I \
c:\ibmcppw\include /I c:\opt\dcelocal\include\dce \
/W3 /Sa /Ge- /Gm+ amqsdsc0.c amqsdsc0.def dceos2.lib

Using the following definition file:

LIBRARY AMQSDSC0
PROTMODE
DESCRIPTION 'DCE Security Exit'
CODE SHARED LOADONCALL
DATA NONSHARED MULTIPLE
HEAPSIZE 4096
STACKSIZE 8192
EXPORTS
DCE_SEC_SCY_CHANNELEXIT
DCE_SEC_SRM_CHANNELEXIT
Sun Solaris
cc -I/opt/dce/share/include/dce \
-I/opt/mqm/inc -KPIC -c amqsdsc0.c

followed by:
ld -G -L/opt/dce/share/usr/lib -ldce amqsdsc0.o -o srm
HP-UX
cc -D_HPUX_SOURCE -Dhpux -DICOL -D_REENTRANT \
-Dsigaction=cma_sigaction +ESlit +DA1.0 -c +z \
amqsdsc0.c -I /opt/mqm/include -I /opt/dce/include/dce \
-Aa && ld -o amqsdsc0 amqsdsc0.o -z +b : -b +I MQStart \
-ldce -lmqm_r -lndbm -lM -lc_r
Windows 95, Windows 98, and Windows NT
c:\msdevstd\bin\cl /DAMQ_PC /VERBOSE /LD /MT \
/Ic:\msdevstd\include /ID:\MQCLIENT\TOOLS\C\INCLUDE \
/IC:\OPT\DIGITAL\DCE\INCLUDE\DCE amqsdsc0.c \
-link /DLL /EXPORT:DCE_SEC_SCY_CHANNELEXIT \
/EXPORT:DCE_SEC_SRM_CHANNELEXIT /STACK:8192 libdce.lib \
advapi32.lib libcmt.lib
AIX
xlC_r -c /usr/mqm/samp/amqsdsc0.c -I/usr/include/dce

ld -e MQStart -bnoquiet -o amqsdsc0 amqsdsc0.o \

-L/usr/lib/dce -T512 -H512 -ldce -bE:amqsdsc0.exp \
-lpthreads -lc_r -liconv -ls

Using DCE channel exits with the runmqlsr listener program

On MQSeries for Windows NT, the exit dll name must be amqrdsc0.dll or
amqsdsc0.dll.

542 MQSeries Intercommunication

 Chapter 37. Channel-exit calls and data structures
This chapter provides reference information about the special MQSeries calls and
data structures used when writing channel exit programs. This is product-sensitive
programming interface information. You can write MQSeries user exits in the
following programming languages:

Platform Programming languages

| MQSeries for OS/390 Assembler and C (which must conform to the C system
| without CICS programming environment for system exits, described in the
| OS/390 C/C++ Programming Guide.)
MQSeries for OS/390 Assembler, C, COBOL, and PL/I
using CICS
MQSeries for AS/400 C, COBOL, and RPG II
All other MQSeries C
platforms

You cannot write MQSeries user exits in TAL.

In a number of cases, parameters are arrays or character strings whose size is not
fixed. For these, a lowercase “n” is used to represent a numeric constant. When the
declaration for that parameter is coded, the “n” must be replaced by the numeric
value required. For further information about the conventions used in these
descriptions, see the MQSeries Application Programming Reference book.

The calls are:

v “MQ_CHANNEL_EXIT - Channel exit” on page 546
v “MQ_CHANNEL_AUTO_DEF_EXIT - Channel auto-definition exit” on page 551
v “MQXWAIT - Wait” on page 553
v “MQ_TRANSPORT_EXIT - Transport retry exit” on page 555

The data structures are:

v “MQCD - Channel data structure” on page 556
v “MQCXP - Channel exit parameter structure” on page 591
v “MQTXP - Transport-exit data structure” on page 605
v “MQXWD - Exit wait descriptor structure” on page 609

Note: Channel exit programs are not supported on DOS or VSE/ESA.

© Copyright IBM Corp. 1993, 2000 543

Calls and structures

Data definition files

The data definition files supplied with the products for each programming
language are:
Main API definition

C CMQC
COBOL CMQV
PL/I CMQP
RPG CMQR
ASM370 CMQA

System extensions (MQX)

C CMQXC
COBOL CMQXV
PL/I CMQXP
RPG CMQXR
ASM370 CMQXA

Channel data (MQCD)

COBOL CMQCDL, CMQCDV

RPG CMQCDR
ASM370 CMQCDA

Channel exit (MQCXP)

COBOL CMQCXPL, CMQCXPV

RPG CMQCXPR
ASM370 CMQCXPA

Dead-letter header (MQDLH)

COBOL CMQDLHL, CMQDLHV

RPG CMQDLHR
ASM370 CMQDLHA

Exit parameter (MQXP)

COBOL CMQXPL, CMQXPV

RPG CMQXPR
ASM370 CMQXPA

Transmission header (MQXQH)

COBOL CMQXQHL, CMQXQHV

RPG CMQXQHR
ASM370 CMQXQHA

Where the file for the C or PL/I language is not included in the above, it has been
included in separate common files containing all C or PL/I data. For message
queuing applications the file names for C and PL/I are:

C CMQC
PL/I CMQP

544 MQSeries Intercommunication

 Calls and structures
For systems programs the file names for C and PL/I are:

C CMQXC
PL/I CMQXP

For a list of the complete set of header files for the product, see the MQSeries
Application Programming Guide, or, for MQSeries for Windows, see the MQSeries for
Windows User’s Guide.

Chapter 37. Channel-exit calls and data structures 545

MQ_CHANNEL_EXIT - Channel exit

MQ_CHANNEL_EXIT - Channel exit

This call definition is provided solely to describe the parameters that are passed to
each of the channel exits called by the Message Channel Agent. No entry point
called MQ_CHANNEL_EXIT is actually provided by the queue manager; the name
MQ_CHANNEL_EXIT is of no special significance since the names of the channel
exits are provided in the channel definition MQCD.

This definition is part of the MQSeries Security Enabling Interface (SEI), which is
one of the MQSeries framework interfaces.

There are five types of channel exit:

v Channel security exit
v Channel message exit
v Channel send exit
v Channel receive exit
v Channel message-retry exit

The parameters are similar for each type of exit, and the description given here
applies to all of them, except where specifically noted.

Syntax
MQ_CHANNEL_EXIT (ChannelExitParms, ChannelDefinition, DataLength,
AgentBufferLength, AgentBuffer, ExitBufferLength, ExitBufferAddr)

Parameters
ChannelExitParms (MQCXP) – input/output
Channel exit parameter block.

This structure contains additional information relating to the invocation of the

exit. The exit sets information in this structure to indicate how the MCA
should proceed.
ChannelDefinition (MQCD) – input/output
Channel definition.

This structure contains parameters set by the administrator to control the

behavior of the channel.
DataLength (MQLONG) – input/output
Length of data.

When the exit is invoked, this contains the length of data in the AgentBuffer
parameter. The exit must set this to the length of the data in either the
AgentBuffer or the ExitBufferAddr (as determined by the ExitResponse2 field
in the ChannelExitParms parameter) that is to proceed.

The data depends on the type of exit:

v For a channel security exit, when the exit is invoked this contains the length
of any security message in the AgentBuffer field, if ExitReason is
MQXR_SEC_MSG. It is zero if there is no message. The exit must set this
field to the length of any security message to be sent to its partner if it sets
ExitResponse to MQXCC_SEND_SEC_MSG or
MQXCC_SEND_AND_REQUEST_SEC_MSG. The message data is in either
AgentBuffer or ExitBufferAddr.

546 MQSeries Intercommunication

 MQ_CHANNEL_EXIT - Channel exit
The content of security messages is the sole responsibility of the security
exits.
v For a channel message exit, when the exit is invoked this contains the length
of the message (including the transmission queue header). The exit must set
this field to the length of the message in either AgentBuffer or
ExitBufferAddr that is to proceed.
v For a channel send or channel receive exit, when the exit is invoked this
contains the length of the transmission. The exit must set this field to the
length of the transmission in either AgentBuffer or ExitBufferAddr that is to
proceed.

If a security exit sends a message, and there is no security exit at the other end
of the channel, or the other end sets an ExitResponse of MQXCC_OK, the
initiating exit is re-invoked with MQXR_SEC_MSG and a null response
(DataLength=0).
AgentBufferLength (MQLONG) – input
Length of agent buffer.

This can be greater than DataLength on invocation.

For channel message, send, and receive exits, any unused space on invocation
can be used by the exit to expand the data in place. If this is done, the
DataLength parameter must be set appropriately by the exit.

In the C programming language, this parameter is passed by address.

AgentBuffer (MQBYTE×AgentBufferLength) – input/output
Agent buffer.

The contents of this depend upon the exit type:

v For a channel security exit, on invocation of the exit it contains a security
message if ExitReason is MQXR_SEC_MSG. If the exit wishes to send a
security message back, it can either use this buffer or its own buffer
(ExitBufferAddr).
v For a channel message exit, on invocation of the exit this contains:
– The transmission queue header (MQXQH), which includes the message
descriptor (which itself contains the context information for the message),
immediately followed by
– The message data

If the message is to proceed, the exit can do one of the following:

– Leave the contents of the buffer untouched
– Modify the contents in place (returning the new length of the data in
DataLength; this must not be greater then AgentBufferLength)
– Copy the contents to the ExitBufferAddr, making any required changes

Any changes that the exit makes to the transmission queue header are not
checked; however, erroneous modifications may mean that the message
cannot be put at the destination.
v For a channel send or receive exit, on invocation of the exit this contains the
transmission data. The exit can do one of the following:
– Leave the contents of the buffer untouched
– Modify the contents in place (returning the new length of the data in
DataLength; this must not be greater then AgentBufferLength)
– Copy the contents to the ExitBufferAddr, making any required changes

Chapter 37. Channel-exit calls and data structures 547

MQ_CHANNEL_EXIT - Channel exit
Note that the first 8 bytes of the data must not be changed by the exit.
ExitBufferLength (MQLONG) – input/output
Length of exit buffer.

On the first invocation of the exit, this is set to zero. Thereafter whatever value
is passed back by the exit, on each invocation, is presented to the exit next
time it is invoked. The value is not used by the MCA (except in MQSeries for
OS/390 using CICS for distributed queue management, where a check is made
that DataLength does not exceed ExitBufferLength, if the exit is returning data
in ExitBufferAddr).

Note: This parameter should not be used by exits written in programming

languages which do not support the pointer data type.
ExitBufferAddr (MQPTR) – input/output
Address of exit buffer.

This is a pointer to the address of a buffer of storage managed by the exit,

where it can choose to return message or transmission data (depending upon
the type of exit) to the agent if the agent’s buffer is or may not be large
enough, or if it is more convenient for the exit to do so.

On the first invocation of the exit, the address passed to the exit is null.
Thereafter whatever address is passed back by the exit, on each invocation, is
presented to the exit the next time it is invoked.

Note: This parameter should not be used by exits written in programming

languages that do not support the pointer data type.

Usage notes
1. The function performed by the channel exit is defined by the provider of the
exit. The exit, however, must conform to the rules defined here and in the
associated control block, the MQCXP.
2. The ChannelDefinition parameter passed to the channel exit may be one of
several versions. See the Version field in the MQCD structure for more
information.
3. If the channel exit receives an MQCD structure with the Version field set to a
value greater than MQCD_VERSION_1, the exit should use the ConnectionName
field in MQCD, in preference to the ShortConnectionName field.
4. In general, channel exits are allowed to change the length of message data. This
may arise as a result of the exit adding data to the message, or removing data
from the message, or compressing or encrypting the message. However, special
restrictions apply if the message is a segment that contains only part of a
logical message. In particular, there must be no net change in the length of the
message as a result of the actions of complementary sending and receiving
exits.
For example, it is permissible for a sending exit to shorten the message by
compressing it, but the complementary receiving exit must restore the original
length of the message by decompressing it, so that there is no net change in the
length of the message.
This restriction arises because changing the length of a segment would cause
the offsets of later segments in the message to be incorrect, and this would
inhibit the queue manager’s ability to recognize that the segments formed a
complete logical message.

548 MQSeries Intercommunication

 MQ_CHANNEL_EXIT - Channel exit
C invocation
exitname (&ChannelExitParms, &ChannelDefinition,
&DataLength, &AgentBufferLength, AgentBuffer,
&ExitBufferLength, &ExitBufferAddr);

Declare the parameters as follows:

MQCXP ChannelExitParms; /* Channel exit parameter block */
MQCD ChannelDefinition; /* Channel definition */
MQLONG DataLength; /* Length of data */
MQLONG AgentBufferLength; /* Length of agent buffer */
MQBYTE AgentBuffer[n]; /* Agent buffer */
MQLONG ExitBufferLength; /* Length of exit buffer */
MQPTR ExitBufferAddr; /* Address of exit buffer */

COBOL invocation
CALL 'exitname' USING CHANNELEXITPARMS, CHANNELDEFINITION,
DATALENGTH, AGENTBUFFERLENGTH, AGENTBUFFER,
EXITBUFFERLENGTH, EXITBUFFERADDR.

Declare the parameters as follows:

** Channel exit parameter block
01 CHANNELEXITPARMS.
COPY CMQCXPV.
** Channel definition
01 CHANNELDEFINITION.
COPY CMQCDV.
** Length of data
01 DATALENGTH PIC S9(9) BINARY.
** Length of agent buffer
01 AGENTBUFFERLENGTH PIC S9(9) BINARY.
** Agent buffer
01 AGENTBUFFER PIC X(n).
** Length of exit buffer
01 EXITBUFFERLENGTH PIC S9(9) BINARY.
** Address of exit buffer
01 EXITBUFFERADDR POINTER.

PL/I invocation
call exitname (ChannelExitParms, ChannelDefinition, DataLength,
AgentBufferLength, AgentBuffer, ExitBufferLength,
ExitBufferAddr);

Declare the parameters as follows:

dcl ChannelExitParms like MQCXP; /* Channel exit parameter
block */
dcl ChannelDefinition like MQCD; /* Channel definition */
dcl DataLength fixed bin(31); /* Length of data */
dcl AgentBufferLength fixed bin(31); /* Length of agent buffer */
dcl AgentBuffer char(n); /* Agent buffer */
dcl ExitBufferLength fixed bin(31); /* Length of exit buffer */
dcl ExitBufferAddr pointer; /* Address of exit buffer */

RPG invocation (ILE)

C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
C CALLP exitname(MQCXP : MQCD : DATLEN :
C ABUFL : ABUF : EBUFL :
C EBUF)

The prototype definition for the call is:

Chapter 37. Channel-exit calls and data structures 549

MQ_CHANNEL_EXIT - Channel exit
D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
Dexitname PR EXTPROC('exitname')
D* Channel exit parameter block
D MQCXP 156A
D* Channel definition
D MQCD 1216A
D* Length of data
D DATLEN 10I 0
D* Length of agent buffer
D ABUFL 10I 0
D* Agent buffer
D ABUF * VALUE
D* Length of exit buffer
D EBUFL 10I 0
D* Address of exit buffer
D EBUF *

RPG invocation (OPM)

C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
C CALL 'exitname'
C* Channel exit parameter block
C PARM MQCXP
C* Channel definition
C PARM MQCD
C* Length of data
C PARM DATLEN 90
C* Length of agent buffer
C PARM ABUFL 90
C* Agent buffer
C PARM ABUF n
C* Length of exit buffer
C PARM EBUFL 90
C* Address of exit buffer
C PARM EBUF 16

Declare the structure parameters as follows:

I*..1....:....2....:....3....:....4....:....5....:....6....:....7..
I* Channel exit parameter block
IMQCXP DS
I/COPY CMQCXPR
I* Channel definition
IMQCD DS
I/COPY CMQCDR

System/390® assembler invocation

CALL EXITNAME,(CHANNELEXITPARMS,CHANNELDEFINITION,DATALENGTH, X
AGENTBUFFERLENGTH,AGENTBUFFER,EXITBUFFERLENGTH, X
EXITBUFFERADDR)

Declare the parameters as follows:

CHANNELEXITPARMS CMQCXPA Channel exit parameter block
CHANNELDEFINITION CMQCDA Channel definition
DATALENGTH DS F Length of data
AGENTBUFFERLENGTH DS F Length of agent buffer
AGENTBUFFER DS CL(n) Agent buffer
EXITBUFFERLENGTH DS F Length of exit buffer
EXITBUFFERADDR DS F Address of exit buffer

550 MQSeries Intercommunication

 MQ_CHANNEL_AUTO_DEF_EXIT - Channel auto-definition exit

MQ_CHANNEL_AUTO_DEF_EXIT - Channel auto-definition exit

This call definition is provided solely to describe the parameters that are passed to
the channel auto-definition exit called by the Message Channel Agent. No entry
point called MQ_CHANNEL_AUTO_DEF_EXIT is actually provided by the queue
manager; the name MQ_CHANNEL_AUTO_DEF_EXIT is of no special significance
because the names of the auto-definition exits are provided in the queue manager.

The MQ_CHANNEL_AUTO_DEF_EXIT call definition is part of the MQSeries

Security Enabling Interface (SEI), which is one of the MQSeries framework
interfaces.

This exit is supported in the following environments: AIX, HP-UX, OS/390, OS/2,
OS/400, Sun Solaris, Windows NT.

Syntax
MQ_CHANNEL_AUTO_DEF_EXIT (ChannelExitParms, ChannelDefinition)

Parameters
ChannelExitParms (MQCXP) – input/output
Channel exit parameter block.

This structure contains additional information relating to the invocation of the

exit. The exit sets information in this structure to indicate how the MCA
should proceed.
ChannelDefinition (MQCD) – input/output
Channel definition.

This structure contains parameters set by the administrator to control the

behavior of channels which are created automatically. The exit sets information
in this structure to modify the default behavior set by the administrator.

The MQCD fields listed below must not be altered by the exit:
ChannelName
ChannelType
StrucLength
Version
If other fields are changed, the value set by the exit must be valid. If the value
is not valid, an error message is written to the error log file or displayed on
the console (as appropriate to the environment).

Usage notes
1. The function performed by the channel exit is defined by the provider of the
exit. The exit, however, must conform to the rules defined here and in the
associated control block, the MQCXP.
2. The ChannelExitParms parameter passed to the channel auto-definition exit is
an MQCXP structure. The version of MQCXP passed depends on the
environment in which the exit is running; see the description of the Version
field in “MQCXP - Channel exit parameter structure” on page 591 for details.
3. The ChannelDefinition parameter passed to the channel auto-definition exit is
an MQCD structure. The version of MQCD passed depends on the

Chapter 37. Channel-exit calls and data structures 551

MQ_CHANNEL_AUTO_DEF_EXIT - Channel auto-definition exit
environment in which the exit is running; see the description of the Version
field in “MQCD - Channel data structure” on page 556 for details.

C invocation
exitname (&ChannelExitParms, &ChannelDefinition);

Declare the parameters as follows:

MQCXP ChannelExitParms; /* Channel exit parameter block */
MQCD ChannelDefinition; /* Channel definition */

COBOL invocation
CALL 'exitname' USING CHANNELEXITPARMS, CHANNELDEFINITION.

Declare the parameters as follows:

** Channel exit parameter block
01 CHANNELEXITPARMS.
COPY CMQCXPV.
** Channel definition
01 CHANNELDEFINITION.
COPY CMQCDV.

RPG invocation (ILE)

C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
C CALLP exitname(MQCXP : MQCD)

The prototype definition for the call is:

D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
Dexitname PR EXTPROC('exitname')
D* Channel exit parameter block
D MQCXP 156A
D* Channel definition
D MQCD 1216A

RPG invocation (OPM)

C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
C CALL 'exitname'
C* Channel exit parameter block
C PARM MQCXP
C* Channel definition
C PARM MQCD

Declare the structure parameters as follows:

I*..1....:....2....:....3....:....4....:....5....:....6....:....7..
I* Channel exit parameter block
IMQCXP DS
I/COPY CMQCXPR
I* Channel definition
IMQCD DS
I/COPY CMQCDR

System/390 assembler invocation

CALL EXITNAME,(CHANNELEXITPARMS,CHANNELDEFINITION)

Declare the parameters as follows:

CHANNELEXITPARMS CMQCXPA Channel exit parameter block
CHANNELDEFINITION CMQCDA Channel definition

552 MQSeries Intercommunication

 MQXWAIT - Wait

MQXWAIT - Wait
The MQXWAIT call waits for an event to occur. It can be used only from a channel
exit on OS/390 when not using CICS.

Syntax
MQXWAIT (Hconn, WaitDesc, CompCode, Reason)

Parameters
Hconn (MQHCONN) – input
Connection handle.

This handle represents the connection to the queue manager. The value of
Hconn was returned by a previous MQCONN call issued in the same or earlier
invocation of the exit.
WaitDesc (MQXWD) – input/output
Wait descriptor.

This describes the event to wait for. See “MQXWD - Exit wait descriptor
structure” on page 609 for details of the fields in this structure.
CompCode (MQLONG) – output
Completion code.

It is one of the following:

MQCC_OK
Successful completion.
MQCC_FAILED
Call failed.
Reason (MQLONG) – output
Reason code qualifying CompCode.

If CompCode is MQCC_OK:
MQRC_NONE
(0, X'000') No reason to report.

If CompCode is MQCC_FAILED:
MQRC_ADAPTER_NOT_AVAILABLE
(2204, X'89C') Adapter not available.
MQRC_OPTIONS_ERROR
(2046, X'7FE') Options not valid or not consistent.
MQRC_XWAIT_CANCELED
(2107, X'83B') MQXWAIT call canceled.
MQRC_XWAIT_ERROR
(2108, X'83C') Invocation of MQXWAIT call not valid.

For more information on these reason codes, see the Application Programming
Reference Manual for your platform.

Chapter 37. Channel-exit calls and data structures 553

MQXWAIT - Wait
C invocation
MQXWAIT (Hconn, &WaitDesc, &CompCode, &Reason);

Declare the parameters as follows:

MQHCONN Hconn; /* Connection handle */
MQXWD WaitDesc; /* Wait descriptor */
MQLONG CompCode; /* Completion code */
MQLONG Reason; /* Reason code qualifying CompCode */

System/390 assembler invocation

CALL MQXWAIT,(HCONN,WAITDESC,COMPCODE,REASON)

Declare the parameters as follows:

HCONN DS F Connection handle
WAITDESC CMQXWDA Wait descriptor
COMPCODE DS F Completion code
REASON DS F Reason code qualifying CompCode

554 MQSeries Intercommunication

 MQ_TRANSPORT_EXIT - Transport retry exit

MQ_TRANSPORT_EXIT - Transport retry exit

This call definition is provided solely to describe the parameters that are passed to
the transport retry exit called by the message channel agent (MCA). No entry point
called MQ_TRANSPORT_EXIT is actually provided by the MCA; the name
MQ_TRANSPORT_EXIT is of no special significance because the name of the
transport retry exit is provided by the queue-manager’s configuration file.

This exit is supported in the following environments: AIX and 16-bit Windows.

Syntax
MQ_TRANSPORT_EXIT (ExitParms, DestAddressLength, DestAddress)

Parameters
ExitParms (MQTXP) – input/output
Exit parameter block.

This structure contains information relating to the invocation of the exit. The
exit sets information in this structure to indicate how processing should
continue.
DestAddressLength (MQLONG) – input
Length in bytes of destination IP address.

This is the length of the destination IP address DestAddress. The value is

always greater than zero.
DestAddress (MQCHAR×DestAddressLength) – input
Destination IP address.

This is the IP address of the destination. Its length is given by the

DestAddressLength parameter.

Usage notes
1. The function performed by the exit is defined by the provider of the exit. The
exit, however, must conform to the rules defined in the associated control block
MQTXP.
2. The transport retry exit allows a channel to be paused based on criteria that are
external to MQSeries.
If configured, the exit is called before each attempt to resend a failing data
packet. When called, the exit can wait based on some external criterion, and not
return control to the MCA until the exit decides that the resend of the data
packet is likely to succeed. If the exit decides that transmission should be
discontinued, the exit can instruct the MCA to close the channel.

C invocation
exitname (&ExitParms, DestAddressLength, DestAddress);

Declare the parameters as follows:

MQTXP ExitParms; /* Exit parameter block */
MQLONG DestAddressLength; /* Length in bytes of destination IP
address */
MQCHAR DestAddress[n]; /* Destination IP address */

Chapter 37. Channel-exit calls and data structures 555

MQCD

MQCD - Channel data structure

The following table summarizes the fields in the structure.
Table 48. Fields in MQCD
Field Description Page
ChannelName Channel definition name 558
Version Structure version number 558
ChannelType Channel type 559
TransportType Transport type 560
Desc Channel description 560
QMgrName Queue manager name 561
XmitQName Transmission queue name 561
ShortConnectionName First 20 bytes of connection name 561
MCAName Reserved 561
ModeName LU 6.2 mode name 561
TpName LU 6.2 transaction program name 562
BatchSize Batch size 562
DiscInterval Disconnect interval 562
ShortRetryCount Short retry count 562
ShortRetryInterval Short retry wait interval 562
LongRetryCount Long retry count 563
LongRetryInterval Long retry wait interval 563
SecurityExit Channel security exit name 563
MsgExit Channel message exit name 563
SendExit Channel send exit name 564
ReceiveExit Channel receive exit name 564
SeqNumberWrap Highest allowable message sequence number 564
MaxMsgLength Maximum message length 565
PutAuthority Put authority 565
DataConversion Data conversion 565
SecurityUserData Channel security exit user data 565
MsgUserData Channel message exit user data 566
SendUserData Channel send exit user data 566
ReceiveUserData Channel receive exit user data 566
UserIdentifier User identifier 566
Password Password 567
MCAUserIdentifier First 12 bytes of MCA user identifier 567
MCAType Message channel agent type 568
ConnectionName Connection name 568
RemoteUserIdentifier First 12 bytes of user identifier from partner 569
RemotePassword Password from partner 569
MsgRetryExit Channel message retry exit name 570

556 MQSeries Intercommunication

 MQCD
Table 48. Fields in MQCD (continued)
Field Description Page
MsgRetryUserData Channel message retry exit user data 570
MsgRetryCount Number of times MCA will try to put the message 571
after the first attempt has failed
MsgRetryInterval Minimum interval in milliseconds after which the 571
open or put operation will be retried
HeartbeatInterval Time in seconds between heartbeat flows 572
BatchInterval Batch duration 573
NonPersistentMsgSpeed Speed at which nonpersistent messages are sent 573
StrucLength Length of MQCD structure 574
ExitNameLength Length of exit name 574
ExitDataLength Length of exit user data 574
MsgExitsDefined Number of message exits defined 574
SendExitsDefined Number of send exits defined 574
ReceiveExitsDefined Number of receive exits defined 575
MsgExitPtr Address of first MsgExit field 575
MsgUserDataPtr Address of first MsgUserData field 575
SendExitPtr Address of first SendExit field 576
SendUserDataPtr Address of first SendUserData field 576
ReceiveExitPtr Address of first ReceiveExit field 576
ReceiveUserDataPtr Address of first ReceiveUserData field 577
ClusterPtr Address of first cluster record 577
ClustersDefined Number of cluster records 578
NetworkPriority Network priority 578
LongMCAUserIdLength Length of long MCA user identifier 578
LongRemoteUserIdLength Length of long remote user identifier 578
LongMCAUserIdPtr Address of long MCA user identifier 578
LongRemoteUserIdPtr Address of long remote user identifier 579
MCASecurityId MCA security identifier 579
RemoteSecurityId Remote security identifier 579

The MQCD structure contains the parameters which control execution of a channel.
It is passed to each channel exit that is called from a Message Channel Agent
(MCA). See MQ_CHANNEL_EXIT.

The meaning of the name in the SecurityExit, MsgExit, SendExit, ReceiveExit,

and MsgRetryExit fields depends on the environment in which the MCA is
running. Except where noted below, the name is left-justified within the field, with
no embedded blanks; the name is padded with blanks to the length of the field. In
the descriptions that follow, square brackets ([ ]) denote optional information:
Environment
Format of exit name
UNIX systems
The name of a dynamically-loadable module or library, suffixed with the

Chapter 37. Channel-exit calls and data structures 557

MQCD
name of a function residing in that library. The function name must be
enclosed in parentheses. The library name can optionally be prefixed with
a directory path:
[path]library(function)

The name is limited to a maximum of 128 characters.

OS/390 not using CICS for distributed queuing
The name of a load module that is valid for specification on the EP
parameter of the LINK or LOAD macro. The name is limited to a
maximum of 8 characters.
OS/390 using CICS for distributed queuing
A 4-character transaction identifier.
OS/2, Windows 3.1, Windows NT, and DOS, and MQSeries for Windows
The name of a dynamic-link library, suffixed with the name of a function
residing in that library. The function name must be enclosed in
parentheses. The library name can optionally be prefixed with a directory
path and drive:
[d:][path]library(function)

The name is limited to a maximum of 128 characters.

OS/400
A 10-byte program name followed by a 10-byte library name. If the names
are less than 10 bytes long, each name is padded with blanks to make it 10
bytes. The library name can be *LIBL except when calling a channel
auto-definition exit, in which case a fully qualified name is required.

Fields
ChannelName (MQCHAR20)
Channel definition name.

There must be a channel definition of the same name at the remote machine to
be able to communicate.

The name must use only the characters:

v Uppercase A–Z
v Lowercase a–z
v Numerics 0–9
v Period (.)
v Forward slash (/)
v Underscore (_)
v Percent sign (%)
and be padded to the right with blanks. Leading or embedded blanks are not
allowed.

The length of this field is given by MQ_CHANNEL_NAME_LENGTH.

Version (MQLONG)
Structure version number.

The value depends on the environment:

MQCD_VERSION_1
Version-1 channel definition structure.

558 MQSeries Intercommunication

 MQCD
The field has this value on OS/390 using CICS for distributed queuing.
Note, however, that the MQCD passed to the exit is in fact a version-2
structure.
MQCD_VERSION_2
Version-2 channel definition structure.
This value is not used by any current MQSeries product.
MQCD_VERSION_3
Version-3 channel definition structure.
The field has this value in the following environments: Compaq
(DIGITAL) OpenVMS, Tandem NonStop Kernel, UNIX systems not
listed elsewhere, 16-bit Windows, 32-bit Windows.
MQCD_VERSION_4
Version-4 channel definition structure.
This value is not used by any current MQSeries product.
MQCD_VERSION_5
Version-5 channel definition structure.
The field has this value on OS/390 not using CICS for distributed
queuing.
MQCD_VERSION_6
Version-6 channel definition structure.
The field has this value in the following environments: AIX, DOS
| client, HP-UX, OS/2, OS/400, Sun Solaris, Windows client, Windows
NT.

Fields that exist only in the earlier versions of the structure are identified as
such in the field descriptions that follow. The following constant specifies the
version number of the current version:
MQCD_CURRENT_VERSION
Current version of channel definition structure.
The value of this constant depends on the environment (see above).

Note: When a new version of the MQCD structure is introduced, the layout of
the existing part is not changed. The exit should therefore check that the
version number is equal to or greater than the lowest version which
contains the fields that the exit needs to use.
ChannelType (MQLONG)
Channel type.

It is one of the following:

MQCHT_SENDER
Sender.
MQCHT_SERVER
Server.
MQCHT_RECEIVER
Receiver.
MQCHT_REQUESTER
Requester.
MQCHT_CLNTCONN
Client connection.

Chapter 37. Channel-exit calls and data structures 559

MQCD
MQCHT_SVRCONN
Server-connection (for use by clients).
MQCHT_CLUSSDR
Cluster sender.
MQCHT_CLUSRCVR
Cluster receiver.
TransportType (MQLONG)
Transport type.

Transmission protocol to be used.

Note that the value will not have been checked if the channel was initiated
from the other end.

The value is one of the following:

MQXPT_LU62
LU 6.2 transport protocol.
This value is not supported on 32-bit Windows.
MQXPT_TCP
TCP/IP transport protocol.
This is the only value supported on 32-bit Windows.
MQXPT_NETBIOS
NetBIOS transport protocol.
This value is supported in the following environments: OS/2, 32-bit
Windows, Windows NT.
MQXPT_SPX
SPX transport protocol.
This value is supported in the following environments: OS/2,
Windows NT, Windows client, DOS client.
MQXPT_DECNET
DECnet transport protocol.
This value is supported in the following environment: Compaq
(DIGITAL) OpenVMS.
MQXPT_UDP
UDP transport protocol.
This value is supported in the following environments: AIX and 16-bit
Windows.
Desc (MQCHAR64)
Channel description.

This is a field that may be used for descriptive commentary. The content of the
field is of no significance to Message Channel Agents. However, it should
contain only characters that can be displayed. It cannot contain any null
characters; if necessary, it is padded to the right with blanks. In a DBCS
installation, the field can contain DBCS characters (subject to a maximum field
length of 64 bytes).

560 MQSeries Intercommunication

 MQCD
Note: If this field contains characters that are not in the queue manager’s
character set (as defined by the CodedCharSetId queue manager
attribute), those characters may be translated incorrectly if this field is
sent to another queue manager.

The length of this field is given by MQ_CHANNEL_DESC_LENGTH.

QMgrName (MQCHAR48)
Queue-manager name.

For channels with a ChannelType other than MQCHT_CLNTCONN, this is the

name of the queue manager that an exit can connect to, which on OS/2, UNIX
systems, and Windows NT, is always nonblank.

The length of this field is given by MQ_Q_MGR_NAME_LENGTH.

XmitQName (MQCHAR48)
Transmission queue name.

The name of the transmission queue from which messages are retrieved.

This field is relevant only for channels with a ChannelType of

MQCHT_SENDER or MQCHT_SERVER.

The length of this field is given by MQ_Q_NAME_LENGTH.

ShortConnectionName (MQCHAR20)
First 20 bytes of connection name.

If the Version field is MQCD_VERSION_1, ShortConnectionName contains the

full connection name.

If the Version field is MQCD_VERSION_2 or greater, ShortConnectionName

contains the first 20 characters of the connection name. The full connection
name is given by the ConnectionName field; ShortConnectionName and the first
20 characters of ConnectionName are identical.

See ConnectionName for details of the contents of this field.

Note: The name of this field was changed for MQCD_VERSION_2 and
subsequent versions of MQCD; the field was previously called
ConnectionName.

The length of this field is given by MQ_SHORT_CONN_NAME_LENGTH.

MCAName (MQCHAR20)
Reserved.

This is a reserved field; its value is blank.

The length of this field is given by MQ_MCA_NAME_LENGTH.

ModeName (MQCHAR8)
LU 6.2 Mode name.

This field is relevant only if the transmission protocol (TransportType) is

MQXPT_LU62, and the ChannelType is not MQCHT_SVRCONN or
MQCHT_RECEIVER.

Chapter 37. Channel-exit calls and data structures 561

MQCD
On OS/400, OS/390 without CICS, UNIX systems, and MQSeries for Windows,
this field is always blank. The information is contained in the communications
Side Object instead.

The length of this field is given by MQ_MODE_NAME_LENGTH.

TpName (MQCHAR64)
LU 6.2 transaction program name.

This field is relevant only if the transmission protocol (TransportType) is

MQXPT_LU62, and the ChannelType is not MQCHT_SVRCONN or
MQCHT_RECEIVER.

On OS/400, OS/390 without CICS, UNIX systems, and MQSeries for Windows,
this field is always blank. The information is contained in the communications
Side Object instead.

The length of this field is given by MQ_TP_NAME_LENGTH.

BatchSize (MQLONG)
Batch size.

The maximum number of messages that can be sent through a channel before
synchronizing the channel.

This field is not relevant for channels with a ChannelType of

MQCHT_SVRCONN or MQCHT_CLNTCONN.
DiscInterval (MQLONG)
Disconnect interval.

The maximum time in seconds for which the channel waits for a message to
arrive on the transmission queue, before terminating the channel. A value of
zero causes the MCA to wait indefinitely.

This field is relevant only for channels with a ChannelType of

MQCHT_SENDER, MQCHT_SERVER, MQCHT_CLUSSDR, or
MQCHT_CLUSRCVR.
ShortRetryCount (MQLONG)
Short retry count.

This is the maximum number of attempts that are made to connect to the
remote machine, at intervals specified by ShortRetryInterval, before the
(normally longer) LongRetryCount and LongRetryInterval are used.

This field is relevant only for channels with a ChannelType of

MQCHT_REQUESTER (only for MQSeries for OS/390 using CICS distributed
queuing), MQCHT_SENDER, MQCHT_SERVER, MQCHT_CLUSSDR, or
MQCHT_CLUSRCVR.
ShortRetryInterval (MQLONG)
Short retry wait interval.

This is the maximum number of seconds to wait before reattempting

connection to the remote machine. Note that the interval between retries may
be extended if the channel has to wait to become active.

562 MQSeries Intercommunication

 MQCD
This field is relevant only for channels with a ChannelType of
MQCHT_REQUESTER (only for MQSeries for OS/390 using CICS distributed
queuing), MQCHT_SENDER, MQCHT_SERVER, MQCHT_CLUSSDR, or
MQCHT_CLUSRCVR.
LongRetryCount (MQLONG)
Long retry count.

This count is used after the count specified by ShortRetryCount has been
exhausted. It specifies the maximum number of further attempts that are made
to connect to the remote machine, at intervals specified by LongRetryInterval,
before logging an error to the operator.

This field is relevant only for channels with a ChannelType of

MQCHT_REQUESTER (only for MQSeries for OS/390 using CICS distributed
queuing), MQCHT_SENDER, MQCHT_SERVER, MQCHT_CLUSSDR, or
MQCHT_CLUSRCVR.
LongRetryInterval (MQLONG)
Long retry wait interval.

This is the maximum number of seconds to wait before reattempting

connection to the remote machine. Note that the interval between retries may
be extended if the channel has to wait to become active.

This field is relevant only for channels with a ChannelType of

MQCHT_REQUESTER (only for MQSeries for OS/390 using CICS distributed
queuing), MQCHT_SENDER, MQCHT_SERVER, MQCHT_CLUSSDR, or
MQCHT_CLUSRCVR.
SecurityExit (MQCHARn)
Channel security exit name.

If this name is nonblank, the exit is called at the following times:

v Immediately after establishing a channel.
Before any messages are transferred, the exit is given the opportunity to
instigate security flows to validate connection authorization.
v Upon receipt of a response to a security message flow.
Any security message flows received from the remote processor on the
remote machine are given to the exit.
v At initialization and termination of the channel.

See above in the introduction to MQCD for a description of the content of this
field in various environments.

The length of this field is given by MQ_EXIT_NAME_LENGTH.

Note: The value of this constant is environment specific.

MsgExit (MQCHARn)
Channel message exit name.

If this name is nonblank, the exit is called at the following times:

v Immediately after a message has been retrieved from the transmission queue
(sender or server), or immediately before a message is put to a destination
queue (receiver or requester).

Chapter 37. Channel-exit calls and data structures 563

MQCD
The exit is given the entire application message and transmission queue
header for modification.
v At initialization and termination of the channel.

This field is not relevant for channels with a ChannelType of

MQCHT_SVRCONN or MQCHT_CLNTCONN; a message exit is never
invoked for such channels.

See above in the introduction to MQCD for a description of the content of this
field in various environments.

The length of this field is given by MQ_EXIT_NAME_LENGTH.

Note: The value of this constant is environment specific.

SendExit (MQCHARn)
Channel send exit name.

If this name is nonblank, the exit is called at the following times:

v Immediately before data is sent out on the network.
The exit is given the complete transmission buffer before it is transmitted.
The contents of the buffer can be modified as required.
v At initialization and termination of the channel.

See above in the introduction to MQCD for a description of the content of this
field in various environments.

The length of this field is given by MQ_EXIT_NAME_LENGTH.

Note: The value of this constant is environment specific.

ReceiveExit (MQCHARn)
Channel receive exit name.

If this name is nonblank, the exit is called at the following times:

v Immediately before the received network data is processed.
The exit is given the complete transmission buffer as received. The contents
of the buffer can be modified as required.
v At initialization and termination of the channel.

See above in the introduction to MQCD for a description of the content of this
field in various environments.

The length of this field is given by MQ_EXIT_NAME_LENGTH.

Note: The value of this constant is environment specific.

SeqNumberWrap (MQLONG)
Highest allowable message sequence number.

When this value is reached, sequence numbers wrap to start again at 1.

This value is non-negotiable and must match in both the local and remote
channel definitions.

564 MQSeries Intercommunication

 MQCD
This field is not relevant for channels with a ChannelType of
MQCHT_SVRCONN or MQCHT_CLNTCONN.
MaxMsgLength (MQLONG)
Maximum message length.

Specifies the maximum message length that can be transmitted on the channel.
This is compared with the value for the remote channel and the actual
maximum is the lower of the two values.
PutAuthority (MQLONG)
Put authority.

Specifies whether the user identifier in the context information associated with
a message should be used to establish authority to put the message to the
destination queue.

This field is relevant only for channels with a ChannelType of

MQCHT_REQUESTER, MQCHT_RECEIVER, or MQCHT_CLUSRCVR. and is
not supported on MQSeries for Windows. It is one of the following:
MQPA_DEFAULT
Default user identifier is used.
MQPA_CONTEXT
Context user identifier is used.
DataConversion (MQLONG)
Data conversion.

This specifies whether the sending message channel agent should attempt
conversion of the application message data if the receiving message channel
agent is unable to perform this conversion. This applies only to messages that
are not segments of logical messages; the MCA never attempts to convert
messages which are segments.

DataConversion is not supported on MQSeries for Windows.

This field is relevant only for channels with a ChannelType of

MQCHT_SENDER, MQCHT_SERVER, MQCHT_CLUSSDR, or
MQCHT_CLUSRCVR. It is one of the following:
MQCDC_SENDER_CONVERSION
Conversion by sender.
This value is not supported on 32-bit Windows.
MQCDC_NO_SENDER_CONVERSION
No conversion by sender.
SecurityUserData (MQCHAR32)
Channel security exit user data.

This is passed to the channel security exit in the ExitData field of the
ChannelExitParms parameter (see MQ_CHANNEL_EXIT).

This field initially contains the data that was set in the channel definition.
However, during the lifetime of this MCA instance, any changes made to the
contents of this field by an exit of any type are preserved by the MCA, and
made visible to subsequent invocations of exits (regardless of type) for this

Chapter 37. Channel-exit calls and data structures 565

MQCD
MCA instance. Such changes have no effect on the channel definition used by
other MCA instances. Any characters (including binary data) can be used.

The length of this field is given by MQ_EXIT_DATA_LENGTH.

MsgUserData (MQCHAR32)
Channel message exit user data.

This is passed to the channel message exit in the ExitData field of the
ChannelExitParms parameter (see MQ_CHANNEL_EXIT).

This field initially contains the data that was set in the channel definition.
However, during the lifetime of this MCA instance, any changes made to the
contents of this field by an exit of any type are preserved by the MCA, and
made visible to subsequent invocations of exits (regardless of type) for this
MCA instance. Such changes have no effect on the channel definition used by
other MCA instances. Any characters (including binary data) can be used.

The length of this field is given by MQ_EXIT_DATA_LENGTH.

SendUserData (MQCHAR32)
Channel send exit user data.

This is passed to the channel send exit in the ExitData field of the
ChannelExitParms parameter (see MQ_CHANNEL_EXIT).

This field initially contains the data that was set in the channel definition.
However, during the lifetime of this MCA instance, any changes made to the
contents of this field by an exit of any type are preserved by the MCA, and
made visible to subsequent invocations of exits (regardless of type) for this
MCA instance. Such changes have no effect on the channel definition used by
other MCA instances. Any characters (including binary data) can be used.

The length of this field is given by MQ_EXIT_DATA_LENGTH.

ReceiveUserData (MQCHAR32)
Channel receive exit user data.

This is passed to the channel receive exit in the ExitData field of the
ChannelExitParms parameter (see MQ_CHANNEL_EXIT).

This field initially contains the data that was set in the channel definition.
However, during the lifetime of this MCA instance, any changes made to the
contents of this field by an exit of any type are preserved by the MCA, and
made visible to subsequent invocations of exits (regardless of type) for this
MCA instance. Such changes have no effect on the channel definition used by
other MCA instances. Any characters (including binary data) can be used.

The length of this field is given by MQ_EXIT_DATA_LENGTH.

The following fields in this structure are not present if Version is less than
MQCD_VERSION_2.
UserIdentifier (MQCHAR12)
User identifier.

This is used by the message channel agent when attempting to initiate a secure
SNA session with a remote message channel agent.

566 MQSeries Intercommunication

 MQCD
This field can be nonblank only on OS/2, UNIX systems, and Windows NT,
and is relevant only for channels with a ChannelType of MQCHT_SENDER,
MQCHT_SERVER, MQCHT_REQUESTER or MQCHT_CLNTCONN. On
OS/390 this field is not relevant.

The length of this field is given by MQ_USER_ID_LENGTH, however only the

first 10 characters are used.

This field is not present in MQSeries for Windows or when Version is less than
MQCD_VERSION_2.
Password (MQCHAR12)
Password.

This is used by the message channel agent when attempting to initiate a secure
SNA session with a remote message channel agent.

This field can be nonblank only on OS/2, UNIX systems, and Windows NT,
and is relevant only for channels with a ChannelType of MQCHT_SENDER,
MQCHT_SERVER, MQCHT_REQUESTER or MQCHT_CLNTCONN. On
OS/390 this field is not relevant.

The length of this field is given by MQ_PASSWORD_LENGTH, however only

the first 10 characters are used.

This field is not present if Version is less than MQCD_VERSION_2.

MCAUserIdentifier (MQCHAR12)
First 12 bytes of MCA user identifier.

There are two fields that contain the MCA user identifier:
v MCAUserIdentifier contains the first 12 bytes of the MCA user identifier, and
is padded with blanks if the identifier is shorter than 12 bytes.
MCAUserIdentifier can be completely blank.
v LongMCAUserIdPtr points to the full MCA user identifier, which can be longer
than 12 bytes. Its length is given by LongMCAUserIdLength. The full identifier
contains no trailing blanks, and is not null-terminated. If the identifier is
completely blank, LongMCAUserIdLength is zero, and the value of
LongMCAUserIdPtr is undefined.

Note: LongMCAUserIdPtr is not present if Version is less than

MQCD_VERSION_6.

If the MCA user identifier is nonblank, it specifies the user identifier to be used
by the message channel agent for authorization to access MQSeries resources,
including (if PutAuthority is MQPA_DEFAULT) authorization to put the
message to the destination queue for receiver or requester channels.

If the MCA user identifier is blank, the message channel agent uses its default
user identifier.

The MCA user identifier can be set by a security exit to indicate the user
identifier that the message channel agent should use. The exit can change
either MCAUserIdentifier, or the string pointed at by LongMCAUserIdPtr. If both
are changed but differ from each other, the MCA uses LongMCAUserIdPtr in
preference to MCAUserIdentifier. If the exit changes the length of the string

Chapter 37. Channel-exit calls and data structures 567

 MQCD
addressed by LongMCAUserIdPtr, LongMCAUserIdLength must be set
correspondingly. If the exit wishes to increase the length of the identifier, the
exit must allocate storage of the required length, set that storage to the
required identifier, and place the address of that storage in LongMCAUserIdPtr.
The exit is responsible for freeing that storage when the exit is later invoked
with the MQXR_TERM reason.

For channels with a ChannelType of MQCHT_SVRCONN, if MCAUserIdentifier

in the channel definition is blank, any user identifier transferred from the client
is copied into it. This user identifier (after any modification by the security exit
at the server) is the one which the client application is assumed to be running
under.

The MCA user identifier is not relevant for channels with a ChannelType of
MQCHT_CLNTCONN.

This is an input/output field to the exit. The length of this field is given by
MQ_USER_ID_LENGTH. This field is not present on MQSeries for Windows
or when Version is less than MQCD_VERSION_2.
MCAType (MQLONG)
Message channel agent type.

This is the type of the message channel agent program.

This field is relevant only for channels with a ChannelType of

MQCHT_SENDER, MQCHT_SERVER, MQCHT_REQUESTER,
| MQCHT_CLUSSDR, or MQCHT_CLUSRCVR.

The value is one of the following:

MQMCAT_PROCESS
Process.
The message channel agent runs as a separate process.
MQMCAT_THREAD
Thread (OS/2 and Windows NT only).
The message channel agent runs as a separate thread.
This value is supported in the following environments: OS/2,
Windows NT.

This field is not present on MQSeries for Windows or when Version is less
than MQCD_VERSION_2.
ConnectionName (MQCHAR264)
Connection name.

This is the full connection name of the partner. The type of name depends on
the transmission protocol (TransportType) to be used:
v For MQXPT_LU62, it is the fully-qualified name of the partner Logical Unit.
v For MQXPT_NETBIOS, it is the NetBIOS name defined on the remote
machine.
v For MQXPT_TCP, it is either the host name, or the network address of the
remote machine.
v For MQXPT_SPX, it is an SPX-style address comprising a 4-byte network
address, a 6-byte node address, and a 2-byte socket number.

568 MQSeries Intercommunication

 MQCD
| When defining a channel, this field is not relevant for channels with a
| ChannelType of MQCHT_SVRCONN or MQCHT_RECEIVER. However, when
| the channel definition is passed to an exit, this field contains the address of the
| partner, whatever the channel type.

The length of this field is given by MQ_CONN_NAME_LENGTH. This field is

not present if Version is less than MQCD_VERSION_2.
RemoteUserIdentifier (MQCHAR12)
First 12 bytes of user identifier from partner.

There are two fields that contain the remote user identifier:
v RemoteUserIdentifier contains the first 12 bytes of the remote user
identifier, and is padded with blanks if the identifier is shorter than 12 bytes.
RemoteUserIdentifier can be completely blank.
v LongRemoteUserIdPtr points to the full remote user identifier, which can be
longer than 12 bytes. Its length is given by LongRemoteUserIdLength. The full
identifier contains no trailing blanks, and is not null-terminated. If the
identifier is completely blank, LongRemoteUserIdLength is zero, and the value
of LongRemoteUserIdPtr is undefined.
LongRemoteUserIdPtr is not present if Version is less than
MQCD_VERSION_6.

The remote user identifier is relevant only for channels with a ChannelType of
MQCHT_CLNTCONN or MQCHT_SVRCONN.
v For a security exit on an MQCHT_CLNTCONN channel, this is a user
identifier which has been obtained from the environment (from an
environment variable on OS/2, Windows 3.1 and Windows NT, or from the
system on UNIX platforms.) The exit can choose to send it to the security
exit at the server.
v For a security exit on an MQCHT_SVRCONN channel, this field may
contain a user identifier which has been obtained from the environment at
the client, if there is no client security exit. The exit may validate this user
ID (possibly in conjunction with the password in RemotePassword) and
update the value in MCAUserIdentifier.
If there is a security exit at the client, then this information can be obtained
in a security flow from the client.

The length of this field is given by MQ_USER_ID_LENGTH. This field is not

present if Version is less than MQCD_VERSION_2.
RemotePassword (MQCHAR12)
Password from partner.

This field contains valid information only if ChannelType is

MQCHT_CLNTCONN or MQCHT_SVRCONN.
v For a security exit at an MQCHT_CLNTCONN channel, this is a password
which has been obtained from the environment from an environment
variable on OS/2 and Windows. The exit can choose to send it to the
security exit at the server.
v For a security exit at an MQCHT_SVRCONN channel, this field may contain
a password which has been obtained from the environment at the client, if
there is no client security exit. The exit may use this to validate the user
identifier in RemoteUserIdentifier.

Chapter 37. Channel-exit calls and data structures 569

MQCD
If there is a security exit at the client, then this information can be obtained
in a security flow from the client.

The length of this field is given by MQ_PASSWORD_LENGTH. This field is

not present if Version is less than MQCD_VERSION_2.

The following fields in this structure are not present if Version is less than
MQCD_VERSION_3.
MsgRetryExit (MQCHARn)
Channel message retry exit name.

The message retry exit is an exit that is invoked by the MCA when the MCA
receives a completion code of MQCC_FAILED from an MQOPEN or MQPUT
call. The purpose of the exit is to specify a time interval for which the MCA
should wait before retrying the MQOPEN or MQPUT operation. Alternatively,
the exit can decide that the operation should not be retried.

The exit is invoked for all reason codes that have a completion code of
MQCC_FAILED — it is up to the exit to decide which reason codes it wants
the MCA to retry, for how many attempts, and at what time intervals.

When the exit decides that the operation should not be retried any more, the
MCA performs its normal failure processing; this includes generating an
exception report message (if specified by the sender), and either placing the
original message on the dead-letter queue or discarding the message
(according to whether the sender specified MQRO_DEAD_LETTER_Q or
MQRO_DISCARD_MSG, respectively). Note that failures involving the
dead-letter queue (for example, dead-letter queue full) do not cause the
message-retry exit to be invoked.

If the exit name is nonblank, the exit is called at the following times:
v Immediately before performing the wait prior to retrying a message
v At initialization and termination of the channel.

See above in the introduction to MQCD for a description of the content of this
field in various environments.

This field is relevant only for channels with a ChannelType of

MQCHT_REQUESTER, MQCHT_RECEIVER, or MQCHT_CLUSRCVR.

The length of this field is given by MQ_EXIT_NAME_LENGTH.

Notes:
1. The value of this constant is environment specific.
2. On OS/390 this field is not relevant.

This field is not present on MQSeries for Windows or when Version is less
than MQCD_VERSION_3.
MsgRetryUserData (MQCHAR32)
Channel message retry exit user data.

This is passed to the channel message-retry exit in the ExitData field of the
ChannelExitParms parameter (see MQ_CHANNEL_EXIT).

570 MQSeries Intercommunication

 MQCD
This field initially contains the data that was set in the channel definition.
However, during the lifetime of this MCA instance, any changes made to the
contents of this field by an exit of any type are preserved by the MCA, and
made visible to subsequent invocations of exits (regardless of type) for this
MCA instance. Such changes have no effect on the channel definition used by
other MCA instances. Any characters (including binary data) can be used.

This field is relevant only for channels with a ChannelType of

MQCHT_REQUESTER, MQCHT_RECEIVER, or MQCHT_CLUSRCVR.

The length of this field is given by MQ_EXIT_DATA_LENGTH. This field is

not present on MQSeries for Windows or when Version is less than
MQCD_VERSION_3.

On OS/390 this field is always blank.

MsgRetryCount (MQLONG)
Number of times MCA will try to put the message, after the first attempt has
failed.

This indicates the number of times that the MCA will retry the open or put
operation, if the first MQOPEN or MQPUT fails with completion code
MQCC_FAILED. The effect of this attribute depends on whether MsgRetryExit
is blank or nonblank:
v If MsgRetryExit is blank, the MsgRetryCount attribute controls whether the
MCA attempts retries. If the attribute value is zero, no retries are attempted.
If the attribute value is greater than zero, the retries are attempted at
intervals given by the MsgRetryInterval attribute.
Retries are attempted only for the following reason codes:
MQRC_PAGESET_FULL
MQRC_PUT_INHIBITED
MQRC_Q_FULL
For other reason codes, the MCA proceeds immediately to its normal failure
processing, without retrying the failing message.
v If MsgRetryExit is nonblank, the MsgRetryCount attribute has no effect on the
MCA; instead it is the message-retry exit which determines how many times
the retry is attempted, and at what intervals; the exit is invoked even if the
MsgRetryCount attribute is zero.
The MsgRetryCount attribute is made available to the exit in the MQCD
structure, but the exit it not required to honor it — retries continue
indefinitely until the exit returns MQXCC_SUPPRESS_FUNCTION in the
ExitResponse field of MQCXP.

This field is relevant only for channels with a ChannelType of

MQCHT_REQUESTER, MQCHT_RECEIVER, or MQCHT_CLUSRCVR.

This field is not present on MQSeries for Windows or when Version is less
than MQCD_VERSION_3.

On OS/390 this field is always zero.

MsgRetryInterval (MQLONG)
Minimum interval in milliseconds after which the open or put operation will
be retried.

Chapter 37. Channel-exit calls and data structures 571

MQCD
The effect of this attribute depends on whether MsgRetryExit is blank or
nonblank:
v If MsgRetryExit is blank, the MsgRetryInterval attribute specifies the
minimum period of time that the MCA will wait before retrying a message,
if the first MQOPEN or MQPUT fails with completion code MQCC_FAILED.
A value of zero means that the retry will be performed as soon as possible
after the previous attempt. Retries are performed only if MsgRetryCount is
greater than zero.
This attribute is also used as the wait time if the message-retry exit returns
an invalid value in the MsgRetryInterval field in MQCXP.
v If MsgRetryExit is not blank, the MsgRetryInterval attribute has no effect on
the MCA; instead it is the message-retry exit which determines how long the
MCA should wait. The MsgRetryInterval attribute is made available to the
exit in the MQCD structure, but the exit it not required to honor it.

The value is in the range 0 through 999 999 999.

This field is relevant only for channels with a ChannelType of

MQCHT_REQUESTER, MQCHT_RECEIVER, or MQCHT_CLUSRCVR.

This field is not present on MQSeries for Windows or when Version is less
than MQCD_VERSION_3.

On OS/390 this field is always zero.

The following fields in this structure are not present if Version is less than
MQCD_VERSION_4.
HeartbeatInterval (MQLONG)
Time in seconds between heartbeat flows.

The interpretation of this field depends on the channel type, as follows:

v For a channel type of MQCHT_SENDER, MQCHT_SERVER,
MQCHT_RECEIVER MQCHT_REQUESTER, MQCHT_CLUSSDR, or
MQCHT_CLUSRCVR, this is the time in seconds between heartbeat flows
passed from the sending MCA when there are no messages on the
transmission queue. This gives the receiving MCA the opportunity to
quiesce the channel. To be useful, HeartbeatInterval should be significantly
less than DiscInterval.
This type of heartbeat is supported in the following environments: AIX,
HP-UX, OS/390, OS/2, OS/400, Sun Solaris, Windows NT.
v For a channel type of MQCHT_CLNTCONN or MQCHT_SVRCONN, this is
the time in seconds between heartbeat flows passed from the server MCA
when that MCA has issued an MQGET call with the MQGMO_WAIT option
on behalf of a client application. This allows the server MCA to handle
situations where the client connection fails during an MQGET with
MQGMO_WAIT.
This type of heartbeat is supported in the following environments: AIX,
HP-UX, OS/2, OS/400, Sun Solaris, Windows NT.

The value is in the range 0 through 999 999. A value of 0 means that no
heartbeat exchange occurs. The value that is actually used is the larger of the
values specified at the sending side and receiving side.

572 MQSeries Intercommunication

 MQCD
This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.
BatchInterval (MQLONG)
Batch duration.

This is the approximate time in milliseconds that a channel will keep a batch
open, if fewer than BatchSize messages have been transmitted in the current
batch.

If BatchInterval is greater than zero, the batch is terminated by whichever of

the following occurs first:
v BatchSize messages have been sent, or
v BatchInterval milliseconds have elapsed since the start of the batch.

If BatchInterval is zero, the batch is terminated by whichever of the following

occurs first:
v BatchSize messages have been sent, or
v the transmission queue becomes empty.

BatchInterval must be in the range zero through 999 999 999.

This field is relevant only for channels with a ChannelType of

MQCHT_SENDER, MQCHT_SERVER, MQCHT_CLUSSDR, or
MQCHT_CLUSRCVR.

This is an input field to the exit. The field is not present when Version is less
than MQCD_VERSION_4.
NonPersistentMsgSpeed (MQLONG)
Speed at which nonpersistent messages are sent.

This specifies the speed at which nonpersistent messages travel through the
channel.

This field is relevant only for channels with a ChannelType of

MQCHT_SENDER, MQCHT_SERVER, MQCHT_RECEIVER,
MQCHT_REQUESTER, MQCHT_CLUSSDR, or MQCHT_CLUSRCVR.

The value is one of the following:

MQNPMS_NORMAL
Normal speed.
If a channel is defined to be MQNPMS_NORMAL, nonpersistent
messages travel through the channel at normal speed. This has the
advantage that these messages will not be lost if there is a channel
failure. Also, persistent and nonpersistent messages on the same
transmission queue maintain their order relative to each other.
MQNPMS_FAST
Fast speed.
If a channel is defined to be MQNPMS_FAST, nonpersistent messages
travel through the channel at fast speed. This improves the throughput
of the channel, but means that nonpersistent messages will be lost if
there is a channel failure. Also, it is possible for nonpersistent messages
to jump ahead of persistent messages waiting on the same
transmission queue, that is, the order of nonpersistent messages is not

Chapter 37. Channel-exit calls and data structures 573

MQCD
maintained relative to persistent messages. However the order of
nonpersistent messages relative to each other is maintained. Similarly,
the order of persistent messages relative to each other is maintained.
StrucLength (MQLONG)
Length of MQCD structure.

This is the length in bytes of the MQCD structure. The length does not include
any of the strings addressed by pointer fields contained within the structure.
The value is one of the following:
MQCD_LENGTH_4
Length of version-4 channel definition structure.
MQCD_LENGTH_5
Length of version-5 channel definition structure.
MQCD_LENGTH_6
Length of version-6 channel definition structure.

The following constant specifies the length of the current version:

MQCD_CURRENT_LENGTH
Length of current version of channel definition structure.

Note: These constants have values that are environment specific.

The field is not present if Version is less than MQCD_VERSION_4.
ExitNameLength (MQLONG)
Length of exit name.

This is the length in bytes of each of the names in the lists of exit names
addressed by the MsgExitPtr, SendExitPtr, and ReceiveExitPtr fields. This
length is not necessarily the same as MQ_EXIT_NAME_LENGTH.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.
ExitDataLength (MQLONG)
Length of exit user data.

This is the length in bytes of each of the user data items in the lists of exit user
data items addressed by the MsgUserDataPtr, SendUserDataPtr, and
ReceiveUserDataPtr fields. This length is not necessarily the same as
MQ_EXIT_DATA_LENGTH.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.
MsgExitsDefined (MQLONG)
Number of message exits defined.

This is the number of channel message exits in the chain. On OS/390 it is

always zero. On other platforms it is greater than or equal to zero.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.
SendExitsDefined (MQLONG)
Number of send exits defined.

574 MQSeries Intercommunication

 MQCD
This is the number of channel send exits in the chain. On OS/390 it is always
zero. On other platforms it is greater than or equal to zero.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.
ReceiveExitsDefined (MQLONG)
Number of receive exits defined.

This is the number of channel receive exits in the chain. On OS/390 it is

always zero. On other platforms it is greater than or equal to zero.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.
MsgExitPtr (MQPTR)
Address of first MsgExit field.

If MsgExitsDefined is greater than zero, this is the address of the list of names
of each channel message exit in the chain.

Each name is in a field of length ExitNameLength, padded to the right with

blanks. There are MsgExitsDefined fields adjoining one another – one for each
exit.

Any changes made to these names by an exit are preserved, although the
message channel exit takes no explicit action – it does not change which exits
are invoked.

If MsgExitsDefined is zero, this field is the null pointer.

On platforms where the programming language does not support the pointer
data type, this field is declared as a byte string of the appropriate length.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.
MsgUserDataPtr (MQPTR)
Address of first MsgUserData field.

If MsgExitsDefined is greater than zero, this is the address of the list of user
data items for each channel message exit in the chain.

Each user data item is in a field of length ExitDataLength, padded to the right
with blanks. There are MsgExitsDefined fields adjoining one another – one for
each exit. If the number of user data items defined is less than the number of
exit names, undefined user data items are set to blanks. Conversely, if the
number of user data items defined is greater than the number of exit names,
the excess user data items are ignored and not presented to the exit.

Any changes made to these names by an exit are preserved. This allows one
exit to pass information to another exit. No validation is carried out on any
changes so, for example, binary data can be written to these fields if required.

If MsgExitsDefined is zero, this field is the null pointer.

Chapter 37. Channel-exit calls and data structures 575

MQCD
On platforms where the programming language does not support the pointer
data type, this field is declared as a byte string of the appropriate length.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.
SendExitPtr (MQPTR)
Address of first SendExit field.

If SendExitsDefined is greater than zero, this is the address of the list of names
of each channel send exit in the chain.

Each name is in a field of length ExitNameLength, padded to the right with

blanks. There are SendExitsDefined fields adjoining one another – one for each
exit.

Any changes made to these names by an exit are preserved, although the
message send exit takes no explicit action – it does not change which exits are
invoked.

If SendExitsDefined is zero, this field is the null pointer.

On platforms where the programming language does not support the pointer
data type, this field is declared as a byte string of the appropriate length.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.
SendUserDataPtr (MQPTR)
Address of first SendUserData field.

If SendExitsDefined is greater than zero, this is the address of the list of user
data items for each channel message exit in the chain.

Each user data item is in a field of length ExitDataLength, padded to the right
with blanks. There are MsgExitsDefined fields adjoining one another – one for
each exit. If the number of user data items defined is less than the number of
exit names, undefined user data items are set to blanks. Conversely, if the
number of user data items defined is greater than the number of exit names,
the excess user data items are ignored and not presented to the exit.

Any changes made to these names by an exit are preserved. This allows one
exit to pass information to another exit. No validation is carried out on any
changes so, for example, binary data can be written to these fields if required.

If SendExitsDefined is zero, this field is the null pointer.

On platforms where the programming language does not support the pointer
data type, this field is declared as a byte string of the appropriate length.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.
ReceiveExitPtr (MQPTR)
Address of first ReceiveExit field.

576 MQSeries Intercommunication

 MQCD
If ReceiveExitsDefined is greater than zero, this is the address of the list of
names of each channel receive exit in the chain.

Each name is in a field of length ExitNameLength, padded to the right with

blanks. There are ReceiveExitsDefined fields adjoining one another – one for
each exit.

Any changes made to these names by an exit are preserved, although the
message channel exit takes no explicit action – it does not change which exits
are invoked.

If ReceiveExitsDefined is zero, this field is the null pointer.

On platforms where the programming language does not support the pointer
data type, this field is declared as a byte string of the appropriate length.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.
ReceiveUserDataPtr (MQPTR)
Address of first ReceiveUserData field.

If ReceiveExitsDefined is greater than zero, this is the address of the list of

user data item for each channel receive exit in the chain.

Each user data item is in a field of length ExitDataLength, padded to the right
with blanks. There are ReceiveExitsDefined fields adjoining one another – one
for each exit. If the number of user data items defined is less than the number
of exit names, undefined user data items are set to blanks. Conversely, if the
number of user data items defined is greater than the number of exit names,
the excess user data items are ignored and not presented to the exit.″

Any changes made to these names by an exit are preserved. This allows one
exit to pass information to another exit. No validation is carried out on any
changes so, for example, binary data can be written to these fields if required.

If ReceiveExitsDefined is zero, this field is the null pointer.

On platforms where the programming language does not support the pointer
data type, this field is declared as a byte string of the appropriate length.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_4.

The following fields in this structure are not present if Version is less than
MQCD_VERSION_5.
ClusterPtr (MQPTR)
Address of first cluster record.

If ClustersDefined is greater than zero, this is the address of the first cluster
record (MQWCR structure) in a chain of cluster records. Each cluster record
identifies a cluster to which the channel belongs.

This field is relevant only for channels with a ChannelType of

MQCHT_CLUSSDR or MQCHT_CLUSRCVR.

Chapter 37. Channel-exit calls and data structures 577

MQCD
This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_5.
ClustersDefined (MQLONG)
Number of cluster records.

This is the number of cluster records (MQWCR structures) pointed to by

ClusterPtr. It is zero or greater.

This field is relevant only for channels with a ChannelType of

MQCHT_CLUSSDR or MQCHT_CLUSRCVR.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_5.
NetworkPriority (MQLONG)
Network priority.

This is the priority of the network connection for this channel. When multiple
paths to a particular destination are available, the path with the highest
priority is chosen. The value is in the range 0 through 9; 0 is the lowest
priority.

This field is relevant only for channels with a ChannelType of

MQCHT_CLUSSDR or MQCHT_CLUSRCVR.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_5.

The following fields in this structure are not present if Version is less than
MQCD_VERSION_6.
LongMCAUserIdLength (MQLONG)
Length of long MCA user identifier.

This is the length in bytes of the full MCA user identifier pointed to by
LongMCAUserIdPtr.

This field is not relevant for channels with a ChannelType of

MQCHT_CLNTCONN.

This is an input/output field to the exit. The field is not present if Version is
less than MQCD_VERSION_6.
LongRemoteUserIdLength (MQLONG)
Length of long remote user identifier.

This is the length in bytes of the full remote user identifier pointed to by
LongRemoteUserIdPtr.

This field is relevant only for channels with a ChannelType of

MQCHT_CLNTCONN or MQCHT_SVRCONN.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_6.
LongMCAUserIdPtr (MQPTR)
Address of long MCA user identifier.

578 MQSeries Intercommunication

 MQCD
If LongMCAUserIdLength is greater than zero, this is the address of the full MCA
user identifier. The length of the full identifier is given by
LongMCAUserIdLength. The first 12 bytes of the MCA user identifier are also
contained in the field MCAUserIdentifier.

See the description of the MCAUserIdentifier field for details of the MCA user
identifier.

This field is not relevant for channels with a ChannelType of

MQCHT_CLNTCONN.

This is an input/output field to the exit. The field is not present if Version is
less than MQCD_VERSION_6.
LongRemoteUserIdPtr (MQPTR)
Address of long remote user identifier.

If LongRemoteUserIdLength is greater than zero, this is the address of the full

remote user identifier. The length of the full identifier is given by
LongRemoteUserIdLength. The first 12 bytes of the remote user identifier are
also contained in the field RemoteUserIdentifier.

See the description of the RemoteUserIdentifier field for details of the remote
user identifier.

This field is relevant only for channels with a ChannelType of

MQCHT_CLNTCONN or MQCHT_SVRCONN.

This is an input field to the exit. The field is not present if Version is less than
MQCD_VERSION_6.
MCASecurityId (MQBYTE40)
MCA security identifier.

This is the security identifier for the MCA.

This field is not relevant for channels with a ChannelType of

MQCHT_CLNTCONN.

The following special value indicates that there is no security identifier:

MQSID_NONE
No security identifier specified.
The value is binary zero for the length of the field.
For the C programming language, the constant MQSID_NONE_ARRAY
is also defined; this has the same value as MQSID_NONE, but is an
array of characters instead of a string.

This is an input/output field to the exit. The length of this field is given by
MQ_SECURITY_ID_LENGTH. This field is not present if Version is less than
MQCD_VERSION_6.
RemoteSecurityId (MQBYTE40)
Remote security identifier.

This is the security identifier for the remote user.

Chapter 37. Channel-exit calls and data structures 579

MQCD
This field is relevant only for channels with a ChannelType of
MQCHT_CLNTCONN or MQCHT_SVRCONN.

The following special value indicates that there is no security identifier:

MQSID_NONE
No security identifier specified.
The value is binary zero for the length of the field.
For the C programming language, the constant MQSID_NONE_ARRAY
is also defined; this has the same value as MQSID_NONE, but is an
array of characters instead of a string.

This is an input field to the exit. The length of this field is given by
MQ_SECURITY_ID_LENGTH. This field is not present if Version is less than
MQCD_VERSION_6.

C declaration
typedef struct tagMQCD {
MQCHAR ChannelName[20]; /* Channel definition
name */
MQLONG Version; /* Structure version number */
MQLONG ChannelType; /* Channel type */
MQLONG TransportType; /* Transport type */
MQCHAR Desc[64]; /* Channel
description */
MQCHAR QMgrName[48]; /* Queue-manager
name */
MQCHAR XmitQName[48]; /* Transmission queue
name */
MQCHAR ShortConnectionName[20]; /* First 20 bytes of
connection name */
MQCHAR MCAName[20]; /* Reserved */
MQCHAR ModeName[8]; /* LU 6.2 Mode name */
MQCHAR TpName[64]; /* LU 6.2 transaction
program name */
MQLONG BatchSize; /* Batch size */
MQLONG DiscInterval; /* Disconnect interval */
MQLONG ShortRetryCount; /* Short retry count */
MQLONG ShortRetryInterval; /* Short retry wait interval */
MQLONG LongRetryCount; /* Long retry count */
MQLONG LongRetryInterval; /* Long retry wait interval */
MQCHAR SecurityExit[n]; /* Channel security
exit name */
MQCHAR MsgExit[n]; /* Channel message exit
name */
MQCHAR SendExit[n]; /* Channel send exit
name */
MQCHAR ReceiveExit[n]; /* Channel receive exit
name */
MQLONG SeqNumberWrap; /* Highest allowable message
sequence number */
MQLONG MaxMsgLength; /* Maximum message length */
MQLONG PutAuthority; /* Put authority */
MQLONG DataConversion; /* Data conversion */
MQCHAR SecurityUserData[32]; /* Channel security
exit user data */
MQCHAR MsgUserData[32]; /* Channel message exit
user data */
MQCHAR SendUserData[32]; /* Channel send exit
user data */
MQCHAR ReceiveUserData[32]; /* Channel receive exit
user data */

580 MQSeries Intercommunication

 MQCD
MQCHAR UserIdentifier[12]; /* User identifier */
MQCHAR Password[12]; /* Password */
MQCHAR MCAUserIdentifier[12]; /* First 12 bytes of
MCA user identifier */
MQLONG MCAType; /* Message channel agent type */
MQCHAR ConnectionName[264]; /* Connection name */
MQCHAR RemoteUserIdentifier[12]; /* First 12 bytes of
user identifier from
partner */
MQCHAR RemotePassword[12]; /* Password from
partner */
MQCHAR MsgRetryExit[n]; /* Channel message
retry exit name */
MQCHAR MsgRetryUserData[32]; /* Channel message
retry exit user data */
MQLONG MsgRetryCount; /* Number of times MCA will try
to put the message, after the
first attempt has failed */
MQLONG MsgRetryInterval; /* Minimum interval in millisec-
onds after which the open or
put operation will be
retried */
MQLONG HeartbeatInterval; /* Time in seconds between
heartbeat flows */
MQLONG BatchInterval; /* Batch duration */
MQLONG NonPersistentMsgSpeed; /* Speed at which nonpersistent
messages are sent */
MQLONG StrucLength; /* Length of MQCD structure */
MQLONG ExitNameLength; /* Length of exit name */
MQLONG ExitDataLength; /* Length of exit user data */
MQLONG MsgExitsDefined; /* Number of message exits
defined */
MQLONG SendExitsDefined; /* Number of send exits
defined */
MQLONG ReceiveExitsDefined; /* Number of receive exits
defined */
MQPTR MsgExitPtr; /* Address of first MsgExit
field */
MQPTR MsgUserDataPtr; /* Address of first MsgUserData
field */
MQPTR SendExitPtr; /* Address of first SendExit
field */
MQPTR SendUserDataPtr; /* Address of first SendUserData
field */
MQPTR ReceiveExitPtr; /* Address of first ReceiveExit
field */
MQPTR ReceiveUserDataPtr; /* Address of first
ReceiveUserData field */
MQPTR ClusterPtr; /* Address of first cluster
record */
MQLONG ClustersDefined; /* Number of cluster records */
MQLONG NetworkPriority; /* Network priority */
MQLONG LongMCAUserIdLength; /* Length of long MCA user iden-
tifier */
MQLONG LongRemoteUserIdLength; /* Length of long remote user
identifier */
MQPTR LongMCAUserIdPtr; /* Address of long MCA user iden-
tifier */
MQPTR LongRemoteUserIdPtr; /* Address of long remote user
identifier */
MQBYTE40 MCASecurityId; /* MCA security identifier */
MQBYTE40 RemoteSecurityId; /* Remote security identifier */
} MQCD;

Chapter 37. Channel-exit calls and data structures 581

MQCD
COBOL declaration
** MQCD structure
10 MQCD.
** Channel definition name
15 MQCD-CHANNELNAME PIC X(20).
** Structure version number
15 MQCD-VERSION PIC S9(9) BINARY.
** Channel type
15 MQCD-CHANNELTYPE PIC S9(9) BINARY.
** Transport type
15 MQCD-TRANSPORTTYPE PIC S9(9) BINARY.
** Channel description
15 MQCD-DESC PIC X(64).
** Queue-manager name
15 MQCD-QMGRNAME PIC X(48).
** Transmission queue name
15 MQCD-XMITQNAME PIC X(48).
** First 20 bytes of connection name
15 MQCD-SHORTCONNECTIONNAME PIC X(20).
** Reserved
15 MQCD-MCANAME PIC X(20).
** LU 6.2 Mode name
15 MQCD-MODENAME PIC X(8).
** LU 6.2 transaction program name
15 MQCD-TPNAME PIC X(64).
** Batch size
15 MQCD-BATCHSIZE PIC S9(9) BINARY.
** Disconnect interval
15 MQCD-DISCINTERVAL PIC S9(9) BINARY.
** Short retry count
15 MQCD-SHORTRETRYCOUNT PIC S9(9) BINARY.
** Short retry wait interval
15 MQCD-SHORTRETRYINTERVAL PIC S9(9) BINARY.
** Long retry count
15 MQCD-LONGRETRYCOUNT PIC S9(9) BINARY.
** Long retry wait interval
15 MQCD-LONGRETRYINTERVAL PIC S9(9) BINARY.
** Channel security exit name
15 MQCD-SECURITYEXIT PIC X(n).
** Channel message exit name
15 MQCD-MSGEXIT PIC X(n).
** Channel send exit name
15 MQCD-SENDEXIT PIC X(n).
** Channel receive exit name
15 MQCD-RECEIVEEXIT PIC X(n).
** Highest allowable message sequence number
15 MQCD-SEQNUMBERWRAP PIC S9(9) BINARY.
** Maximum message length
15 MQCD-MAXMSGLENGTH PIC S9(9) BINARY.
** Put authority
15 MQCD-PUTAUTHORITY PIC S9(9) BINARY.
** Data conversion
15 MQCD-DATACONVERSION PIC S9(9) BINARY.
** Channel security exit user data
15 MQCD-SECURITYUSERDATA PIC X(32).
** Channel message exit user data
15 MQCD-MSGUSERDATA PIC X(32).
** Channel send exit user data
15 MQCD-SENDUSERDATA PIC X(32).
** Channel receive exit user data
15 MQCD-RECEIVEUSERDATA PIC X(32).
** User identifier
15 MQCD-USERIDENTIFIER PIC X(12).
** Password
15 MQCD-PASSWORD PIC X(12).
** First 12 bytes of MCA user identifier

582 MQSeries Intercommunication

 MQCD
15 MQCD-MCAUSERIDENTIFIER PIC X(12).
** Message channel agent type
15 MQCD-MCATYPE PIC S9(9) BINARY.
** Connection name
15 MQCD-CONNECTIONNAME PIC X(264).
** First 12 bytes of user identifier from partner
15 MQCD-REMOTEUSERIDENTIFIER PIC X(12).
** Password from partner
15 MQCD-REMOTEPASSWORD PIC X(12).
** Channel message retry exit name
15 MQCD-MSGRETRYEXIT PIC X(n).
** Channel message retry exit user data
15 MQCD-MSGRETRYUSERDATA PIC X(32).
** Number of times MCA will try to put the message, after the
** first attempt has failed
15 MQCD-MSGRETRYCOUNT PIC S9(9) BINARY.
** Minimum interval in milliseconds after which the open or put
** operation will be retried
15 MQCD-MSGRETRYINTERVAL PIC S9(9) BINARY.
** Time in seconds between heartbeat flows
15 MQCD-HEARTBEATINTERVAL PIC S9(9) BINARY.
** Batch duration
15 MQCD-BATCHINTERVAL PIC S9(9) BINARY.
** Speed at which nonpersistent messages are sent
15 MQCD-NONPERSISTENTMSGSPEED PIC S9(9) BINARY.
** Length of MQCD structure
15 MQCD-STRUCLENGTH PIC S9(9) BINARY.
** Length of exit name
15 MQCD-EXITNAMELENGTH PIC S9(9) BINARY.
** Length of exit user data
15 MQCD-EXITDATALENGTH PIC S9(9) BINARY.
** Number of message exits defined
15 MQCD-MSGEXITSDEFINED PIC S9(9) BINARY.
** Number of send exits defined
15 MQCD-SENDEXITSDEFINED PIC S9(9) BINARY.
** Number of receive exits defined
15 MQCD-RECEIVEEXITSDEFINED PIC S9(9) BINARY.
** Address of first MsgExit field
15 MQCD-MSGEXITPTR POINTER.
** Address of first MsgUserData field
15 MQCD-MSGUSERDATAPTR POINTER.
** Address of first SendExit field
15 MQCD-SENDEXITPTR POINTER.
** Address of first SendUserData field
15 MQCD-SENDUSERDATAPTR POINTER.
** Address of first ReceiveExit field
15 MQCD-RECEIVEEXITPTR POINTER.
** Address of first ReceiveUserData field
15 MQCD-RECEIVEUSERDATAPTR POINTER.
** Address of first cluster record
15 MQCD-CLUSTERPTR POINTER.
** Number of cluster records
15 MQCD-CLUSTERSDEFINED PIC S9(9) BINARY.
** Network priority
15 MQCD-NETWORKPRIORITY PIC S9(9) BINARY.
** Length of long MCA user identifier
15 MQCD-LONGMCAUSERIDLENGTH PIC S9(9) BINARY.
** Length of long remote user identifier
15 MQCD-LONGREMOTEUSERIDLENGTH PIC S9(9) BINARY.
** Address of long MCA user identifier
15 MQCD-LONGMCAUSERIDPTR POINTER.
** Address of long remote user identifier
15 MQCD-LONGREMOTEUSERIDPTR POINTER.
** MCA security identifier
15 MQCD-MCASECURITYID PIC X(40).
** Remote security identifier
15 MQCD-REMOTESECURITYID PIC X(40).

Chapter 37. Channel-exit calls and data structures 583

MQCD
PL/I declaration
dcl
1 MQCD based,
3 ChannelName char(20), /* Channel definition name */
3 Version fixed bin(31), /* Structure version number */
3 ChannelType fixed bin(31), /* Channel type */
3 TransportType fixed bin(31), /* Transport type */
3 Desc char(64), /* Channel description */
3 QMgrName char(48), /* Queue-manager name */
3 XmitQName char(48), /* Transmission queue name */
3 ShortConnectionName char(20), /* First 20 bytes of connection
name */
3 MCAName char(20), /* Reserved */
3 ModeName char(8), /* LU 6.2 Mode name */
3 TpName char(64), /* LU 6.2 transaction program
name */
3 BatchSize fixed bin(31), /* Batch size */
3 DiscInterval fixed bin(31), /* Disconnect interval */
3 ShortRetryCount fixed bin(31), /* Short retry count */
3 ShortRetryInterval fixed bin(31), /* Short retry wait interval */
3 LongRetryCount fixed bin(31), /* Long retry count */
3 LongRetryInterval fixed bin(31), /* Long retry wait interval */
3 SecurityExit char(n), /* Channel security exit
name */
3 MsgExit char(n), /* Channel message exit name */
3 SendExit char(n), /* Channel send exit name */
3 ReceiveExit char(n), /* Channel receive exit name */
3 SeqNumberWrap fixed bin(31), /* Highest allowable message
sequence number */
3 MaxMsgLength fixed bin(31), /* Maximum message length */
3 PutAuthority fixed bin(31), /* Put authority */
3 DataConversion fixed bin(31), /* Data conversion */
3 SecurityUserData char(32), /* Channel security exit user
data */
3 MsgUserData char(32), /* Channel message exit user
data */
3 SendUserData char(32), /* Channel send exit user
data */
3 ReceiveUserData char(32), /* Channel receive exit user
data */
3 UserIdentifier char(12), /* User identifier */
3 Password char(12), /* Password */
3 MCAUserIdentifier char(12), /* First 12 bytes of MCA user
identifier */
3 MCAType fixed bin(31), /* Message channel agent
type */
3 ConnectionName char(264), /* Connection name */
3 RemoteUserIdentifier char(12), /* First 12 bytes of user iden-
tifier from partner */
3 RemotePassword char(12), /* Password from partner */
3 MsgRetryExit char(n), /* Channel message retry exit
name */
3 MsgRetryUserData char(32), /* Channel message retry exit
user data */
3 MsgRetryCount fixed bin(31), /* Number of times MCA will try
to put the message, after
the first attempt has
failed */
3 MsgRetryInterval fixed bin(31), /* Minimum interval in milli-
seconds after which the open
or put operation will be
retried */
3 HeartbeatInterval fixed bin(31), /* Time in seconds between
heartbeat flows */
3 BatchInterval fixed bin(31), /* Batch duration */
3 NonPersistentMsgSpeed fixed bin(31), /* Speed at which nonpersistent

584 MQSeries Intercommunication

 MQCD
messages are sent */
3 StrucLength fixed bin(31), /* Length of MQCD structure */
3 ExitNameLength fixed bin(31), /* Length of exit name */
3 ExitDataLength fixed bin(31), /* Length of exit user data */
3 MsgExitsDefined fixed bin(31), /* Number of message exits
defined */
3 SendExitsDefined fixed bin(31), /* Number of send exits
defined */
3 ReceiveExitsDefined fixed bin(31), /* Number of receive exits
defined */
3 MsgExitPtr pointer, /* Address of first MsgExit
field */
3 MsgUserDataPtr pointer, /* Address of first MsgUserData
field */
3 SendExitPtr pointer, /* Address of first SendExit
field */
3 SendUserDataPtr pointer, /* Address of first
SendUserData field */
3 ReceiveExitPtr pointer, /* Address of first ReceiveExit
field */
3 ReceiveUserDataPtr pointer, /* Address of first
ReceiveUserData field */
3 ClusterPtr pointer, /* Address of first cluster
record */
3 ClustersDefined fixed bin(31), /* Number of cluster records */
3 NetworkPriority fixed bin(31); /* Network priority */

ILE RPG declaration

D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
D* MQCD Structure
D*
D* Channel definition name
D CDCHN 1 20
D* Structure version number
D CDVER 21 24I 0
D* Channel type
D CDCHT 25 28I 0
D* Transport type
D CDTRT 29 32I 0
D* Channel description
D CDDES 33 96
D* Queue-manager name
D CDQM 97 144
D* Transmission queue name
D CDXQ 145 192
D* First 20 bytes of connection name
D CDSCN 193 212
D* Reserved
D CDMCA 213 232
D* LU 6.2 Mode name
D CDMOD 233 240
D* LU 6.2 transaction program name
D CDTP 241 304
D* Batch size
D CDBS 305 308I 0
D* Disconnect interval
D CDDI 309 312I 0
D* Short retry count
D CDSRC 313 316I 0
D* Short retry wait interval
D CDSRI 317 320I 0
D* Long retry count
D CDLRC 321 324I 0
D* Long retry wait interval
D CDLRI 325 328I 0
D* Channel security exit name

Chapter 37. Channel-exit calls and data structures 585

MQCD
D CDSCX 329 348
D* Channel message exit name
D CDMSX 349 368
D* Channel send exit name
D CDSNX 369 388
D* Channel receive exit name
D CDRCX 389 408
D* Highest allowable message sequence number
D CDSNW 409 412I 0
D* Maximum message length
D CDMML 413 416I 0
D* Put authority
D CDPA 417 420I 0
D* Data conversion
D CDDC 421 424I 0
D* Channel security exit user data
D CDSCD 425 456
D* Channel message exit user data
D CDMSD 457 488
D* Channel send exit user data
D CDSND 489 520
D* Channel receive exit user data
D CDRCD 521 552
D* User identifier
D CDUID 553 564
D* Password
D CDPW 565 576
D* First 12 bytes of MCA user identifier
D CDAUI 577 588
D* Message channel agent type
D CDCAT 589 592I 0
D* Connection name (characters 1 through 256)
D CDCON 593 848
D* Connection name (characters 257 through 264)
D CDCN2 849 856
D* First 12 bytes of user identifier from partner
D CDRUI 857 868
D* Password from partner
D CDRPW 869 880
D* Channel message retry exit name
D CDMRX 881 900
D* Channel message retry exit user data
D CDMRD 901 932
D* Number of times MCA will try to put the message, after the first
D* attempt has failed
D CDMRC 933 936I 0
D* Minimum interval in milliseconds after which the open or put
D* operation will be retried
D CDMRI 937 940I 0
D* Time in seconds between heartbeat flows
D CDHBI 941 944I 0
D* Batch duration
D CDBI 945 948I 0
D* Speed at which nonpersistent messages are sent
D CDNPM 949 952I 0
D* Length of MQCD structure
D CDLEN 953 956I 0
D* Length of exit name
D CDXNL 957 960I 0
D* Length of exit user data
D CDXDL 961 964I 0
D* Number of message exits defined
D CDMXD 965 968I 0
D* Number of send exits defined
D CDSXD 969 972I 0
D* Number of receive exits defined
D CDRXD 973 976I 0

586 MQSeries Intercommunication

 MQCD
D* Address of first MsgExit field
D CDMXP 977 992*
D* Address of first MsgUserData field
D CDMUP 993 1008*
D* Address of first SendExit field
D CDSXP 1009 1024*
D* Address of first SendUserData field
D CDSUP 1025 1040*
D* Address of first ReceiveExit field
D CDRXP 1041 1056*
D* Address of first ReceiveUserData field
D CDRUP 1057 1072*
D* Address of first cluster record
D CDCLP 1073 1088*
D* Number of cluster records
D CDCLD 1089 1092I 0
D* Network priority
D CDNP 1093 1096I 0
D* Length of long MCA user identifier
D CDLML 1097 1100I 0
D* Length of long remote user identifier
D CDLRL 1101 1104I 0
D* Address of long MCA user identifier
D CDLMP 1105 1120*
D* Address of long remote user identifier
D CDLRP 1121 1136*
D* MCA security identifier
D CDMSI 1137 1176
D* Remote security identifier
D CDRSI 1177 1216

OPM RPG declaration

I*..1....:....2....:....3....:....4....:....5....:....6....:....7..
I* MQCD Structure
I*
I* Channel definition name
I 1 20 CDCHN
I* Structure version number
I B 21 240CDVER
I* Channel type
I B 25 280CDCHT
I* Transport type
I B 29 320CDTRT
I* Channel description
I 33 96 CDDES
I* Queue-manager name
I 97 144 CDQM
I* Transmission queue name
I 145 192 CDXQ
I* First 20 bytes of connection name
I 193 212 CDSCN
I* Reserved
I 213 232 CDMCA
I* LU 6.2 Mode name
I 233 240 CDMOD
I* LU 6.2 transaction program name
I 241 304 CDTP
I* Batch size
I B 305 3080CDBS
I* Disconnect interval
I B 309 3120CDDI
I* Short retry count
I B 313 3160CDSRC
I* Short retry wait interval
I B 317 3200CDSRI
I* Long retry count

Chapter 37. Channel-exit calls and data structures 587

MQCD
I B 321 3240CDLRC
I* Long retry wait interval
I B 325 3280CDLRI
I* Channel security exit name
I 329 348 CDSCX
I* Channel message exit name
I 349 368 CDMSX
I* Channel send exit name
I 369 388 CDSNX
I* Channel receive exit name
I 389 408 CDRCX
I* Highest allowable message sequence number
I B 409 4120CDSNW
I* Maximum message length
I B 413 4160CDMML
I* Put authority
I B 417 4200CDPA
I* Data conversion
I B 421 4240CDDC
I* Channel security exit user data
I 425 456 CDSCD
I* Channel message exit user data
I 457 488 CDMSD
I* Channel send exit user data
I 489 520 CDSND
I* Channel receive exit user data
I 521 552 CDRCD
I* User identifier
I 553 564 CDUID
I* Password
I 565 576 CDPW
I* First 12 bytes of MCA user identifier
I 577 588 CDAUI
I* Message channel agent type
I B 589 5920CDCAT
I* Connection name (characters 1 through 256)
I 593 848 CDCON
I* Connection name (characters 257 through 264)
I 849 856 CDCN2
I* First 12 bytes of user identifier from partner
I 857 868 CDRUI
I* Password from partner
I 869 880 CDRPW
I* Channel message retry exit name
I 881 900 CDMRX
I* Channel message retry exit user data
I 901 932 CDMRD
I* Number of times MCA will try to put the message, after the first
I* attempt has failed
I B 933 9360CDMRC
I* Minimum interval in milliseconds after which the open or put
I* operation will be retried
I B 937 9400CDMRI
I* Time in seconds between heartbeat flows
I B 941 9440CDHBI
I* Batch duration
I B 945 9480CDBI
I* Speed at which nonpersistent messages are sent
I B 949 9520CDNPM
I* Length of MQCD structure
I B 953 9560CDLEN
I* Length of exit name
I B 957 9600CDXNL
I* Length of exit user data
I B 961 9640CDXDL
I* Number of message exits defined
I B 965 9680CDMXD

588 MQSeries Intercommunication

 MQCD
I* Number of send exits defined
I B 969 9720CDSXD
I* Number of receive exits defined
I B 973 9760CDRXD
I* Address of first MsgExit field
I 977 992 CDMXP
I* Address of first MsgUserData field
I 9931008 CDMUP
I* Address of first SendExit field
I 10091024 CDSXP
I* Address of first SendUserData field
I 10251040 CDSUP
I* Address of first ReceiveExit field
I 10411056 CDRXP
I* Address of first ReceiveUserData field
I 10571072 CDRUP
I* Address of first cluster record
I 10731088 CDCLP
I* Number of cluster records
I B108910920CDCLD
I* Network priority
I B109310960CDNP
I* Length of long MCA user identifier
I B109711000CDLML
I* Length of long remote user identifier
I B110111040CDLRL
I* Address of long MCA user identifier
I 11051120 CDLMP
I* Address of long remote user identifier
I 11211136 CDLRP
I* MCA security identifier
I 11371176 CDMSI
I* Remote security identifier
I 11771216 CDRSI

System/390 assembler declaration

MQCD DSECT
MQCD_CHANNELNAME DS CL20 Channel definition name
MQCD_VERSION DS F Structure version number
MQCD_CHANNELTYPE DS F Channel type
MQCD_TRANSPORTTYPE DS F Transport type
MQCD_DESC DS CL64 Channel description
MQCD_QMGRNAME DS CL48 Queue-manager name
MQCD_XMITQNAME DS CL48 Transmission queue name
MQCD_SHORTCONNECTIONNAME DS CL20 First 20 bytes of connection
* name
MQCD_MCANAME DS CL20 Reserved
MQCD_MODENAME DS CL8 LU 6.2 Mode name
MQCD_TPNAME DS CL64 LU 6.2 transaction program
* name
MQCD_BATCHSIZE DS F Batch size
MQCD_DISCINTERVAL DS F Disconnect interval
MQCD_SHORTRETRYCOUNT DS F Short retry count
MQCD_SHORTRETRYINTERVAL DS F Short retry wait interval
MQCD_LONGRETRYCOUNT DS F Long retry count
MQCD_LONGRETRYINTERVAL DS F Long retry wait interval
MQCD_SECURITYEXIT DS CLn Channel security exit name
MQCD_MSGEXIT DS CLn Channel message exit name
MQCD_SENDEXIT DS CLn Channel send exit name
MQCD_RECEIVEEXIT DS CLn Channel receive exit name
MQCD_SEQNUMBERWRAP DS F Highest allowable message
* sequence number
MQCD_MAXMSGLENGTH DS F Maximum message length
MQCD_PUTAUTHORITY DS F Put authority
MQCD_DATACONVERSION DS F Data conversion
MQCD_SECURITYUSERDATA DS CL32 Channel security exit user

Chapter 37. Channel-exit calls and data structures 589

MQCD
* data
MQCD_MSGUSERDATA DS CL32 Channel message exit user
* data
MQCD_SENDUSERDATA DS CL32 Channel send exit user data
MQCD_RECEIVEUSERDATA DS CL32 Channel receive exit user
* data
MQCD_USERIDENTIFIER DS CL12 User identifier
MQCD_PASSWORD DS CL12 Password
MQCD_MCAUSERIDENTIFIER DS CL12 First 12 bytes of MCA user
* identifier
MQCD_MCATYPE DS F Message channel agent type
MQCD_CONNECTIONNAME DS CL264 Connection name
MQCD_REMOTEUSERIDENTIFIER DS CL12 First 12 bytes of user
* identifier from partner
MQCD_REMOTEPASSWORD DS CL12 Password from partner
MQCD_MSGRETRYEXIT DS CLn Channel message retry exit
* name
MQCD_MSGRETRYUSERDATA DS CL32 Channel message retry exit
* user data
MQCD_MSGRETRYCOUNT DS F Number of times MCA will try
* to put the message, after
* the first attempt has failed
MQCD_MSGRETRYINTERVAL DS F Minimum interval in
* milliseconds after which the
* open or put operation will
* be retried
MQCD_HEARTBEATINTERVAL DS F Time in seconds between
* heartbeat flows
MQCD_BATCHINTERVAL DS F Batch duration
MQCD_NONPERSISTENTMSGSPEED DS F Speed at which nonpersistent
* messages are sent
MQCD_STRUCLENGTH DS F Length of MQCD structure
MQCD_EXITNAMELENGTH DS F Length of exit name
MQCD_EXITDATALENGTH DS F Length of exit user data
MQCD_MSGEXITSDEFINED DS F Number of message exits
* defined
MQCD_SENDEXITSDEFINED DS F Number of send exits defined
MQCD_RECEIVEEXITSDEFINED DS F Number of receive exits
* defined
MQCD_MSGEXITPTR DS F Address of first MsgExit
* field
MQCD_MSGUSERDATAPTR DS F Address of first MsgUserData
* field
MQCD_SENDEXITPTR DS F Address of first SendExit
* field
MQCD_SENDUSERDATAPTR DS F Address of first
* SendUserData field
MQCD_RECEIVEEXITPTR DS F Address of first ReceiveExit
* field
MQCD_RECEIVEUSERDATAPTR DS F Address of first
* ReceiveUserData field
MQCD_CLUSTERPTR DS F Address of first cluster
* record
MQCD_CLUSTERSDEFINED DS F Number of cluster records
MQCD_NETWORKPRIORITY DS F Network priority
MQCD_LENGTH EQU *-MQCD Length of structure
ORG MQCD
MQCD_AREA DS CL(MQCD_LENGTH)

590 MQSeries Intercommunication

 MQCXP

MQCXP - Channel exit parameter structure

The following table summarizes the fields in the structure.
Table 49. Fields in MQCXP
Field Description Page
StrucId Structure identifier 591
Version Structure version number 592
ExitId Type of exit 592
ExitReason Reason for invoking exit 593
ExitResponse Response from exit 595
ExitResponse2 Secondary response from exit 596
Feedback Feedback code 598
MaxSegmentLength Maximum segment length 598
ExitUserArea Exit user area 598
ExitData Exit data 599
MsgRetryCount Number of times the message has been retried 599
MsgRetryInterval Minimum interval in milliseconds after which the 599
put operation should be retried
MsgRetryReason Reason code from previous attempt to put the 600
message
HeaderLength Length of header 600
PartnerName Partner name 600
FAPLevel Negotiated Formats and Protocols level 600
CapabilityFlags Capability flags 601
ExitNumber Exit number 601

The MQCXP structure is passed to each type of exit called by a Message Channel
Agent (MCA). See MQ_CHANNEL_EXIT.

The fields described as “input to the exit” in the descriptions that follow are
ignored by the MCA when the exit returns control to the MCA. The exit should
not expect that any input fields that it changes in the channel exit parameter block
will be preserved for its next invocation. Changes made to input/output fields (for
example, the ExitUserArea field), are preserved for invocations of that instance of
the exit only. Such changes cannot be used to pass data between different exits
defined on the same channel, or between the same exit defined on different
channels.

Fields
StrucId (MQCHAR4)
Structure identifier.

The value must be:

MQCXP_STRUC_ID
Identifier for channel exit parameter structure.

Chapter 37. Channel-exit calls and data structures 591

 MQCXP
For the C programming language, the constant
MQCXP_STRUC_ID_ARRAY is also defined; this has the same value as
MQCXP_STRUC_ID, but is an array of characters instead of a string.

This is an input field to the exit.

Version (MQLONG)
Structure version number.

The value depends on the environment:

MQCXP_VERSION_1
Version-1 channel exit parameter structure.
The field has this value on OS/390 using CICS for distributed queuing.
MQCXP_VERSION_2
Version-2 channel exit parameter structure.
The field has this value in the following environments: Compaq
(DIGITAL) OpenVMS, Tandem NonStop Kernel, 16-bit Windows.
MQCXP_VERSION_3
Version-3 channel exit parameter structure.
The field has this value in the following environments: UNIX systems
not listed elsewhere, 32-bit Windows.
MQCXP_VERSION_4
Version-4 channel exit parameter structure.
The field has this value in the following environments: AIX, HP-UX,
| OS/390 not using CICS for distributed queuing, OS/2, OS/400, Sun
Solaris, Windows NT.

Fields that exist only in the earlier versions of the structure are identified as
such in the field descriptions that follow. The following constant specifies the
version number of the current version:
MQCXP_CURRENT_VERSION
Current version of channel exit parameter structure.
The value of this constant depends on the environment (see above).

Note: When a new version of the MQCXP structure is introduced, the layout
of the existing part is not changed. The exit should therefore check that
the version number is equal to or greater than the lowest version which
contains the fields that the exit needs to use.

This is an input field to the exit.

ExitId (MQLONG)
Type of exit.

This indicates the type of exit being called, and is set on entry to the exit
routine. Possible values are:
MQXT_CHANNEL_SEC_EXIT
Channel security exit.
MQXT_CHANNEL_MSG_EXIT
Channel message exit.

592 MQSeries Intercommunication

 MQCXP
MQXT_CHANNEL_SEND_EXIT
Channel send exit.
MQXT_CHANNEL_RCV_EXIT
Channel receive exit.
MQXT_CHANNEL_MSG_RETRY_EXIT
Channel message-retry exit.
This type of exit is not supported on OS/390, 16-bit Windows, and
32-bit Windows.
MQXT_CHANNEL_AUTO_DEF_EXIT
Channel auto-definition exit.
On OS/390, this type of exit is supported only for channels of type
MQCHT_CLUSSDR and MQCHT_CLUSRCVR.
On 16-bit Windows and 32-bit Windows, this type of exit is not
supported.

This is an input field to the exit.

ExitReason (MQLONG)
Reason for invoking exit.

This indicates the reason why the exit is being called, and is set on entry to the
exit routine. It is not used by the auto-definition exit. Possible values are:
MQXR_INIT
Exit initialization.
This indicates that the exit is being invoked for the first time. It allows
the exit to acquire and initialize any resources that it may need (for
example: main storage).
MQXR_TERM
Exit termination.
This indicates that the exit is about to be terminated. The exit should
free any resources that it may have acquired since it was initialized (for
example: main storage).
MQXR_MSG
Process a message.
This indicates that the exit is being invoked to process a message. This
occurs for channel message exits only.
MQXR_XMIT
Process a transmission.
This occurs for channel send and receive exits only.
MQXR_SEC_MSG
Security message received.
This occurs for channel security exits only.
MQXR_INIT_SEC
Initiate security exchange.
This occurs for channel security exits only.
The receiver’s security exit is always invoked with this reason
immediately after being invoked with MQXR_INIT, to give it the

Chapter 37. Channel-exit calls and data structures 593

 MQCXP
opportunity to initiate a security exchange. If it declines the
| opportunity (by returning MQXCC_OK instead of
| MQXCC_SEND_SEC_MSG or
| MQXCC_SEND_AND_REQUEST_SEC_MSG), the sender’s security exit
is invoked with MQXR_INIT_SEC.
| If the receiver’s security exit does initiate a security exchange (by
| returning MQXCC_SEND_SEC_MSG or
| MQXCC_SEND_AND_REQUEST_SEC_MSG), the sender’s security exit
is never invoked with MQXR_INIT_SEC; instead it is invoked with
MQXR_SEC_MSG to process the receiver’s message. (In either case it is
first invoked with MQXR_INIT.)
Unless one of the security exits requests termination of the channel (by
setting ExitResponse to MQXCC_SUPPRESS_FUNCTION or
MQXCC_CLOSE_CHANNEL), the security exchange must complete at
the side that initiated the exchange. Therefore, if a security exit is
invoked with MQXR_INIT_SEC and it does initiate an exchange, the
| next time the exit is invoked it will be with MQXR_SEC_MSG. This
| happens whether or not there is a security message for the exit to
| process. There will be a security message if the partner returns
| MQXCC_SEND_SEC_MSG or
| MQXCC_SEND_AND_REQUEST_SEC_MSG, but not if the partner
| returns MQXCC_OK or there is no security exit at the partner. If there
is no security message to process, the security exit at the initiating end
is re-invoked with a DataLength of zero.
MQXR_RETRY
Retry a message.
This occurs for message-retry exits only.
On OS/390, this is not supported.
MQXR_AUTO_CLUSSDR
Automatic definition of a cluster-sender channel.
This occurs for channel auto-definition exits only.
MQXR_AUTO_RECEIVER
Automatic definition of a receiver channel.
This occurs for channel auto-definition exits only.
MQXR_AUTO_SVRCONN
Automatic definition of a server-connection channel.
This occurs for channel auto-definition exits only.
MQXR_AUTO_CLUSRCVR
Automatic definition of a cluster-receiver channel.
This occurs for channel auto-definition exits only.
Notes:
1. If you have more than one exit defined for a channel, they will each be
invoked with MQXR_INIT when the MCA is initialized, and will each be
invoked with MQXR_TERM when the MCA is terminated.
2. For the channel auto-definition exit, ExitReason is not set if Version is less
than MQCXP_VERSION_4. The value MQXR_AUTO_SVRCONN is implied
in this case.

594 MQSeries Intercommunication

 MQCXP
This is an input field to the exit.
ExitResponse (MQLONG)
Response from exit.

This is set by the exit to communicate with the MCA. It must be one of the
following:
MQXCC_OK
Continue normally.
v For the channel security exit, this indicates that message transfer
should now proceed normally.
v For the channel message retry exit, this indicates that the MCA
should wait for the time interval returned by the exit in the
MsgRetryInterval field in MQCXP, and then retry the message.
The ExitResponse2 field may contain additional information.
MQXCC_SUPPRESS_FUNCTION
Suppress function.
v For the channel security exit, this indicates that the channel should
be terminated.
v For the channel message exit, this indicates that the message is not
to proceed any further towards its destination. Instead the MCA
generates an exception report message (if one was requested by the
sender of the original message), and places the original message on
the dead-letter queue (if the sender specified
MQRO_DEAD_LETTER_Q), or discards it (if the sender specified
MQRO_DISCARD_MSG).
If the sender specified MQRO_DEAD_LETTER_Q, but the put to the
dead-letter queue fails, or there is no dead-letter queue, the original
message is left on the transmission queue and the report message is
not generated. The original message is also left on the transmission
queue if the report message cannot be generated successfully.
The Feedback field in the MQDLH structure at the start of the
message on the dead-letter queue indicates why the message was
put on the dead-letter queue; this feedback code is also used in the
message descriptor of the exception report message (if one was
requested by the sender).
v For the channel message retry exit, this indicates that the MCA
should not wait and retry the message; instead, the MCA continues
immediately with its normal failure processing (the message is
placed on the dead-letter queue or discarded, as specified by the
sender of the message).
v For the channel auto-definition exit, either MQXCC_OK or
MQXCC_SUPPRESS_FUNCTION must be specified. If neither of
these is specified, MQXCC_SUPPRESS_FUNCTION is assumed by
default and the auto-definition is abandoned.

This response is not supported for the channel send and receive exits.
MQXCC_SEND_SEC_MSG
Send security message.
This value can be set only by a channel security exit. It indicates that
the exit has provided a security message which should be transmitted
to the partner.

Chapter 37. Channel-exit calls and data structures 595

MQCXP
MQXCC_SEND_AND_REQUEST_SEC_MSG
Send security message that requires a reply.
This value can be set only by a channel security exit. It indicates
v that the exit has provided a security message which should be
transmitted to the partner, and
v that the exit requires a response from the partner. If no response is
received, the channel must be terminated, because the exit has not
yet decided whether communications can proceed.

This is not valid on OS/390 if you are using CICS for distributed
queuing.
MQXCC_SUPPRESS_EXIT
Suppress exit.
v This value can be set by all types of channel exit other than a
security exit or an auto-definition exit. It suppresses any further
invocation of that exit (as if its name had been blank in the channel
definition), until termination of the MCA, when the exit is again
invoked with an ExitReason of MQXR_TERM.
v If a message retry exit returns this value, message retries for
subsequent messages are controlled by the MsgRetryCount and
MsgRetryInterval channel attributes as normal. For the current
message, the MCA performs the number of outstanding retries, at
intervals given by the MsgRetryInterval channel attribute, but only
if the reason code is one that the MCA would normally retry (see the
MsgRetryCount field described in “MQCD - Channel data structure”
on page 556). The number of outstanding retries is the value of the
MsgRetryCount attribute, less the number of times the exit returned
MQXCC_OK for the current message; if this number is negative, no
further retries are performed by the MCA for the current message.

This is not valid on OS/390 if you are using CICS for distributed
queuing.
MQXCC_CLOSE_CHANNEL
Close channel.
This value can be set by any type of channel exit except an
auto-definition exit. It causes the message channel agent (MCA) to
close the channel.
This is not valid on OS/390 if you are using CICS for distributed
queuing.

This is an input/output field from the exit.

ExitResponse2 (MQLONG)
Secondary response from exit.

This is set to zero on entry to the exit routine. It can be set by the exit to
provide further information to the MCA. It is not used by the auto-definition
exit.

The exit can set one or more of the following. If more than one is required, the
values are added together. Combinations that are not valid are noted; other
combinations are allowed.

596 MQSeries Intercommunication

 MQCXP
MQXR2_PUT_WITH_DEF_ACTION
Put with default action.
This is set by the receiver’s channel message exit. It indicates that the
message is to be put with the MCA’s default action, that is either the
MCA’s default user ID, or the context UserIdentifier in the MQMD
(message descriptor) of the message.
The value of this constant is zero, which corresponds to the initial
value set when the exit is invoked. The constant is provided for
documentation purposes.
MQXR2_PUT_WITH_DEF_USERID
Put with default user identifier.
This can only be set by the receiver’s channel message exit. It indicates
that the message is to be put with the MCA’s default user identifier.
MQXR2_PUT_WITH_MSG_USERID
Put with message’s user identifier.
This can only be set by the receiver’s channel message exit. It indicates
that the message is to be put with the context UserIdentifier in the
MQMD (message descriptor) of the message (this may have been
modified by the exit).

Only one of MQXR2_PUT_WITH_DEF_ACTION,

MQXR2_PUT_WITH_DEF_USERID, and MQXR2_PUT_WITH_MSG_USERID
should be set.
MQXR2_USE_AGENT_BUFFER
Use agent buffer.
This indicates that any data to be passed on is in AgentBuffer, not
ExitBufferAddr.
The value of this constant is zero, which corresponds to the initial
value set when the exit is invoked. The constant is provided for
documentation purposes.
MQXR2_USE_EXIT_BUFFER
Use exit buffer.
This indicates that any data to be passed on is in ExitBufferAddr, not
AgentBuffer.

Only one of MQXR2_USE_AGENT_BUFFER and MQXR2_USE_EXIT_BUFFER

should be set.
MQXR2_DEFAULT_CONTINUATION
Exit continuation criteria.
Continuation with the next exit in the chain depends on the response
from the last exit invoked:
v If MQXCC_SUPPRESS_FUNCTION or MQXCC_CLOSE_CHANNEL
are returned, no further exits in the chain are called.
v Otherwise, the next exit in the chain is invoked.

On OS/390, this is not supported.

MQXR2_CONTINUE_CHAIN
Continue with the next exit.

Chapter 37. Channel-exit calls and data structures 597

MQCXP
On OS/390, this is not supported.
MQXR2_SUPPRESS_CHAIN
No further exits are invoked.
On OS/390, this is not supported.

This is an input/output field from the exit.

Feedback (MQLONG)
Feedback code.

This is set to zero on entry to the exit routine.

If a channel message exit sets the ExitResponse field to

MQXCC_SUPPRESS_FUNCTION, the Feedback field specifies the feedback
code that identifies why the message was put on the dead-letter
(undelivered-message) queue, and is also used to send an exception report if
one has been requested. If the Feedback field is zero in this case, the following
feedback code is used:
MQFB_STOPPED_BY_MSG_EXIT
Message stopped by channel message exit.

The value returned in this field by channel security, send, receive, and
message-retry exits is not used by the MCA.

The value returned in this field by auto-definition exits is not used if

ExitResponse is MQXCC_OK, but otherwise is used for the AuxErrorDataInt1
parameter in the event message.

This is an input/output field from the exit.

MaxSegmentLength (MQLONG)
Maximum segment length.

This is the maximum length in bytes that can be sent in a single transmission.
It is not used by the auto-definition exit. It is of interest to a channel send exit,
because this exit must ensure that it does not increase the size of a
transmission segment to a value greater than MaxSegmentLength. The length
includes the initial 8 bytes that the exit must not change. The value is
negotiated between the message channel agents when the channel is initiated.
See “Writing and compiling channel-exit programs” on page 518 for more
information about segment lengths.

The value in this field is not meaningful if ExitReason is MQXR_INIT.

This is an input field to the exit.

ExitUserArea (MQBYTE16)
Exit user area.

This is a field that is available for the exit to use. (It is not used by the
auto-definition exit.) It is initialized to binary zero before the first invocation of
the exit (which has an ExitReason set to MQXR_INIT), and thereafter any
changes made to this field by the exit are preserved across invocations of the
exit.

The following value is defined:

598 MQSeries Intercommunication

 MQCXP
MQXUA_NONE
No user information.
The value is binary zero for the length of the field.
For the C programming language, the constant
MQXUA_NONE_ARRAY is also defined; this has the same value as
MQXUA_NONE, but is an array of characters instead of a string.

The length of this field is given by MQ_EXIT_USER_AREA_LENGTH. This is

an input/output field to the exit.
ExitData (MQCHAR32)
Exit data.

This is set on entry to the exit routine to information that the MCA took from
the channel definition. If no such information is available, this field is all
blanks.

The length of this field is given by MQ_EXIT_DATA_LENGTH.

This is an input field to the exit.

| The following fields in this structure are not present if Version is less than
| MQCXP_VERSION_2.
MsgRetryCount (MQLONG)
Number of times the message has been retried.

The first time the exit is invoked for a particular message, this field has the
value zero (no retries yet attempted). On each subsequent invocation of the exit
for that message, the value is incremented by one by the MCA. On OS/390,
the value is always zero.

This is an input field to the exit. The value in this field is not meaningful if
ExitReason is MQXR_INIT. The field is not present if Version is less than
MQCXP_VERSION_2.
MsgRetryInterval (MQLONG)
Minimum interval in milliseconds after which the put operation should be
retried.

The first time the exit is invoked for a particular message, this field contains
the value of the MsgRetryInterval channel attribute. The exit can leave the
value unchanged, or modify it to specify a different time interval in
milliseconds. If the exit returns MQXCC_OK in ExitResponse, the MCA will
wait for at least this time interval before retrying the MQOPEN or MQPUT
operation. The time interval specified must be zero or greater.

The second and subsequent times the exit is invoked for that message, this
field contains the value returned by the previous invocation of the exit.

If the value returned in the MsgRetryInterval field is less than zero or greater
than 999 999 999, and ExitResponse is MQXCC_OK, the MCA ignores the
MsgRetryInterval field in MQCXP and waits instead for the interval specified
by the MsgRetryInterval channel attribute. On OS/390, the value of this field
is always zero.

Chapter 37. Channel-exit calls and data structures 599

 MQCXP
This is an input/output field to the exit. The value in this field is not
meaningful if ExitReason is MQXR_INIT. The field is not present if Version is
less than MQCXP_VERSION_2.
MsgRetryReason (MQLONG)
Reason code from previous attempt to put the message.

This is the reason code from the previous attempt to put the message; it is one
of the MQRC_* values. On OS/390 the value of this field is always zero.

This is an input field to the exit. The value in this field is not meaningful if
ExitReason is MQXR_INIT. The field is not present if Version is less than
MQCXP_VERSION_2.

| The following fields in this structure are not present if Version is less than
| MQCXP_VERSION_3.
HeaderLength (MQLONG)
Length of header information.

This field is relevant only for a message exit. The value is the length of the
routing header structures at the start of the message data; these are the
MQXQH structure, and (for a distribution-list message) the MQDH structure
and arrays of MQOR and MQPMR records that follow the MQXQH structure.

The message exit can examine this header information, and modify it if
necessary, but the data that the exit returns must still be in the correct format.
The exit must not, for example, encrypt or compress the header data at the
sending end, even if the message exit at the receiving end makes compensating
changes.

If the message exit modifies the header information in such a way as to change
its length (for example, by adding another destination to a distribution-list
message), it must change the value of HeaderLength correspondingly before
returning.

This is an input/output field to the exit. The value in this field is not
meaningful if ExitReason is MQXR_INIT. The field is not present if Version is
less than MQCXP_VERSION_3.
PartnerName (MQCHAR48)
Partner Name.

The name of the partner, as follows:

v For SVRCONN channels, it is the logged-on user ID at the client.
v For all other types of channel, it is the queue-manager name of the partner.

When the exit is initialized this field is blank because the queue manager does
not know the name of the partner until after initial negotiation has taken place.

This is an input field to the exit. The field is not present if Version is less than
MQCXP_VERSION_3.
FAPLevel (MQLONG)
Negotiated Formats and Protocols level.

600 MQSeries Intercommunication

 MQCXP
This is an input field to the exit. The field is not present if Version is less than
MQCXP_VERSION_3.
CapabilityFlags (MQLONG)
Capability flags.

The following are defined:

MQCF_NONE
No flags.
MQCF_DIST_LISTS
Distribution lists supported.

This is an input field to the exit. The field is not present if Version is less than
MQCXP_VERSION_3.
ExitNumber (MQLONG)
Exit number.

The ordinal number of the exit, within the type defined in ExitId. For
example, if the exit being invoked is the third message exit defined, this field
contains the value 3. If the exit type is one for which a list of exits cannot be
defined (for example, a security exit), this field has the value 1.

This is an input field to the exit. The field is not present if Version is less than
MQCXP_VERSION_3.

C declaration
typedef struct tagMQCXP {
MQCHAR4 StrucId; /* Structure identifier */
MQLONG Version; /* Structure version number */
MQLONG ExitId; /* Type of exit */
MQLONG ExitReason; /* Reason for invoking exit */
MQLONG ExitResponse; /* Response from exit */
MQLONG ExitResponse2; /* Secondary response from exit */
MQLONG Feedback; /* Feedback code */
MQLONG MaxSegmentLength; /* Maximum segment length */
MQBYTE16 ExitUserArea; /* Exit user area */
MQCHAR32 ExitData; /* Exit data */
MQLONG MsgRetryCount; /* Number of times the message has been
retried */
MQLONG MsgRetryInterval; /* Minimum interval in milliseconds after
which the put operation should be
retried */
MQLONG MsgRetryReason; /* Reason code from previous attempt to
put the message */
MQLONG HeaderLength; /* Length of header information */
MQCHAR48 PartnerName; /* Partner Name */
MQLONG FAPLevel; /* Negotiated Formats and Protocols
level */
MQLONG CapabilityFlags; /* Capability flags */
MQLONG ExitNumber; /* Exit number */
} MQCXP;

COBOL declaration
** MQCXP structure
10 MQCXP.
** Structure identifier
15 MQCXP-STRUCID PIC X(4).
** Structure version number
15 MQCXP-VERSION PIC S9(9) BINARY.

Chapter 37. Channel-exit calls and data structures 601

MQCXP
** Type of exit
15 MQCXP-EXITID PIC S9(9) BINARY.
** Reason for invoking exit
15 MQCXP-EXITREASON PIC S9(9) BINARY.
** Response from exit
15 MQCXP-EXITRESPONSE PIC S9(9) BINARY.
** Secondary response from exit
15 MQCXP-EXITRESPONSE2 PIC S9(9) BINARY.
** Feedback code
15 MQCXP-FEEDBACK PIC S9(9) BINARY.
** Maximum segment length
15 MQCXP-MAXSEGMENTLENGTH PIC S9(9) BINARY.
** Exit user area
15 MQCXP-EXITUSERAREA PIC X(16).
** Exit data
15 MQCXP-EXITDATA PIC X(32).
** Number of times the message has been retried
15 MQCXP-MSGRETRYCOUNT PIC S9(9) BINARY.
** Minimum interval in milliseconds after which the put
** operation should be retried
15 MQCXP-MSGRETRYINTERVAL PIC S9(9) BINARY.
** Reason code from previous attempt to put the message
15 MQCXP-MSGRETRYREASON PIC S9(9) BINARY.
** Length of header information
15 MQCXP-HEADERLENGTH PIC S9(9) BINARY.
** Partner Name
15 MQCXP-PARTNERNAME PIC X(48).
** Negotiated Formats and Protocols level
15 MQCXP-FAPLEVEL PIC S9(9) BINARY.
** Capability flags
15 MQCXP-CAPABILITYFLAGS PIC S9(9) BINARY.
** Exit number
15 MQCXP-EXITNUMBER PIC S9(9) BINARY.

PL/I declaration
dcl
1 MQCXP based,
3 StrucId char(4), /* Structure identifier */
3 Version fixed bin(31), /* Structure version number */
3 ExitId fixed bin(31), /* Type of exit */
3 ExitReason fixed bin(31), /* Reason for invoking exit */
3 ExitResponse fixed bin(31), /* Response from exit */
3 ExitResponse2 fixed bin(31), /* Secondary response from exit */
3 Feedback fixed bin(31), /* Feedback code */
3 MaxSegmentLength fixed bin(31), /* Maximum segment length */
3 ExitUserArea char(16), /* Exit user area */
3 ExitData char(32), /* Exit data */
3 MsgRetryCount fixed bin(31), /* Number of times the message has
been retried */
3 MsgRetryInterval fixed bin(31), /* Minimum interval in milliseconds
after which the put operation
should be retried */
3 MsgRetryReason fixed bin(31), /* Reason code from previous attempt
to put the message */
3 HeaderLength fixed bin(31), /* Length of header information */
3 PartnerName char(48), /* Partner Name */
3 FAPLevel fixed bin(31), /* Negotiated Formats and Protocols
level */
3 CapabilityFlags fixed bin(31), /* Capability flags */
3 ExitNumber fixed bin(31); /* Exit number */

ILE RPG declaration

D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
D* MQCXP Structure
D*

602 MQSeries Intercommunication

 MQCXP
D* Structure identifier
D CXSID 1 4
D* Structure version number
D CXVER 5 8I 0
D* Type of exit
D CXXID 9 12I 0
D* Reason for invoking exit
D CXREA 13 16I 0
D* Response from exit
D CXRES 17 20I 0
D* Secondary response from exit
D CXRE2 21 24I 0
D* Feedback code
D CXFB 25 28I 0
D* Maximum segment length
D CXMSL 29 32I 0
D* Exit user area
D CXUA 33 48
D* Exit data
D CXDAT 49 80
D* Number of times the message has been retried
D CXMRC 81 84I 0
D* Minimum interval in milliseconds after which the put operation
D* should be retried
D CXMRI 85 88I 0
D* Reason code from previous attempt to put the message
D CXMRR 89 92I 0
D* Length of header information
D CXHDL 93 96I 0
D* Partner Name
D CXPNM 97 144
D* Negotiated Formats and Protocols level
D CXFAP 145 148I 0
D* Capability flags
D CXCAP 149 152I 0
D* Exit number
D CXEXN 153 156I 0

OPM RPG declaration

I*..1....:....2....:....3....:....4....:....5....:....6....:....7..
I* MQCXP Structure
I*
I* Structure identifier
I 1 4 CXSID
I* Structure version number
I B 5 80CXVER
I* Type of exit
I B 9 120CXXID
I* Reason for invoking exit
I B 13 160CXREA
I* Response from exit
I B 17 200CXRES
I* Secondary response from exit
I B 21 240CXRE2
I* Feedback code
I B 25 280CXFB
I* Maximum segment length
I B 29 320CXMSL
I* Exit user area
I 33 48 CXUA
I* Exit data
I 49 80 CXDAT
I* Number of times the message has been retried
I B 81 840CXMRC
I* Minimum interval in milliseconds after which the put operation
I* should be retried

Chapter 37. Channel-exit calls and data structures 603

MQCXP
I B 85 880CXMRI
I* Reason code from previous attempt to put the message
I B 89 920CXMRR
I* Length of header information
I B 93 960CXHDL
I* Partner Name
I 97 144 CXPNM
I* Negotiated Formats and Protocols level
I B 145 1480CXFAP
I* Capability flags
I B 149 1520CXCAP
I* Exit number
I B 153 1560CXEXN

System/390 assembler declaration

MQCXP DSECT
MQCXP_STRUCID DS CL4 Structure identifier
MQCXP_VERSION DS F Structure version number
MQCXP_EXITID DS F Type of exit
MQCXP_EXITREASON DS F Reason for invoking exit
MQCXP_EXITRESPONSE DS F Response from exit
MQCXP_EXITRESPONSE2 DS F Secondary response from exit
MQCXP_FEEDBACK DS F Feedback code
MQCXP_MAXSEGMENTLENGTH DS F Maximum segment length
MQCXP_EXITUSERAREA DS XL16 Exit user area
MQCXP_EXITDATA DS CL32 Exit data
MQCXP_MSGRETRYCOUNT DS F Number of times the message
* has been retried
MQCXP_MSGRETRYINTERVAL DS F Minimum interval in
* milliseconds after which the
* put operation should be
* retried
MQCXP_MSGRETRYREASON DS F Reason code from previous
* attempt to put the message
MQCXP_HEADERLENGTH DS F Length of header information
MQCXP_PARTNERNAME DS CL48 Partner Name
MQCXP_FAPLEVEL DS F Negotiated Formats and
* Protocols level
MQCXP_CAPABILITYFLAGS DS F Capability flags
MQCXP_EXITNUMBER DS F Exit number
MQCXP_LENGTH EQU *-MQCXP Length of structure
ORG MQCXP
MQCXP_AREA DS CL(MQCXP_LENGTH)

604 MQSeries Intercommunication

 MQTXP

MQTXP - Transport-exit data structure

The following table summarizes the fields in the structure.
Table 50. Fields in MQTXP
Field Description Page
StrucId Structure identifier 605
Version Structure version number 605
ExitReason Reason for invoking exit 606
ExitUserArea Exit user area 606
TransportType Transport type 606
RetryCount Number of times data has been retried 607
DataLength Length of data to be sent 607
SessionId Session identifier 607
GroupId Group identifier 607
DataId Data identifier 607
ExitResponse Response from exit 607

The MQTXP structure describes the information that is passed to the transport
retry exit.

This structure is supported in the following environments: AIX and 16-bit

Windows.

Fields
StrucId (MQCHAR4)
Structure identifier.

The value is:

MQTXP_STRUC_ID
Identifier for transport retry exit parameter structure.
For the C programming language, the constant
MQTXP_STRUC_ID_ARRAY is also defined; this has the same value as
MQTXP_STRUC_ID, but is an array of characters instead of a string.

This is an input field to the exit.

Version (MQLONG)
Structure version number.

The value is:

MQTXP_VERSION_1
Version-1 transport retry exit parameter structure.

The following constant specifies the version number of the current version:
MQTXP_CURRENT_VERSION
Current version of transport retry exit parameter structure.

This is an input field to the exit.

Chapter 37. Channel-exit calls and data structures 605

MQTXP
Reserved (MQLONG)
Reserved.

This is a reserved field. The value is zero.

ExitReason (MQLONG)
Reason for invoking exit.

This indicates the reason why the exit is being called. Possible values are:
MQXR_INIT
Exit initialization.
This indicates that the exit is being invoked for the first time. It allows
the exit to acquire and initialize any resources that it may need (for
example: main storage).
MQXR_TERM
Exit termination.
This indicates that the exit is about to be terminated. The exit should
free any resources that it may have acquired since it was initialized (for
example: main storage).
MQXR_RETRY
Retry a message.
MQXR_END_BATCH
Called from MCA when batch completed.
MQXR_ACK_RECEIVED
Called from MCA when an acknowledgement has been received.

This is an input field to the exit.

ExitUserArea (MQBYTE16)
Exit user area.

This is a field that is available for the exit to use. It is initialized to

MQXUA_NONE (binary zero) before the first invocation of the exit, and
thereafter any changes made to this field by the exit are preserved across
invocations of the exit. The first invocation of the exit has ExitReason set to
MQXR_INIT.

The following value is defined:

MQXUA_NONE
No user information.
The value is binary zero for the length of the field.
For the C programming language, the constant
MQXUA_NONE_ARRAY is also defined; this has the same value as
MQXUA_NONE, but is an array of characters instead of a string.

The length of this field is given by MQ_EXIT_USER_AREA_LENGTH. This is

an input/output field to the exit.
TransportType (MQLONG)
Transport type.

This is the type of transport being used. The value is:

606 MQSeries Intercommunication

 MQTXP
MQXPT_UDP
UDP transport protocol.

This is an input field to the exit.

RetryCount (MQLONG)
Number of times data has been retried.

This is the number of previous attempts that have been made to send the
current data. It is zero on first invocation of the exit for the current data.

This is an input field to the exit.

DataLength (MQLONG)
Length of data to be sent.

This is always greater than zero. For MQXPT_UDP, it is one complete encoded
datagram.

This is an input field to the exit.

SessionId (MQLONG)
Session identifier.

This is the identifier of the session of channel. For MQXPT_UDP, it is the

UdpHandle.

This is an input field to the exit.

GroupId (MQLONG)
Group identifier.

This is the identifier of the group, bunch, or message to which the data
belongs. For MQXPT_UDP, it identifies the bunch.

This is an input field to the exit.

DataId (MQLONG)
Data identifier.

For MQXPT_UDP, this is the datagram identifier.

This is an input field to the exit.

ExitResponse (MQLONG)
Response from exit.

This is set by the exit to indicate how processing should continue. It must be
one of the following:
MQXCC_OK
Continue normally.
This indicates that processing should continue normally.
MQXCC_REQUEST_ACK
Request acknowledgement.
This indicates that processing should continue normally, but that the
datagram about to be sent should request that an acknowledgement be
returned by the receiver of the datagram.

Chapter 37. Channel-exit calls and data structures 607

MQTXP
MQXCC_CLOSE_CHANNEL
Close channel.
This indicates that processing should be discontinued and the channel
closed.

If any other value is returned by the exit, processing continues as if

MQXCC_CLOSE_CHANNEL had been specified.

This is an output field from the exit.

Feedback (MQLONG)
Reserved.

This is a reserved field. The value is zero.

C declaration
typedef struct tagMQTXP {
MQCHAR4 StrucId; /* Structure identifier */
MQLONG Version; /* Structure version number */
MQLONG Reserved; /* Reserved */
MQLONG ExitReason; /* Reason for invoking exit */
MQBYTE16 ExitUserArea; /* Exit user area */
MQLONG TransportType; /* Transport type */
MQLONG RetryCount; /* Number of times data has been retried */
MQLONG DataLength; /* Length of data to be sent */
MQLONG SessionId; /* Session identifier */
MQLONG GroupId; /* Group identifier */
MQLONG DataId; /* Data identifier */
MQLONG ExitResponse; /* Response from exit */
MQLONG Feedback; /* Reserved */
} MQTXP;

608 MQSeries Intercommunication

 MQXWD

MQXWD - Exit wait descriptor structure

The following table summarizes the fields in the structure.
Table 51. Fields in MQXWD
Field Description Page
StrucId Structure identifier 609
Version Structure version number 609
ECB Event control block to wait on 610

The MQXWD structure is an input/output parameter on the MQXWAIT call.

| This structure is supported only on OS/390.

Fields
StrucId (MQCHAR4)
Structure identifier.

The value must be:

MQXWD_STRUC_ID
Identifier for exit wait descriptor structure.
For the C programming language, the constant
MQXWD_STRUC_ID_ARRAY is also defined; this has the same value
as MQXWD_STRUC_ID, but is an array of characters instead of a
string.

The initial value of this field is MQXWD_STRUC_ID.

Version (MQLONG)
Structure version number.

The value must be:

MQXWD_VERSION_1
Version number for exit wait descriptor structure.

The initial value of this field is MQXWD_VERSION_1.

Reserved1 (MQLONG)
Reserved.

This is a reserved field; its value must be zero.

This is an input field.

Reserved2 (MQLONG)
Reserved.

This is a reserved field; its value must be zero.

This is an input field.

Reserved3 (MQLONG)
Reserved.

Chapter 37. Channel-exit calls and data structures 609

MQXWD
This is a reserved field; its value must be zero.

This is an input field.

ECB (MQLONG)
Event control block to wait on.

This is the event control block (ECB) to wait on. It should be set to zero before
the MQXWAIT call is issued; on successful completion it will contain the post
code.

This is an input/output field.

C declaration
typedef struct tagMQXWD {
MQCHAR4 StrucId; /* Structure identifier */
MQLONG Version; /* Structure version number */
MQLONG Reserved1; /* Reserved */
MQLONG Reserved2; /* Reserved */
MQLONG Reserved3; /* Reserved */
MQLONG ECB; /* Event control block to wait on */
} MQXWD;

System/390 assembler declaration

MQXWD DSECT
MQXWD_STRUCID DS CL4 Structure identifier
MQXWD_VERSION DS F Structure version number
MQXWD_RESERVED1 DS F Reserved
MQXWD_RESERVED2 DS F Reserved
MQXWD_RESERVED3 DS F Reserved
MQXWD_ECB DS F Event control block to wait
* on
MQXWD_LENGTH EQU *-MQXWD Length of structure
ORG MQXWD
MQXWD_AREA DS CL(MQXWD_LENGTH)

610 MQSeries Intercommunication

Chapter 38. Problem determination in DQM
This chapter explains the various aspects of problem determination and suggests
methods of resolving problems. Some of the problems mentioned in this chapter
are platform and installation specific. Where this is the case, it is made clear in the
text.

Problem determination for the following scenarios is discussed:

v “Error message from channel control”
v “Ping”
v “Dead-letter queue considerations” on page 612
v “Validation checks” on page 612
v “In-doubt relationship” on page 613
v “Channel startup negotiation errors” on page 613
v “When a channel refuses to run” on page 613
v “Retrying the link” on page 615
v “Data structures” on page 616
v “User exit problems” on page 616
v “Disaster recovery” on page 616
v “Channel switching” on page 617
v “Connection switching” on page 617
v “Client problems” on page 617
v “Error logs” on page 618

Error message from channel control

Problems found during normal operation of the channels are reported to the
system console and to the system log. In MQSeries for OS/390 using CICS, they
are reported to the CICS Transient Data Queue CKMQ, if that is defined and
available. In MQSeries for Windows they are reported to the channel log. Problem
diagnosis starts with the collection of all relevant information from the log, and
analysis of this information to identify the problem.

However, this could be difficult in a network where the problem may arise at an
intermediate system that is staging some of your messages. An error situation,
such as transmission queue full, followed by the dead-letter queue filling up,
would result in your channel to that site closing down.

In this example, the error message you receive in your error log will indicate a
problem originating from the remote site, but may not be able to tell you any
details about the error at that site.

You need to contact your counterpart at the remote site to obtain details of the
problem, and to receive notification of that channel becoming available again.

Ping
Ping, which is not supported on MQSeries for Windows, is useful in determining
whether the communication link and the two message channel agents that make
up a message channel are functioning across all interfaces.

Ping makes no use of transmission queues, but it does invoke some user exit
programs. If any error conditions are encountered, error messages are issued.

© Copyright IBM Corp. 1993, 2000 611

Ping
To use ping, you can issue the MQSC command PING CHANNEL (you cannot do
this if you are using CICS for distributed queuing on OS/390). On OS/390 and
OS/400, you can also use the panel interface to select this option.

On UNIX platforms, OS/2, Windows NT, and OS/400, you can also use the MQSC
command PING QMGR to test whether the queue manager is responsive to
commands. See the MQSeries Command Reference book for more information about
this.

Dead-letter queue considerations

In some MQSeries products the dead-letter queue is referred to as an
undelivered-message queue. There are no dead-letter queues in MQSeries for
Windows.

If a channel ceases to run for any reason, applications will probably continue to
place messages on transmission queues, creating a potential overflow situation.
Applications can monitor transmission queues to find the number of messages
waiting to be sent, but this would not be a normal function for them to carry out.

When this occurs in a message-originating node, and the local transmission queue
is full, the application’s PUT fails.

When this occurs in a staging or destination node, there are three ways that the
MCA copes with the situation:
1. By calling the message-retry exit, if one is defined.
2. By directing all overflow messages to a dead-letter queue (DLQ), returning an
exception report to applications that requested these reports.

Note: In distributed-queuing management, if the message is too big for the

DLQ, the DLQ is full, or the DLQ is not available, the channel stops and
the message remains on the transmission queue. Ensure your DLQ is
defined, available, and sized for the largest messages you handle.
3. By closing down the channel, if neither of the previous options succeeded.
4. By returning the undelivered messages back to the sending end and returning a
full report to the reply-to queue (MQRC_EXCEPTION_WITH_FULL_DATA and
MQRO_DISCARD_MSG).

If an MCA is unable to put a message on the DLQ:

v The channel stops
v Appropriate error messages are issued at the system consoles at both ends of the
message channel
v The unit of work is backed out, and the messages reappear on the transmission
queue at the sending channel end of the channel
v Triggering is disabled for the transmission queue

Validation checks
A number of validation checks are made when creating, altering, and deleting
channels, and where appropriate, an error message returned.

Errors may occur when:

v A duplicate channel name is chosen when creating a channel
v Unacceptable data is entered in the channel parameter fields

612 MQSeries Intercommunication

 Validation checks
v The channel to be altered is in doubt, or does not exist

In-doubt relationship
If a channel is in doubt, it is usually resolved automatically on restart, so the
system operator does not need to resolve a channel manually in normal
circumstances. See “In-doubt channels” on page 69 for information about this.

Channel startup negotiation errors

During channel startup, the starting end has to state its position and agree channel
running parameters with the corresponding channel. It may happen that the two
ends cannot agree on the parameters, in which case the channel closes down with
error messages being issued to the appropriate error logs.

When a channel refuses to run

If a channel refuses to run:
v Check that DQM and the channels have been set up correctly. This is a likely
problem source if the channel has never run. Reasons could be:
– A mismatch of names between sending and receiving channels (remember
that uppercase and lowercase letters are significant)
– Incorrect channel types specified
– The sequence number queue (if applicable) is not available, or is damaged
– The dead-letter queue is not available
– The sequence number wrap value is different on the two channel definitions
– A queue manager, CICS system, or communication link is not available
– Following a restart, the wrong queue manager may have been attached to
CICS
– A receiver channel might be in STOPPED state
– The connection might not be defined correctly
– There might be a problem with the communications software (for example, is
TCP running?)
– In OS/390 using CICS, check that the DFHSIT SYSIDNT name of the target
CICS system matches the connection name that you have specified for that
system
v It is possible that an in-doubt situation exists, if the automatic synchronization
on startup has failed for some reason. This is indicated by messages on the
system console, and the status panel may be used to show channels that are in
doubt.
The possible responses to this situation are:
– Issue a Resolve channel request with Backout or Commit.
You need to check with your remote link supervisor to establish the number
of the last message or unit of work committed. Check this against the last
number at your end of the link. If the remote end has committed a number,
and that number is not yet committed at your end of the link, then issue a
RESOLVE COMMIT command.
In all other cases, issue a RESOLVE BACKOUT command.
The effect of these commands is that backed out messages reappear on the
transmission queue and are sent again, while committed messages are
discarded.

Chapter 38. Problem determination in DQM 613

 Channel refuses to run
If in doubt yourself, perhaps backing out with the probability of duplicating a
sent message would be the safer decision.
– Issue a RESET command.
This command is for use when sequential numbering is in effect, and should
be used with care. Its purpose is to reset the sequence number of messages
and you should use it only after using the RESOLVE command to resolve any
in-doubt situations.
v On MQSeries for AS/400, OS/2, Windows NT, UNIX systems, and OS/390
without CICS, there is no need for the administrator to choose a particular
sequence number to ensure that the sequence numbers are put back in step.
When a sender channel starts up after being reset, it informs the receiver that it
has been reset and supplies the new sequence number that is to be used by both
the sender and receiver.

Note: If the sender is MQSeries for OS/390 using CICS, the sequence number
should be reset to the same number as any receiving queue managers.
v If the status of a receiver end of the channel is STOPPED, it can be reset by
starting the receiver end.

Note: This does not start the channel, it merely resets the status. The channel
must still be started from the sender end.

Triggered channels
If a triggered channel refuses to run, the possibility of in-doubt messages should be
investigated as described above.

Another possibility is that the trigger control parameter on the transmission queue
has been set to NOTRIGGER by the channel. This happens when:
v There is a channel error
v The channel was stopped because of a request from the receiver
v The channel was stopped because of a problem on the sender that requires
manual intervention

After diagnosing and fixing the problem, you must reset the trigger control
parameter to TRIGGER.

An example of a situation where a triggered channel fails to start is as follows:

1. A transmission queue is defined with a trigger type of FIRST.
2. A message arrives on the transmission queue, and a trigger message is
produced.
3. The channel is started, but stops immediately because the communications to
the remote system are not available.
4. The remote system is made available.
5. Another message arrives on the transmission queue.
| 6. The second message does not increase the queue depth from zero to one, so no
| trigger message is produced (unless the channel is in RETRY state). If this
| happens, the channel must be started manually.
| On MQSeries for OS/390, if the queue manager is stopped using
| MODE(FORCE) during channel initiator shutdown, it may be necessary to
| manually restart some channels after channel initiator restart.

614 MQSeries Intercommunication

 Channel refuses to run
Because the second message does not cause the queue depth to go from zero to
one, no trigger message is produced (unless the channel is in RETRY state). If this
happens, the channel must be started manually.

Conversion failure
Another reason for the channel refusing to run could be that neither end is able to
carry out necessary conversion of message descriptor data between ASCII and
EBCDIC, and integer formats. In this instance, communication is not possible.

Network problems
When using LU 6.2, make sure that your definitions are consistent throughout the
network. For example, if you have increased the RU sizes in your CICS Transaction
Server for OS/390 or Communications Manager definitions, but you have a
controller with a small MAXDATA value in its definition, the session may fail if
you attempt to send large messages across the network. A symptom of this may be
that channel negotiation takes place successfully, but the link fails when message
transfer occurs.

When using TCP, if your channels are unreliable and your connections breaking,
use the SO_KEEPALIVE option, as discussed in “Checking that the other end of
the channel is still available” on page 66.

Dial-up problems
MQSeries supports connection over dial-up lines but you should be aware that
with TCP, some protocol providers assign a new IP address each time you dial in.
This can cause channel synchronization problems because the channel cannot
recognize the new IP addresses and so cannot ensure the authenticity of the
partner. If you encounter this problem, you need to use a security exit program to
override the connection name for the session.

| This problem does not occur when a V5.1 of MQSeries for AIX, AS/400, HP-UX,
| OS/2 Warp, Sun Solaris, and Windows NT product is communicating with another
| product at the same level, because the queue manager name is used for
| synchronization instead of the IP address.

Retrying the link

An error scenario may occur that is difficult to recognize. For example, the link
and channel may be functioning perfectly, but some occurrence at the receiving
end causes the receiver to stop. Another unforeseen situation could be that the
receiver system has run out of storage and is unable to complete a transaction.

You need to be aware that such situations can arise, often characterized by a
system that appears to be busy but is not actually moving messages. You need to
work with your counterpart at the far end of the link to help detect the problem
and correct it.

Retry considerations
If a link failure occurs during normal operation, a sender or server channel
program will itself start another instance, provided that:
1. Initial data negotiation and security exchanges are complete
2. The retry count in the channel definition is greater than zero

Chapter 38. Problem determination in DQM 615

 Retrying the link
| Note: For OS/2, OS/400, UNIX systems, and Windows NT, to attempt a retry a
| channel initiator must be running. In platforms other than V5.1 of MQSeries
| for AIX, AS/400, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT, this
| channel initiator must be monitoring the initiation queue specified in the
| transmission queue that the channel in using. There is no channel initiator in
| MQSeries for Windows.
|
Data structures
Data structures are needed for reference when checking logs and trace entries
during problem diagnosis. Details can be found in “Chapter 37. Channel-exit calls
and data structures” on page 543 and in the MQSeries Application Programming
Reference book.

User exit problems

The interaction between the channel programs and the user-exit programs has
some error-checking routines, but this facility can only work successfully when the
user exits obey the rules described in “Part 7. Further intercommunication
considerations” on page 503. When errors occur, the most likely outcome will be
that the channel stops and the channel program issues an error message, together
with any return codes from the user exit. Any errors detected on the user exit side
of the interface can be determined by scanning the messages created by the user
exit itself.

You might need to use a trace facility of your host system to identify the problem.

Disaster recovery
Disaster recovery planning is the responsibility of individual installations, and the
functions performed may include the provision of regular system ‘snapshot’
dumps that are stored safely off-site. These dumps would be available for
regenerating the system, should some disaster overtake it. If this occurs, you need
to know what to expect of the messages, and the following description is intended
to start you thinking about it.

First a recap on system restart. If a system fails for any reason, it may have a
system log that allows the applications running at the time of failure to be
regenerated by replaying the system software from a syncpoint forward to the
instant of failure. If this occurs without error, the worst that can happen is that
message channel syncpoints to the adjacent system may fail on startup, and that
the last batches of messages for the various channels will be sent again. Persistent
messages will be recovered and sent again, nonpersistent messages may be lost.

If the system has no system log for recovery, or if the system recovery fails, or
where the disaster recovery procedure is invoked, the channels and transmission
queues may be recovered to an earlier state, and the messages held on local queues
at the sending and receiving end of channels may be inconsistent.

Messages may have been lost that were put on local queues. The consequence of
this happening depends on the particular MQSeries implementation, and the
channel attributes. For example, where strict message sequencing is in force, the
receiving channel detects a sequence number gap, and the channel closes down for
manual intervention. Recovery then depends upon application design, as in the
worst case the sending application may need to restart from an earlier message
sequence number.

616 MQSeries Intercommunication

 Channel switching

Channel switching
A possible solution to the problem of a channel ceasing to run would be to have
two message channels defined for the same transmission queue, but with different
communication links. One message channel would be preferred, the other would
be a replacement for use when the preferred channel is unavailable.

If triggering is required for these message channels, the associated process

definitions must exist for each sender channel end.

To switch message channels:

v If the channel is triggered, set the transmission queue attribute NOTRIGGER.
v Ensure the current channel is inactive.
v Resolve any in-doubt messages on the current channel.
v If the channel is triggered, change the process attribute in the transmission
queue to name the process associated with the replacement channel.
In this context, some implementations allow a channel to have a blank process
object definition, in which case you may omit this step as the queue manager
will find and start the appropriate process object.
v Restart the channel, or if the channel was triggered, set the transmission queue
attribute TRIGGER.

Connection switching
Another solution would be to switch communication connections from the
transmission queues.

To do this:
v If the sender channel is triggered, set the transmission queue attribute
NOTRIGGER.
v Ensure the channel is inactive.
v Resolve any in-doubt messages on the channel.
v Change the connection and profile fields to connect to the replacement
communication link.
v Ensure that the corresponding channel at the remote end has been defined.
v Restart the channel, or if the sender channel was triggered, set the transmission
queue attribute TRIGGER.

Client problems
A client application may receive an unexpected error return code, for example:
v Queue manager not available
v Queue manager name error
v Connection broken

Look in the client error log for a message explaining the cause of the failure. There
may also be errors logged at the server, depending on the nature of the failure.

Terminating clients
Even though a client has terminated, it is still possible for its surrogate process to
be holding its queues open. Normally this will only be for a short time until the
communications layer notifies that the partner has gone.

Chapter 38. Problem determination in DQM 617

 Error logs

Error logs
MQSeries error messages are placed in different error logs depending on the
platform. There are error logs for:
v OS/2 and Windows NT
v UNIX systems
v VSE/ESA
v DOS, Windows 3.1, Windows 95, and Windows 98 clients
v OS/390
v MQSeries for Windows
| v MQSeries for Tandem NSK

Error logs for OS/2 and Windows NT

MQSeries for OS/2 Warp and Windows NT use a number of error logs to capture
messages concerning the operation of MQSeries itself, any queue managers that
you start, and error data coming from the channels that are in use.

The location the error logs are stored in depends on whether the queue manager
name is known and whether the error is associated with a client.
v If the queue manager name is known and the queue manager is available:
C:\MQM\QMGRS\QMgrName\ERRORS\AMQERR01.LOG
v If the queue manager is not available:
C:\MQM\QMGRS\@SYSTEM\ERRORS\AMQERR01.LOG
v If an error has occurred with a client application:
C:\MQM\ERRORS\AMQERR01.LOG

Note: The above examples assume that you have installed MQSeries on the C:
drive and in the MQM directory. On Windows NT, the default data path is
C:\WINNT\Profiles\All Users\Application Data\MQSeries\.

On Windows NT, you should also examine the Windows NT application event log
for relevant messages.

Error logs on UNIX systems

MQSeries on UNIX systems uses a number of error logs to capture messages
concerning the operation of MQSeries itself, any queue managers that you start,
and error data coming from the channels that are in use. The location the error
logs are stored in depends on whether the queue manager name is known and
whether the error is associated with a client.
v If the queue manager name is known and the queue manager is available:
/var/mqm/qmgrs/QMgrName/errors/AMQERR01.LOG
v If the queue manager is not available:
/var/mqm/qmgrs/@SYSTEM/errors/AMQERR01.LOG
v If an error has occurred with a client application:
/var/mqm/errors/AMQERR01.LOG

Error logs on DOS, Windows 3.1, and Windows 95 and

Windows 98 clients
MQSeries clients use two error logs, stored in a location set by the environment
variable MQDATA (the default is the root drive of the client).
v Error messages:

618 MQSeries Intercommunication

 Error logs
AMQERR01.LOG
v FFDC messages:
AMQERR01.FDC

These files are not readable. See the MQSeries Clients book for information about
formatting the information.

Error logs on OS/390

If you are not using CICS, error messages are written to:
v The OS/390 system console
v The channel-initiator job log

If you are using the OS/390 message processing facility to suppress messages, the
console messages may be suppressed. See the MQSeries for OS/390 System
Management Guide for more information.

If you are using CICS, error messages are written to the OS/390 system console or
the CKMQ extrapartition transient data queue. See the MQSeries for OS/390 System
Management Guide for more information.

Error logs on MQSeries for Windows

Error logs are written to a file called channel.log in the directory of the running
queue manager. You can view the log using the Channel Logs sub-tab of the
Services tab of the MQSeries for Windows properties dialog.

Error logs on MQSeries for VSE/ESA

| All MQSeries-generated error messages are written to SYSTEM.LOG.

| Error logs on MQSeries for Tandem NSK

| For information about this, see “Queue manager configuration file” on page 74.

Chapter 38. Problem determination in DQM 619

Further intercommunication considerations

620 MQSeries Intercommunication

Part 8. Appendixes

© Copyright IBM Corp. 1993, 2000 621

622 MQSeries Intercommunication
Appendix A. Channel planning form
The form shown in Table 52 on page 625 is supplied for you to create and maintain
a list of all message channels for each queue manager in your system. Do not fill
in the form in this book. Instead, photocopy it as many times as required to hold
the definitions of all the channels in your system. The filled-in form, see Table 53
on page 626, is included to illustrate how the two examples in “Chapter 28.
Message channel planning example for OS/390 using CICS” on page 387 and
“Chapter 34. Message channel planning example for OS/400” on page 477 could be
shown.

How to use the form

The channel planning form allows you to keep an overview of the channels and
associated objects in your system. It will help to prevent you from making errors
when changing your channel configuration.

One of the more obvious errors is to allocate items more than once:
Communications connections identifiers
Allocate only once. It may be possible to share connections between
channels when using LU 6.2.
Channel names
Allocate only once.
Transmission queues
Allocate to only one channel. It is possible to allocate to more than one
channel for standby purposes, but ensure that only one is active, unless the
host environment is MQSeries for OS/390, and there is no sequential
delivery of messages selected.
Remote queue definition
The name must be unique.
Queue manager alias name
The name must be unique.
Reply-to queue name
The name must be unique.
Reply-to queue alias name
The name must be unique.
Adjacent channel system name
The name must be unique.

© Copyright IBM Corp. 1993, 2000 623

Channel planning form
One method of completing the form would be to allocate, systematically, in this
order:
v Channels to adjacent systems
v Transmission queues to channels
v Remote queue definitions to queue names and queue manager names, and to
transmission queues
v Reply-to queue aliases to reply-to queue names and route names
v Queue manager aliases to remote queue managers and transmission queues

Proceed as follows:
1. Start with one adjacent system, define the first outward channel to that
system, and give it a name.
2. Fill in the channel name on the form with the channel type, transmission
queue name, adjacent system name, and remote queue manager name.
3. For each class-of-service, logically-named connection, fill in the logical queue
manager name to list the queue manager name resolutions using this channel.
4. Allocate a communication connection and fill in the name and profile, where
applicable.
5. Record the names of all the queues that your applications are going to use on
this channel, using the columns provided on the form. This is necessary where
remote queue definitions are used, so that the name resolutions are listed.
6. Do not forget to include the reply-to alias queue names in this list.
7. Move to the next channel and continue until all outward channels have been
completed for this adjacent system.
8. When this has been completed, repeat from the beginning for incoming
channels from this adjacent system.
9. Move on to the next adjacent system, and repeat.
10. Check the complete list for unwanted multiple assignments of names, objects
and connections.

When the list is complete and checked out, use it as an aid in creating the objects,
and defining the channels listed.

624 MQSeries Intercommunication

 Table 52. Channel planning form. System name: Queue manager name: Page no:
Channel name Channel CICS system Transmission Connection Profile, Adjacent system Logical queue Logical queue Physical queue Physical queue
type ID (where queue name name or mode, name manager name name manager name name
needed) name
Appendix A. Channel planning form

Channel planning form

625
626

Channel planning form

Table 53. Channel planning form. System name: QM2 Queue manager name: QM2 Page no: 1
Channel name Channel type CICS system Transmission Connection name Profile, Adjacent Logical queue Logical queue Physical queue Physical queue
ID (where queue name or mode, system name manager name name manager name name
MQSeries Intercommunication

needed) name
QM1.T.QM2. SENDER (default) QM2 QM2C (none) QM2 QM2 Payrollr QM2 Payroll
CHANNEL

QM1.to.QM2 SENDER (none) QM2 QM2D (none) QM2 QM2 Payroll QM2 Payroll

QM2.to.QM1 RECEIVER (none) (none) (none) (none) QM2 (none) (none) (none) (none)
Appendix B. Constants for channels and exits
This appendix specifies the values of the named constants that apply to channels
and exits in the Message Queue Interface.

The constants are grouped according to the parameter or field to which they relate.
All of the names of the constants in a group begin with a common prefix of the
form “MQxxxx_”, where xxxx represents a string of 0 through 4 characters that
indicates the parameter or field to which the values relate. The constants are
ordered alphabetically by this prefix.
Notes:
1. For constants with numeric values, the values are shown in both decimal and
hexadecimal forms.
2. Hexadecimal values are represented using the notation X'hhhh', where each “h”
denotes a single hexadecimal digit.
3. Character values are shown delimited by single quotation marks; the quotation
marks are not part of the value.
4. Blanks in character values are represented by one or more occurrences of the
symbol “b”.
5. If the value is shown as “(variable)”, it indicates that the value of the constant
depends on the environment in which the application is running.

List of constants
The following sections list all of the named constants mentioned in this book, and
show their values.

MQ_* (Lengths of character string and byte fields)

MQ_CHANNEL_DESC_LENGTH 64 X'00000040'
MQ_CHANNEL_NAME_LENGTH 20 X'00000014'
MQ_CONN_NAME_LENGTH 264 X'00000108'
MQ_EXIT_DATA_LENGTH 32 X'00000020'
MQ_EXIT_NAME_LENGTH (variable)
MQ_EXIT_USER_AREA_LENGTH 16 X'00000010'
MQ_MAX_EXIT_NAME_LENGTH 128 X'00000080'
MQ_MAX_MCA_USER_ID_LENGTH 64 X'00000040'
MQ_MCA_NAME_LENGTH 20 X'00000014'
MQ_MCA_USER_ID_LENGTH (variable)
MQ_MODE_NAME_LENGTH 8 X'00000008'
MQ_PASSWORD_LENGTH 12 X'0000000C'
MQ_Q_MGR_NAME_LENGTH 48 X'00000030'
MQ_Q_NAME_LENGTH 48 X'00000030'
MQ_SHORT_CONN_NAME_LENGTH 20 X'00000014'
MQ_TOTAL_EXIT_DATA_LENGTH 999 X'000003E7'
MQ_TOTAL_EXIT_NAME_LENGTH 999 X'000003E7'
MQ_TP_NAME_LENGTH 64 X'00000040'
MQ_USER_ID_LENGTH 12 X'0000000C'

© Copyright IBM Corp. 1993, 2000 627

Constants
MQCD_* (Channel definition structure length)
See the StrucLength field described in “MQCD - Channel data structure” on
page 556.

MQCD_LENGTH_4 (variable)
MQCD_LENGTH_5 (variable)
MQCD_LENGTH_6 (variable)
MQCD_CURRENT_LENGTH (variable)

MQCD_* (Channel definition structure version)

See the Version field described in “MQCD - Channel data structure” on page 556.

MQCD_VERSION_1 1 X'00000001'
MQCD_VERSION_2 2 X'00000002'
MQCD_VERSION_3 3 X'00000003'
MQCD_VERSION_4 4 X'00000004'
MQCD_VERSION_5 5 X'00000005'
MQCD_VERSION_6 6 X'00000006'
MQCD_CURRENT_VERSION (variable)

MQCDC_* (Channel data conversion)

See the DataConversion field described in “MQCD - Channel data structure” on
page 556.

MQCDC_NO_SENDER_CONVERSION 0 X'00000000'
MQCDC_SENDER_CONVERSION 1 X'00000001'

MQCF_* (Channel capability flags)

See the CapabilityFlags field described in “MQCXP - Channel exit parameter
structure” on page 591.

MQCF_NONE 0 X'00000000'
MQCF_DIST_LISTS 1 X'00000001'

MQCHT_* (Channel type)

See the ChannelType field described in “MQCD - Channel data structure” on
page 556.

MQCHT_SENDER 1 X'00000001'
MQCHT_SERVER 2 X'00000002'
MQCHT_RECEIVER 3 X'00000003'
MQCHT_REQUESTER 4 X'00000004'
MQCHT_CLNTCONN 6 X'00000006'
MQCHT_SVRCONN 7 X'00000007'
MQCHT_CLUSRCVR 8 X'00000008'
MQCHT_CLUSSDR 9 X'00000009'

MQCXP_* (Channel-exit parameter structure identifier)

See the StrucId field described in “MQCXP - Channel exit parameter structure” on
page 591.

628 MQSeries Intercommunication

 Constants
MQCXP_STRUC_ID 'CXPb'

For the C programming language, the following array version is also defined:

MQCXP_STRUC_ID_ARRAY 'C','X','P','b'

MQCXP_* (Channel-exit parameter structure version)

See the Version field described in “MQCXP - Channel exit parameter structure” on
page 591.

MQCXP_VERSION_1 1 X'00000001'
MQCXP_VERSION_2 2 X'00000002'
MQCXP_VERSION_3 3 X'00000003'
MQCXP_VERSION_4 4 X'00000004'
MQCXP_CURRENT_VERSION (variable)

MQMCAT_* (MCA type)

See the MCAType field described in “MQCD - Channel data structure” on page 556.

MQMCAT_PROCESS 1 X'00000001'
MQMCAT_THREAD 2 X'00000002'

MQNPMS_* (Nonpersistent message speed)

See the NonPersistentMsgSpeed field described in “MQCD - Channel data
structure” on page 556.

MQNPMS_NORMAL 1 X'00000001'
MQNPMS_FAST 2 X'00000002'

MQPA_* (Put authority)

See the PutAuthority field described in “MQCD - Channel data structure” on
page 556.

MQPA_DEFAULT 1 X'00000001'
MQPA_CONTEXT 2 X'00000002'

MQSID_* (Security identifier)

See the MCASecurityId and RemoteSecurityId fields described in “MQCD - Channel
data structure” on page 556.

MQSID_NONE X'00...00' (40 nulls)

For the C programming language, the following array version is also defined:

MQSID_NONE_ARRAY '\0','\0',...'\0','\0'

Appendix B. Constants for channels and exits 629

Constants
MQSIDT_* (Security identifier type)
See the MCASecurityId and RemoteSecurityId fields described in “MQCD - Channel
data structure” on page 556.

MQSIDT_NONE X'00'
MQSIDT_NT_SECURITY_ID X'01'

MQTXP_* (Transport retry exit structure identifier)

See the StrucId field described in “MQTXP - Transport-exit data structure” on
page 605.

MQTXP_STRUC_ID 'TXPb'

For the C programming language, the following array version is also defined:

MQTXP_STRUC_ID_ARRAY 'T','X','P','b'

MQTXP_* (Transport retry exit version)

See the Version field described in “MQTXP - Transport-exit data structure” on
page 605.

MQTXP_VERSION_1 1 X'00000001'
MQTXP_CURRENT_VERSION 1 X'00000001'

MQXCC_* (Exit response)

See the ExitResponse field described in “MQCXP - Channel exit parameter
structure” on page 591.

MQXPT_* (Transmission protocol type)

See the TransportType field described in “MQCD - Channel data structure” on
page 556.

MQXR_* (Exit reason)

See the ExitReason field described in “MQCXP - Channel exit parameter structure”
on page 591.

MQXR2_* (Secondary exit response)

See the ExitResponse2 field described in “MQCXP - Channel exit parameter
structure” on page 591.

MQXR2_PUT_WITH_DEF_ACTION 0 X'00000000'
MQXR2_USE_AGENT_BUFFER 0 X'00000000'
MQXR2_DEFAULT_CONTINUATION 0 X'00000000'
MQXR2_PUT_WITH_DEF_USERID 1 X'00000001'
MQXR2_PUT_WITH_MSG_USERID 2 X'00000002'
MQXR2_USE_EXIT_BUFFER 4 X'00000004'
MQXR2_CONTINUE_CHAIN 8 X'00000008'
MQXR2_SUPPRESS_CHAIN 16 X'00000010'

630 MQSeries Intercommunication

 Constants
MQXT_* (Exit identifier)
See the ExitId field described in “MQCXP - Channel exit parameter structure” on
page 591.

MQXUA_* (Exit user area)

See the ExitUserArea field described in “MQCXP - Channel exit parameter
structure” on page 591.

MQXUA_NONE X'00...00' (16 nulls)

For the C programming language, the following array version is also defined:

MQXUA_NONE_ARRAY '\0','\0',...'\0','\0'

| MQXWD_* (Exit wait descriptor structure identifier)

| See the StrucId field described in “MQXWD - Exit wait descriptor structure” on
| page 609.
|| MQXWD_STRUC_ID 'XWDb'
|

| For the C programming language, the following array version is also defined:
|| MQXWD_STRUC_ID_ARRAY 'X','W','D','b'
|

| MQXWD_* (Exit wait descriptor version)

| See the Version field described in “MQXWD - Exit wait descriptor structure” on
| page 609.
|| MQXWD_VERSION_1 1 X'00000001'
|

Appendix B. Constants for channels and exits 631

Constants

632 MQSeries Intercommunication

|

Appendix C. Queue name resolution

This appendix describes queue name resolution as performed by queue managers
at both sending and receiving ends of a channel.

In larger networks, the use of queue managers has a number of advantages over
other forms of communication. These advantages derive from the name resolution
function in DQM and the main benefits are:
v Applications do not need to make routing decisions
v Applications do not need to know the network structure
v Network links are created by systems administrators
v Network structure is controlled by network planners
v Multiple channels can be used between nodes to partition traffic

Machine A Machine B

Application Application

Putting Getting
application application

MQPUT call MQGET call

Queue Manager Queue Manager

Channel
Queue name Queue name
resolution resolution
process process
MCA MCA

MQGET MQPUT
call call
Queue transmission Sending Network Receiving Queue 'Target'

File Channel definition File Channel definition

Figure 144. Name resolution

Referring to Figure 144, the basic mechanism for putting messages on a remote
queue, as far as the application is concerned, is the same as for putting messages
on a local queue:
v The application putting the message issues MQOPEN and MQPUT calls to put
messages on the target queue.
v The application getting the messages issues MQOPEN and MQGET calls to get
the messages from the target queue.

© Copyright IBM Corp. 1993, 2000 633

Queue name resolution
If both applications are connected to the same queue manager then no inter-queue
manager communication is required, and the target queue is described as local to
both applications.

However, if the applications are connected to different queue managers, two MCAs
and their associated network connection are involved in the transfer, as shown in
the figure. In this case, the target queue is considered to be a remote queue to the
putting application.

The sequence of events is as follows:

1. The putting application issues MQOPEN and MQPUT calls to put messages to
the target queue.
2. During the MQOPEN call, the name resolution function detects that the target
queue is not local, and decides which transmission queue is appropriate.
Thereafter, on the MQPUT calls associated with the MQOPEN call, all messages
are placed on this transmission queue.
3. The sending MCA gets the messages from the transmission queue and passes
them to the receiving MCA at the remote computer.
4. The receiving MCA puts the messages on the target queue, or queues.
5. The getting application issues MQOPEN and MQGET calls to get the messages
from the target queue.

Note: Only step 1 and step 5 involve application code; steps 2 through 4 are
performed by the local queue managers and the MCA programs. The
putting application is unaware of the location of the target queue, which
could be in the same processor, or in another processor on another
continent.

The combination of sending MCA, the network connection, and the receiving
MCA, is called a message channel, and is inherently a unidirectional device.
Normally, it is necessary to move messages in both directions, and two channels
are set up for this, one in each direction.

634 MQSeries Intercommunication

 Queue name resolution

What is queue name resolution?

Queue name resolution is vital to DQM. It removes the need for applications to be
concerned with the physical location of queues, and insulates them against the
details of networks. A systems administrator can move queues from one queue
manager to another, and change the routing between queue managers without
applications needing to know anything about it.

In order to uncouple from the application design the exact path over which the
data travels, it is necessary to introduce a level of indirection between the name
used by the application when it refers to the target queue, and the naming of the
channel over which the flow occurs. This indirection is achieved using the queue
name resolution mechanism.

In essence, when an application refers to a queue name, the name is mapped by

the resolution mechanism either to a transmission queue or to a local queue that is
not a transmission queue. In the case of mapping to a transmission queue, a
second name resolution is needed at the destination, and the received message is
placed on the target queue as intended by the application designer. The application
remains unaware of the transmission queue and channel used for moving the
message.

Note: The definition of the queue and channel is a system management

responsibility and can be changed by an operator or a system management
utility, without the need to change applications.

An important requirement for the system management of message flows is that

alternative paths should be provided between queue managers. For example,
business requirements might dictate that different classes of service should be sent
over different channels to the same destination. This is a system management
decision and the queue name resolution mechanism provides a very flexible way
to achieve it. The next section describes in detail how this is done, but the basic
idea is to use queue name resolution at the sending queue manager to map the
queue name supplied by the application to the appropriate transmission queue for
the type of traffic involved. Similarly at the receiving end, queue name resolution
maps the name in the message descriptor to a local (not a transmission) queue or
again to an appropriate transmission queue.

Not only is it possible for the forward path from one queue manager to another to
be partitioned into different types of traffic, but the return message that is sent to
the reply-to queue definition in the outbound message can also use the same traffic
partitioning. Queue name resolution satisfies this requirement and the application
designer need not be involved in these traffic partitioning decisions.

The point that the mapping is carried out at both the sending and receiving queue
managers is an important aspect of the way name resolution works. This allows
the queue name supplied by the putting application to be mapped to a local queue
or a transmission queue at the sending queue manager, and again remapped to a
local queue or a transmission queue at the receiving queue manager.

Reply messages from receiving applications or MCAs have the name resolution
carried out in exactly the same way, allowing return routing over specific paths by
means of queue definitions at all the queue managers on route.

Appendix C. Queue name resolution 635

 Queue name resolution
How queue name resolution works
| The MQSeries Application Programming Guide provides the rules for queue name
| resolution.

636 MQSeries Intercommunication

 Appendix D. Configuration file stanzas for distributed queuing
This appendix shows the stanzas in the queue manager configuration file that
relate to distributed queuing. It applies to:
v The queue manager configuration file for MQSeries for OS/2 Warp, called
qm.ini
v The queue manager configuration file for MQSeries on UNIX systems, called
qm.ini
| v The queue manager initialization file for MQSeries for AS/400, called qm.ini, in
| /QIBM/UserData/mqm/qmgrs/QMNAME/
Notes:
1. The stanzas in the QMINI file for Tandem NSK are different and are described
in the MQSeries for Tandem NonStop Kernel System Management Guide.
2. MQSeries for Windows NT, V5.1 uses the registry. Use the MQSeries Services
snap-in within the Microsoft Management Console (MMC) to make equivalent
changes to the configuration information.

The stanzas that relate to distributed queuing are:

v CHANNELS
v TCP
v LU62
v NETBIOS
v SPX
v EXITPATH

Figure 145 on page 638 shows the values that you can set using these stanzas.
When you are defining one of these stanzas, you do not need to start each item on
a new line. You can use either a semicolon (;) or a hash character (#) to indicate a
comment.

© Copyright IBM Corp. 1993, 2000 637

 Configuration file stanzas
CHANNELS:
MAXCHANNELS=n ; Maximum number of channels allowed, the
; default value is 100
MAXACTIVECHANNELS=n ; Maximum number of channels allowed to be active at
; any time, the default is the value of MaxChannels
MAXINITIATORS=n ; Maximum number of initiators allowed, the
; default value is 3 (see note 1)
MQIBINDTYPE=type ; Whether the binding for applications is to be
; “fastpath” or “standard”.
;The default is “standard”. (see note 2)
ADOPTNEWMCA=chltype ; Stops previous process if channel fails to start.
; The default is “NO”.
ADOPTNEWMCATIMEOUT=n ; Specifies the amount of time that the new
; process should wait for the old process to end.
; The default is 60.
ADOPTNEWMCACHECK= ; Specifies the type checking required.
typecheck ; For FAP1, FAP2, and FAP3, “NAME” and
; “ADDRESS” is the default.
; For FAP4 and later, “NAME”,
; “ADDRESS”, and “QM” is the
; default.
TCP: ; TCP entries
PORT=n ; Port number, the default is 1414
LIBRARY1=DLLName1 ; Name of TCP Sockets DLL (OS/2 only)
LIBRARY2=DLLName2 ; Same as above if code is in two libraries (OS/2 only)
KEEPALIVE=Yes ; Switch TCP/IP KeepAlive on

LU62: ; LU 6.2 entries (OS/2 only)

TPNAME=name ; TP Name to start on remote side
LIBRARY1=DLLName1 ; Name of APPC DLL (see note 3)
LIBRARY2=DLLName2 ; Same as above if code is in two libraries (see note 3)
LOCALLU=name ; LU to use on local system (OS/2 only)

NETBIOS: ; NetBIOS entries (OS/2 only)

LOCALNAME=name ; The name this machine will be known as on the LAN
ADAPTERNUM=n ; LAN adapter number, the default is adapter 0
NUMSESS=n ; Number of sessions to allocate, the default is 1
NUMCMDS=n ; Number of commands to allocate, the default is 1
NUMNAMES=n ; Number of names to allocate, the default is 1
LIBRARY1=DLLName1 ; Name of NetBIOS DLL
LIBRARY2=DLLName2 ; Same as above if code is in two libraries (OS/2 only)

SPX: ; SPX entries (OS/2 only)

SOCKET=n ; The socket number, the default is 5E86
BOARDNUM=0 ; LAN adapter number, the default is adapter 0 (OS/2 only)
KEEPALIVE=Yes ; Switch on “watchdog” to monitor sessions (OS/2 only)
LIBRARY1=DLLName1 ; Name of SPX DLL
LIBRARY2=DLLName2 ; Same as above if code is in two libraries (OS/2 only)

EXITPATH: ; Location of user exits (MQSeries for AIX,

; HP-UX, OS/2 Warp, and Sun Solaris only)
EXITPATHS= ; String of directory paths

QUEUEMANAGERSTARTUP:
CHINIT=Yes ; Start the CHINIT"

Figure 145. qm.ini stanzas for distributed queuing

| Notes:
| 1. MAXINITIATORS applies only to MQSeries for AIX, MQSeries for AS/400,
| MQSeries for HP-UX, MQSeries for OS/2 Warp, and MQSeries for Sun Solaris.

638 MQSeries Intercommunication

 Configuration file stanzas
| 2. MQIBINDTYPE applies only to MQSeries for AIX, MQSeries for AS/400,
| MQSeries for HP-UX, MQSeries for OS/2 Warp, and MQSeries for Sun Solaris.
| 3. The default values for LIBRARY1 and LIBRARY2 are as follows:
| TCP SO32DLL and TCP32DLL (OS/2)
| LU 6.2 APPC and ACSSVC (OS/2)
| NetBIOS
| ACSNETB (OS/2)
| SPX IPXCALLS.DLL and SPXCALLS.DLL (OS/2)

| For more information about the qm.ini file and the other stanzas in it, refer to the
| MQSeries System Administration book for V5.1 of MQSeries for AIX, HP-UX, OS/2
| Warp, Sun Solaris, and Windows NT, and to the MQSeries for AS/400 V5.1 System
| Administration book for MQSeries for AS/400.

Appendix D. Configuration file stanzas for distributed queuing 639

Further intercommunication considerations

640 MQSeries Intercommunication

Appendix E. Notices
This information was developed for products and services offered in the United
States. IBM may not offer the products, services, or features discussed in this
information in other countries. Consult your local IBM representative for
information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply
that only that IBM product, program, or service may be used. Any functionally
equivalent product, program, or service that does not infringe any IBM intellectual
property right may be used instead. However, it is the user’s responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this information. The furnishing of this information does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore this statement may not apply
to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the information. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
information at any time without notice.

Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

© Copyright IBM Corp. 1993, 2000 641

 Notices
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM United Kingdom Laboratories,
Mail Point 151,
Hursley Park,
Winchester,
Hampshire,
England
SO21 2JN.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Programming License Agreement, or any equivalent agreement
between us.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM for the purposes of developing, using, marketing, or distributing application
programs conforming to IBM’s application programming interfaces.

Programming interface information

This book is intended to help you set up and control message channels between
queue managers.

This book also documents General-use Programming Interface and Associated

Guidance Information and Product-sensitive Programming Interface and
Associated Guidance Information provided by:
MQSeries for AIX, V5.1,
| MQSeries for AS/400 V5.1,
MQSeries for AT&T GIS UNIX V2.2,
MQSeries for Compaq (DIGITAL) OpenVMS, V2.2.1.1,
| MQSeries for DIGITAL UNIX (Compaq Tru64 UNIX), V2.2.1
MQSeries for HP-UX, V5.1,
MQSeries for OS/390, V2.1,

642 MQSeries Intercommunication

 Notices
MQSeries for OS/2 Warp, V5.1,
MQSeries for SINIX and DC/OSx, V2.2,
MQSeries for Sun Solaris, V5.1,
| MQSeries for Tandem NonStop Kernel, V2.2,
MQSeries for VSE/ESA V2.1,
MQSeries for Windows V2.0,
MQSeries for Windows V2.1,
MQSeries for Tandem NonStop Kernel, V2.2.0.1.

General-use programming interfaces allow the customer to write programs that

obtain the services of these products.

General-use Programming Interface and Associated Guidance Information is

identified where it occurs, by an introductory statement to a chapter or section.

Product-sensitive programming interfaces allow the customer installation to

perform tasks such as diagnosing, modifying, monitoring, repairing, tailoring, or
tuning of these products. Use of such interfaces creates dependencies on the
detailed design or implementation of the IBM software product. Product-sensitive
programming interfaces should be used only for these specialized purposes.
Because of their dependencies on detailed design and implementation, it is to be
expected that programs written to such interfaces may need to be changed in order
to run with new product releases or versions, or as a result of service.

Product-sensitive Programming Interface and Associated Guidance Information is

identified where it occurs, by an introductory statement to a chapter or section.

Trademarks
The following terms are trademarks of International Business Machines
Corporation in the United States, or other countries, or both:

Advanced Peer-to-Peer ACF/VTAM AIX

Networking
APPN AS/400 BookManager
CICS CICS/ESA CICS/VSE
CICS/400 C/400 FFST
First Failure Support IBM IMS
Technology
Integrated Language MQSeries MVS/ESA
Environment
OpenEdition OS/2 OS/390
OS/400 RACF RS/6000
System/390 S/390 VSE/ESA
VTAM

Lotus and LotusScript are trademarks of Lotus Development Corporation in the

United States, or other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and/or other countries.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States and/or other countries.

Appendix E. Notices 643

Notices
UNIX is a registered trademark in the United States and/or other countries
licensed exclusively through X/Open Company Limited.

Other company, product, and service names may be trademarks or service marks
of others.

644 MQSeries Intercommunication

Glossary of terms and abbreviations
This glossary defines MQSeries terms and queue manager. When an application or a queue
abbreviations used in this book. If you do not manager uses an alias queue, the alias name is resolved
find the term you are looking for, see the Index or and the requested operation is performed on the
the IBM Dictionary of Computing, New York: associated base queue.
McGraw-Hill, 1994. allied address space. See ally.

This glossary includes terms and definitions from ally. An OS/390 address space that is connected to
the American National Dictionary for Information MQSeries for OS/390.
Systems, ANSI X3.172-1990, copyright 1990 by the
alternate user security. A security feature in which the
American National Standards Institute (ANSI).
authority of one user ID can be used by another user
Copies may be purchased from the American
ID; for example, to open an MQSeries object.
National Standards Institute, 11 West 42 Street,
New York, New York 10036. Definitions are APAR. Authorized program analysis report.
identified by the symbol (A) after the definition.
APC. Advanced Program Communication.

A APPC. Advanced Program-to-Program

Communication.
abend reason code. A 4-byte hexadecimal code that
uniquely identifies a problem with MQSeries for application environment. The software facilities that
OS/390. A complete list of MQSeries for OS/390 abend are accessible by an application program. On the
reason codes and their explanations is contained in the OS/390 platform, CICS and IMS are examples of
MQSeries for OS/390 Messages and Codes manual. application environments.

active log. See recovery log. application log. In Windows NT, a log that records
significant application events.
adapter. An interface between MQSeries for OS/390
and TSO, IMS™, CICS, or batch address spaces. An application queue. A queue used by an application.
adapter is an attachment facility that enables
applications to access MQSeries services. archive log. See recovery log.

address space. The area of virtual storage available for ARM. Automatic Restart Management
a particular job.
ASID. Address space identifier.
address space identifier (ASID). A unique,
asynchronous messaging. A method of
system-assigned identifier for an address space.
communication between programs in which programs
administrator commands. MQSeries commands used place messages on message queues. With asynchronous
to manage MQSeries objects, such as queues, processes, messaging, the sending program proceeds with its own
and namelists. processing without waiting for a reply to its message.
Contrast with synchronous messaging.
Advanced Program-to-Program Communication
(APPC). The general facility characterizing the LU 6.2 attribute. One of a set of properties that defines the
architecture and its various implementations in characteristics of an MQSeries object.
products.
authorization checks. Security checks that are
alert. A message sent to a management services focal performed when a user tries to issue administration
point in a network to identify a problem or an commands against an object, for example to open a
impending problem. queue or connect to a queue manager.

alert monitor. In MQSeries for OS/390, a component authorization file. In MQSeries on UNIX systems, a
of the CICS adapter that handles unscheduled events file that provides security definitions for an object, a
occurring as a result of connection requests to class of objects, or all classes of objects.
MQSeries for OS/390.
authorization service. In MQSeries on UNIX systems,
alias queue object. An MQSeries object, the name of MQSeries for OS/2 Warp, and MQSeries for Windows
which is an alias for a base queue defined to the local NT, a service that provides authority checking of

© Copyright IBM Corp. 1993, 2000 645

commands and MQI calls for the user identifier channel. See message channel.
associated with the command or call.
channel control function (CCF). In MQSeries, a
authorized program analysis report (APAR). A report program to move messages from a transmission queue
of a problem caused by a suspected defect in a current, to a communication link, and from a communication
unaltered release of a program. link to a local queue, together with an operator panel
interface to allow the setup and control of channels.
Automatic Restart Management (ARM). An OS/390
recovery function that can improve the availability of channel definition file (CDF). In MQSeries, a file
specific batch jobs or started tasks, and therefore result containing communication channel definitions that
in faster resumption of productive work. associate transmission queues with communication
links.
B channel event. An event indicating that a channel
instance has become available or unavailable. Channel
backout. An operation that reverses all the changes events are generated on the queue managers at both
made during the current unit of recovery or unit of ends of the channel.
work. After the operation is complete, a new unit of
recovery or unit of work begins. Contrast with commit. channel exit program. A user-written program that
can be entered from one of a defined number of places
basic mapping support (BMS). An interface between during channel operation.
CICS and application programs that formats input and
output display data and routes multiple-page output channel initiator. A component of MQSeries
messages without regard for control characters used by distributed queuing, which monitors the initiation
various terminals. queue to see when triggering criteria have been met
and then starts the sender channel.
BMS. Basic mapping support.
channel listener. A component of MQSeries
bootstrap data set (BSDS). A VSAM data set that distributed queuing, which monitors the network for a
contains: startup request and then starts the receiving channel.
v An inventory of all active and archived log data sets
known to MQSeries for OS/390 checkpoint. A time when significant information is
written on the log. Contrast with syncpoint. In
v A wrap-around inventory of all recent MQSeries for
MQSeries on UNIX systems, the point in time when a
OS/390 activity
data record described in the log is the same as the data
record in the queue. Checkpoints are generated
The BSDS is required if the MQSeries for OS/390
automatically and are used during the system restart
subsystem has to be restarted.
process.
browse. In message queuing, to use the MQGET call
CI. Control interval.
to copy a message without removing it from the queue.
See also get. circular logging. In MQSeries on UNIX systems,
MQSeries for OS/2 Warp, and MQSeries for Windows
browse cursor. In message queuing, an indicator used
NT, the process of keeping all restart data in a ring of
when browsing a queue to identify the message that is
log files. Logging fills the first file in the ring and then
next in sequence.
moves on to the next, until all the files are full. At this
BSDS. Bootstrap data set. point, logging goes back to the first file in the ring and
starts again, if the space has been freed or is no longer
buffer pool. An area of main storage used for needed. Circular logging is used during restart
MQSeries for OS/390 queues, messages, and object recovery, using the log to roll back transactions that
definitions. See also page set. were in progress when the system stopped. Contrast
with linear logging.

C CL. Control Language.

call back. In MQSeries, a requester message channel client. A run-time component that provides access to
initiates a transfer from a sender channel by first calling queuing services on a server for local user applications.
the sender, then closing down and awaiting a call back. The queues used by the applications reside on the
server. See also MQSeries client.
CCF. Channel control function.
client application. An application, running on a
CCSID. Coded character set identifier. workstation and linked to a client, that gives the
application access to queuing services on a server.
CDF. Channel definition file.

646 MQSeries Intercommunication

client connection channel type. The type of MQI NT, a file that contains configuration information
channel definition associated with an MQSeries client. related to, for example, logs, communications, or
See also server connection channel type. installable services. Synonymous with .ini file. See also
stanza.
CLUSRCVR. Cluster-receiver channel definition.
connect. To provide a queue manager connection
CLUSSDR. Cluster-sender channel definition. handle, which an application uses on subsequent MQI
calls. The connection is made either by the MQCONN
cluster. A network of queue managers that are call, or automatically by the MQOPEN call.
logically associated in some way.
connection handle. The identifier or token by which a
cluster-receiver channel (CLUSRCVR). A channel on program accesses the queue manager to which it is
which a cluster queue manager can receive messages connected.
from other queue managers in the cluster and cluster
information from the repository queue managers. context. Information about the origin of a message.

cluster-sender channel (CLUSSDR). A channel on context security. In MQSeries, a method of allowing

which a cluster queue manager can send messages to security to be handled such that messages are obliged
other queue managers in the cluster and cluster to carry details of their origins in the message
information to the repository queue managers. descriptor.

cluster transmission queue. A transmission queue control command. In MQSeries on UNIX systems,
that transmits all messages from a queue manager to MQSeries for OS/2 Warp, and MQSeries for Windows
any other queue manager that is in the same cluster. NT, a command that can be entered interactively from
The queue is called the operating system command line. Such a command
SYSTEM.CLUSTER.TRANSMIT.QUEUE. requires only that the MQSeries product be installed; it
does not require a special utility or program to run it.
coded character set identifier (CCSID). The name of a
coded set of characters and their code point control interval (CI). A fixed-length area of direct
assignments. access storage in which VSAM stores records and
creates distributed free spaces. The control interval is
command. In MQSeries, an administration instruction the unit of information that VSAM transmits to or from
that can be carried out by the queue manager. direct access storage.
command prefix (CPF). In MQSeries for OS/390, a Control Language (CL). In MQSeries for AS/400, a
character string that identifies the queue manager to language that can be used to issue commands, either at
which MQSeries for OS/390 commands are directed, the command line or by writing a CL program.
and from which MQSeries for OS/390 operator
messages are received. controlled shutdown. See quiesced shutdown.

command processor. The MQSeries component that CPF. Command prefix.

processes commands.
CRE. Common Run-Time Environment.
command server. The MQSeries component that reads
commands from the system-command input queue,
verifies them, and passes valid commands to the D
command processor.
DAE. Dump analysis and elimination.
commit. An operation that applies all the changes
made during the current unit of recovery or unit of daemon. In UNIX systems, a program that runs
work. After the operation is complete, a new unit of unattended to perform a standard service. Some
recovery or unit of work begins. Contrast with backout. daemons are triggered automatically to perform their
tasks; others operate periodically.
Common Run-Time Environment (CRE). A set of
services that enable system and application data conversion interface (DCI). The MQSeries
programmers to write mixed-language programs. These interface to which customer- or vendor-written
shared, run-time services can be used by C, COBOL85, programs that convert application data between
FORTRAN, Pascal, and TAL programs. different machine encodings and CCSIDs must
conform. A part of the MQSeries Framework.
completion code. A return code indicating how an
MQI call has ended. datagram. The simplest message that MQSeries
supports. This type of message does not require a reply.
configuration file. In MQSeries on UNIX systems,
MQSeries for OS/2 Warp, and MQSeries for Windows DCE. Distributed Computing Environment.

Glossary of terms and abbreviations 647

DCE principal. A user ID that uses the distributed
computing environment.
E
DCI. Data conversion interface. environment. See application environment.

dead-letter queue (DLQ). A queue to which a queue ESM. External security manager.
manager or application sends messages that it cannot
ESTAE. Extended specify task abnormal exit.
deliver to their correct destination.
event. See channel event, instrumentation event,
dead-letter queue handler. An MQSeries-supplied
performance event, and queue manager event.
utility that monitors a dead-letter queue (DLQ) and
processes messages on the queue in accordance with a event data. In an event message, the part of the
user-written rules table. message data that contains information about the event
(such as the queue manager name, and the application
default object. A definition of an object (for example,
that gave rise to the event). See also event header.
a queue) with all attributes defined. If a user defines an
object but does not specify all possible attributes for event header. In an event message, the part of the
that object, the queue manager uses default attributes message data that identifies the event type of the
in place of any that were not specified. reason code for the event.
deferred connection. A pending event that is activated event log. See application log.
when a CICS subsystem tries to connect to MQSeries
for OS/390 before MQSeries for OS/390 has been event message. Contains information (such as the
started. category of event, the name of the application that
caused the event, and queue manager statistics) relating
distributed application. In message queuing, a set of to the origin of an instrumentation event in a network
application programs that can each be connected to a of MQSeries systems.
different queue manager, but that collectively constitute
a single application. event queue. The queue onto which the queue
manager puts an event message after it detects an
Distributed Computing Environment (DCE). event. Each category of event (queue manager,
Middleware that provides some basic services, making performance, or channel event) has its own event
the development of distributed applications easier. DCE queue.
is defined by the Open Software Foundation (OSF).
Event Viewer. A tool provided by Windows NT to
distributed queue management (DQM). In message examine and manage log files.
queuing, the setup and control of message channels to
queue managers on other systems. extended specify task abnormal exit (ESTAE). An
OS/390 macro that provides recovery capability and
DLQ. Dead-letter queue. gives control to the specified exit routine for
processing, diagnosing an abend, or specifying a retry
DQM. Distributed queue management.
address.
dual logging. A method of recording MQSeries for
external security manager (ESM). A security product
OS/390 activity, where each change is recorded on two
that is invoked by the OS/390 System Authorization
data sets, so that if a restart is necessary and one data
Facility. RACF is an example of an ESM.
set is unreadable, the other can be used. Contrast with
single logging.
F
dual mode. See dual logging.
FAP. Formats and Protocols.
dump analysis and elimination (DAE). An OS/390
service that enables an installation to suppress SVC FFST™. First Failure Support Technology™.
dumps and ABEND SYSUDUMP dumps that are not
needed because they duplicate previously written FIFO. First-in-first-out.
dumps.
First Failure Support Technology (FFST). Used by
dynamic queue. A local queue created when a MQSeries on UNIX systems, MQSeries for OS/2 Warp,
program opens a model queue object. See also MQSeries for Windows NT, and MQSeries for AS/400
permanent dynamic queue and temporary dynamic queue. to detect and report software problems.

first-in-first-out (FIFO). A queuing technique in which

the next item to be retrieved is the item that has been
in the queue for the longest time. (A)

648 MQSeries Intercommunication

forced shutdown. A type of shutdown of the CICS to send. The pulse unblocks the receiving MCA, which
adapter where the adapter immediately disconnects otherwise, would remain in a wait state until a message
from MQSeries for OS/390, regardless of the state of arrived or the disconnect interval expired.
any currently active tasks. Contrast with quiesced
shutdown. heartbeat interval. The time, in seconds, that is to
elapse between heartbeat flows.
Formats and Protocols (FAP). The MQSeries FAPs
define how queue managers communicate with one
another, and also how MQSeries clients communicate
I
with server queue managers.
ICE. Intersystem Communications Environment is a
Framework. In MQSeries, a collection of programming family of Tandem-based software products that enables
interfaces that allow customers or vendors to write you to access a variety of applications on Tandem
programs that extend or replace certain functions computers.
provided in MQSeries products. The interfaces are:
ILE. Integrated Language Environment®.
v MQSeries data conversion interface (DCI)
v MQSeries message channel interface (MCI) immediate shutdown. In MQSeries, a shutdown of a
queue manager that does not wait for applications to
v MQSeries name service interface (NSI)
disconnect. Current MQI calls are allowed to complete,
v MQSeries security enabling interface (SEI) but new MQI calls fail after an immediate shutdown
v MQSeries trigger monitor interface (TMI) has been requested. Contrast with quiesced shutdown
and preemptive shutdown.
FRR. Functional recovery routine.
in-doubt unit of recovery. In MQSeries, the status of a
functional recovery routine (FRR). An OS/390 unit of recovery for which a syncpoint has been
recovery/termination manager facility that enables a requested but not yet confirmed.
recovery routine to gain control in the event of a
program interrupt. Integrated Language Environment (ILE). The AS/400
Integrated Language Environment. This replaces the
AS/400 Original Program Model (OPM).
G
.ini file. See configuration file.
GCPC. Generalized command preprocessor.
initialization file. In MQSeries for AS/400, a file that
generalized command preprocessor (GCPC). An contains two parameters; the TCP/IP listener port
MQSeries for OS/390 component that processes number and the maximum number of channels that can
MQSeries commands and runs them. be current at a time. The file is called qm.ini.
Generalized Trace Facility (GTF). An OS/390 service initialization input data sets. Data sets used by
program that records significant system events, such as MQSeries for OS/390 when it starts up.
supervisor calls and start I/O operations, for the
purpose of problem determination. initiation queue. A local queue on which the queue
manager puts trigger messages.
get. In message queuing, to use the MQGET call to
remove a message from a queue. See also browse. input/output parameter. A parameter of an MQI call
in which you supply information when you make the
global trace. An MQSeries for OS/390 trace option call, and in which the queue manager changes the
where the trace data comes from the entire MQSeries information when the call completes or fails.
for OS/390 subsystem.
input parameter. A parameter of an MQI call in which
GTF. Generalized Trace Facility. you supply information when you make the call.

H installable services. In MQSeries on UNIX systems,

MQSeries for OS/2 Warp, and MQSeries for Windows
NT, additional functionality provided as independent
handle. See connection handle and object handle.
components. The installation of each component is
hardened message. A message that is written to optional: in-house or third-party components can be
auxiliary (disk) storage so that the message will not be used instead. See also authorization service, name service,
lost in the event of a system failure. See also persistent and user identifier service.
message.
instrumentation event. A facility that can be used to
heartbeat flow. A pulse that is passed from a sending monitor the operation of queue managers in a network
MCA to a receiving MCA when there are no messages of MQSeries systems. MQSeries provides

Glossary of terms and abbreviations 649

instrumentation events for monitoring queue manager locale. On UNIX systems, a subset of a user’s
resource definitions, performance conditions, and environment that defines conventions for a specific
channel conditions. Instrumentation events can be used culture (such as time, numeric, or monetary formatting
by a user-written reporting mechanism in an and character classification, collation, or conversion).
administration application that displays the events to a The queue manager CCSID is derived from the locale
system operator. They also allow applications acting as of the user ID that created the queue manager.
agents for other administration networks to monitor
reports and create the appropriate alerts. local queue. A queue that belongs to the local queue
manager. A local queue can contain a list of messages
Interactive Problem Control System (IPCS). A waiting to be processed. Contrast with remote queue.
component of OS/390 that permits online problem
management, interactive problem diagnosis, online local queue manager. The queue manager to which a
debugging for disk-resident abend dumps, problem program is connected and that provides message
tracking, and problem reporting. queuing services to the program. Queue managers to
which a program is not connected are called remote
Interactive System Productivity Facility (ISPF). An queue managers, even if they are running on the same
IBM licensed program that serves as a full-screen editor system as the program.
and dialog manager. It is used for writing application
programs, and provides a means of generating log. In MQSeries, a file recording the work done by
standard screen panels and interactive dialogues queue managers while they receive, transmit, and
between the application programmer and terminal user. deliver messages, to enable them to recover in the
event of failure.
Internet Protocol (IP). A protocol used to route data
from its source to its destination in an Internet log control file. In MQSeries on UNIX systems,
environment. This is the base layer, on which other MQSeries for OS/2 Warp, and MQSeries for Windows
protocol layers, such as TCP and UDP are built. NT, the file containing information needed to monitor
the use of log files (for example, their size and location,
Intersystem communication. In CICS, communication and the name of the next available file).
between separate systems by means of SNA
networking facilities or by means of the log file. In MQSeries on UNIX systems, MQSeries for
application-to-application facilities of an SNA access OS/2 Warp, and MQSeries for Windows NT, a file in
method. which all significant changes to the data controlled by a
queue manager are recorded. If the primary log files
IP. Internet Protocol. become full, MQSeries allocates secondary log files.

IPCS. Interactive Problem Control System. logical unit of work (LUW). See unit of work.

ISC. Intersystem communication. luname. The name of the logical unit on your
workstation, that is the name of the software that
ISPF. Interactive System Productivity Facility. interfaces between your applications and the network.

LUWID. Logical unit of work identifier.

L
LU 6.2. A type of logical unit (LU) that supports
linear logging. In MQSeries on UNIX systems, general communication between programs in a
MQSeries for OS/2 Warp, and MQSeries for Windows distributed processing environment.
NT, the process of keeping restart data in a sequence of
files. New files are added to the sequence as necessary.
The space in which the data is written is not reused M
until the queue manager is restarted. Contrast with
circular logging. machine check interrupt. An interruption that occurs
as a result of an equipment malfunction or error. A
listener. In MQSeries distributed queuing, a program machine check interrupt can be either hardware
that monitors for incoming network connections. recoverable, software recoverable, or nonrecoverable.

local definition. An MQSeries object belonging to a MCA. Message channel agent.

local queue manager.
MCI. Message channel interface.
local definition of a remote queue. An MQSeries
object belonging to a local queue manager. This object media image. In MQSeries on UNIX systems,
defines the attributes of a queue that is owned by MQSeries for OS/2 Warp, and MQSeries for Windows
another queue manager. In addition, it is used for NT, the sequence of log records that contain an image
queue-manager aliasing and reply-to-queue aliasing. of an object. The object can be recreated from this
image.

650 MQSeries Intercommunication

message. In message queuing applications, a message-retry. An option available to an MCA that is
communication sent between programs. See also unable to deliver a message. The MCA can wait for a
persistent message and nonpersistent message. In system predefined amount of time and then try to send the
programming, information intended for the terminal message again.
operator or system administrator.
message sequence numbering. A programming
message channel. In distributed message queuing, a technique in which messages are given unique numbers
mechanism for moving messages from one queue during transmission over a communication link. This
manager to another. A message channel comprises two enables the receiving process to check whether all
message channel agents (a sender at one end and a messages are received, to place them in a queue in the
receiver at the other end) and a communication link. original order, and to discard duplicate messages.
Contrast with MQI channel.
messaging. See synchronous messaging and asynchronous
message channel agent (MCA). A program that messaging.
transmits prepared messages from a transmission
queue to a communication link, or from a model queue object. A set of queue attributes that act
communication link to a destination queue. See also as a template when a program creates a dynamic
message queue interface. queue.

message channel interface (MCI). The MQSeries MQAI. MQSeries Administration Interface.
interface to which customer- or vendor-written
programs that transmit messages between an MQSeries MQI. Message queue interface.
queue manager and another messaging system must
MQI channel. Connects an MQSeries client to a queue
conform. A part of the MQSeries Framework.
manager on a server system, and transfers only MQI
message descriptor. Control information describing calls and responses in a bidirectional manner. Contrast
the message format and presentation that is carried as with message channel.
part of an MQSeries message. The format of the
MQSC. MQSeries commands.
message descriptor is defined by the MQMD structure.
MQSeries. A family of IBM licensed programs that
message flow control. A distributed queue
provides message queuing services.
management task that involves setting up and
maintaining message routes between queue managers. MQSeries Administration Interface (MQAI). A
programming interface to MQSeries.
message priority. In MQSeries, an attribute of a
message that can affect the order in which messages on MQSeries client. Part of an MQSeries product that
a queue are retrieved, and whether a trigger event is can be installed on a system without installing the full
generated. queue manager. The MQSeries client accepts MQI calls
from applications and communicates with a queue
message queue. Synonym for queue.
manager on a server system.
message queue interface (MQI). The programming
MQSeries commands (MQSC). Human readable
interface provided by the MQSeries queue managers.
commands, uniform across all platforms, that are used
This programming interface allows application
to manipulate MQSeries objects. Contrast with
programs to access message queuing services.
programmable command format (PCF).
message queue management. The Message Queue
MQSeries server. An MQSeries server is a queue
Management (MQM) facility in MQSeries for Tandem
manager that provides queuing services to one or more
NSK V2.2 uses PCF command formats and control
clients. All the MQSeries objects, for example queues,
commands. MQM runs as a PATHWAY SCOBOL
exist only on the queue manager system, that is, on the
requester under the Terminal Control Process (TCP)
MQI server machine. A server can support normal local
and uses an MQM SERVERCLASS server, which
MQI applications as well.
invokes the C language API to perform PCF
commands. There is a separate instance of MQM for multi-hop. To pass through one or more intermediate
each queue manager configured on a system, since each queue managers when there is no direct
queue manager is controlled under its own PATHWAY communication link between a source queue manager
configuration. Consequently, an MQM is limited to the and the target queue manager.
management of the queue manager to which it belongs.

message queuing. A programming technique in which N

each program within an application communicates with
the other programs by putting messages on queues. namelist. An MQSeries object that contains a list of
names, for example, queue names.

Glossary of terms and abbreviations 651

 name service. In MQSeries on UNIX systems, OPM. Original Program Model.
MQSeries for OS/2 Warp, and MQSeries for Windows
NT, the facility that determines which queue manager Original Program Model (OPM). The AS/400
owns a specified queue. Original Program Model. This is no longer supported
on MQSeries. It is replaced by the Integrated Language
name service interface (NSI). The MQSeries interface Environment (ILE).
to which customer- or vendor-written programs that
resolve queue-name ownership must conform. A part of OTMA. Open Transaction Manager Access.
the MQSeries Framework.
output log-buffer. In MQSeries for OS/390, a buffer
name transformation. In MQSeries on UNIX systems, that holds recovery log records before they are written
MQSeries for OS/2 Warp, and MQSeries for Windows to the archive log.
NT, an internal process that changes a queue manager
name so that it is unique and valid for the system output parameter. A parameter of an MQI call in
being used. Externally, the queue manager name which the queue manager returns information when
remains unchanged. the call completes or fails.

NetBIOS. Network Basic Input/Output System. An

operating system interface for application programs
P
used on IBM personal computers that are attached to page set. A VSAM data set used when MQSeries for
the IBM Token-Ring Network. OS/390 moves data (for example, queues and
messages) from buffers in main storage to permanent
New Technology File System (NTFS). A Windows NT
backing storage (DASD).
recoverable file system that provides security for files.
PCF. Programmable command format.
nonpersistent message. A message that does not
survive a restart of the queue manager. Contrast with PCF command. See programmable command format.
persistent message.
pending event. An unscheduled event that occurs as a
NSI. Name service interface. result of a connect request from a CICS adapter.
NTFS. New Technology File System. percolation. In error recovery, the passing along a
preestablished path of control from a recovery routine
null character. The character that is represented by
to a higher-level recovery routine.
X'00'.
performance event. A category of event indicating
O that a limit condition has occurred.

OAM. Object authority manager. performance trace. An MQSeries trace option where
the trace data is to be used for performance analysis
object. In MQSeries, an object is a queue manager, a and tuning.
queue, a process definition, a channel, a namelist, or a
storage class (OS/390 only). permanent dynamic queue. A dynamic queue that is
deleted when it is closed only if deletion is explicitly
| object authority manager (OAM). In MQSeries on requested. Permanent dynamic queues are recovered if
| UNIX systems, MQSeries for AS/400, and MQSeries for the queue manager fails, so they can contain persistent
| Windows NT, the default authorization service for messages. Contrast with temporary dynamic queue.
| command and object management. The OAM can be
| replaced by, or run in combination with, a persistent message. A message that survives a restart
| customer-supplied security service. of the queue manager. Contrast with nonpersistent
message.
object descriptor. A data structure that identifies a
particular MQSeries object. Included in the descriptor ping. In distributed queuing, a diagnostic aid that
are the name of the object and the object type. uses the exchange of a test message to confirm that a
message channel or a TCP/IP connection is
object handle. The identifier or token by which a functioning.
program accesses the MQSeries object with which it is
working. platform. In MQSeries, the operating system under
which a queue manager is running.
off-loading. In MQSeries for OS/390, an automatic
process whereby a queue manager’s active log is point of recovery. In MQSeries for OS/390, the term
transferred to its archive log. used to describe a set of backup copies of MQSeries for
OS/390 page sets and the corresponding log data sets

652 MQSeries Intercommunication

required to recover these page sets. These backup v An error condition has occurred in relation to the
copies provide a potential restart point in the event of resources used by a queue manager. For example, a
page set loss (for example, page set I/O error). queue is unavailable.
v A significant change has occurred in the queue
preemptive shutdown. In MQSeries, a shutdown of a
manager. For example, a queue manager has stopped
queue manager that does not wait for connected
or started.
applications to disconnect, nor for current MQI calls to
complete. Contrast with immediate shutdown and queuing. See message queuing.
quiesced shutdown.
quiesced shutdown. In MQSeries, a shutdown of a
principal. In MQSeries on UNIX systems, MQSeries queue manager that allows all connected applications
for OS/2 Warp, and MQSeries for Windows NT, a term to disconnect. Contrast with immediate shutdown and
used for a user identifier. Used by the object authority preemptive shutdown. A type of shutdown of the CICS
manager for checking authorizations to system adapter where the adapter disconnects from MQSeries,
resources. but only after all the currently active tasks have been
completed. Contrast with forced shutdown.
process definition object. An MQSeries object that
contains the definition of an MQSeries application. For quiescing. In MQSeries, the state of a queue manager
example, a queue manager uses the definition when it prior to it being stopped. In this state, programs are
works with trigger messages. allowed to finish processing, but no new programs are
allowed to start.
programmable command format (PCF). A type of
MQSeries message used by:
v User administration applications, to put PCF R
commands onto the system command input queue of
a specified queue manager RBA. Relative byte address.
v User administration applications, to get the results of reason code. A return code that describes the reason
a PCF command from a specified queue manager for the failure or partial success of an MQI call.
v A queue manager, as a notification that an event has
occurred receiver channel. In message queuing, a channel that
responds to a sender channel, takes messages from a
Contrast with MQSC. communication link, and puts them on a local queue.

program temporary fix (PTF). A solution or by-pass of recovery log. In MQSeries for OS/390, data sets
a problem diagnosed by IBM field engineering as the containing information needed to recover messages,
result of a defect in a current, unaltered release of a queues, and the MQSeries subsystem. MQSeries for
program. OS/390 writes each record to a data set called the active
log. When the active log is full, its contents are
PTF. Program temporary fix. off-loaded to a DASD or tape data set called the archive
log. Synonymous with log.
Q recovery termination manager (RTM). A program that
handles all normal and abnormal termination of tasks
queue. An MQSeries object. Message queuing by passing control to a recovery routine associated with
applications can put messages on, and get messages the terminating function.
from, a queue. A queue is owned and maintained by a
queue manager. Local queues can contain a list of Registry. In Windows NT, a secure database that
messages waiting to be processed. Queues of other provides a single source for system and application
types cannot contain messages—they point to other configuration data.
queues, or can be used as models for dynamic queues.
Registry Editor. In Windows NT, the program item
queue manager. A system program that provides that allows the user to edit the Registry.
queuing services to applications. It provides an
application programming interface so that programs Registry Hive. In Windows NT, the structure of the
can access messages on the queues that the queue data stored in the Registry.
manager owns. See also local queue manager and remote
queue manager. An MQSeries object that defines the relative byte address (RBA). The displacement in
attributes of a particular queue manager. bytes of a stored record or control interval from the
beginning of the storage space allocated to the data set
queue manager event. An event that indicates: to which it belongs.

Glossary of terms and abbreviations 653

remote queue. A queue belonging to a remote queue resynch. In MQSeries, an option to direct a channel to
manager. Programs can put messages on remote start up and resolve any in-doubt status messages, but
queues, but they cannot get messages from remote without restarting message transfer.
queues. Contrast with local queue.
return codes. The collective name for completion
remote queue manager. To a program, a queue codes and reason codes.
manager that is not the one to which the program is
connected. return-to-sender. An option available to an MCA that
is unable to deliver a message. The MCA can send the
remote queue object. See local definition of a remote message back to the originator.
queue.
rollback. Synonym for back out.
remote queuing. In message queuing, the provision of
services to enable applications to put messages on RTM. Recovery termination manager.
queues belonging to other queue managers.
rules table. A control file containing one or more rules
reply message. A type of message used for replies to that the dead-letter queue handler applies to messages
request messages. Contrast with request message and on the DLQ.
report message.

reply-to queue. The name of a queue to which the

S
program that issued an MQPUT call wants a reply
SAF. System Authorization Facility.
message or report message sent.
SDWA. System diagnostic work area.
report message. A type of message that gives
information about another message. A report message security enabling interface (SEI). The MQSeries
can indicate that a message has been delivered, has interface to which customer- or vendor-written
arrived at its destination, has expired, or could not be programs that check authorization, supply a user
processed for some reason. Contrast with reply message identifier, or perform authentication must conform. A
and request message. part of the MQSeries Framework.
requester channel. In message queuing, a channel that SEI. Security enabling interface.
may be started remotely by a sender channel. The
requester channel accepts messages from the sender sender channel. In message queuing, a channel that
channel over a communication link and puts the initiates transfers, removes messages from a
messages on the local queue designated in the message. transmission queue, and moves them over a
See also server channel. communication link to a receiver or requester channel.
request message. A type of message used to request a sequential delivery. In MQSeries, a method of
reply from another program. Contrast with reply transmitting messages with a sequence number so that
message and report message. the receiving channel can reestablish the message
sequence when storing the messages. This is required
RESLEVEL. In MQSeries for OS/390, an option that where messages must be delivered only once, and in
controls the number of CICS user IDs checked for the correct order.
API-resource security in MQSeries for OS/390.
sequential number wrap value. In MQSeries, a
resolution path. The set of queues that are opened method of ensuring that both ends of a communication
when an application specifies an alias or a remote link reset their current message sequence numbers at
queue on input to an MQOPEN call. the same time. Transmitting messages with a sequence
number ensures that the receiving channel can
resource. Any facility of the computing system or
reestablish the message sequence when storing the
operating system required by a job or task. In MQSeries
messages.
for OS/390, examples of resources are buffer pools,
page sets, log data sets, queues, and messages. server. (1) In MQSeries, a queue manager that
provides queue services to client applications running
resource manager. An application, program, or
on a remote workstation. (2) The program that
transaction that manages and controls access to shared
responds to requests for information in the particular
resources such as memory buffers and data sets.
two-program, information-flow model of client/server.
MQSeries, CICS, and IMS are resource managers.
See also client.
responder. In distributed queuing, a program that
server channel. In message queuing, a channel that
replies to network connection requests from another
responds to a requester channel, removes messages
system.

654 MQSeries Intercommunication

from a transmission queue, and moves them over a storage class. In MQSeries for OS/390, a storage class
communication link to the requester channel. defines the page set that is to hold the messages for a
particular queue. The storage class is specified when
server connection channel type. The type of MQI the queue is defined.
channel definition associated with the server that runs
a queue manager. See also client connection channel type. store and forward. The temporary storing of packets,
messages, or frames in a data network before they are
service interval. A time interval, against which the retransmitted toward their destination.
elapsed time between a put or a get and a subsequent
get is compared by the queue manager in deciding subsystem. In OS/390, a group of modules that
whether the conditions for a service interval event have provides function that is dependent on OS/390. For
been met. The service interval for a queue is specified example, MQSeries for OS/390 is an OS/390
by a queue attribute. subsystem.

service interval event. An event related to the service supervisor call (SVC). An OS/390 instruction that
interval. interrupts a running program and passes control to the
supervisor so that it can perform the specific service
session ID. In MQSeries for OS/390, the CICS-unique indicated by the instruction.
identifier that defines the communication link to be
used by a message channel agent when moving SVC. Supervisor call.
messages from a transmission queue to a link.
switch profile. In MQSeries for OS/390, a RACF
shutdown. See immediate shutdown, preemptive profile used when MQSeries starts up or when a
shutdown, and quiesced shutdown. refresh security command is issued. Each switch profile
that MQSeries detects turns off checking for the
signaling. In MQSeries for OS/390 and MQSeries for specified resource.
Windows 2.1, a feature that allows the operating
system to notify a program when an expected message symptom string. Diagnostic information displayed in
arrives on a queue. a structured format designed for searching the IBM
software support database.
single logging. A method of recording MQSeries for
OS/390 activity where each change is recorded on one synchronous messaging. A method of communication
data set only. Contrast with dual logging. between programs in which programs place messages
on message queues. With synchronous messaging, the
single-phase backout. A method in which an action in sending program waits for a reply to its message before
progress must not be allowed to finish, and all changes resuming its own processing. Contrast with
that are part of that action must be undone. asynchronous messaging.

single-phase commit. A method in which a program syncpoint. An intermediate or end point during
can commit updates to a queue without coordinating processing of a transaction at which the transaction’s
those updates with updates the program has made to protected resources are consistent. At a syncpoint,
resources controlled by another resource manager. changes to the resources can safely be committed, or
Contrast with two-phase commit. they can be backed out to the previous syncpoint.

SIT. System initialization table. System Authorization Facility (SAF). An OS/390

facility through which MQSeries for OS/390
SNA. Systems Network Architecture. communicates with an external security manager such
as RACF.
source queue manager. See local queue manager.
system.command.input queue. A local queue on
SPX. Sequenced Packet Exchange transmission
which application programs can put MQSeries
protocol.
commands. The commands are retrieved from the
stanza. A group of lines in a configuration file that queue by the command server, which validates them
assigns a value to a parameter modifying the behavior and passes them to the command processor to be run.
of a queue manager, client, or channel. In MQSeries on
system control commands. Commands used to
UNIX systems, MQSeries for OS/2 Warp, and
manipulate platform-specific entities such as buffer
MQSeries for Windows NT, a configuration (.ini) file
pools, storage classes, and page sets.
may contain a number of stanzas.
system diagnostic work area (SDWA). Data recorded
star-connected communications network. A network
in a SYS1.LOGREC entry, which describes a program or
in which all nodes are connected to a central node.
hardware error.

Glossary of terms and abbreviations 655

 system initialization table (SIT). A table containing GTF and the system management facility (SMF). See
parameters used by CICS on start up. also global trace and performance trace.

Systems Network Architecture (SNA). The tranid. See transaction identifier.

description of the logical structure, formats, protocols,
and operational sequences for transmitting information transaction identifier. In CICS, a name that is
units through, and controlling the configuration and specified when the transaction is defined, and that is
operation of, networks. used to invoke the transaction.

SYS1.LOGREC. A service aid containing information Transmission Control Protocol (TCP). Part of the
about program and hardware errors. TCP/IP protocol suite. A host-to-host protocol between
hosts in packet-switched communications networks.
TCP provides connection-oriented data stream delivery.
T Delivery is reliable and orderly.

TACL. Tandem Advanced Command Language. Transmission Control Protocol/Internet Protocol

(TCP/IP). A suite of communication protocols that
target library high-level qualifier (thlqual). support peer-to-peer connectivity functions for both
High-level qualifier for OS/390 target data set names. local and wide area networks.
target queue manager. See remote queue manager. transmission program. See message channel agent.
task control block (TCB). An OS/390 control block transmission queue. A local queue on which prepared
used to communicate information about tasks within an messages destined for a remote queue manager are
address space that are connected to an OS/390 temporarily stored.
subsystem such as MQSeries for OS/390 or CICS.
trigger event. An event (such as a message arriving
task switching. The overlapping of I/O operations on a queue) that causes a queue manager to create a
and processing between several tasks. In MQSeries for trigger message on an initiation queue.
OS/390, the task switcher optimizes performance by
allowing some MQI calls to be executed under subtasks triggering. In MQSeries, a facility allowing a queue
rather than under the main CICS TCB. manager to start an application automatically when
predetermined conditions on a queue are satisfied.
TCB. Task control block.
trigger message. A message containing information
TCP. Transmission Control Protocol. about the program that a trigger monitor is to start.
TCP/IP. Transmission Control Protocol/Internet trigger monitor. A continuously-running application
Protocol. serving one or more initiation queues. When a trigger
message arrives on an initiation queue, the trigger
temporary dynamic queue. A dynamic queue that is
monitor retrieves the message. It uses the information
deleted when it is closed. Temporary dynamic queues
in the trigger message to start a process that serves the
are not recovered if the queue manager fails, so they
queue on which a trigger event occurred.
can contain nonpersistent messages only. Contrast with
permanent dynamic queue. trigger monitor interface (TMI). The MQSeries
interface to which customer- or vendor-written trigger
| teraspace. In MQSeries for AS/400, a form of shared
monitor programs must conform. A part of the
| memory introduced in OS/400 V4R4.
MQSeries Framework.
termination notification. A pending event that is
two-phase commit. A protocol for the coordination of
activated when a CICS subsystem successfully connects
changes to recoverable resources when more than one
to MQSeries for OS/390.
resource manager is used by a single transaction.
thlqual. Target library high-level qualifier. Contrast with single-phase commit.

thread. In MQSeries, the lowest level of parallel

execution available on an operating system platform.
U
UDP. User Datagram Protocol.
time-independent messaging. See asynchronous
messaging. UIS. User identifier service.
TMI. Trigger monitor interface. undelivered-message queue. See dead-letter queue.
trace. In MQSeries, a facility for recording MQSeries
activity. The destinations for trace entries can include

656 MQSeries Intercommunication

undo/redo record. A log record used in recovery. The
redo part of the record describes a change to be made
to an MQSeries object. The undo part describes how to
back out the change if the work is not committed.

unit of recovery. A recoverable sequence of operations

within a single resource manager. Contrast with unit of
work.

unit of work. A recoverable sequence of operations

performed by an application between two points of
consistency. A unit of work begins when a transaction
starts or after a user-requested syncpoint. It ends either
at a user-requested syncpoint or at the end of a
transaction. Contrast with unit of recovery.

User Datagram Protocol (UDP). Part of the TCP/IP

protocol suite. A packet-level protocol built directly on
the Internet Protocol layer. UDP is a connectionless and
less reliable alternative to TCP. It is used for
application-to-application programs between TCP/IP
host systems.

user identifier service (UIS). In MQSeries for OS/2

Warp, the facility that allows MQI applications to
associate a user ID, other than the default user ID, with
MQSeries messages.

utility. In MQSeries, a supplied set of programs that

provide the system operator or system administrator
with facilities in addition to those provided by the
MQSeries commands. Some utilities invoke more than
one function.

Glossary of terms and abbreviations 657

658 MQSeries Intercommunication
 Bibliography
This section describes the documentation storage requirements, backup and
available for all current MQSeries products. recovery, security, and migration from
earlier releases, and specifies hardware
and software requirements for every
MQSeries cross-platform MQSeries platform.
publications
MQSeries Intercommunication
Most of these publications, which are sometimes The MQSeries Intercommunication book,
referred to as the MQSeries “family” books, apply SC33-1872, defines the concepts of
to all MQSeries Level 2 products. The latest distributed queuing and explains how to
MQSeries Level 2 products are: set up a distributed queuing network in a
v MQSeries for AIX, V5.1 variety of MQSeries environments. In
| v MQSeries for AS/400, V5.1 particular, it demonstrates how to (1)
v MQSeries for AT&T GIS UNIX V2.2 configure communications to and from a
| v MQSeries for Compaq (DIGITAL) OpenVMS, representative sample of MQSeries
| V2.2.1.1 products, (2) create required MQSeries
| v MQSeries for DIGITAL UNIX (Compaq Tru64 objects, and (3) create and configure
| UNIX), V2.2.1 MQSeries channels. The use of channel
v MQSeries for HP-UX, V5.1 exits is also described.
v MQSeries for OS/2 Warp, V5.1
MQSeries Queue Manager Clusters
v MQSeries for OS/390, V2.1
MQSeries Queue Manager Clusters,
v MQSeries for SINIX and DC/OSx, V2.2
SC34-5349, describes MQSeries clustering.
v MQSeries for Sun Solaris, V5.1
It explains the concepts and terminology
| v MQSeries for Tandem NonStop Kernel, V2.2.0.1
and shows how you can benefit by taking
v MQSeries for VSE/ESA V2.1
advantage of clustering. It details changes
v MQSeries for Windows V2.0
to the MQI, and summarizes the syntax of
v MQSeries for Windows V2.1
new and changed MQSeries commands. It
v MQSeries for Windows NT, V5.1
shows a number of examples of tasks you
can perform to set up and maintain
Any exceptions to this general rule are indicated.
clusters of queue managers.
MQSeries Brochure
This book applies to the following
The MQSeries Brochure, G511-1908, gives a
MQSeries products only:
brief introduction to the benefits of
v MQSeries for AIX V5.1
MQSeries. It is intended to support the
| v MQSeries for AS/400 V5.1
purchasing decision, and describes some
v MQSeries for HP-UX V5.1
authentic customer use of MQSeries.
v MQSeries for OS/2 Warp V5.1
MQSeries: An Introduction to Messaging and v MQSeries for OS/390 V2.1
Queuing v MQSeries for Sun Solaris V5.1
An Introduction to Messaging and Queuing, v MQSeries for Windows NT V5.1
GC33-0805, describes briefly what
MQSeries Clients
MQSeries is, how it works, and how it
The MQSeries Clients book, GC33-1632,
can solve some classic interoperability
describes how to install, configure, use,
problems. This book is intended for a
and manage MQSeries client systems.
more technical audience than the
MQSeries Brochure. MQSeries System Administration
The MQSeries System Administration book,
MQSeries Planning Guide
SC33-1873, supports day-to-day
The MQSeries Planning Guide, GC33-1349,
management of local and remote
describes some key MQSeries concepts,
MQSeries objects. It includes topics such
identifies items that need to be considered
as security, recovery and restart,
before MQSeries is installed, including
transactional support, problem

© Copyright IBM Corp. 1993, 2000 659

 determination, and the dead-letter queue v MQSeries for Windows V2.0
handler. It also includes the syntax of the v MQSeries for Windows V2.1
MQSeries control commands.
This book is available in softcopy only.
This book applies to the following
MQSeries products only:
For other MQSeries platforms, the
v MQSeries for AIX, V5.1
messages are supplied with the system.
v MQSeries for HP-UX, V5.1
They do not appear in softcopy manual
v MQSeries for OS/2 Warp, V5.1
form.
v MQSeries for Sun Solaris, V5.1
v MQSeries for Windows NT, V5.1 MQSeries Application Programming Guide
The MQSeries Application Programming
MQSeries Command Reference
Guide, SC33-0807, provides guidance
The MQSeries Command Reference,
information for users of the message
SC33-1369, contains the syntax of the
queue interface (MQI). It describes how to
MQSC commands, which are used by
design, write, and build an MQSeries
MQSeries system operators and
application. It also includes full
administrators to manage MQSeries
descriptions of the sample programs
objects.
supplied with MQSeries.
MQSeries Programmable System Management
MQSeries Application Programming Reference
The MQSeries Programmable System
The MQSeries Application Programming
Management book, SC33-1482, provides
Reference, SC33-1673, provides
both reference and guidance information
comprehensive reference information for
for users of MQSeries events,
users of the MQI. It includes: data-type
Programmable Command Format (PCF)
descriptions; MQI call syntax; attributes of
messages, and installable services.
MQSeries objects; return codes; constants;
MQSeries Administration Interface and code-page conversion tables.
Programming Guide and Reference
MQSeries Application Programming Reference
The MQSeries Administration Interface
Summary
Programming Guide and Reference,
The MQSeries Application Programming
SC34-5390, provides information for users
Reference Summary, SX33-6095,
of the MQAI. The MQAI is a
summarizes the information in the
programming interface that simplifies the
MQSeries Application Programming
way in which applications manipulate
Reference manual.
Programmable Command Format (PCF)
messages and their associated data MQSeries Using C++
structures. MQSeries Using C++, SC33-1877, provides
both guidance and reference information
This book applies to the following
for users of the MQSeries C++
MQSeries products only:
programming-language binding to the
v MQSeries for AIX V5.1
MQI. MQSeries C++ is supported by
| v MQSeries for AS/400 V5.1
these MQSeries products:
v MQSeries for HP-UX V5.1
v MQSeries for AIX, V5.1
v MQSeries for OS/2 Warp V5.1
v MQSeries for HP-UX, V5.1
v MQSeries for Sun Solaris V5.1
v MQSeries for OS/2 Warp, V5.1
v MQSeries for Windows NT V5.1
| v MQSeries for AS/400, V5.1
MQSeries Messages v MQSeries for OS/390, V2.1
The MQSeries Messages book, GC33-1876, v MQSeries for Sun Solaris, V5.1
which describes “AMQ” messages issued v MQSeries for Windows NT, V5.1
by MQSeries, applies to these MQSeries
products only: MQSeries C++ is also supported by
v MQSeries for AIX, V5.1 MQSeries clients supplied with these
v MQSeries for HP-UX, V5.1 products and installed in the following
v MQSeries for OS/2 Warp, V5.1 environments:
v MQSeries for Sun Solaris, V5.1 v AIX
v MQSeries for Windows NT, V5.1 v HP-UX

660 MQSeries Intercommunication

 v OS/2 MQSeries for HP-UX, V5.1 Quick
v Sun Solaris Beginnings, GC33-1869
v Windows NT
MQSeries for OS/2 Warp
v Windows 3.1
v Windows 95 and Windows 98 MQSeries for OS/2 Warp, V5.1 Quick
Beginnings, GC33-1868
MQSeries Using Java
MQSeries Using Java, SC34-5456, provides MQSeries for OS/390
both guidance and reference information MQSeries for OS/390 Version 2 Release 1
for users of the MQSeries Bindings for Licensed Program Specifications,
Java and the MQSeries Client for Java. GC34-5377
MQSeries classes for Java are supported MQSeries for OS/390 Version 2 Release 1
by these MQSeries products: Program Directory
v MQSeries for AIX, V5.1
MQSeries for OS/390 System
| v MQSeries for AS/400, V5.1
Management Guide, SC34-5374
v MQSeries for HP-UX, V5.1
| v MQSeries for MVS/ESA V1.2 MQSeries for OS/390 Messages and
v MQSeries for OS/2 Warp, V5.1 Codes, GC34-5375
v MQSeries for Sun Solaris, V5.1 MQSeries for OS/390 Problem
v MQSeries for Windows NT, V5.1 Determination Guide, GC34-5376
MQSeries link for R/3
| This book is available in softcopy only.
MQSeries link for R/3 Version 1.2 User’s
Guide, GC33-1934
MQSeries platform-specific
MQSeries for SINIX and DC/OSx
publications
MQSeries for SINIX and DC/OSx System
Each MQSeries product is documented in at least Management Guide, GC33-1768
one platform-specific publication, in addition to
MQSeries for Sun Solaris
the MQSeries family books.
MQSeries for Sun Solaris, V5.1 Quick
MQSeries for AIX Beginnings, GC33-1870
MQSeries for AIX, V5.1 Quick
MQSeries for Tandem NonStop Kernel
Beginnings, GC33-1867
| MQSeries for Tandem NonStop Kernel
MQSeries for AS/400 | System Management Guide, GC33-1893
| MQSeries for AS/400 V5.1 Quick
MQSeries for VSE/ESA
| Beginnings, GC34-5557
MQSeries for VSE/ESA Version 2 Release
| MQSeries for AS/400 V5.1 System
1 Licensed Program Specifications,
| Administration, SC34-5558
GC34-5365
| MQSeries for AS/400 V5.1 Application
MQSeries for VSE/ESA System
| Programming Reference (ILE RPG),
Management Guide, GC34-5364
| SC34-5559
MQSeries for Windows
MQSeries for AT&T GIS UNIX
MQSeries for Windows V2.0 User’s
MQSeries for AT&T GIS UNIX System
Guide, GC33-1822
Management Guide, SC33-1642
MQSeries for Windows V2.1 User’s
| MQSeries for Compaq (DIGITAL) OpenVMS Guide, GC33-1965
| MQSeries for Digital OpenVMS System
MQSeries for Windows NT
| Management Guide, GC33-1791
MQSeries for Windows NT, V5.1 Quick
| MQSeries for Digital UNIX (Compaq Tru64 Beginnings, GC34-5389
| UNIX)
MQSeries for Windows NT Using the
| MQSeries for Digital UNIX System Component Object Model Interface,
| Management Guide, GC34-5483 SC34-5387
| MQSeries for HP-UX

Bibliography 661
 MQSeries LotusScript Extension, v MQSeries for HP-UX, V5.1
SC34-5404 v MQSeries for OS/2 Warp, V5.1
v MQSeries for Sun Solaris, V5.1
v MQSeries for Windows NT, V5.1
Softcopy books v MQSeries link for R/3 V1.2
Most of the MQSeries books are supplied in both
hardcopy and softcopy formats. PDF versions of all current MQSeries books are
also available from the MQSeries product family
BookManager format Web site at:
http://www.ibm.com/software/ts/mqseries/
The MQSeries library is supplied in IBM
BookManager® format on a variety of online
library collection kits, including the Transaction PostScript format
Processing and Data collection kit, SK2T-0730. You The MQSeries library is provided in PostScript
can view the softcopy books in IBM BookManager (.PS) format with many MQSeries Version 2
format using the following IBM licensed products. Books in PostScript format can be
programs: printed on a PostScript printer or viewed with a
BookManager READ/2 suitable viewer.
BookManager READ/6000
BookManager READ/DOS Windows Help format
BookManager READ/MVS
The MQSeries for Windows User’s Guide is
BookManager READ/VM
provided in Windows Help format with MQSeries
BookManager READ for Windows
for Windows Version 2.0 and MQSeries for
Windows Version 2.1.
HTML format
Relevant MQSeries documentation is provided in
HTML format with these MQSeries products:
MQSeries information available
v MQSeries for AIX, V5.1 on the Internet
| v MQSeries for AS/400, V5.1
The MQSeries product family Web site is at:
v MQSeries for HP-UX, V5.1
v MQSeries for OS/2 Warp, V5.1 http://www.ibm.com/software/ts/mqseries/
v MQSeries for Sun Solaris, V5.1
v MQSeries for Windows NT, V5.1 (compiled By following links from this Web site you can:
HTML) v Obtain latest information about the MQSeries
v MQSeries link for R/3 V1.2 product family.
The MQSeries books are also available in HTML v Access the MQSeries books in HTML and PDF
format from the MQSeries product family Web formats.
site at: v Download MQSeries SupportPacs.
http://www.ibm.com/software/ts/mqseries/
Related publications
Portable Document Format (PDF)
This section describes the documentation
PDF files can be viewed and printed using the available for related products.
Adobe Acrobat Reader.

If you need to obtain the Adobe Acrobat Reader, Programming

or would like up-to-date information about the OS/390 C/C++ Programming Guide, SC09-2362
platforms on which the Acrobat Reader is
supported, visit the Adobe Systems Inc. Web site OS/390
at: OS/390 OpenEdition Planning, SC28-1890
http://www.adobe.com/
CICS
PDF versions of relevant MQSeries books are CICS Family: Interproduct Communication,
supplied with these MQSeries products: SC33-0824
v MQSeries for AIX, V5.1 CICS/400 Intercommunication, SC33-1388
| v MQSeries for AS/400, V5.1

662 MQSeries Intercommunication

 Related publications
CICS Intercommunication Guide, SC33-1695
CICS Resource Definition Guide, SC33-1684

OS/400
OS/400 Communication Configuration, SC41-3401
OS/400 Communication Management, SC41-3406
OS/400 Work Management, SC41-3306
OS/400 APPC Communications Programming,
SC41-3443

Digital
Digital DECnet SNA Gateway Guide to IBM
Parameters
Digital DECnet for OpenVMS Networking
Manual

SNA
Microsoft SNA Server APPC Programmers Guide
Microsoft SNA Server CPI-C Programmers Guide
OpenNet LU 6.2, System Administrator’s Guide
OpenNet SNA Engine, System Administrator’s
Guide

SINIX
Transit SINIX Version 3.2 Administration of
Transit

You may also find the following International

Technical Support Organization “Red Books”
useful:
APPC Security: MVS/ESA, CICS/ESA, and OS/2,
GG24-3960
Examples of Using MQSeries on S/390, RS/6000,
AS/400, and PS/2, GG24-4326
Multiplatform APPC Configuration Guide,
GG24-4485

You can find a list of all the red books available at

URL http://www.almaden.ibm.com/redbooks/ > >

Request these books through your IBM

representative.

Bibliography 663
Related publications

664 MQSeries Intercommunication

Index
A attributes (continued)
LONGRTY 85
attributes (continued)
transmission queue name 94
active channels, maximum number 64 LONGTMR 85 transport type 95
add routing entry 455 LU 6.2 mode name 86 TRPTYPE 95
addressing information 25 LU 6.2 TP name 86 user ID 95
addrtge 455 maximum message length 87 USERID 95
administration, channel 60 maximum transmission size 87 XMITQ 94
AgentBuffer parameter 547 MAXMSGL 87 authority, PUT 90
AgentBufferLength parameter 547 MCA name 87 auto-definition exit program 516
aliases 25 MCA type 88 auto-definition of channels 60
ALTDATE attribute 78 MCA user 88 automatic channel reconnect for
alter channel MCANAME 87 TCP/IP 344
OS/390 325 MCATYPE 88 Automatic Restart Management
OS/390 using CICS 356 MCAUSER 88 (ARM) 344
Alter option 370 message exit name 88 AUTOSTART attribute 78
alternate channels 15 message exit user data 89
ALTTIME attribute 78 message retry count 89
AMQCRCTA channel program 445
AMQCRS6A channel program 119
message-retry exit name 89
message-retry exit user data 89
B
AMQCRSTA channel program 119, 445 back out in-doubt messages
message retry interval 89
AMQRMCLA channel program 445 Digital OpenVMS 116
mode name 86
APC pathway definition, example 295 OS/2 116
MODENAME 86
APPC/MVS, defining a connection 342 OS/400 439
MRDATA 89
applications, trusted 12, 121 Tandem NSK 116
MREXIT 89
ARM (Automatic Restart UNIX systems 116
MRRTY 89
Management) 344 Windows NT 116
MRTMR 89
assured delivery 22 batch interval 79
MSGDATA 89
AT&T GIS SNA Server 246 batch size 79
MSGEXIT 88
Attachmate PathWay 280 BATCHINT attribute 79
NETPRTY 90
attributes BatchInterval field 573
network-connection priority 90
ALTDATE 78 BatchSize field 562
nonpersistent message speed 90
alter date 78 BATCHSZ attribute 79
NPMSPEED 90
alter time 78 bibliography 659
password 90
ALTTIME 78 bind type 121
profile name, CICS 81
auto start 78 binding, fastpath 121
PUT authority 90
AUTOSTART 78 BINDING channel state 62
PUTAUT 90
batch interval 79 BookManager 662
QMNAME 91
batch size 79 browsing a channel 356, 430
queue manager name 91
BATCHINT 79 RCVDATA 92
BATCHSZ 79 RCVEXIT 91
CHANNEL 80 receive exit name 91 C
channel description 84 receive exit user data 92 caller
channel name 80 SCYDATA 93 MCA 9
channel type 81 SCYEXIT 92 caller, responder 9
CHLTYPE 81 security exit name 92 caller MCA 9
CLUSNL 82 security exit user data 93 calls
CLUSTER 81 send exit name 93 MQ_CHANNEL_AUTO_DEF_EXIT 551
cluster name 81 send exit user data 93 MQ_CHANNEL_EXIT 546
cluster namelist 82 SENDDATA 93 MQ_TRANSPORT_EXIT 555
communication connection SENDEXIT 93 MQXWAIT 553
identifier 82 sequence number wrap 93 CapabilityFlags field 601
CONNAME 82 sequential delivery 93 CEDA CICS transaction 383
connection name 82 SEQWRAP 93 change definition, channel 113, 436
CONVERT 83 short retry count 93 Change option 436
convert message 83 short retry interval 94 channel
DESCR 84 SHORTRTY 93 administration 60
DISCINT 84 SHORTTMR 94 alter
disconnect interval 84 target system identifier 94 OS/390 325
HBINT 85 TPNAME 86 OS/390 using CICS 370
heartbeat interval 85 transaction identifier 94 altering 356
long retry count 85 transmission protocol 95 attributes 111
long retry interval 85 auto-definition 60

© Copyright IBM Corp. 1993, 2000 665

channel (continued) channel (continued) channel (continued)
auto-definition exit program 516 display settings preparing 60
browsing 356, 430 OS/390 using CICS 365 program types
change definition 113, 436 display status Digital OpenVMS 119
channel control function Digital OpenVMS 113 MQSeries for AS/400 445
Digital OpenVMS 105 OS/2 113 OS/2 119
OS/2 105 OS/390 using CICS 364 Tandem NSK 119
OS/400 423 OS/400 437 UNIX systems 119
Tandem NSK 105 Tandem NSK 113 Windows NT 119
UNIX systems 105 UNIX systems 113 programs 445
Windows NT 105 Windows NT 113 AMQCCLA 445
characteristics displaying 110, 437 AMQCRCTA 445
Digital OpenVMS 119 displaying settings AMQCRS6A 119, 445
OS/2 119 Digital OpenVMS 113 AMQCRSTA 119
OS/390 using CICS 351 OS/2 113 AMQRMCLA 445
OS/400 445 OS/390 using CICS 364 OS/390 using CICS 351
Tandem NSK 119 OS/400 437 pull-down menu 373
UNIX systems 119 Tandem NSK 113 quiescing 67
Windows NT 119 UNIX Systems 113 receiver 7
client-connection 7 Windows NT 113 receiving parameters 59
cluster-receiver 9 displaying status 437 refuses to run 613
cluster-sender 8 Digital OpenVMS 113 renaming
command queue OS/2 113 Digital OpenVMS 111
OS/390 343 OS/390 using CICS 364 OS/2 111
configuration 490 OS/400 437 OS/390 using CICS 357
constants 627 Tandem NSK 113 OS/400 432
control commands 60 UNIX Systems 113 Tandem NSK 111
copy definition 367, 436 Windows NT 113 UNIX Systems 111
create definition enabling 61 Windows NT 111
Digital OpenVMS 113 end 438 requester 7
OS/2 113 error 65 requester-sender 9
OS/390 using CICS 368 restarting after 69 requester-server 9
OS/400 435 exit current function 366 reset
Tandem NSK 113 fastpath binding 121 OS/390 332
UNIX Systems 113 find 370 OS/390 using CICS 362
Windows NT 113 in doubt 69 Reset
creating 109, 356, 426 in-doubt channels 69 Digital OpenVMS 116
creating your own defaults 369, 435 initial data negotiation 61 OS/2 116
default values supplied by MQSeries initiator OS/400 439
for AS/400 435 AIX, OS/2, HP-UX, Sun Solaris, Tandem NSK 116
default values supplied by OS/390 and Windows NT 118 UNIX systems 116
using CICS 369, 372 OS/390 327 Windows NT 116
define overview 10 resolving
OS/390 324 starting 118 Digital OpenVMS 116
OS/390 using CICS 372 stopping 118 OS/2 116
definition, what is it? 57 listener OS/390 333
definition file overview 10 OS/390 using CICS 363
Digital OpenVMS 106 start, OS/390 329 OS/400 439
OS/2 106 start, OS/400 437 Tandem NSK 116
OS/390 using CICS 351 stop, OS/390 329 UNIX Systems 116
OS/400 423 STRMQMLSR command 437 Windows NT 116
Tandem NSK 106 trusted 12 restart 61
UNIX systems 106 menu-bar choice 373 restarting when stopped 69
Windows NT 106 monitoring 60 resync, OS/390 using CICS 361
delete 113, 437 MQI 7 run 110, 429
OS/390 326 OS/400 segregating messages 15
OS/390 using CICS 370 resolve 439 selecting 430
description 84 ping selecting OS/390 using CICS 354
display Digital OpenVMS 113 sender-receiver 8
Digital OpenVMS 113 OS/2 113 sequence numbers 59
OS/2 113 OS/390 331 server-connection 7
OS/400 437 OS/390 using CICS 366 server-receiver 8
Tandem NSK 113 OS/400 437 sharing 14
UNIX systems 113 Tandem NSK 113 start 61
Windows NT 113 UNIX systems 113 Digital OpenVMS 110, 114
display, OS/390 325 Windows NT 113 OS/2 110, 114
planning form 623 OS/390 330

666 MQSeries Intercommunication

channel (continued) channel definition file (continued) channel initiator (continued)
OS/390 using CICS 357 UNIX systems 106 running the MCA as a thread 88
OS/400 429, 437 Windows NT 106 start, OS/2, Windows NT, Digital
Tandem NSK 110, 114 channel description 84 OpenVMS, Tandem NSK, and UNIX
UNIX systems 114 channel exit systems 118
UNIX Systems 110 MQCXP structure 591 start, OS/390 327
Windows NT 110, 114 MQTXP structure 605 start, OS/400 438
startup, data negotiation 61, 506, 507 MQXWD structure 609 stop, OS/2, Windows NT, Digital
startup negotiation errors 613 channel-exit programs 505, 542 OpenVMS, Tandem NSK, and UNIX
state 62 channel definition structure, systems 118
status 59 MQCD 518 stop, OS/390 328
stopping 67, 438 channel-exit programs 529 STRMQMCHLI command 438
Digital OpenVMS 115 data buffer 518 channel listener
OS/2 115 introduction 12 overview 10
OS/390 334 MQSeries for AIX 526 start, OS/390 329
OS/390 using CICS 359, 385 MQSeries for AS/400 521 start, OS/400 438
OS/400 438 MQSeries for AT&T GIS UNIX 531 stop, OS/390 329
Tandem NSK 115 MQSeries for Compaq (DIGITAL) STRMQMLSR command 438
UNIX systems 115 OpenVMS 528 trusted 12
Windows NT 115 MQSeries for DIGITAL UNIX channel name attribute 80
switching 617 (Compaq Tru64 UNIX) 529 channel planning example
synchronizing 361, 506 MQSeries for HP-UX 530 Digital OpenVMS 305
test, OS/390 331 MQSeries for OS/2 Warp 522 OS/2 305
transport-retry exit program 517 MQSeries for OS/390 using OS/390 345
triggering 20, 358 CICS 521 OS/400 477
OS/2 117 MQSeries for OS/390 without UNIX systems 305
OS/390 342 CICS 520 Windows NT 305
OS/390 using CICS 358 MQSeries for SINIX and channel planning form, how to use 623
Tandem NSK 117 DC/OSx 532 channel programs
UNIX systems 117 MQSeries for Sun Solaris 532 Digital OpenVMS 119
Windows NT 117 MQSeries for Tandem NonStop MQSeries for AS/400 445
trusted 121 Kernel 533 OS/2 119
types 81, 111, 119, 352 MQSeries for Windows 526 OS/390 using CICS 351
using alternate channels 15 MQSeries for Windows NT 524 Tandem NSK 119
working with OS/390 using parameter structure, MQCXP 518 UNIX systems 119
CICS 354 supplied programs, DCE 537 Windows NT 119
CHANNEL attribute 80 Windows 3.1 client 524 channel refuses to run 613
channel attributes 533 Windows 95 and Windows 98 channel settings panel, OS/390 using
channel auto-definition exit, client 524 CICS 374
introduction 12 Windows NT client 524 channel startup negotiation errors 613
channel configuration writing and compiling 518 channel states
MQSeries for AIX 210 channel exits BINDING 62
MQSeries for AS/400 471 auto-definition 516 INACTIVE 65
MQSeries for AT&T GIS UNIX 252 message 514 OS/400 446
MQSeries for DIGITAL UNIX message-retry 516 channel status
(Compaq Tru64 UNIX) 216 receive 512 display, Digital OpenVMS 113
MQSeries for HP-UX 238 security 507 display, OS/2 113
MQSeries for OS/2 Warp 163 send 512 display, OS/390 335
MQSeries for OS/390 405 transport-retry 517 display, OS/390 using CICS 364
MQSeries for Sun Solaris 272 channel functions display, OS/400 437
MQSeries for Windows NT 185 Digital OpenVMS 112 display, Tandem NSK 113
channel control error messages 611 OS/2 112 display, UNIX systems 113
channel control function 59 Tandem NSK 112 display, Windows NT 113
Digital OpenVMS 105 UNIX systems 112 channel type attribute 81
OS/2 105 Windows NT 112 ChannelDefinition parameter
OS/390 321 channel initiator MQ_CHANNEL_AUTO_DEF_EXIT
OS/390 using CICS 351 display, OS/390 326 call 551
OS/400 423 overview 10 MQ_CHANNEL_EXIT call 546
Tandem NSK 105 retries 65, 85 ChannelExitParms parameter
UNIX systems 105 runmqchi command, MQSeries for MQ_CHANNEL_AUTO_DEF_EXIT
Windows NT 105 OS/2 Warp 114 call 551
channel definition file runmqchi command, MQSeries for MQ_CHANNEL_EXIT call 546
Digital OpenVMS 106 Windows NT 114 ChannelName field 558
OS/2 106 runmqchi command, MQSeries on channels, alternate to 15
OS/390 using CICS 351 UNIX systems 114 CHANNELS stanza 637
OS/400 423 runmqchi command, Tandem ChannelType field 559
Tandem NSK 106 NSK 114 CHLTYPE attribute 81

Index 667
CICS communications examples (continued) connection (continued)
CEDA INSTALL command 383 TCP/IP 303 LU 6.2 (continued)
installing communication communications Manager/2 128 OS/390 using CICS 382
connection 383 Communications Manager/2 127 OS/400 449
profile name 81 Communications Server for AIX V5 202 Tandem NSK 289
regions 352 Communications Server for Windows UNIX systems 191
transaction NT 174 Windows NT 123
CEDA 383 communications setup, Tandem NetBIOS
CKMC 352 NSK 292 OS/2 123
CKSG 384 communications side object Windows NT 123
Cisco MultiNet for Digital OS/390 342 SPX
OpenVMS 279 OS/400 451, 452 OS/2 123
CKMC CICS transaction 352 CompCode parameter 553 Windows NT 123
CKSG CICS transaction 384 components, cluster 6 switching 617
class of routing entry 457 components of distributed-queuing TCP
class of service 47 environment 13 Digital OpenVMS 277
client-connection channel 7 channel initiator 10 OS/2 123
clients, problem determination 617 channel listener 10 OS/390 339
CLUSNL attribute 82 message channel 7 OS/400 449
CLUSTER attribute 81 message channel agent 9 Tandem NSK 289
cluster channels, OS/390 337 transmission queue 10 UNIX systems 191
cluster components 6 compression of data 512 Windows NT 123
cluster name attribute 81 concentrating messages 44 UDP
cluster namelist attribute 82 concentrators 31 UNIX systems 191
cluster-receiver 9 concepts of intercommunication 3, 16, connection name 82
cluster-receiver channel 7 22 for function shipping 383
cluster-sender 8 configuration ConnectionName field 568
cluster-sender channel 7 MQSeries for AIX 209 constants 627
ClusterPtr field 577 MQSeries for AS/400 471 constants, values of 627
clusters MQSeries for AT&T GIS UNIX 251 channel capability flags
choosing transmission queue 39 MQSeries for DIGITAL UNIX (MQCF_*) 628
components 6 (Compaq Tru64 UNIX) 215 channel data conversion
concentrating messages 44 MQSeries for HP-UX 238 (MQCDC_*) 628
distribution lists 46 MQSeries for OS/2 Warp 162 channel definition structure length
message flow 35 MQSeries for OS/390 405 (MQCD_*) 628
networking considerations 52 MQSeries for Sun Solaris 271 channel definition structure version
passing messages 41 MQSeries for VSE/ESA 490 (MQCD_*) 628
putting messages 38 MQSeries for Windows NT 184 channel-exit parameter structure
reply-to queue 47 configuration file 73 identifier (MQCXP_*) 628
return routing 53 Digital OpenVMS 73 channel-exit parameter structure
separating message flows 42 OS/2 73 version (MQCXP_*) 629
using 16 SINIX and DC/OSx 311 channel type (MQCHT_*) 628
ClustersDefined field 578 Tandem NSK 73 exit identifier (MQXT_*) 631
command queue channel, OS/390 343 UNIX systems 73 exit reason (MQXR_*) 630
command validation 71 configuration worksheet 485 exit response (MQXCC_*) 630
commit in-doubt messages configuring the UDP transport-retry exit user area (MQXUA_*) 631
Digital OpenVMS 116 exit 518 exit wait descriptor structure identifier
OS/2 116 CONNAME attribute 82 (MQXWD_*) 631
OS/400 439 connection exit wait descriptor version
Tandem NSK 116 APPC/MVS, OS/390 339 (MQXWD_*) 631
UNIX systems 116 deciding upon lengths of character string and byte
Windows NT 116 OS/390 339 fields (MQ_*) 627
committed messages OS/400 449 MCA type (MQMCAT_*) 629
Digital OpenVMS 116 DECnet Phase IV 285 nonpersistent message speed
OS/2 116 DECnet Phase V 286 (MQNPMS_*) 629
OS/400 439 defining APPC/MVS (LU 6.2) 342 put authority (MQPA_*) 629
Tandem NSK 116 defining LU 6.2 secondary exit response
UNIX systems 116 Digital OpenVMS 281 (MQXR2_*) 630
Windows NT 116 OS/2 126 security identifier (MQSID_*) 629
communication OS/400 451 security identifier type
between CICS systems attached to one UNIX systems 194 (MQSIDT_*) 630
queue manager 383 Windows NT 126 transmission protocol type
between queue managers 381 installing 383 (MQXPT_*) 630
intersystem (ISC) 382 LU 6.2 transport retry exit structure identifier
communications examples Digital OpenVMS 277 (MQTXP_*) 630
ICE 299 OS/2 123 transport retry exit version
SNAX 292 OS/390 339 (MQTXP_*) 630

668 MQSeries Intercommunication

context security 91 decompression of data 512 display channel status
control commands, channel 60 default channel values OS/390 335
conversion failure, problem OS/390 using CICS 369, 372 Display channel status
determination 615 OS/400 435 Digital OpenVMS 110
conversion of data 59 default object creation 108 OS/2 110
CONVERT attribute 83 define channel Tandem NSK 110
convert message 83 OS/390 324 UNIX systems 110
coordination with adjacent systems 44 defining Windows NT 110
Copy option 367, 436 an LU 6.2 connection display DQM 326
Create option 368, 435 Digital OpenVMS 281 display settings 365
creating OS/2 126 display status 364
channel OS/400 451 distributed queuing
Digital OpenVMS 109 UNIX systems 194 components 7, 13
OS/2 109 Windows NT 126 functions 57
OS/390 using CICS 356 APPC/MVS (LU 6.2) connection distributed queuing in OS/390 using
OS/400 426 OS/390 342 CICS 381
Tandem NSK 109 objects 384 distributed-queuing management in
UNIX systems 109 OS/390 342 MQSeries for AS/400 441
Windows NT 109 OS/390 324 distribution lists 46, 59
defaults 369, 435 OS/390 using CICS 372 diverting message flows 45
objects queues 384 DQM
Digital OpenVMS 108 OS/390 342 display, OS/390 326
OS/2 108 DQM panels
definition file
OS/400 426 OS/390 using CICS 352
data 544
Tandem NSK 108
Digital OpenVMS 106
UNIX systems 108
OS/2 106
Windows NT 108
queues 117, 441
OS/390 using CICS 351 E
OS/400 423 ECB field 610
transmission queue 117, 441
Tandem NSK 106 edit
CRTCSI command 452
UNIX systems 106 alter, OS/390 using CICS 370
CRTMQM command 109
Windows NT 106 change
current channels
delete channel Digital OpenVMS 113
specifying maximum number 64
distributed platforms 113 OS/2 113
OS/390 326 OS/400 436
OS/390 using CICS 370 Tandem NSK 113
D OS/400 437 UNIX systems 113
data delivery, messages 22 Windows NT 113
compression 512 Desc field 560 copy
conversion 514 DESCR attribute 84 OS/390 using CICS 367
decompression 512 description, channel 84 OS/400 436
encryption 514 DestAddress parameter 555 create
negotiation 20, 60 DestAddressLength parameter 555 Digital OpenVMS 113
data conversion 75 destination queue 42
OS/2 113
data types, detailed description OS/390 using CICS 368
dial-up support 615
MQCD 556 OS/400 435
Digital TCP/IP services for
MQCXP 591 Tandem NSK 113
OpenVMS 278
MQTXP 605 UNIX systems 113
disabled receiver channels 114, 437
MQXWD 609 Windows NT 113
DataConversion field 565 disaster recovery 616 delete
DataId field 607 DISCINT attribute 84 Digital OpenVMS 113
DataLength field 607 DiscInterval field 562 OS/2 113
DataLength parameter 546 disconnect interval 84 OS/390 using CICS 370
DCE display OS/400 437
supplied exit programs 537 option 437 Tandem NSK 113
dead-letter queue 52 OS/390, DQM 326 UNIX systems 113
Digital OpenVMS 119 settings 365 Windows NT 113
MQSeries for AS/400 447 status 364 find
OS/2 119 display channel OS/390 using CICS 370
overview 13 Digital OpenVMS 110 menu-bar choice
problem determination 612 OS/2 110 OS/390 using CICS 367
processing 612 OS/390 325 pull-down menu 367
Tandem NSK 119 OS/400 437 enabling a channel to transmit
UNIX systems 119 Tandem NSK 110 messages 61
Windows NT 119 UNIX systems 110 encryption of messages 505
DECnet Phase IV 277 Windows NT 110 end 115
DECnet Phase IV connection 285 display channel initiator End option 438
DECnet phase V connection 286 OS/390 326 ending a channel 115, 438

Index 669
ending SNA Listener process 284 example (continued) examples (continued)
ENDMQLSR command 119 running (continued) message channels (continued)
error Tandem NSK 309 requester-server 9
at remote sites 611 UNIX systems 309 sender-receiver 8
channel 65 Windows NT 309 MQSeries for AIX configuration 197
logs 115, 618 sender channel definition MQSeries for AS/400
message from channel control 611 Digital OpenVMS 308, 309 configuration 459
recovery 611 OS/2 308, 309 MQSeries for AT&T GIS UNIX
OS/390 347, 348 configuration 243
example
OS/400 479, 481 MQSeries for HP-UX
channel planning Tandem NSK 308, 309 configuration 219
Digital OpenVMS 305 UNIX systems 308, 309 MQSeries for OS/2 Warp
OS/2 305 Windows NT 308, 309 configuration 137
OS/390 345 transmission queue definition MQSeries for OS/390
OS/400 477 Digital OpenVMS 307, 308 configuration 395
UNIX systems 305 OS/2 307, 308 MQSeries for Sun Solaris
Windows NT 305 OS/390 347, 348 configuration 257
communications setup OS/400 479, 481 MQSeries for VSE/ESA
Tandem NSK 292 Tandem NSK 307, 308 configuration 485
configuration file, SINIX and UNIX systems 307, 308 MQSeries for Windows NT
DC/OSx 311 Windows NT 307, 308 configuration 169
configurations 97, 98 multi-hopping 14
example configurations
flow control 35 passing messages through system 41
local queue definition MQSeries for AIX 197, 214
MQSeries for AS/400 459, 476 passing through intermediate queue
Digital OpenVMS 308 managers 14
OS/2 308 MQSeries for AT&T GIS UNIX 243,
257 putting messages on remote
OS/390 348 queues 38
OS/400 480 MQSeries for Digital OpenVMS 277,
289 QM-concentrators 31
Tandem NSK 308 queue name resolution 54
UNIX systems 308 MQSeries for DIGITAL UNIX
(Compaq Tru64 UNIX) 215, 219 receiving messages 40
Windows NT 308 renaming a channel 111
process definition MQSeries for HP-UX 219, 243
MQSeries for OS/2 Warp 137, 168 reply-to queue 47, 48
Digital OpenVMS 307, 309 reply-to-queue alias 28
OS/2 307, 309 MQSeries for OS/390 395, 419
MQSeries for Sun Solaris 257, 277 sending messages 5, 17
OS/390 347, 348 sending messages in both
OS/400 479, 481 MQSeries for Windows NT 169, 189
directions 5
Tandem NSK 307, 309 examples
separating message flows 42
UNIX systems 307, 309 alias walk-through 51 setting up communication for OS/2
Windows NT 307, 309 channel initiators 10 and Windows NT
receiver channel definition channel listeners 10 defining a NetBIOS
Digital OpenVMS 308, 309 channel names 30 connection 128
OS/2 308, 309 channel planning defining a TCP connection 124
OS/390 347, 348 for distributed platforms 305 defining an LU 6.2
OS/400 480, 481 for OS/390 345 connection 126
Tandem NSK 308, 309 for OS/390 using CICS 387 defining an SPX connection 131
UNIX systems 308, 309 for OS/400 477 setting up communication in Digital
Windows NT 308, 309 choosing the transmission queue 39 OpenVMS
remote queue definition cluster of queue managers 6 defining a DECnet Phase IV
Digital OpenVMS 307 communication in MQSeries for connection 285
OS/2 307 AS/400, TCP connection 449 defining a DECnet Phase V
OS/390 346 concentrating messages 44 connection 286
OS/400 478 configuration file on bight 312 defining an LU 6.2
Tandem NSK 307 configuration file on forties 313 connection 281
UNIX systems 307 configuration files setting up communication in
Windows NT 307 for Pyramid DC/OSx 313 MQSeries for OS/390
reply-to queue definition SINIX and DC/OSx 311 LU 6.2 connection 342
Digital OpenVMS 308 create channel 109 TCP connection 339
OS/2 308 creating reply-to aliases 36 setting up communication in Tandem
OS/390 347 defining channels 18 NSK
OS/400 480 defining queues 19 SNA channels 289
Tandem NSK 308 defining remote queue definitions 36 TCP channels 291
UNIX systems 308 display channel 110 setting up communication in UNIX
Windows NT 308 display channel status 110 systems
running diverting message flows 45 defining a TCP connection 191
Digital OpenVMS 309 message channels defining an LU 6.2
OS/2 309 cluster-receiver 9 connection 194
OS/390 349 cluster-sender 8
OS/400 482 requester-sender 9

670 MQSeries Intercommunication

examples (continued) fields (continued) fields (continued)
setting up communications in Digital ExitData 599 Reserved3 610
OpenVMS ExitDataLength 574 RetryCount 607
defining a TCP connection 278 ExitId 592 SecurityExit 563
sharing a transmission queue 14 ExitNameLength 574 SecurityUserData 565
SINIX and DC/OSx configuration ExitNumber 601 SendExit 564
files 311 ExitReason SendExitPtr 576
starting a channel 110, 429 MQCXP structure 593 SendExitsDefined 575
triggering 21, 118 MQTXP structure 606 SendUserData 566
using multiple channels 15 ExitResponse SendUserDataPtr 576
using the remote queue definition MQCXP structure 595 SeqNumberWrap 564
object 37 MQTXP structure 607 SessionId 607
exit 366 ExitResponse2 596 ShortConnectionName 561
exit wait descriptor structure 609 ExitUserArea ShortRetryCount 562
ExitBufferAddr parameter 548 MQCXP structure 598 ShortRetryInterval 562
ExitBufferLength parameter 548 MQTXP structure 606 StrucId
ExitData field 599 FAPLevel 601 MQCXP structure 591
ExitDataLength field 574 Feedback MQTXP structure 605
ExitId field 592 MQCXP structure 598 MQXWD structure 609
ExitNameLength field 574 MQTXP structure 608 StrucLength 574
ExitNumber field 601 GroupId 607 TpName 562
ExitParms parameter 555 HeaderLength 600 TransportType
EXITPATH HeartbeatInterval 572 MQCD structure 560
stanza of qm.ini file 637 LongMCAUserIdLength 578 MQTXP structure 606
ExitReason field LongMCAUserIdPtr 579 UserIdentifier 566
MQCXP structure 593 LongRemoteUserIdLength 578 Version
MQTXP structure 606 LongRemoteUserIdPtr 579 MQCD structure 558
ExitResponse field LongRetryCount 563 MQCXP structure 592
MQCXP structure 595 LongRetryInterval 563 MQTXP structure 605
MQTXP structure 607 MaxMsgLength 565 MQXWD structure 609
ExitResponse2 field 596 MaxSegmentLength 598 XmitQName 561
exits MCAName 561 find option 370
constants 627 MCASecurityId 579 flow control 35
ExitUserArea field MCAType 568 function keys
MQCXP structure 598 MCAUserIdentifier 567 OS/390 using CICS 353
MQTXP structure 606 ModeName 561 function shipping 383
MsgExit 563 functions available
MsgExitPtr 575 Digital OpenVMS 106
F MsgExitsDefined 574
MsgRetryCount
OS/2 106
FAPLevel field 601 Tandem NSK 106
MQCD structure 571 UNIX systems 106
fast, nonpersistent messages 22
MQCXP structure 599 Windows NT 106
sequence of retrieval 56
MsgRetryExit 570
specifying 90
MsgRetryInterval
Feedback field
MQCD structure 572
MQCXP structure 598
MQCXP structure 599 G
MQTXP structure 608 glossary 645
MsgRetryReason 600
fields MsgRetryUserData 570 GroupId field 607
BatchInterval 573 MsgUserData 566
BatchSize 562 MsgUserDataPtr 575
CapabilityFlags 601
ChannelName 558
NetworkPriority 578
NonPersistentMsgSpeed 573
H
ChannelType 559 HBINT attribute 85
PartnerName 600
ClusterPtr 577 Password 567 Hconn parameter 553
ClustersDefined 578 PutAuthority 565 HeaderLength field 600
ConnectionName 568 QMgrName 561 heartbeat interval 85
DataConversion 565 ReceiveExit 564 HeartbeatInterval field 572
DataId 607 ReceiveExitPtr 577 help
DataLength 607 ReceiveExitsDefined 575 OS/390 using CICS 372
Desc 560 ReceiveUserData 566 pull-down menus 372, 373
details of receiver channel panel 377 ReceiveUserDataPtr 577
details of requester channel settings help menu-bar choice 372, 373
RemotePassword 569 how to use
panel 379 RemoteSecurityId 579
details of sender channel settings 376 channel planning form 623
RemoteUserIdentifier 569
details of server channel settings HTML (Hypertext Markup
Reserved 606
panel 378 Language) 662
Reserved1 609
DiscInterval 562 Reserved2 609 Hypertext Markup Language
ECB 610 (HTML) 662

Index 671
I keyboard functions (continued)
OS/390 using CICS (continued)
LU 6.2 connection (continued)
MQSeries for AT&T GIS UNIX 243
IBM Communications Server for enter key 354 MQSeries for Digital OpenVMS 277
Windows NT 174 unassigned keys and unavailable MQSeries for HP-UX 219
ICE communications example 299 choices 354 MQSeries for OS/2 Warp 137
in-doubt 80 MQSeries for OS/390 395
in-doubt channels, manual MQSeries for OS/390 with CICS 381,
resynchronization 69
in-doubt message on channel, resolve on L 402
MQSeries for OS/390 without
OS/390 333 links, wide-band 31
CICS 400
in-doubt messages, commit or back out list cluster channels, OS/390 337
MQSeries for Sun Solaris 257
Digital OpenVMS 116 listener, trusted 10, 12, 121
MQSeries for Tandem NSK 289
OS/2 116 listening on LU 6.2
MQSeries for VSE/ESA 485
OS/400 439 OS/2 127
MQSeries for Windows NT 169
Tandem NSK 116 OS/390 342
setting up
UNIX systems 116 UNIX systems 195
OS/2 123
Windows NT 116 Windows NT 127
OS/390 342
INACTIVE channel state 62, 65 listening on NetBIOS
OS/390 using CICS 382
ini file 73 OS/2 131
OS/400 449
initial data negotiation 20, 61 Windows NT 131
UNIX systems 191
initialization data set, OS/390 without listening on SPX
Windows NT 123
CICS 73 OS/2 132, 162
LU62
initialization file 73 Windows NT 132, 183
stanza of qm.ini file 637
initiator for channel listening on TCP
AIX, OS/2, HP-UX, Sun Solaris, and Digital OpenVMS 278
Windows NT 118 OS/2 124
OS/390 327 OS/390 340 M
installing OS/400 450 maximum
CICS communication connection 383 UNIX systems 192 active channels 64
integrity of delivery 22 Windows NT 124 current channels 64
intercommunication local queue definition message length 87
concepts 3, 16, 22 example transmission size 87
example 485 Digital OpenVMS 308 MAXMSGL attribute 87
example configuration 97 OS/2 308 MaxMsgLength field 565
intercommunication example 485, 503 OS/390 348 MaxSegmentLength field 598
intercommunication examples OS/400 480 MCA
MQSeries for AIX 197 Tandem NSK 308 caller 9
MQSeries for AS/400 459 UNIX systems 308 name 87
MQSeries for AT&T GIS UNIX 243 Windows NT 308 responder 9
MQSeries for DIGITAL UNIX local queue manager 3 type 88
(Compaq Tru64 UNIX) 215 location name 42 user 88
MQSeries for HP-UX 219 log user-written 75
MQSeries for OS/2 Warp 137 error 115, 618 MCANAME attribute 87
MQSeries for OS/390 395 file, @SYSTEM 618 MCAName field 561
MQSeries for Sun Solaris 257 logs for errors 115 MCASecurityId field 579
MQSeries for VSE/ESA 485 long retry count attribute 85 MCATYPE attribute 88
MQSeries for Windows NT 169 long retry interval attribute 85 MCAType field 568
interfaces LongMCAUserIdLength field 578 MCAUSER attribute 88
Interlink SNSTCPAccess 344 LongMCAUserIdPtr field 579 MCAUserIdentifier field 567
IUCV 344 LongRemoteUserIdLength field 578 message
Interlink SNSTCPAccess interface 344 LongRemoteUserIdPtr field 579 committed
intersystem communication (ISC) 381 LongRetryCount field 563 Digital OpenVMS 116
ISC (intersystem communication) 381 LongRetryInterval field 563 OS/2 116
IUCV interface 344 LONGRTY attribute 85 OS/400 439
LONGTMR attribute 85 Tandem NSK 116
loopback testing 56 UNIX systems 116
J LU 6.2 Windows NT 116
journaling 514 mode name 86 concentrating 44
responder processes 291 converting 83
settings diverting flows 45
K OS/2 126 encryption 505
KEEPALIVE 66 OS/400 451 error 611
OS/2 132, 162 UNIX systems 194 for distribution list 46
keyboard functions Windows NT 126 passing through system 41
function keys TP name 86 putting on remote queue 37
OS/390 using CICS 353 LU 6.2 connection queue name translations 53
OS/390 using CICS MQSeries for AIX 197 receiving 40
clear key 354 MQSeries for AS/400 459 return routing 53

672 MQSeries Intercommunication

message (continued) monitoring and controlling channels MQSeries for HP-UX (continued)
return to sender 72 (continued) LU 6.2 connection 219
routing 39 OS/390 using CICS 351 TCP connection 237
sending and receiving 58 OS/400 423 MQSeries for OS/2 Warp
separating flows 42 Tandem NSK 105 channel configuration 163
sequence numbering 54 UNIX systems 105 channel-exit programs 522
sequential retrieval 55 Windows NT 105 configuration 162
splitting 59 monitoring channels 60 intercommunication example 137,
undeliverable 71 moving service component 4 168
message channel MQ_* values 627 LU 6.2 connection 137
cluster-receiver 7, 9 MQ_CHANNEL_AUTO_DEF_EXIT NetBIOS connection 160
cluster-sender 7, 8 call 551 SPX connection 160
receiver 7 MQ_CHANNEL_EXIT call 546 TCP connection 158
requester 7 MQ_TRANSPORT_EXIT call 555 MQSeries for OS/390
requester-sender 9 MQCD, channel definition structure 518 channel configuration 405
requester-server 9 MQCD structure 556 configuration 405
sender 7 MQCXP_* values 591 intercommunication example 395,
sender-receiver 8 MQCXP, channel exit parameter 419
server 7 structure 518 LU 6.2 connection 395
server-receiver 8 MQCXP structure 591 reset channel sequence numbers 332
message channel agent MQFB_* values 598 resolving in-doubt message on
caller 9 MQI channels 7 channel 333
initiation 507, 512 MQIBindType 121 TCP connection 404
responder 9 MQRMH, reference-message header 515 MQSeries for OS/390 using CICS
security 91 mqs.ini 74 channel-exit programs 521
termination 507, 512 MQSeries for AIX MQSeries for OS/390 without CICS
user-written 75 channel configuration 210 channel-exit programs 520
message channel agent (MCA) 9, 57 channel-exit programs 526 MQSeries for SINIX and DC/OSx
message channels configuration 209 channel-exit programs 532
list panel intercommunication example 197, MQSeries for Sun Solaris
OS/390 using CICS 353 214 channel configuration 272
message exit 12 LU 6.2 connection 197 channel-exit programs 532
message exit name 88 TCP connection 209 configuration 271
message exit program 514 UDP connection 209 intercommunication example 257,
overview 506 MQSeries for AS/400 277
message exit user data 89 channel configuration 471 LU 6.2 connection 257
message flow control 35 channel-exit programs 521 TCP connection 271
networking considerations 52 configuration 471 MQSeries for Tandem NonStop Kernel
message retry 72 intercommunication example 459, channel-exit programs 533
message-retry exit 476 setting up communication 289
introduction 12 LU 6.2 connection 459 MQSeries for VSE/ESA
name 89 TCP connection 469 channel configuration 490
retry count 89 MQSeries for AT&T GIS UNIX configuration 490
retry interval 89 channel configuration 252 configuration worksheet 485
user data 89 channel-exit programs 531 LU 6.2 connection 485
message-retry exit program 516 configuration 251 MQSeries for Windows 104
messages intercommunication example 243, channel-exit programs 526
assured delivery 22 257 MQSeries for Windows NT
back out in-doubt messages LU 6.2 connection 243 channel configuration 185
OS/400 439 TCP connection 251 channel-exit programs 524
commit in-doubt messages MQSeries for Digital OpenVMS configuration 184
OS/400 439 channel-exit programs 528 intercommunication example 169,
resolve in-doubt messages problem solving 285 189
OS/400 439 setting up communication 277 LU 6.2 connection 169
sending 17 SNA configuration 281 NetBIOS connection 181
Messages MQSeries for DIGITAL UNIX (Compaq SPX connection 182
back out in-doubt messages 116 Tru64 UNIX) TCP connection 181
commit in-doubt messages 116 channel configuration 216 MQSeries publications 659
resolve in-doubt messages 116 configuration 215 MQSINI 74
messages and codes 71 intercommunication example 215 MQTXP_* values 605
mode name 86 TCP connection 215 MQTXP structure 605
MODENAME attribute 86 MQSeries for HP-UX MQXCC_* values
ModeName field 561 channel configuration 238 MQCXP structure 595
monitoring and controlling channels channel-exit programs 530 MQTXP structure 607
Digital OpenVMS systems 105 configuration 238 MQXQH, transmission header 515, 516
OS/2 105 intercommunication example 219, MQXR_* values
OS/390 321 243 MQCXP structure 593

Index 673
MQXR_* values (continued) network infrastructure, example panels (continued)
MQTXP structure 606 configurations 98 display status
MQXR2_* values 596 network planner 31 message channel list 364
MQXT_* values 592 networking 41 edit menu-bar options
MQXUA_* values networking considerations 52 message channel list 367
MQCXP structure 606 NetworkPriority field 578 ending channel
MQTXP structure 598 networks 29 OS/400 438
MQXWAIT call 553 node centric 36 exit
MQXWD_* values 609 nonpersistent message speed 90 message channel list 366
MQXWD structure 609 NonPersistentMsgSpeed field 573 exit from 373
MRDATA attribute 89 help menu-bar choice, message
MREXIT attribute 89 channel list 372
MRO (multiregion operation) 381 O OS/390 using CICS, message channel
MRRTY attribute 89 objects list 354
MRTMR attribute 89 creating OS/400
MSGDATA attribute 89 default 108 resolve 439
MSGEXIT attribute 88 Digital OpenVMS 108 work with status 437
MsgExit field 563 OS/2 108 ping
MsgExitPtr field 575 OS/400 426 message channel list 366
MsgExitsDefined field 574 Tandem NSK 108 OS/400 437
MsgRetryCount field UNIX systems 108 receiver channel settings 377
MQCD structure 571 Windows NT 108 reset
MQCXP structure 599 defining 384 message channel list 362
MsgRetryExit field 570 OS/390 342 OS/400 439
MsgRetryInterval field security 120, 447 resolve
MQCD structure 572 operator commands message channel list 363
MQCXP structure 599 OS/400 424 resync
MsgRetryReason field 600 options message channel list 361
MsgRetryUserData field 570 alter 370 selecting a channel
MsgUserData field 566 change 436 OS/400 430
MsgUserDataPtr field 575 copy 367, 436 starting channel
multi-hopping 14 create 368, 435 message channel list 357
multiple message channels per display 437 stopping channel
transmission queue display settings 365 message channel list 359
Digital OpenVMS 120 display status 364, 437 using, OS/390 322
OS/2 120 end 438 view menu-bar choice
OS/390 using CICS 384 exit 366, 373 message channel list 371
OS/400 447 find 370 work-with-channel choices
Tandem NSK 120 ping 366, 437 OS/400 434
UNIX systems 120 reset 362, 439 Work with channel status
Windows NT 120 resolve 116, 363 OS/400 432
multiple queue managers 127 OS/400 439 parameters
multiregion operation (MRO) 381 resync 361 AgentBuffer 547
save 373 AgentBufferLength 547
N start 357, 437
stop
ChannelDefinition
MQ_CHANNEL_AUTO_DEF_EXIT
name resolution
OS/390 using CICS 359 call 551
conflicts 53
OS/390 connections MQ_CHANNEL_EXIT call 546
convention 52
connecting systems 381 ChannelExitParms
description 633
LU 6.2 381 MQ_CHANNEL_AUTO_DEF_EXIT
introduction 26
call 551
location 42
MQ_CHANNEL_EXIT call 546
queue name translations 53
restriction 48 P CompCode 553
DataLength 546
NDF file configuration 128 panel data, validation 71
DestAddress 555
negotiations on startup 61, 613 panels
DestAddressLength 555
NetBIOS 4, 128 browsing a channel
ExitBufferAddr 548
NETBIOS OS/400 430
ExitBufferLength 548
stanza of qm.ini file 637 channel start
ExitParms 555
NetBIOS, example configurations 98 OS/400 437
Hconn 553
NetBIOS connection creating a channel
Reason 553
MQSeries for OS/2 Warp 160 OS/400 426
WaitDesc 553
MQSeries for Windows NT 181 display
parameters, receiving 59
OS/2 123 channel status 364
Windows NT 123 OS/400 437 PartnerName field 600
NetBIOS products, in example display channel status 437 password 90
configurations 98 display settings Password field 567
network-connection priority 90 message channel list 365 PAUSED channel state 62, 66

674 MQSeries Intercommunication

PDF (Portable Document Format) 662 process definition example (continued) queue manager alias 25, 36
ping 366, 437 OS/2 307 introduction 26
Digital OpenVMS 113 OS/390 347 receiving 40
OS/2 113 OS/400 479 queue name
problem determination 611 Tandem NSK 307 resolution 633
Tandem NSK 113 UNIX systems 307 how it works 636
UNIX systems 113 Windows NT 307 what is it? 635
Windows NT 113 process definition for triggering translations 53
ping channel Digital OpenVMS 117 queues
OS/390 331 OS/2 117 create a transmission queue 117, 441
ping with LU 6.2 114, 437 OS/390 343 defining 384
planning OS/390 using CICS 358, 384 OS/390 342
message channel planning example OS/400 443 quiescing channels 67
OS/390 using CICS 387 Tandem NSK 117
planning form 623
port
UNIX systems 117
Windows NT 117
R
in qm.ini file 637 process security 91 RCVDATA attribute 92
MQSeries for AIX 203 processing problems 71 RCVEXIT attribute 91
MQSeries for Digital OpenVMS 278 profile name, CICS 81 Reason parameter 553
MQSeries for HP-UX 225 programs receive exit 12
MQSeries for OS/2 124 AMQCRCTA 445 name 91
MQSeries for OS/390 327, 405 AMQCRS6A 119 program 512
MQSeries for VSE/ESA 500 AMQCRSTA 119, 445 user data 92
MQSeries for Windows NT 124 AMQRMCLA 445 ReceiveExit field 564
Tandem NSK 303 RUNMQCHI 119 ReceiveExitPtr field 577
Portable Document Format (PDF) 662 RUNMQCHL 119 ReceiveExitsDefined field 575
RUNMQLSR 119 receiver
PostScript format 662
publications channel 7
preparation
MQSeries 659 channel definition example
getting started
related 662 Digital OpenVMS 308
Digital OpenVMS 108
pull-down menus OS/2 308
OS/2 108
channel 373 OS/390 347
OS/400 426
edit 367 OS/400 480
Tandem NSK 108
help (channel definition panels) 373 Tandem NSK 308
UNIX systems 108
help (message channel list panel) 372 UNIX systems 308
Windows NT 108
selected 357 Windows NT 308
preparing channels 60
view 371 channel panel
preparing MQSeries for AS/400 441 details 377
problem determination 611 PUT authority 90
PUTAUT attribute 90 panel settings
channel refuses to run 613 OS/390 using CICS 377
PutAuthority field 565
channel startup negotiation receiver channel definition
putting messages 37
errors 613 example
on remote queues 37
channel switching 617 Digital OpenVMS 309
to distribution lists 46
clients 617 OS/2 309
connection switching 617 OS/390 348
conversion failure 615 OS/400 481
data structures 616 Q Tandem NSK 309
dead-letter queue 612 qm.ini 74 UNIX systems 309
error messages 611 stanzas used for distributed Windows NT 309
retrying the link 615 queuing 637 overview 5
scenarios 611 QMgrName field 561 ReceiveUserData field 566
transmission queue overflow 612 QMINI 74 ReceiveUserDataPtr field 577
triggered channels 614 QMINI file receiving
undelivered-message queue 612 stanzas used for distributed messages 40, 58
user-exit programs 616 queuing 637 on DECnet Phase IV 286
using the PING command 611 QMNAME attribute 91 on LU 6.2
validation checks 612 queue OS/2 127
process definition destination 42 OS/390 342
example reply-to 47 Tandem NSK 291
Digital OpenVMS 309 queue manager UNIX systems 195
OS/2 309 alias 25, 36 Windows NT 127
OS/390 348 receiving 40 on SPX
OS/400 481 interconnection procedure OS/2 132, 162
Tandem NSK 309 example 387 Windows NT 132, 183
UNIX systems 309 multiple 124 on TCP
Windows NT 309 name 91 Digital OpenVMS 278
process definition example alias 42 OS/2 124
Digital OpenVMS 307 types 3 OS/390 340

Index 675
receiving (continued) requester channel settings panel, security (continued)
OS/400 450 details 379 objects (continued)
Tandem NSK 304 REQUESTING channel state 62 MQSeries for AS/400 447
UNIX systems 192 Reserved field 606 OS/2 120
Windows NT 124 Reserved1 field 609 Tandem NSK 120
receiving messages 40, 58 Reserved2 field 609 UNIX systems 120
receiving on DECnet Phase IV 286 Reserved3 field 610 Windows NT 120
receiving on LU 6.2 reset 116, 362, 439 process 91
OS/2 127 RESET CHANNEL command 614 SecurityExit field 563
OS/390 342 reset channel sequence numbers, SecurityUserData field 565
Tandem NSK 291 OS/390 332 segregating messages 15
UNIX systems 195 resolve 363 selected menu-bar choice 357
Windows NT 127 RESOLVE CHANNEL command 613 selecting a channel 430
receiving on SPX resolve in-doubt message on channel, OS/390 using CICS 354
OS/2 132, 162 OS/390 333 send
Windows NT 132, 183 resolve in-doubt messages 116 exit 12
receiving on TCP OS/400 439 exit name 93
Digital OpenVMS 278 resolve option 116 exit program 512
OS/2 124 OS/400 439 message 57
OS/390 340 responder send exit user data 93
OS/400 450 LU6.2 78, 114, 291 SENDDATA attribute 93
Tandem NSK 304 MCA 9 sender channel 7
UNIX systems 192 responder MCA 9
sender channel definition
Windows NT 124 responder process 78, 114, 291
example
reference-message header restarting
Digital OpenVMS 308, 309
message exit program 515 channels 61
OS/2 308, 309
registry 73, 74, 126, 129, 135, 182, 524 restarting stopped channels 69
OS/390 347, 348
remote queue definition 36 resync 361
OS/400 479, 481
example RETRY channel state 62, 65
Tandem NSK 308, 309
Digital OpenVMS 307 retry considerations 615
UNIX systems 308, 309
OS/2 307 RetryCount field 607
Windows NT 308, 309
OS/390 346 retrying the link, problem
overview 5
OS/400 478 determination 615
sender channel settings
Tandem NSK 307 return routing 53
details 376
UNIX systems 307 return to sender 72
reusing exit programs 533 SENDEXIT attribute 93
Windows NT 307
introduction 15, 25 routing entry SendExit field 564
what it is 14 add 456 SendExitPtr field 576
remote queue manager 3 class 457 SendExitsDefined field 575
RemotePassword field 569 routing entry class 457 sending
RemoteSecurityId field 579 routing messages 39 messages 17, 58
RemoteUserIdentifier field 569 run channel 110, 429 on DECnet Phase IV 286
run channel initiator 118 on SPX
renaming a channel
runmqchi command OS/2 131
Digital OpenVMS 111
AIX, OS/2, HP-UX, Sun Solaris, and Windows NT 131
OS/2 111
Windows NT 118 on TCP
OS/390 using CICS 357
RUNMQCHI command 119 Digital OpenVMS 278
OS/400 432
RUNMQCHL command 119 OS/2 124
Tandem NSK 111
RUNMQLSR command 119 Windows NT 124
UNIX systems 111
sending on TCP 191
Windows NT 111
SendUserData field 566
reply-to alias 36 S SendUserDataPtr field 576
reply-to queue 47 save option 373 SeqNumberWrap field 564
alias definition 28 scenarios, problem determination 611
alias example 48 sequence number wrap 93
SCF configuration file, example 292
aliases 25 sequence numbering 54
SCYDATA attribute 93
preparing for 29 sequence numbers 59
SCYEXIT attribute 92
specifying 28 reset, OS/390 332
security
reply-to queue definition context 91 sequential delivery 93
example exit 12 sequential retrieval of messages 55
Digital OpenVMS 308 exit name 92 SEQWRAP attribute 93
OS/2 308 exit program 507 server
OS/390 347 exit program, overview 506 AT&T GIS SNA 246
OS/400 480 exit user data 93 channel 7
Tandem NSK 308 levels for exit programs 121 channel settings panel, detail 378
UNIX systems 308 message channel agent 91 server-connection channel 7
Windows NT 308 objects service, class of 47
requester channel 7 Digital OpenVMS 120 SessionId field 607

676 MQSeries Intercommunication

setting up status TCP (continued)
CICS communication for OS/390 381 display channel 110 connection (continued)
communication work with channel 432 MQSeries for AS/400 469
Digital OpenVMS systems 277 status, channel 59 MQSeries for AT&T GIS
OS/2 123 status panels 364, 437 UNIX 251
OS/400 449 stop MQSeries for Digital
Tandem NSK 289 channel 67, 115, 359 OpenVMS 277
UNIX systems 191 channel, OS/390 334 MQSeries for DIGITAL UNIX
Windows NT 123 channel, OS/390 using CICS 385 (Compaq Tru64 UNIX) 215
sharing channels 14 channel initiator, OS/390 328 MQSeries for HP-UX 237
short retry channel listener, OS/390 329 MQSeries for OS/2 Warp 158
count 93 controlled 439 MQSeries for OS/390 404
interval 94 immediate 439 MQSeries for Sun Solaris 271
ShortConnectionName field 561 option 359 MQSeries for Tandem NSK 289
ShortRetryCount field 562 quiesce 115, 361 MQSeries for VSE/ESA 490
ShortRetryInterval field 562 stop channel initiator 118 MQSeries for Windows NT 181
SHORTRTY attribute 93 stop force 116 example configurations 98
SHORTTMR attribute 94 stop immediate 360 listener backlog option 125, 132, 193,
side object STOPPED channel state 62, 65 340, 450
OS/400 452 stopped channels, restarting 69 OpenEdition MVS sockets 344
SINIX and DC/OSx configuration STOPPING channel state 62 products, in example
files 311 STRMQM command 109 configurations 98
SNA 4 StrucId field stanza of qm.ini file 637
configuration, Digital OpenVMS 281 MQCXP structure 591 stanza of QMINI file 637
listener process, ending 284 MQTXP structure 605 TCP connection
products, in example MQXWD structure 609 setting up
configurations 98 StrucLength field 574 OS/2 123
Server 127 structures OS/390 339
SNAplus2 223 MQCD 556 UNIX systems 191
SNAX communications examples 292 MQCXP 591 Windows NT 123
SO_KEEPALIVE MQTXP 605 TCP/IP 4
Digital OpenVMS 279 MQXWD 609 TCP/IP communications example 303
OS/2 126 SunLink Version 9.1 261 TCP/IP KEEPALIVE 66
OS/400 450 switching channels 617 Digital OpenVMS 279
UNIX systems 194, 279 synchronization queue, OS/390 343 UNIX systems 279
Windows NT 126 synchronizing channels 361, 506 TCP KEEPALIVE
softcopy books 662 syncpoint introduction 80
OS/2 126
source queue manager 3 SYSTEM.CHANNEL.INITQ queue
OS/400 450
splitting messages 59 Digital OpenVMS 305
UNIX systems 194
SPX 4 OS/2 305
Windows NT 126
connection OS/390 321, 343
TCPware 280
MQSeries for OS/2 Warp 160 OS/400 477
terminology used in this book 645
MQSeries for Windows NT 182 UNIX systems 305
test channel, OS/390 331
OS/2 123 Windows NT 305
SYSTEM.CHANNEL.REPLY.INFO testing connections, lookback testing 56
example configurations 98 time-out 84
KEEPALIVE, OS/2 132, 162 queue 321, 343
SYSTEM.CHANNEL.SYNCQ 343 TPNAME and TPPATH
products, in example
system extension 121, 448 OS/2 126
configurations 98
system extensions OS/400 451
stanza of qm.ini file 637
user-exit programs UNIX systems 194
Windows NT 123
Digital OpenVMS 121 Windows NT 126
stanza file 73
MQSeries for AS/400 448 TPNAME attribute 86
start
OS/2 121 TpName field 562
channel 61
Tandem NSK 121 transaction
Digital OpenVMS 110
UNIX systems 121 identifier, CICS 94
OS/2 110
Windows NT 121 program name 86
OS/390 330
system identifier, target 94 transactions
Tandem NSK 110
UNIX systems 110 CEDA 383
Windows NT 110 T CKMC 352
channel initiator, OS/390 327 target queue manager 3 CKSG 384
channel listener, OS/390 329 target system identifier 94 transmission header
DQM panels, OS/390 using TCP alias
CICS 352 channels, Tandem NSK 291 definition 26
option 357, 437 connection message exit program 515
STARTING channel state 62 listener backlog 125, 132, 193, message-retry exit program 516
startup dialog 506 340, 450 queue name 36
state, channel 62 MQSeries for AIX 209 transmission protocol 95

Index 677
transmission queue UDP transport-retry exit, worksheet (continued)
definition of 10 configuring 517 MQSeries for AS/400
example definition undeliverable message 71 configuration 459
Digital OpenVMS 307 user exit MQSeries for AT&T GIS UNIX
OS/2 307 data definition files 544 configuration 243
OS/390 347 MQCXP structure 591 MQSeries for HP-UX
OS/400 479 MQTXP structure 605 configuration 219
Tandem NSK 307 MQXWD structure 609 MQSeries for OS/2 Warp
UNIX systems 307 user-exit configuration 137
Windows NT 307 programs 616 MQSeries for OS/390
multiple message channels user-exit programs 505, 542 configuration 396
Digital OpenVMS 120 problem determination 616 MQSeries for Sun Solaris
MQSeries for AS/400 447 security levels 121 configuration 257
OS/2 120 system extension MQSeries for Windows NT
OS/390 using CICS 384 Digital OpenVMS 121 configuration 170
Tandem NSK 120 OS/2 121 writing your own message channel
UNIX systems 120 OS/400 448 agents 75
Windows NT 120 Tandem NSK 121 WRKCLS command 457
overflow 612 UNIX systems 121 WRKSBSD command 455
selecting 42 Windows NT 121
sharing 14 writing and compiling 518
transmission queue definition
example
user ID 95, 121
user identifier service 121
X
XMITQ attribute 94
Digital OpenVMS 308 user-written MCAs 75
XmitQName field 561
OS/2 308 USERDATA parameter 358, 384, 443
OS/390 348 OS/390 343
OS/400 481 USERID attribute 95
Tandem NSK 308 UserIdentifier field 566
UNIX systems 308
Windows NT 308
transmission queue name 94
transport-retry exit
V
validation
introduction 12
checks 612
transport-retry exit program 517
command 71
transport type 95
of user IDs 514
supported 4
panel data 71
TransportType field
values supplied by MQSeries for
MQCD structure 560
AS/400 435
MQTXP structure 606
values supplied by OS/390 using
triggered channels, problem
CICS 369, 372
determination 614
Version field
triggering
MQCD structure 558
channels 20
MQCXP structure 592
Digital OpenVMS 117
MQTXP structure 605
MQSeries for AS/400 443
MQXWD structure 609
OS/2 117
view
OS/390 343
activities
OS/390 using CICS 358
OS/390 using CICS 371
Tandem NSK 117
menu-bar choice 371
UNIX systems 117
VSAM 351
Windows NT 117
MCAs
OS/390 using CICS 384
TRPTYPE attribute 95 W
trusted applications 12, 121 WaitDesc parameter 553
type, bind 121 WAITING channel state 62
types of channel 81 wide-band links 31
Windows 3.1 client, channel-exit
U programs 524
Windows 95 and Windows 98 client,
UCD products, in example
configurations 98 channel-exit programs 524
UDP Windows Help 662
example configurations 98 work-with-channel choices 434
UDP connection work with channel status 432
MQSeries for AIX 209 work with status 437
setting up worksheet
UNIX systems 191 MQSeries for AIX configuration 197

678 MQSeries Intercommunication

Sending your comments to IBM
If you especially like or dislike anything about this book, please use one of the
methods listed below to send your comments to IBM.

Feel free to comment on what you regard as specific errors or omissions, and on
the accuracy, organization, subject matter, or completeness of this book.

Please limit your comments to the information in this book and the way in which
the information is presented.

To request additional publications, or to ask questions or make comments about

the functions of IBM products or systems, you should talk to your IBM
representative or to your IBM authorized remarketer.

When you send comments to IBM, you grant IBM a nonexclusive right to use or
distribute your comments in any way it believes appropriate, without incurring
any obligation to you.

You can send your comments to IBM in any of the following ways:
v By mail, to this address:
Information Development Department (MP095)
IBM United Kingdom Laboratories
Hursley Park
WINCHESTER,
Hampshire
United Kingdom
v By fax:
– From outside the U.K., after your international access code use
44–1962–870229
– From within the U.K., use 01962–870229
v Electronically, use the appropriate network ID:
– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL
™
– IBMLink : HURSLEY(IDRCF)
– Internet: [email protected]

Whichever you use, ensure that you include:

v The publication number and title
v The topic to which your comment applies
v Your name and address/telephone number/fax number/network ID.

© Copyright IBM Corp. 1993, 2000 679

IBMR

Printed in the United States of America

on recycled paper containing 10%
recovered post-consumer fiber.

SC33-1872-03
Spine information:

IBM MQSeries® MQSeries Intercommunication