What is MQSeries and how does it works?

loyalsockvillemobΔίκτυα και Επικοινωνίες

27 Οκτ 2013 (πριν από 3 χρόνια και 10 μήνες)

491 εμφανίσεις

Introduction

Programs_connected_to_the_same_QM

Programs_connected_to_different_QM

Channels_clusters_remote_queuing

Message_Queue_Interface

PCF_commands

PCF_commands_in_groups

Other_administration_interfaces

MQAI

MQBag_properties_and_methods

Programming_language
_considerations

ActiveX

Application_Integration_Segments

Platform_spacific_books

Cross_
product_books

What is MQSeries and how does it works?

The IBM MQSeries

range of products provides application programming services that enable programs to communicate with
each other using messages and queues. This form of communication is referred to as
asynchronous messaging. It provides
once
-
only delivery of messages. It means that you can separate application programs, so that the program sending a
message can continue processing without having to wait for a reply from the receiver. If the receiver, or

the communication
channel to it, is temporarily unavailable, the message can be forwarded at a later time. MQSeries also provides mechanisms
for generating acknowledgements of messages received.


The programs that comprise an MQSeries application can be
running on different computers, on different operating systems,
and at different locations. The applications are written using a common programming interface known as the Message Queue
Interface (MQI), so that applications developed on one platform can be
transferred to another.


Note:
Notice that configuration, administration and interfaces are
platform
-
specific. See

Platform_spacific_books

for more info.



Queue managers.

Queues are managed by a component cal
led a queue manager. The queue manager provides messaging services for the
applications and processes the MQI calls they issue. The queue manager ensures that messages are put on the correct queue
or that they are routed to another queue manager. Applica
tion must make a successful connection to a queue manager
before it can make any other MQI calls. When the application successfully makes the connection, the queue manager returns
a connection handle. This is an identifier that the application must specify

each time it issues an MQI call. An application can
connect to only one queue manager at a time, so only one connection handle is valid (for that particular application) at a ti
me.
When the application has connected to a queue manager, all the MQI calls i
t issues are processed by that queue manager
until it issues another MQI call to disconnect from that queue manager.


Opening a queue.

Before your application can use a queue for messaging, it must open the queue. If you are putting a message on a queue,
your application must open the queue for putting. Similarly, if you are getting a message from a queue, your application must

open the queue for getting. You can specify that a queue is opened for both getting and putting, if required. The queue
manager re
turns an object handle if the open request is successful. The application specifies this handle, together with the
connection handle, when it issues a put or a get call. This ensures that the request is carried out on the correct queue.

Putting and gettin
g messages.

When the open request is confirmed, your application can put a message on the queue. To do this, it uses another MQI call on
which you have to specify a number of parameters and data structures. These define all the information about the messag
e
you are putting, including the message type, its destination, which options are set, and so on. The message data (that is, th
e
application
-
specific contents of the message your application is sending) is defined in a buffer, which you specify in the MQI
call. When the queue manager processes the call, it adds a message descriptor, which contains information that is needed to
ensure the message can be delivered properly. The message descriptor is in a format defined by MQSeries; the message data
is defined

by your application (this is what you put into the message data buffer in your application code).


The program that gets the messages from the queue must first open the queue for getting messages. It must then issue
another MQI call to get the message

fr
om the queue. On this call, you have to specify which message you want to get.


The figure below shows that when two applications communicate using messages and queues, one
application puts a message on a queue, and the other application gets that message

from the queue.





Programs connected to the same queue manager:

This figure shows how messaging works in the simple case where the
program putting the message and the program getting the message
are both on the same computer and connected to the same q
ueue
manager.

Program A puts messages on the queue; program B gets messages
from the queue. In this case, the programs and the queue manager
are running on the same workstation.










Messaging using more than one queue manager.



The figure below show
s how messaging works where the program putting the message and the program getting the message
are on the different computers and are connected to different queue managers.


In this situation, you also need to create message channels to carry MQSeries me
ssages between the queue managers.


Programs connected to different queue managers

This figure shows how messaging works in the case where
the program putting the message and the program getting
the message are on different computers and are connected
to
different queue managers.

Program A makes an MQPUT call specifying not a local queue but a
local definition of a remote queue. This definition identifies a queue
on another queue manager. The queue manager to which program A
is connected puts the message
on a special queue called a
transmission queue. The message is then automatically sent along
the channel connecting the two queue managers. (If the channel is
running). The receiving queue manager puts the message on the
queue that was originally specified

by program A. This message is
stored on the queue until it is retrieved by program B, after program B
has issued an MQGET call.




Transactional Integrity.

MQSeries supports transactional messaging, which means that operations on messages can be grouped

i
nto ‘units of work’. A
unit of work is either committed in its entirety, or backed
-
out, so that it’s as if none of the operations took place. This means
that data is always in a consistent state.


For example, an application gets a message off a queue, pr
ocesses the data in the message and creates five further
messages, to be sent to other applications, all within one unit of work. If the output queue for the last of the five message
s is
temporarily full, then the application can back out the entire unit o
f work, so the input message that it got from the queue will
be returned to the queue, and the first four messages that were put onto output queues will be removed. After the back out, i
t’s
as if the application had never got the message in the first place
. The application can then try the processing again, at a later
time.


MQSeries can also coordinate units of messaging work with other transactional work, like database updates, so that message
data and database data remain completely in
-
sync at all times
.

Triggering.

The asynchronous nature of message queuing may mean that applications are idle for periods of

time when there are no messages to process. To avoid having idle processes consume system resources while there is no
work to do, MQSeries provides

a mechanism to ‘trigger’ applications to start when certain conditions are met.


Triggering works by defining a specific condition for an application’s queue, which when met, will cause the queue manager to

send a trigger message to an MQSeries queue cal
led an ‘initiation queue’. The trigger message is processed by a special
application called a trigger monitor, which reads the trigger message from the initiation queue and uses the information in t
he
message to decide which application to start to process

the messages on the application’s queue.


By using a trigger monitor you can have a single process that initiates many application processes to handle messages
arriving on many different queues, as required.



Thin Clients.

To save disk space to store th
e messages on queues thin clients are used. With thin clients applications can use the
same MQI programming interface, but without the need for a queue manager running on their local system. The thin client
sends the MQI call to a server machine over an MQ
Series channel. The work is performed by the server on behalf of the
client, and the results are passed back to the client. It’s very much like Remote Procedure Calls (RPC), but using MQSeries
channels.


Channels, clusters, and remote queuing.


A queue ma
nager communicates with another queue manager by sending a message and, if required, receiving back
a response. The receiving queue manager could be:



On the same machine



On another machine in the same location or on the other side of the world



Running o
n the same platform as the local queue manager



Running on another platform supported by MQSeries

These messages may originate from:



User
-
written application programs that transfer data from one node to another.



User
-
written administration applications
that use PCFs, the MQAI, or the ADSI



Queue managers sending:



Instrumentation event messages to another queue manager.



MQSC commands issued from a
runmqsc

command in indirect mode (where the commands are
run on another queue manager).

Before a message c
an be sent to a remote queue manager, the local queue manager needs a mechanism to detect
the arrival of messages and transport them, consisting of:



At least one channel



A transmission queue



A message channel agent (MCA)



A channel listener



A channel i
nitiator

A channel is a one
-
way communication link between two queue managers and can carry messages destined for any
number of queues at the remote queue manager.


Each end of the channel has a separate definition. For example, if one end is a sender or
a server, the other end
must be a receiver or a requester. A simple channel consists of a
sender channel definition

at the local queue
manager end and a
receiver channel definition

at the remote queue manager end. The two definitions must have the
same nam
e and together constitute a single channel.

If the remote queue manager is expected to respond to messages sent by the local queue manager, a second
channel needs to be set up to send responses back to the local queue manager.

Channels are defined using
the MQSC DEFINE CHANNEL command. In this chapter, the examples relating to
channels use the default channel attributes unless otherwise specified.

There is a message channel agent (MCA) at each end of a channel which controls the sending and receiving of
messages. It is the job of the MCA to take messages from the transmission queue and put them on the
communication link between the queue managers.

A transmission queue is a specialized local queue that temporarily holds messages before they are picked up
by the
MCA and sent to the remote queue manager. You specify the name of the transmission queue on a
remote queue
definition
.

Remote administration using clusters.


In a traditional MQSeries network using distributed queuing, every queue manager is indepe
ndent. If one queue
manager needs to send messages to another queue manager it must have defined a transmission queue, a channel
to the remote queue manager, and a remote queue definition for every queue to which it wants to send messages.

A
cluster

is a
group of queue managers set up in such a way so that the queue managers can communicate directly
with one another over a single network without the need for complex transmission queue, channels, and queue
definitions. Clusters can be set up easily, and typ
ically contain queue managers that are logically related in some way
and need to share data or applications.

Once a cluster has been created the queue managers within it can communicate with each other
without the need for
complicated channel or remote qu
eue definitions
. Even the smallest cluster will reduce system administration
overheads.

Establishing a network of queue managers in a cluster involves fewer definitions than establishing a traditional
distributed queuing environment. With fewer definition
s to make, you can set up or change your network more quickly
and easily, and the risk in making an error in your definitions is reduced.

To set up a cluster, you usually need one cluster sender (CLUSSDR) definition and one cluster receiver
(CLUSRCVR) def
inition per queue manager. You do not need any transmission queue definitions or remote queue
definitions. The principles of remote administration are the same when used within a cluster, but the definitions
themselves are greatly simplified.


Configuring

communication links.

In MQSeries the logical communication links are called
channels
. You set up channel definitions at each end of your
link so that your MQSeries application on the MQSeries client can communicate with the queue manager on the
server.

Be
fore you define your MQI channels:


1.

Decide on the form of communications you are going to use.

2.

Define the connection at each end:



Configure the connection.



Record the values of the parameters that you will need for the channel definitions later on.



Ena
ble the server to detect incoming network requests from your MQSeries client. This involves
starting a
listener
.


There are six types of communication for MQSeries on different platforms:



DECnet



LU 6.2



NetBIOS



SPX



TCP



UDP

Note:
UDP is not supported

for client to server communication. It is supported for peer
-
to
-
peer communication only.

When you define your MQI channels, each channel definition must specify a Transmission protocol (Transport Type)
attribute. A server is not restricted to one protoco
l, so different channel definitions can specify different protocols. For
MQSeries clients, it may be useful to have alternate MQI channels using different transmission protocols.

Your choice of transmission protocol also depends on your particular combina
tion of MQSeries client and server
platforms. The possible combinations are shown in the following table.

http://www
-
4.ibm.com/software/ts/mqseries
/library/manuals99/csqzaf/csqzaf03.htm
-

FT_TBLCOMMS


Defining a TCP/IP connection


The steps to take are detailed in the sections that follow:

On the MQSeries client

Initialize TCP/IP

On the server

There are three things to do:

3.

Decide on a port numb
er.

The port to connect to will default to 1414. Port number 1414 is assigned by the Internet Assigned
Numbers Authority to MQSeries.

4.

Initialize TCP/IP, and record the network address of the server machine.

5.

Configure files (or run a command) to specify
the port number and to run a listener program (non
-
OS/390). On OS/390, start a channel initiator and a listener.

TCP/IP connection limits

On any platform, there is a limit to the number of outstanding connection requests that can be queued at a single
TCP/
IP port. These backlog values are shown in the following table:

http://www
-
4.ibm.com/software/ts/mqseries/library/manuals99/csqzaf/csqzaf03.htm
-

FT
_Table_3

Server platform

Maximum connection requests

AIX Version 4.2 or later

100

AS/400

255

AT&T GIS UNIX

5

Digital OpenVMS

5

HP
-
UX

20

OS/2

10

OS/390

255

Sun Solaris

100

SINIX and DC/OSx

5

Tandem NSK

5

VSE/ESA

5

Windows NT Server

100

Windows NT Workstation

5

If the connection limit is reached, the client will receive an MQRC_Q_MGR_NOT_AVAILABLE message from the
MQCONN call, and an AMQ9202 error in the client error log (mqm
\
errors
\
amqerr0n.log). If the cl
ient retries the
MQCONN, it may be successful.

To avoid error messages being generated by this limitation, you can define multiple ports with only one queue
manager, or with multiple queue managers.

TCP/IP on an MQSeries client (any platform)


Initialize

TCP/IP.

The channel definitions that you create later will include the network address and port number of the server to which
the MQSeries client is sending.

If you want to use the KEEPALIVE option you need to create a queue manager configuration file (
QM.INI) and add
the following entry to it:


TCP:


KeepAlive=yes

Store the QM.INI file in the appropriate directory, depending upon the platform:



OS/2, Windows 95, Windows 98, Windows NT:

<drive>:
\
<dir>
\
mqm



DOS, Windows 3.1, WIN
-
OS/2:

The root direc
tory of the drive where the client is installed



Unix systems:

/var/mqm

Note for Windows NT users:
On Windows NT this information is in the registry. For more information, see the
MQSeries Information Center.

TCP/IP on an OS/2 server


First initialize TC
P/IP, and record the network address of the server machine (displayed in a box as TCP/IP
initializes).

Then there are two alternative methods; using INETD or using the Run Listener (RUNMQLSR) command:

Using INETD

First type:

SET ETC

This will return the

path to the
ETC

subdirectory.

To use
INETD

to start MQI channels, configure files as follows, where in this case the path is taken to be
TCPIP
:.
Note that this is case sensitive and the entries in the two files must match.



To TCPIP
\
ETC
\
SERVICES (or MPTN
\
ETC
\
SERVICES) add the line:

MQSeries 1414/tcp

where 1414, the default, is the port number required.

Alternatively, you may want to use another port, for example, port number 1822, in which case you add the
line:

MQSeries 1822/tcp



To TCPIP
\
ETC
\
INETD.LST, add the line:

MQSeries tcp C:
\
MQM
\
BIN
\
AMQCRSTA [
-
m QMName]

The part in square brackets is optional and is not required for the default queue manager. If your MQSeries
for OS/2 was not installed on the C drive, replace the C: above with th
e correct drive letter.

It is possible to have more than one queue manager on the server machine. Add a line to each of the two files, as
above, for each queue manager. For example:

MQSeries1 1414/tcp

MQSeries2 1415/tcp



MQSeries1 tcp C:
\
MQM
\
BIN
\
AMQCRSTA
-
m QM1

MQSeries2 tcp C:
\
MQM
\
BIN
\
AMQCRSTA
-
m QM2

Now stop and then start the inetd program, before continuing.

Note:
There is a limit to the number of outstanding connection requests that can be queued at a single TCP/IP port.

Using the
Run Listener (RUNMQLSR) command

To run the Listener supplied with MQSeries for OS/2, which starts new MQI channels as threads, use the
RUNMQLSR command. For example:

RUNMQLSR
-
t tcp [
-
m QMNAME] [
-
p 1822]

The square brackets indicate optional pa
rameters:

-
m QMNAME

is not required for the default queue manager.

-
p 1822

is not required if the default port number 1414 is used.

It is possible to have more than one queue manager running on the server machine. Start a listener program for each
one,
on different ports. For example:

RUNMQLSR
-
t tcp

RUNMQLSR
-
t tcp
-
m QM2
-
p 1415

Note:
There is a limit to the number of outstanding connection requests that can be queued at a single TCP/IP port.

TCP/IP on a Windows NT server


TCP/IP is initial
ized automatically as a service during Windows NT startup, but first define the port number as follows.

To the file c:
\
winnt
\
system32
\
drivers
\
etc
\
services, add the line:

MQSeries 1414/tcp

where 1414, the default, is the port number required.

(On so
me versions the path is c:
\
winnt35
\
system32
\
drivers
\
etc
\
services)

Alternatively, you may want to use another port, for example, port number 1822, in which case you add the line:

MQSeries 1822/tcp

It is possible to have more than one queue manager on

the server machine. Add a line, as above, for each queue
manager. For example:

MQSeries1 1414/tcp

MQSeries2 1415/tcp

Note:
There is a limit to the number of outstanding connection requests that can be queued at a single TCP/IP port.

Using the Run

Listener (RUNMQLSR) command

To run the Listener supplied with MQSeries for Windows NT, which starts new MQI channels as threads, use the
RUNMQLSR command. For example:

RUNMQLSR
-
t tcp [
-
m QMNAME] [
-
p 1822]

The square brackets indicate optional

parameters:

-
m QMNAME

is not required for the default queue manager.

-
p 1822

is not required if the default port number 1414 is used.

It is possible to have more than one queue manager running on the server machine. Start a listener program for each
on
e, on different ports. For example:

RUNMQLSR
-
t tcp

RUNMQLSR
-
t tcp
-
m QM2
-
p 1415

TCP/IP on a UNIX system server


Note:
The name of the installation directory on your UNIX system is represented here by
mqmtop
.

Configure the
inetd

daemon on th
e server, so that
inetd

will start the MQI channels. Log on as root and configure the
following files:

6.

Add a line in the /etc/services file:
MQSeries 1414/tcp


where 1414, the default, is the port number required.

Alternatively, you may want to use a dif
ferent port, for example, port number 1822 in which case add the
line:

MQSeries 1822/tcp

7.

Add a line (case sensitive) in the inetd.conf file to call the program
amqcrsta
:

MQSeries stream tcp nowait mqm /
mqmtop
/bin/amqcrsta amqcrsta [
-
m QM1]

where
QM1

is the queue manager name, not required for the default queue manager.

8.

The updates are active after you issue the following commands from the root user ID:

On AIX:

inetimp

refresh
-
s inetd

On other UNIX systems:

kill
-
1 <process number of inetd daemon
>

It is possible to have more than one queue manager on the server machine. Add a line to each of the two files, as
above, for each queue manager. For example, in /etc/services:

MQSeries1 1414/tcp

MQSeries2 1415/tcp

and in the inetd.conf file:

MQ
Series1 stream tcp nowait mqm /
mqmtop
/bin/amqcrsta amqcrsta
-
m QM1

MQSeries2 stream tcp nowait mqm /
mqmtop
/bin/amqcrsta amqcrsta
-
m QM2

Note:
There is a limit to the number of outstanding connection requests that can be queued at a single TCP/IP port.

Usi
ng the Run Listener (RUNMQLSR) command

To run the Listener supplied with MQSeries for UNIX systems, which starts new MQI channels as threads, use the
RUNMQLSR command. For example:

RUNMQLSR
-
t tcp [
-
m QMNAME] [
-
p 1822]

The square brackets indic
ate optional parameters:

-
m QMNAME

is not required for the default queue manager.

-
p 1822

is not required if the default port number 1414 is used.

It is possible to have more than one queue manager running on the server machine. Start a listener program

for each
one, on different ports. For example:

RUNMQLSR
-
t tcp

RUNMQLSR
-
t tcp
-
m QM2
-
p 1415

TCP/IP on an AS/400 server


TCP/IP is normally initialized automatically as a service during AS/400 startup.

Use the Start Listener (STRMQMLSR) comm
and to enable the MQSeries server to receive incoming client
connections.

By default, the MQSeries for AS/400 TCP/IP listener program uses port 1414.

Note:
There is a limit to the number of outstanding connection requests that can be queued at a single T
CP/IP port.


Defining an LU 6.2 connection


The steps to take are detailed in the sections that follow:

On the MQSeries client

9.

Configure SNA.

10.

Set TpName and TpPath.

11.

Establish a valid SNA session between the MQSeries client and server machines.

On the
server

1.

Start a listener, or create a listening attachment (non
-
OS/390).

2.

Start a channel initiator and a listener (OS/390).

LU 6.2 on an OS/2 MQSeries client


First configure SNA so that an LU 6.2 conversation can be established between the MQSeries clie
nt machine and the
server machine. See the book
Multiplatform APPC Configuration Guide
. This is supplied online with some MQSeries
products as
APPC Configuration Guide (Red Book)

for information.

Set the Transaction Program name (TpName or TPNAME) as show
n in the following table:

http://www
-
4.ibm.com/software/ts/mqseries/library/manuals99/csqzaf/csqzaf03.htm
-

FT_Table_4

Server platform

T
PNAME

OS/2

As specified in the OS/2 Run Listener command on the server, or defaulted
from the OS/2 queue manager configuration file on the server.

Windows NT

As specified in the Windows NT Run Listener command, or the invokable
Transaction Program th
at was defined using TpSetup on Windows NT.

Other UNIX systems

The same as the corresponding TpName in the side information on the
remote queue manager on the server.

AS/400

The same as the compare value in the routing entry on the AS/400 system.

T
andem NSK

As specified in the channel definition on the server.

OS/390

The same as the corresponding TpName in the side information on the
remote queue manager on the server.

Establish a valid session between the two machines. You can specify the loc
al LU that MQSeries for OS/2 will use,
either by creating the MQSeries client configuration file (QM.INI), or as an environment variable. An entry in the
configuration file takes precedence over the environment variable. For an MQSeries client on OS/2 the
QM.INI file is
located in directory C:
\
MQM.

In the QM.INI file, under the LU 6.2 section add the line:

LocalLU = Your_LU_Name

or specify the environment variable:

SET APPNLLU=Your_LU_Name

If nothing has been specified, your default LU will be used.

Fin
d out the name of the partner LU alias, as defined in the MQSeries client machine's Communications Manager/2
profile. You will need this later, when you define the MQI channels
-

it is the Connection name (CONNAME).

SECURITY PROGRAM is always used when MQ
Series for OS/2 attempts to establish an SNA session if a password
and user ID are specified. Otherwise SECURITY NONE is used.

LU 6.2 on an OS/2 server


Start the listener program with the RUNMQLSR command, giving the TpName to listen on, or use Attach Ma
nager in
Communications Manager/2.

Using the RUNMQLSR command

Here is an example of a command to start the listener:

RUNMQLSR
-
t LU62
-
n RECV [
-
m QMNAME]

where
RECV

is the TpName that is specified in the client channel definition at the MQSeri
es client end (as the
"TpName to start on the remote, or server, 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 the server machine. Assi
gn a different TpName to
each queue manager, and then start a listener program for each one. For example:

RUNMQLSR
-
t LU62
-
m QM1
-
n TpName1

RUNMQLSR
-
t LU62
-
m QM2
-
n TpName2

Using Communications Manager/2


You can use Attach Manager in Commun
ications Manager/2 to start the listener program. You must supply a
Transaction program (TP) definition specifying:



TP name



program path and file name



program parameter string

You can do this using the panel configuration in Communications Manager/2, o
r you can edit your NDF file directly
(see the heading "Define Transaction Programs" in the online
APPC Configuration Guide (Red Book)
).

Panel configuration:
These are the entries required on the TP definition panel:

Transaction Program (TP) name : AMQ
CRS6A

OS/2 program path and file name: c:/mqm/bin/amqcrs6a.exe

Program parameter string :
-
n AMQCRS6A

Note:
The above is for the default queue manager, for other queue managers include
-
m QMNAME

in the Program
parameter string.

NDF file configurat
ion:

Your node definitions file (.ndf) must contain a
define_tp command
. The following example shows what to include:

define_tp


tp_name(AMQCRS6A)


filespec(c:/mqm/bin/amqcrs6a.exe)


parm_string(
-
n AMQCRS6A)

Note:
The above is for the default queue ma
nager, for other queue managers include
-
m QMNAME

in the
parm_string.

LU 6.2 on a Windows NT MQSeries client


First configure SNA to allow an LU 6.2 conversation to be established between the MQSeries client machine and the
server machine.

Set the Transa
ction Program name (TpName or TPNAME) as shown in the following table:

Table 5. Settings on the MQSeries client Windows NT system for a server platform

Server platform

TPNAME

OS/2

As specified in t
he OS/2 Run Listener command on the server, or defaulted
from the OS/2 queue manager configuration file on the server.

Windows NT

As specified in the Windows NT Run Listener command, or the invokable
Transaction Program that was defined using TpSetup on

Windows NT.

Other UNIX systems

The same as the corresponding TpName in the side information on the
remote queue manager on the server.

AS/400

The same as the compare value in the routing entry on the AS/400 system.

Tandem NSK

As specified in the
channel definition on the server.

OS/390

The same as the corresponding TpName in the side information on the
remote queue manager on the server.

Create a CPI
-
C Side Object (symbolic destination) and record this name to use later in your channel defini
tions as the
Connection name (CONNAME).

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

SECURITY PROGRAM is used, where supported by CPI
-
C, when MQSeries attempts to establish an SNA session.

LU 6.2 on a Windows NT server


You can use either of these methods:



Start the listener program with the RUNMQLSR command, giving the TpN
ame to listen on. This starts a
thread to process each inbound client connection.



Use one of the SNA servers listed to set up an invokable transaction program (TP). Then
invoke amqcrs6a as a separate process for each client connection. The TpName should
m
atch that specified in the CPI
-
C side object information referenced by CONNAME in
the client
-
connection channel definition. 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 MQSeries client end as the "TpName to start on the remote side
(server)". 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 ma
nager running on the server machine. Assign a different TpName to
each queue manager, and then start a listener program for each one. For example:

RUNMQLSR
-
t LU62
-
m QM1
-
n TpName1

RUNMQLSR
-
t LU62
-
m QM2
-
n TpName2

Using an SNA server

You can

use TpSetup (from the SNA Server SDK) to define amqcrs6a as an invokable TP, or set various registry
values manually.

LU 6.2 on a UNIX system MQSeries client


First configure SNA so that an LU 6.2 conversation can be established between the MQSeries clie
nt machine and the
server machine. See the online book
APPC Configuration Guide (Red Book)

for information, or for Sun Solaris see
the book
Sunlink P2P LU 6.2 Programmer's Guide
.

Set the Transaction Program name (TpName or TPNAME) as shown in the followin
g table:

Table 6. Settings on the MQSeries client UNIX system for a server platform

Server platform

TPNAME

OS/2

As specified in the OS/2 Run Listener command on the server, or defaulted
from the OS
/2 queue manager configuration file on the server.

Windows NT

As specified in the Windows NT Run Listener command, or the invokable
Transaction Program that was defined using TpSetup on Windows NT.

Other UNIX systems

The same as the corresponding TpN
ame in the side information on the
remote queue manager on the server.

AS/400

The same as the compare value in the routing entry on the AS/400 system.

Tandem NSK

As specified in the channel definition on the server.

OS/390

The same as the correspo
nding TpName in the side information on the
remote queue manager on the server.

Create a CPI
-
C Side Object (symbolic destination) and record this name to use later in your channel definitions as the
Connection name (CONNAME).

On Sun Solaris, set the env
ironment variable APPC_LOCAL_LU to refer to the name of your Local LU.

On SINIX create a XSYMDEST entry in the TRANSIT KOGS file:

XSYMDEST sendMP01,


RLU = forties,


MODE = MODE1,


TP

= recvMP01,


TP
-
TYP = USER,


SEC
-
TYP = NONE

On DC/OSx create an entry in the /etc/opt/lu62/cpic_cfg file:

sendMP01 <local LU name> <remote LU name> <mode name> <remote TP name>

On other UNIX systems, i
n the CPI
-
C Side Object enter the Partner LU Name at the receiving machine, the TpName
and the Mode Name. For example:

Partner LU Name OS2ROG2

Remote TP Name recv

Service Transaction Program no

Mode Name #INT
ER

SECURITY PROGRAM is used, where supported by CPI
-
C, when MQSeries attempts to establish an SNA session.

LU 6.2 on a UNIX server


On the server create a TPN profile. In the TPN profile, enter the full path to the executable and the Transaction
program n
ame. For example:

Full path to TPN executable /
mqmtop
/bin/amqcrs6a

Transaction Program name recv

User ID 0

On SINIX create an XTP entry in the TRANSIT KOGS file:

XTP recvMP01,


UID = guenther,



TYP = USER,


PATH = /home/guenther/recvMP01.sh,


SECURE = NO

The file /home/guenther/recvMP01.sh contains:

#!/bin/ksh

#

# script to start the receiving side for the qmgr MP01

#

exec /opt/mqm/bin/amqcr
s6a
-
m <queue manager>

You cannot use LU 6.2 for an MQSeries server running on DC/OSx because the DC/OSx SNA implementation does
not support the ACCEPT verb (use TCP/IP instead).

The
User ID

field may specify a user who is a member of the mqm group.

You
may require to use a queue manager other than the default queue manager. If so, define a command file that
includes:

amqcrs6a
-
m Queue_Man_Name

and call the command file.

LU 6.2 on an AS/400 server


Use ADDRTGE command to add a routing entry to a subsyst
em at the initiated end to enable the initiating end to
start the channel. The routing entry specifies the program that is invoked when the channel starts.

Alternatively, create and start a new subsystem by using the Work with Subsystem Descriptions (WRKS
BSD) panel.

The ADDRTGE panel is shown in
Figure 3
.

Figure 3. LU 6.2 communication setup panel
-

initiated end

+
-----------------------------------------------------------------
---------------
+

| Add Routing Entry (ADDRTGE) |

| |

| Type choices, press Enter.

|

| |

| Subsystem description . . . . . QSNADS 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

. . . . . . . . . . . QMQM Name, *LIBL, *CURLIB |

| Class . . . . . . . . . . . . . *SBSD Name, *SBSD |

| Library . . . . . . . . . . . *LIBL Name, *LIBL, *CURLIB |

| Maximum active r
outing steps . . *NOMAX 0
-
1000, *NOMAX |

| Storage pool identifier . . . . 1 1
-
10 |

| |

|

|

| |

| Bottom |

| F3=Exit F4=Prompt F5=Refre
sh F12=Cancel F13=How to use this display |

| F24=More keys |

| |

+
--------------------------------------
------------------------------------------
+

Subsystem description

The name of your subsystem where this definition resides. Use the AS/400 WRKSBSD command to view and
update the appropriate subsystem description for the routing entry.

Routing entry seque
nce number

A unique number in your subsystem to identify this communication definition. It may be set to a number from 1 to
9999.

Comparison data: compare value

A text string to compare with that received when the session is started by
transaction progr
am

parameter. The
value can be any unique string. 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 s
tarting position field is the character position in the string for comparison, and this is always 37.

Program to call

The name of program that runs the inbound message program to be called to start the session.

Note:
AMQCRC6A is a program supplied with
MQSeries for AS/400 that sets up the environment and then calls
AMQCRS6A.

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 specif
ies the job priority. Specify an appropriate class
entry. 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 Program
ming:
Work Management Guide
.

Defining a NetBIOS connection


The steps to take are detailed in the sections that follow:

On the client

Define a local NetBIOS name for the client.

On the server

12.

Define a local NetBIOS name for the server.

13.

Start a listen
er program.

NetBIOS on an MQSeries client (any suitable platform)


Define a local NetBIOS name for the client.

The local NetBIOS name that the MQSeries processes use can be specified in two ways on the MQSeries client. In
order of precedence they are:

3.

T
he
MQNAME

environment variable

SET MQNAME=Your_env_Name


4.

A queue manager configuration file (QM.INI) parameter.

If you want to use this method, you need to create a QM.INI file and add the following entry to it:

NETBIOS:


LocalName = Your_env_Name

Stor
e the QM.INI file in the appropriate directory, depending on the platform:

OS/2, Windows 95, and Windows 98

<drive>:
\
<dir>
\
mqm


DOS, Windows 3.1, WIN
-
OS/2

The root directory of the drive where the MQSeries client is installed, or where the MQDATA
enviro
nment variable points.

Note for Windows NT users:
On Windows NT this information is in the registry. For more information, see
the MQSeries Information Center.

Note:
For use with Novell NetBIOS emulation, or with NetBIOS on Windows NT, each MQSeries proc
ess should use a
different local NetBIOS name.

NetBIOS on an OS/2 server


Define a local NetBIOS name for the server.

The local NetBIOS name that the MQSeries processes use can be specified in three ways on the server. In order of
precedence they are:

1.

T
he
-
l

parameter on the RUNMQLSR command

2.

The
MQNAME

environment variable

SET MQNAME=Your_env_Name

3.

A queue manager configuration file (QM.INI) parameter. QM.INI is located in
\
mqm
\
qmgrs
\
QueueManagerName


The entry in QM.INI is:

NETBIOS:


LocalName = Your
_env_Name

Note:
For use with Novell NetBIOS emulation each MQSeries process should use a different local NetBIOS name.

Start a listener program

Start the listener program with the RUNMQLSR command, optionally giving the local NetBIOS name (
LOCALNAME
)
to l
isten on. For example:

RUNMQLSR
-
t netbios [
-
m QMNAME] [
-
s Sessions]

[
-
e NAMES] [
-
o COMMANDS] [
-
l LOCALNAME]


Note:
Both sending end (MQSeries client) and receiving end (server)
must

have a local NetBIOS name defined. You
are strongly advised t
o make sure that all NetBIOS names used are unique in the network. If this is not done,
unpredictable results may occur.

NetBIOS on a Windows NT server


Define a local NetBIOS name for the server.

The local NetBIOS name that the MQSeries processes use ca
n be specified in three ways on the server. In order of
precedence they are:

14.

The
-
l

parameter on the RUNMQLSR command. This defines the NetBIOS station name to be used with that
instance of RUNMQLSR.

15.

The
MQNAME

environment variable

SET MQNAME=Your_env_N
ame

16.

A parameter in the registry.

The entry in the registry is:

NETBIOS:


LocalName = Your_env_Name

Note:
For use with NetBIOS on Windows NT each MQSeries process should use a different local NetBIOS name; if
you are running multiple MQSeries application
s simultaneously on the MQSeries client, they must use different
NetBIOS names set using the environment variable MQNAME.

Start a listener program

Start the listener program with the RUNMQLSR command, optionally giving the local NetBIOS name (
LOCALNAME
)
t
o listen on. For example:

RUNMQLSR
-
t netbios [
-
m QMNAME] [
-
s Sessions]

[
-
e NAMES] [
-
o COMMANDS] [
-
l LOCALNAME]


Defining an SPX connection


The steps to take are detailed in the sections that follow:

On the client

No action is required until

you create the channel definitions.

On the server

17.

Decide on a socket number.

The socket to connect to defaults to 5E86. The default can be changed by adding a socket parameter to
the qm.ini file or, for Windows NT, the registry (see

http://www
-
4.ibm.com/software/ts/mqseries/library/manuals99/csqzae/csqzae6o.htm
-

HDRINSTAN

18.

Determine the IPX/SPX network address and the node (LAN adapter address) of

the server machine.

19.

Start a listener, specifying the chosen socket.

SPX on an MQSeries client (any suitable platform)


There is no action required now other than to make sure that SPX is running on your client machine.

The channel definitions that you
create later will include the SPX network address, node address, and socket number
of the server to which the MQSeries client is sending.

SPX on an MQSeries server (OS/2 or Windows NT)


Find out and record the IPX/SPX network address of the server. Your n
etwork administrator has this information.

Record the node (LAN adaptor address) of the server machine.

Using the Run Listener (RUNMQLSR) command

To run the listener supplied with MQSeries, which starts new MQI channels as threads, use the RUNMQLSR
comma
nd. For example:

RUNMQLSR
-
t spx [
-
m QMNAME] [
-
x 5E87]

The square brackets indicate optional parameters:

-
m QMNAME

is not required for the default queue manager.

-
x 5E87

is not required if the default socket number 5E86 is used.

It is possib
le to have more than one queue manager running on the server machine. Start a listener program for each
one, on different socket numbers. For example:

RUNMQLSR
-
t spx

RUNMQLSR
-
t spx
-
m QM2
-
x 5E87

SPX and IPX parameters

You may need to modify
some of the default SPX or IPX parameters of your environment to tune its use for
MQSeries. In most cases the default settings will be fine. The actual parameters, and the method of changing them
vary according to your platform and the provider of the SPX
communications support. The following describes some
of these parameters, particularly where they could influence the operation of MQSeries channels and client
connections.

SPX on an OS/2 client

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.

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 contro
ls 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, it sends a packet to the receiving end. It then waits for the listen timeout for a
response. If one is still not received, another packet is sent and a response is expected within the abort
timeout period.

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 on a DOS or Windows 3.1 client


Please refer to the Novell Client for DOS and 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 c
an affect MQSeries SPX channels
and client connections.

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 depen
ding on the number of
MQSeries channels or client connections you need to run.

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 requi
rements 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 on a Windows NT client


Please refer to the Micro
soft documentation for full details of the use and setting of the NWLink SPX and IPX
parameters. The IPX/SPX paramters are in the following paths in the registry:

HKEY_LOCAL_MACHINE
\
SYSTEM
\
CurrentControlSet
\
Service
\
NWLinkSPX
\
Parameters

HKEY_LOCAL_MACHINE
\
SYSTEM
\
CurrentControlSet
\
Service
\
NWLinkIPX
\
Parameters

SPX on an MQSeries client for Windows 95 and Windows 98

Please refer to the Microsoft documentation for full details of the use and setting of the SPX and IPX parameters.
They are accessed by selecting
Network option in the control panel, then double clicking on IPX/SPX Compatible
Transport.

Defining a DECnet connection


The steps to take are detailed in the sections that follow:

On the client

No action is required until you create the channel definit
ions

On the server

20.

Decide on an object number or task name

21.

Determine the nodename of the server machine

22.

Configure a DECnet object

DECnet on an MQSeries client

There is no action required now other than to make sure that DECnet is running on your clien
t machine.

The channel definitions that you create later will include the DECnet nodename and object number, or task name, of
the server to which the MQSeries client is sending
.

DECnet on an MQSeries server (Digital OpenVMS)

Decide on an object number or

task name.

Find out and record the nodename of the server. Your network administrator has this information.

Receiving on DECnet Phase IV

To use DECnet Phase IV to start channels, you must configure a DECnet object as follows:

5.

Create a file which has th
e DCL command to start the DECnet receiver program, amqcrsta.exe. Place this
file in the SYS$MANAGER directory as follows:


$ create sys$manager:mqrecvdecnet.com


$ mcr amqcrsta.exe [
-
m Queue_Man_Name]
-
t DECnet


Ctrl
-
Z


$

Note:
If you have m
ultiple queue managers you
must

make a new file and DECnet object for each queue
manager.

6.

Create a DECnet object to start the receiving channel program automatically:

$ 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


(note: y
ou must supply the correct password for MQM)

Account (1
-
39 characters):

Proxy access (INCOMING, OUTGOING, BOTH, NONE, REQUIRED):

NCP> set known objects all

NCP> exit

Not
e:

The preceding example should be amended to use proxy user identi
fiers 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
.

7.

Ensure that all known objects are set when
DECnet is started.

Receiving on DECnet OSI

Configure for MQSeries channel objects:

4.

Start the NCL configuration interface:


$ MC NCL


NCL>

5.

Create a session control application entity:


NCL> create session control application MARK


NCL> set sess
con app MARK address {name=MARK{


NCL> set sess con app MARK image name
-


_ SYS$SPECIFIC:[MQS_SERVER]MARK.COM


NCL> set sess con app MARK user name "MQM"


NCL> set sess con app MARK node synonym true




NCL> show sess con app MARK all [character
istics]

Note that user
-
defined values are in uppercase.

6.

Create the com file (MARK.COM above) as for DECnet Phase IV.

7.

The log file for the object is net$server.log in the sys$login dir for the user name specified for the application.

8.

The MQSC configurati
on for conname, as for DECnet PhaseIV, is:


NODE(APP_OR_OBJ_NAME)


Message Queue interface (MQI).

MQI Calls.


The calls in the MQI can be grouped as follows:

MQCONN, MQCONNX, and MQDISC

Use these calls to connect a program to (with or without options)
, and disconnect a program from, a queue manager.
If you write CICS programs for OS/390, or VSE/ESA, you do not need to use these calls. However, you are recommended to
use them if you want your application to be portable to other platforms.

MQOPEN and MQ
CLOSE

Use these calls to open and close an object, such as a queue.

MQPUT and MQPUT1

Use these calls to put a message on a queue.

MQGET

Use this call to browse messages on a queue, or to remove messages from a queue.

MQINQ

Use this call to inquire a
bout the attributes of an object.

MQSET

Use this call to set some of the attributes of a queue. You cannot set the attributes of other types of object.

MQBEGIN, MQCMIT, and MQBACK

Use these calls when MQSeries is the coordinator of a unit of work. MQBE
GIN starts the unit of work. MQCMIT and
MQBACK end the unit of work, either committing or rolling back the updates made during the unit of work. OS/400
commitment controller is used to coordinate global units of work on AS/400. Native start commitment cont
rol, commit, and
rollback commands are used.


PCF commands.

MQSeries PCF commands can be used to simplify queue manager administration and other network administration.
PCF commands allow you to use a single application to perform network administration f
rom a single queue manager within
the network.

PCFs define command and reply messages that can be exchanged between a program and any queue manager
(that supports PCFs) in a network. You can use PCF commands in a systems management application program for

administration of MQSeries objects: queue managers, process definitions, queues, and channels. The application can operate
from a single point in the network to communicate command and reply information with any queue manager, local or remote,
via the loc
al queue manager. Each queue manager has an administration queue with a standard queue name and your
application can send PCF command messages to that queue. Each queue manager also has a command server to service the
command messages from the administrati
on queue. PCF command messages can therefore be processed by any queue
manager in the network and the reply data can be returned to your application, using your specified reply queue. PCF
commands and reply messages are sent and received using the normal M
essage Queue interface (MQI).

Each command and its parameters are sent as a separate command message containing a PCF header followed by a number
of parameter structures. The PCF header identifies the command and the number of parameter structures that fo
llow in the
same message. Each parameter structure provides a parameter to the command.

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

The queue to which the PCF commands are sent is always called the
SYSTEM.ADMIN.COMMAND.QUEUE
. The command
server servicing this queue sends the replies to the queue defined by

the
ReplyToQ

and
ReplyToQMgr

fields in the message
descriptor of the command message.

How to issue PCF command messages

Use the normal Message Queue Interface (MQI) calls, MQPUT, MQGET and so on, to put and retrieve PCF
command and response messages to a
nd from their respective queues. In response to each command, the command server
generates one or more response messages. A response message has a similar format to a command message; the PCF
header has the same command identifier value as the command to w
hich it is a response.


PCF commands and responses in groups.

Queue Manager commands.

Change Queue Manager

The Change Queue Manager (MQCMD_CHANGE_Q_MGR) command changes the specified attributes of the queue
manager.

This PCF is supported on all platforms.


For any optional parameters that are omitted, the value does not change.

Required parameters:

None

Optional parameters:

Force
,
QMgrDesc
,
TriggerInterval
,
DeadLetterQName
,
MaxHandles
,
MaxUncommittedMsgs
,
DefXmitQName
,
AuthorityEvent
,
InhibitEvent
,
Loc
alEvent
,
RemoteEvent
,
StartStopEvent
,
PerformanceEvent
,
MaxMsgLength
,
ChannelAutoDef
,
ChannelAutoDefEvent
,
ChannelAutoDefExit

ClusterWorkloadExit
,
ClusterWorkloadData
,
ClusterWorkloadLength
,
RepositoryName
,
RepositoryNamelist
,
CodedCharSetId


Inquire Queue

Manager


The Inquire Queue Manager (MQCMD_INQUIRE_Q_MGR) command inquires about the attributes of a queue manager.

This PCF is supported on all platforms.

Required parameters:

None

Optional parameters:

QMgrAttrs



Ping Queue Manager


The Ping Queue M
anager (MQCMD_PING_Q_MGR) command tests whether the queue manager and its command server is
responsive to commands. If the queue manager is responding a positive reply is returned.

This PCF is supported on all platforms.

Required parameters:

None

Optio
nal parameters:

None

Namelist commands.

Change Namelist


The Change Namelist (MQCMD_CHANGE_NAMELIST) command changes the specified attributes of an existing MQSeries
namelist definition.

This PCF is supported if you are using AIX, HP
-
UX, OS/2, Sun Solar
is, or Windows NT only.

For any optional parameters that are omitted, the value does not change.

Required parameters:

NamelistName


Optional parameters:

NamelistDesc
,
Names


Delete Namelist

The Delete Namelist (MQCMD_DELETE_NAMELIST) command deletes an

existing MQSeries namelist definition.

This PCF is supported if you are using AIX, HP
-
UX, OS/2, Sun Solaris, and Windows NT only.

Required parameters:

NamelistName


Optional parameters:

None


Inquire Namelist


The Inquire Namelist (MQCMD_INQUIRE_NAME
LIST) command inquires about the attributes of existing MQSeries namelists.

This PCF is supported if you are using AIX, HP
-
UX, OS/2, Sun Solaris, and Windows NT only.

Required parameters:

NamelistName


Optional parameters:

NamelistAttrs


Process comman
ds

Change Process


The Change Process (MQCMD_CHANGE_PROCESS) command changes the specified attributes of an existing MQSeries
process definition.

This PCF is not supported if you are using MQSeries for Windows Version 2.1.

For any optional parameters tha
t are omitted, the value does not change.

Required parameters:

ProcessName


Optional parameters:

ProcessDesc
,
ApplType
,
ApplId
,
EnvData

UserData


Copy Process


The Copy Process (MQCMD_COPY_PROCESS) command creates a new MQSeries process definition, usin
g, for attributes
not specified in the command, the attribute values of an existing process definition.

This PCF is not supported if you are using MQSeries for Windows Version 2.1.

Required parameters:

FromProcessName
,
ToProcessName


Optional parameters
:

Replace
,
ProcessDesc
,
ApplType
,
ApplId
,
EnvData
,
UserData



Create Process


The Create Process (MQCMD_CREATE_PROCESS) command creates a new MQSeries process definition. Any attributes
that are not defined explicitly are set to the default values on the
destination queue manager.

This PCF is not supported if you are using MQSeries for Windows Version 2.1.

Required parameters:

ProcessName


Optional parameters:

Replace
,
ProcessDesc
,
ApplType
,
ApplId
,
EnvData
,
UserData



Delete Process


The Delete Proces
s (MQCMD_DELETE_PROCESS) command deletes an existing MQSeries process definition.

This PCF is not supported if you are using MQSeries for Windows Version 2.1.

Required parameters:

ProcessName


Optional parameters:

None


Inquire Process


The Inquire Pr
ocess (MQCMD_INQUIRE_PROCESS) command inquires about the attributes of existing MQSeries processes.

This PCF is not supported if you are using MQSeries for Windows Version 2.1.

Required parameters:

ProcessName


Optional parameters:

ProcessAttrs


Inquir
e Process Names


The Inquire Process Names (MQCMD_INQUIRE_PROCESS_NAMES) command inquires for a list of process names that
match the generic process name specified.

This PCF is not supported if you are using MQSeries for Windows Version 2.1.

Required par
ameters:

ProcessName


Optional parameters:

None

Queue commands

Change Queue

The Change Queue (MQCMD_CHANGE_Q) command changes the specified attributes of an existing MQSeries queue.

This PCF is supported on all platforms.

For any optional parameters t
hat are omitted, the value does not change.

Required parameters:

QName
,
QType
,

Optional parameters (any QType):

QDesc
,
InhibitPut
,
DefPriority
,
DefPersistence


Optional parameters (alias QType):

Force
,
InhibitGet
,
BaseQName
,
Scope
,
ClusterName
,
Cluste
rNamelist
,
DefBind


Optional parameters (local QType):

Force
,
InhibitGet
,
ProcessName
,
MaxQDepth
,
MaxMsgLength
,
BackoutThreshold
,
BackoutRequeueName
,
Shareability
,
DefInputOpenOption
,
HardenGetBackout
,
MsgDeliverySequence
,
RetentionInterval
,
DistLists
,
Us
age
,
InitiationQName
,
TriggerControl
,
TriggerType
,
TriggerMsgPriority
,
TriggerDepth
,
TriggerData
,
Scope
,
QDepthHighLimit
,
QDepthLowLimit
,
QDepthMaxEvent
,
QDepthHighEvent
,
QDepthLowEvent
,
QServiceInterval
,
QServiceIntervalEvent
,
ClusterName
,
ClusterNamelist
,
DefBind


Optional parameters (remote QType):

Force
,
RemoteQName
,
RemoteQMgrName
,
XmitQName
,
Scope
,
ClusterName
,
ClusterNamelist
,
DefBind


Optional parameters (model QType):

InhibitGet
,
ProcessName
,
MaxQDepth
,
MaxMsgLength
,
BackoutThreshold
,
BackoutRequ
eueName
,
Shareability
,
DefInputOpenOption
,
HardenGetBackout
,
MsgDeliverySequence
,
RetentionInterval
,
DistLists
,
Usage
,
InitiationQName
,
TriggerControl
,
TriggerType
,
TriggerMsgPriority
,
TriggerDepth
,
TriggerData
,
DefinitionType
,
QDepthHighLimit
,
QDepthLowLi
mit
,
QDepthMaxEvent
,
QDepthHighEvent
,
QDepthLowEvent
,
QServiceInterval
,
QServiceIntervalEvent



Copy Channel


The Copy Channel (MQCMD_COPY_CHANNEL) command creates a new channel definition using, for attributes not specified
in the command, the attribute v
alues of an existing channel definition.

This PCF is supported on all platforms.

Required parameters:

FromChannelName
,
ToChannelName
,
ChannelType


Optional parameters (any ChannelType):

Replace
,
TransportType
,
ChannelDesc
,
SecurityExit
,
MsgExit
,
SendEx
it
,
ReceiveExit
,
MaxMsgLength
,
SecurityUserData
,
MsgUserData
,
SendUserData
,
ReceiveUserData


Optional parameters (sender or server ChannelType):

ModeName
,
TpName
,
ConnectionName
,
XmitQName
,
MCAName
,
BatchSize
,
DiscInterval
,
ShortRetryCount
,
ShortRetryInte
rval
,
LongRetryCount
,
LongRetryInterval
,
SeqNumberWrap
,
DataConversion
,
MCAType
,
MCAUserIdentifier
,
UserIdentifier
,
Password
,
HeartbeatInterval
,
NonPersistentMsgSpeed

BatchInterval


Optional parameters (receiver ChannelType):

BatchSize
,
PutAuthority
,
SeqN
umberWrap
,
MCAUserIdentifier
,
MsgRetryExit
,
MsgRetryUserData
,
MsgRetryCount
,
MsgRetryInterval
,
HeartbeatInterval
,
NonPersistentMsgSpeed


Optional parameters (requester ChannelType):

ModeName
,
TpName
,
ConnectionName
,
MCAName
,
BatchSize
,
PutAuthority
,
SeqNu
mberWrap
,
MCAType
,
MCAUserIdentifier
,
UserIdentifier
,
Password
,
MsgRetryExit
,
MsgRetryUserData
,
MsgRetryCount
,
MsgRetryInterval
,
HeartbeatInterval
,
NonPersistentMsgSpeed


Optional parameters (server
-
connection ChannelType):

MCAUserIdentifier


Optional par
ameters (client
-
connection ChannelType):

ModeName
,
TpName
,
QMgrName
,
ConnectionName
,
UserIdentifier
,
Password


Optional parameters (cluster
-
receiver ChannelType):

ModeName
,
TpName
,
DiscInterval
,
ShortRetryCount
,
ShortRetryInterval
,
LongRetryCount
,
LongRe
tryInterval
,
DataConversion
,
BatchSize
,
PutAuthority
,
SeqNumberWrap
,
MCAUserIdentifier
,
MsgRetryExit
,
MsgRetryUserData
,
MsgRetryCount
,
MsgRetryInterval
,
HeartbeatInterval
,
NonPersistentMsgSpeed
,
BatchInterval
,
ClusterName
,
ClusterNamelist
,
ConnectionName
,
NetworkPriority


Optional parameters (cluster
-
sender ChannelType):

ModeName
,
TpName
,
ConnectionName
,
MCAName
,
BatchSize
,
DiscInterval
,
ShortRetryCount
,
ShortRetryInterval
,
LongRetryCount
,
LongRetryInterval
,
SeqNumberWrap
,
DataConversion
,
MCAType
,
MCAUserI
dentifier
,
UserIdentifier
,
Password
,
HeartbeatInterval
,
NonPersistentMsgSpeed
,
BatchInterval
,
ClusterName
,
ClusterNamelist



Create Channel


The Create Channel (MQCMD_CREATE_CHANNEL) command creates an MQSeries channel definition. Any attributes that
are n
ot defined explicitly are set to the default values on the destination queue manager. If a system default channel exists for
the type of channel being created, the default values are taken from there.

This PCF is supported on all platforms.

Required para
meters:

ChannelName
,
ChannelType


Optional parameters (any ChannelType):

Replace
,
TransportType
,
ChannelDesc
,
SecurityExit
,
MsgExit
,
SendExit
,
ReceiveExit
,
MaxMsgLength
,
SecurityUserData
,
MsgUserData
,
SendUserData
,
ReceiveUserData


Optional parameters (s
ender or server ChannelType):

ModeName
,
TpName
,
ConnectionName
,
XmitQName
,
MCAName
,
BatchSize
,
DiscInterval
,
ShortRetryCount
,
ShortRetryInterval
,
LongRetryCount
,
LongRetryInterval
,
SeqNumberWrap
,
DataConversion
,
MCAType
,
MCAUserIdentifier
,
UserIdentifier
,

Password
,
HeartbeatInterval
,
NonPersistentMsgSpeed

BatchInterval


Optional parameters (receiver ChannelType):

BatchSize
,
PutAuthority
,
SeqNumberWrap
,
MCAUserIdentifier
,
MsgRetryExit
,
MsgRetryUserData
,
MsgRetryCount
,
MsgRetryInterval
,
HeartbeatInterval
,
N
onPersistentMsgSpeed


Optional parameters (requester ChannelType):

ModeName
,
TpName
,
ConnectionName
,
MCAName
,
BatchSize
,
PutAuthority
,
SeqNumberWrap
,
MCAType
,
MCAUserIdentifier
,
UserIdentifier
,
Password
,
MsgRetryExit
,
MsgRetryUserData
,
MsgRetryCount
,
MsgR
etryInterval
,
HeartbeatInterval
,
NonPersistentMsgSpeed


Optional parameters (server
-
connection ChannelType):

MCAUserIdentifier
,

Optional parameters (client
-
connection ChannelType):

ModeName
,
TpName
,
QMgrName
,
ConnectionName
,
UserIdentifier
,
Password


Op
tional parameters (cluster
-
receiver ChannelType):

ModeName
,
TpName
,
DiscInterval
,
ShortRetryCount
,
ShortRetryInterval
,
LongRetryCount
,
LongRetryInterval
,
DataConversion
,
BatchSize
,
PutAuthority
,
SeqNumberWrap
,
MCAUserIdentifier
,
MsgRetryExit
,
MsgRetryUser
Data
,
MsgRetryCount
,
MsgRetryInterval
,
HeartbeatInterval
,
NonPersistentMsgSpeed
,
BatchInterval
,
ClusterName
,
ClusterNamelist
,
ConnectionName
,
NetworkPriority


Optional parameters (cluster
-
sender ChannelType):

ModeName
,
TpName
,
ConnectionName
,
MCAName
,
Bat
chSize
,
DiscInterval
,
ShortRetryCount
,
ShortRetryInterval
,
LongRetryCount
,
LongRetryInterval
,
SeqNumberWrap
,
DataConversion
,
MCAType
,
MCAUserIdentifier
,
UserIdentifier
,
Password
,
HeartbeatInterval
,
NonPersistentMsgSpeed
,
BatchInterval
,
ClusterName
,
Cluster
Namelist



Delete Channel


The Delete Channel (MQCMD_DELETE_CHANNEL) command deletes the specified channel definition.

This PCF is supported on all platforms.

Required parameters:

ChannelName


Optional parameters:

ChannelTable


Inquire Channel


The Inq
uire Channel (MQCMD_INQUIRE_CHANNEL) command inquires about the attributes of MQSeries channel definitions.

This PCF is supported on all platforms.

Required parameters:

ChannelName


Optional parameters:

ChannelType
,
ChannelAttrs


Inquire Channel Names


The Inquire Channel Names (MQCMD_INQUIRE_CHANNEL_NAMES) command inquires a list of MQSeries channel names
that match the generic channel name, and the optional channel type specified.

This PCF is supported on all platforms.

Required parameters:

Channel
Name


Optional parameters:

ChannelType


Inquire Channel Status


The Inquire Channel Status (MQCMD_INQUIRE_CHANNEL_STATUS) command inquires about the status of one or more
MQSeries channel instances.

Required parameters

ChannelName

(MQCFST)

Channel name
(parameter identifier: MQCACH_CHANNEL_NAME).

Generic channel names are supported. A generic name is a character string followed by an asterisk (*), for example ABC*,
and it selects all objects having names that start with the selected character string. An

asterisk on its own matches all possible
names. The channel name is always returned, regardless of the instance attributes requested. The maximum length of the
string is MQ_CHANNEL_NAME_LENGTH.

Optional parameters

XmitQName

(MQCFST),
ConnectionName
(MQCFST
),
ChannelInstanceType
(MQCFIN)
,
ChannelInstanceAttrs

(MQCFIL)


Ping Channel


The Ping Channel (MQCMD_PING_CHANNEL) command tests a channel by sending data as a special message to the
remote message queue manager and checking that the data is returned. The
data is generated by the local queue manager.

This command can only be used for channels with a
ChannelType

value of MQCHT_SENDER, MQCHT_SERVER, or
MQCHT_CLUSSDR.

Where there is both a locally defined channel and an auto
-
defined cluster
-
sender channel of

the same name, the command
applies to the locally defined channel.

If there is no locally defined channel but more than one auto
-
defined cluster
-
sender channel, the command applies to the last
channel added to the repository on the local queue manager.

The command is not valid if the channel is running; however it is valid if the channel is stopped or in retry mode.

This PCF is not supported if you are using MQSeries for Windows Version 2.1.

Required parameters:

ChannelName


Optional parameters:

Data
Count


Reset Channel


The Reset Channel (MQCMD_RESET_CHANNEL) command resets the message sequence number for an MQSeries channel
with, optionally, a specified sequence number to be used the next time that the channel is started.

This command can be issued

to a channel of any type (except MQCHT_SVRCONN and MQCHT_CLNTCONN). However, if it
is issued to a sender (MQCHT_SENDER), server (MQCHT_SERVER), or cluster
-
sender (MQCHT_CLUSSDR) channel, the
value at both ends (issuing end and receiver or requester end),
is reset when the channel is next initiated or resynchronised.
The value at both ends is reset to be equal.

If the command is issued to a receiver (MQCHT_RECEIVER), requester (MQCHT_REQUESTER), or cluster
-
receiver
(MQCHT_CLUSRCVR) channel, the value at th
e other end is
not

reset as well; this must be done separately if necessary.

Where there is both a locally defined channel and an auto
-
defined cluster
-
sender channel of the same name, the command
applies to the locally defined channel.

If there is no loc
ally defined channel but more than one auto
-
defined cluster
-
sender channel, the command applies to the last
channel added to the repository on the local queue manager.

This PCF is supported on all platforms.

Required parameters:

ChannelName


Optional pa
rameters:

MsgSeqNumber


Resolve Channel


The Resolve Channel (MQCMD_RESOLVE_CHANNEL) command requests a channel to commit or back out in
-
doubt
messages.

This command is used when the other end of a link fails during the confirmation stage, and for some r
eason it is not possible
to reestablish the connection. In this situation the sending end remains in an in
-
doubt state, as to whether or not the messages
were received. Any outstanding units of work must be resolved using Resolve Channel with either backou
t or commit.

Care must be exercised in the use of this command. If the resolution specified is not the same as the resolution at the
receiving end, messages can be lost or duplicated.

This command can only be used for channels with a
ChannelType

value of

MQCHT_SENDER, MQCHT_SERVER, or
MQCHT_CLUSSDR.

Where there is both a locally defined channel and an auto
-
defined cluster
-
sender channel of the same name, the command
applies to the locally defined channel.

If there is no locally defined channel but more
than one auto
-
defined cluster
-
sender channel, the command applies to the last
channel added to the repository on the local queue manager.

This PCF is supported on all platforms.

Required parameters:

ChannelName
,
InDoubt


Optional parameters:

None

Star
t Channel


The Start Channel (MQCMD_START_CHANNEL) command starts an MQSeries channel.

Client connections on MQSeries Version 5, or later, products cannot initiate this command.

This command can be issued to a channel of any type (except MQCHT_CLNTCONN).

If, however, it is issued to a channel
with a
ChannelType

value of MQCHT_RECEIVER, MQCHT_SVRCONN, or MQCHT_CLUSRCVR, the only action is to enable
the channel, not start it.

Where there is both a locally defined channel and an auto
-
defined cluster
-
sender
channel of the same name, the command
applies to the locally defined channel.

If there is no locally defined channel but more than one auto
-
defined cluster
-
sender channel, the command applies to the last
channel added to the repository on the local queue
manager.

This PCF is supported on all platforms.

Required parameters:

ChannelName


Optional parameters:

None

Start Channel Initiator


The Start Channel Initiator (MQCMD_START_CHANNEL_INIT) command starts an MQSeries channel initiator.

This PCF is not

supported if you are using MQSeries for Windows Version 2.1.

Required parameters:

InitiationQName


Optional parameters:

None

Start Channel Listener


The Start Channel Listener (MQCMD_START_CHANNEL_LISTENER) command starts an MQSeries TCP listener.

Th
is PCF is supported if you are using MQSeries for AS/400 V4R2, or later, MQSeries for OS/2 Warp V5, or MQSeries for
Windows NT V5, only.

This command is valid only for TCP transmission protocols.

Required parameters:

None

Optional parameters:

Transpor
tType


Stop Channel


The Stop Channel (MQCMD_STOP_CHANNEL) command stops an MQSeries channel.

Client connections on MQSeries Version 5, or later, products cannot initiate this command.

This command can be issued to a channel of any type (except MQCHT_CLN
TCONN).

Where there is both a locally defined channel and an auto
-
defined cluster
-
sender channel of the same name, the command
applies to the locally defined channel.

If there is no locally defined channel but more than one auto
-
defined cluster
-
sender ch
annel, the command applies to the last
channel added to the repository on the local queue manager.

This PCF is supported on all platforms.


Required parameters:

ChannelName


Optional parameters:

Quiesce


Statistics command

Reset Queue Statistics


The Re
set Queue Statistics (MQCMD_RESET_Q_STATS) command reports the performance data for a queue and then
resets the performance data.

This PCF is not supported if you are using MQSeries for Tandem NSK version 2.2.

Performance data is maintained for each loca
l queue (including transmission queues). It is reset at the following times:



When a Reset Queue Statistics command is issued



When the queue manager is restarted

Required parameters:

QName


Optional parameters: