MQSC command attributes

 

A number of MQSC commands have cluster attributes:

  1. Queue-manager definition commands
  2. Channel definition commands
  3. Queue definition commands

In the commands, a cluster name, specified using the CLUSTER attribute, can be up to 48 characters long. Cluster names must conform to the rules described in the WebSphere MQ Script (MQSC) Command Reference book.

A list of cluster names, specified using the CLUSNL attribute, can contain up to 256 names. To create a cluster namelist, use the command DEFINE NAMELIST described in the WebSphere MQ Script (MQSC) Command Reference book.

 

Queue-manager definition commands

To specify that a queue manager holds a full repository for a cluster, use the ALTER QMGR command specifying the attribute REPOS(clustername). To specify a list of several cluster names, define a cluster namelist and then use the attribute REPOSNL(namelist) on the ALTER QMGR command: 

DEFINE NAMELIST(CLUSTERLIST)
       DESCR('List of clusters whose repositories I host')
       NAMES(CLUS1, CLUS2, CLUS3)
 
ALTER QMGR REPOSNL(CLUSTERLIST)

Use the CLWLEXIT(name) attribute to specify the name of a user exit to be called when a message is put to a cluster queue. Use the CLWLDATA(data) attribute to specify data to be passed to the cluster workload user exit. Use the CLWLLEN(length) attribute to specify the maximum amount of message data to be passed to the cluster workload user exit.

The attributes on the ALTER QMGR command also apply to the DISPLAY QMGR command.

For full details of the attributes and syntax of the ALTER QMGR command and the DISPLAY QMGR command, refer to the WebSphere MQ Script (MQSC) Command Reference book.

The equivalent PCFs are MQCMD_CHANGE_Q_MGR and MQCMD_INQUIRE_Q_MGR. These are described in the WebSphere MQ Programmable Command Formats and Administration Interface book.

 

Channel definition commands

The DEFINE CHANNEL, ALTER CHANNEL, and DISPLAY CHANNEL commands have two specific CHLTYPE parameters for clusters: CLUSRCVR and CLUSSDR. To define a cluster-receiver channel you use the DEFINE CHANNEL command, specifying CHLTYPE(CLUSRCVR). Many of the other attributes needed on a cluster-receiver channel definition are the same as those that apply to a receiver-channel or a sender-channel definition. To define a cluster-sender channel you use the DEFINE CHANNEL command, specifying CHLTYPE(CLUSSDR), and many of the same attributes as you use to define a sender channel.

It is no longer necessary to specify the full repository queue manager's name when you define a cluster-sender channel. So long as you know the naming convention used for channels in your cluster you can make a CLUSSDR definition using the +QMNAME+ construction (+QMNAME+ is not supported on z/OS). After connection WebSphere MQ changes the name of the channel and substitutes the correct full repository queue manager name in place of +QMNAME+. The resulting channel name is truncated to 20 characters.

Clearly this works only if your convention for naming channels includes the name of the queue manager. For example, if you have a full repository queue manager called PARIS with a cluster-receiver channel called TO.PARIS.ALPHA, another queue manager can define a cluster-sender channel to this queue manager, but specify the channel name as TO.+QMNAME+.ALPHA.

If you use the same naming convention for all your channels, be aware that only one +QMNAME+ definition can exist at one time.

The attributes on the DEFINE CHANNEL and ALTER CHANNEL commands that are specific to clusters are:

The CLUSTER and CLUSNL attributes apply only if you specify CHLTYPE(CLUSRCVR) or CHLTYPE(CLUSSDR). The NETPRTY attribute applies only to cluster-receiver channels.

Use the CLUSTER attribute to specify the name of the cluster with which this channel is associated. Alternatively, use the CLUSNL attribute to specify a namelist of cluster names.

Use the NETPRTY attribute to specify a priority for the channel. This helps the workload management routines. If there is more than one possible route to a destination, the workload management routine selects the one with the highest priority.

These attributes on the DEFINE CHANNEL command and ALTER CHANNEL command also apply to the DISPLAY CHANNEL command.

The CONNAME specified on a cluster-receiver channel definition is used throughout the cluster to identify the network address of the queue manager. Take care to select a value for the CONNAME parameter that resolves throughout your WebSphere MQ cluster. Do not use a generic name. Remember that the value specified on the cluster-receiver channel takes precedence over any value specified in a corresponding cluster-sender channel.

The following paragraphs discuss the facility to omit the CONNAME value on a CLUSRCVR definition. This is not possible on z/OS.

When the network protocol you are using is TCP/IP it is not necessary to specify the network address of your queue manager when you define a cluster-receiver channel. You can issue the DEFINE CHANNEL command without supplying a value for CONNAME. WebSphere MQ generates a CONNAME for you, assuming the default port and using the current IP address of the system. The generated CONNAME is always in the dotted-decimal form, rather than in the form of an alphanumeric DNS host name.

This facility is useful when you have machines using Dynamic Host Configuration Protocol (DHCP). With WebSphere MQ if you do not supply a value for the CONNAME on a CLUSRCVR channel, you do not need to make any changes to your definitions if DHCP allocates you a new IP address.

If you specify a blank for the CONNAME on the CLUSRCVR definition, WebSphere MQ generates a CONNAME from the IP address of the system. Only the generated CONNAME is stored in the repositories. Other queue managers in the cluster do not know that the CONNAME was originally blank.

If you issue the DISPLAY CLUSQMGR command you will see the generated CONNAME. However, if you issue the DISPLAY CHANNEL command from the local queue manager, you will see that the CONNAME is blank.

If the queue manager is stopped and restarted with a different IP address, because of DHCP, WebSphere MQ regenerates the CONNAME and updates the repositories accordingly.

Note:
Auto-defined cluster-sender channels take their attributes from those specified in the corresponding cluster-receiver channel definition on the receiving queue manager. Even if there is a manually-defined cluster-sender channel, its attributes are automatically modified to ensure that they match those on the corresponding cluster-receiver definition. Beware that you can, for example, define a CLUSRCVR without specifying a port number in the CONNAME parameter, whilst manually defining a CLUSSDR that does specify a port number. When the auto-defined CLUSSDR replaces the manually defined one, the port number (taken from the CLUSRCVR) becomes blank. The default port number would be used and the channel would fail.

Note that the DISPLAY CHANNEL command does not display auto-defined channels. However, you can use the DISPLAY CLUSQMGR command, introduced in DISPLAY CLUSQMGR , to examine the attributes of auto-defined cluster-sender channels.

Use the DISPLAY CHSTATUS command to display the status of a cluster-sender or cluster-receiver channel. This command gives the status of both manually defined channels and auto-defined channels.

For full details of the attributes and syntax of the DEFINE CHANNEL, ALTER CHANNEL, DISPLAY CHANNEL, and DISPLAY CHSTATUS commands, refer to the WebSphere MQ Script (MQSC) Command Reference book.

The equivalent PCFs are MQCMD_CHANGE_CHANNEL, MQCMD_COPY_CHANNEL, MQCMD_CREATE_CHANNEL, and MQCMD_INQUIRE_CHANNEL. For information about these PCFs, refer to the WebSphere MQ Programmable Command Formats and Administration Interface book.

 

Queue definition commands

The cluster attributes on the DEFINE QLOCAL, DEFINE QREMOTE, and DEFINE QALIAS commands, and the three equivalent ALTER commands, are:

CLUSTER
To specify the name of the cluster to which the queue belongs.

CLUSNL
To specify a namelist of cluster names.

DEFBIND
To specify the binding to be used when an application specifies MQOO_BIND_AS_Q_DEF on the OPEN call. The default for this attribute is DEFBIND(OPEN), which binds the queue handle to a specific instance of the cluster queue when the queue is opened. The alternative is to specify DEFBIND(NOTFIXED) so that the queue handle is not bound to any particular instance of the cluster queue. When you specify DEFBIND on a queue definition, the queue is defined with one of the attributes, MQBND_BIND_ON_OPEN or MQBND_BIND_NOT_FIXED.

We recommend that you set the DEFBIND attribute to the same value on all instances of the same cluster queue.

The attributes on the DEFINE QLOCAL, DEFINE QREMOTE, and DEFINE QALIAS commands also apply to the DISPLAY QUEUE command. To display information about cluster queues, specify a queue type of QCLUSTER or the keyword CLUSINFO on the DISPLAY QUEUE command, or use the command DISPLAY QCLUSTER.

The DISPLAY QUEUE or DISPLAY QCLUSTER command returns the name of the queue manager that hosts the queue (or the names of all queue managers if there is more than one instance of the queue). It also returns the system name for each queue manager that hosts the queue, the queue type represented, and the date and time at which the definition became available to the local queue manager. This information is returned using the CLUSQMGR, QMID, CLUSQT, CLUSDATE, and CLUSTIME attributes respectively.

The system name for the queue manager (QMID), is a unique, system-generated name for the queue manager.

You can define a cluster queue that is also a shared queue. For example you can define: 

DEFINE QLOCAL(MYQUEUE) CLUSTER(MYCLUSTER) QSGDISP(SHARED) CFSTRUCT(STRUCTURE)

For full details of the parameters and syntax of the QUEUE definition commands, refer to the WebSphere MQ Script (MQSC) Command Reference book.

The equivalent PCFs are MQCMD_CHANGE_Q, MQCMD_COPY_Q, MQCMD_CREATE_Q, and MQCMD_INQUIRE_Q.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.