MQ/204 queue management

MQ/204 enables a Model 204 Online or batch job running under z/OS to access the IBM z/OS WebSphere MQ communication facilities. All the queues and queue managers available to MQ/204 are originally defined by the WebSphere MQ software.

Determining message destination

When a WebSphere MQ application, such as MQ/204, sends a message, WebSphere MQ must know the final destination of the message. The final destination is identified by the combination of a queue manager name, called the target queue manager, and a queue name, as one of the following categories. WebSphere MQ determines which category a queue is in at the time the queue is opened.

Local queues

An MQ/204 application delivers a message to a queue by connecting directly to the target queue manager, that is, the queue manager that owns the target queue. The queue is described as a local queue from the perspective of the application sending the message. The MQ/204 application needs to know the target queue manager name and the target queue name.

Remote queues

An MQ/204 application might send a message to a queue, but cannot connect directly to the target queue manager; for example, the target queue manager is running under a different OS on a different machine. In this case, the queue is described as a remote queue from the perspective of the application sending the message.

To deliver the message, the MQ/204 application connects directly to a local queue manager, called the source queue manager, and requests that the source queue manager pass the message to the target queue manager. The MQ/204 application must know the source queue manager name, the target queue manager name, and the target queue name. In MQ/204, the source queue manager name is identified by the MQ/204 MQDEQMAN parameter.

Locally defined remote queues

As an alternative to remote queues, a queue manager can have queue definitions that point to remote queues, that is, queues owned by another queue manager. To deliver the message, the MQ/204 application connects directly to the local queue manager using the local name. From the point of view of the MQ/204 application, the queue behaves as if it were local. The MQ/204 application needs only the source queue manager name and the source queue name; the source queue manager knows the target queue manager name and the target queue name.

Cluster queues

Cluster queues are used in a similar way to locally defined remote queues, but require reduced WebSphere MQ administration. A cluster queue is a queue that is hosted by a cluster queue manager and made available to other queue managers in the cluster. The cluster queue manager makes a local queue definition for the queue, specifying the name of the cluster where the queue is to be found.

Determining message handling

WebSphere MQ allows messages to be sent via an MQPUT statement to local, remote, or locally defined remote queues, but allows messages to be received only via MQGET from local queues.

Rules for queue names

MQ/204 determines whether a queue is opened as local or remote based on the following rules for queue names:

A queue name without an embedded colon (:) is an MQ/204 entity name that refers to either a local queue or a local definition of a remote queue.
A queue name with an embedded colon (:) is interpreted as QueueManagerName:QueueName:
- If no default queue manager is specified by the MQDEQMAN parameter, the open fails.
- Otherwise, the queue is opened as a remote queue using the value in MQDEQMAN parameter as the local queue manager.

Model 204 support

MQ/204 has the following Model 204 support features:

User 0 parameters within Model 204 allocate resources that support:
- Connections to queue managers
- Number of concurrent threads that can use this support
Model 204 commands define queues and queue managers to Model 204 and control access to and monitoring of queue managers.

Using MQ/204, you can refer to queues and queue managers as entities, that is, by names that differ from their operating system level (external) names. Also, the MONITOR command permits the system manager to track the use of MQ/204. Commands and objects similar in syntax and function to the DEFINE commands used for Horizon identify queue managers and queues to Model 204.

Within SOUL, the following additional features are implemented:

You can open and close WebSphere MQ queues with extensions to the OPEN and CLOSE statements, which is consistent with the Model 204 approach to interactions with external communication entities.
You can reset defaults for open queues with an extension to the MODIFY statement.
You can easily map between WebSphere MQ and SOUL, because the statements that manipulate queues are named like the WebSphere MQ API. For example:

SOUL statement	WebSphere MQ action
MQBACK	Backs out WebSphere MQ transactions
MQCMIT	Commits WebSphere MQ transactions
MQGET	Gets messages from a queue
MQPUT	Puts messages on an open queue
MQPUT1	Puts one message on a not-yet-opened queue

Remote queue support

You can put a message on remote queues that do not have corresponding DEFINE QUEUE commands in the Online. Remote queues might be owned by any queue manager on the network and are typically not on the same mainframe. Support for remote queues means that you can write MQ/204 applications that reply to any queues on the network, without issuing additional DEFINE QUEUE commands in Model 204.

To put a message on a remote queue with WebSphere MQ, you must open a remote queue using remote queue manager and remote queue names. MQ/204 connects you to the default queue manager, which should have all connections necessary to send your message to the remote queue. The next MQPUT statement you make sends your message to a remote queue.

Default queue manager

To support remote queues, a default queue manager is employed, because multiple queue managers can be defined to the Online. The default queue manager is the one to which you put messages when the destination queue is unknown to Model 204. The z/OS queue manager forwards the message to the queue manager that contains the destination remote queue. If the destination remote queue is unknown to the WebSphere MQ network, error information is returned to the SOUL program in $STATUS and $STATUSD return codes.

Local dynamic queue support

Sometimes you want an application to create a queue on an as-needed basis, which is called a local, dynamic queue. For example, if after a query the application has data to send, it creates a local dynamic queue; if there is no data to send, it does not create a queue. Also, when the queue is no longer needed it is closed and deleted.

So that an MQ/204 application can create a local dynamic queue, the WebSphere MQ system administrator defines and makes available a template known as a model queue. MQ/204 can create a local dynamic queue that takes the attributes of a WebSphere MQ model queue. You can request many attributes to define a model queue for your application. Of special interest is whether the preallocated model queue has specified DEFTYPE as permanent or temporary.

Local dynamic queues, either permanent or temporary, are created in your application by issuing an MQOPEN call with the name of a model queue.

Model queues can have one of the following DefinitionType attributes defined for local dynamic use

MQQDT_PERMANENT_DYNAMIC
MQQDT_TEMPORARY_DYNAMIC

This type of queue is deleted according to the rules that govern WebSphere MQ queues and queue managers. Consult the IBM WebSphere MQ documentation for details.

Reusing dynamic queue names

You can reuse the internal Model 204 name of a dynamic queue, after you issue a CLOSE QUEUE DELETE or CLOSE QUEUE DELETE_PURGE statement for that queue name. For example, to reuse the dynamic queue name, CCA1, issue the following statement:

CLOSE QUEUE CCA1 DELETE_PURGE

Rules of inheritance

The Model 204 commands, introduced in MQ/204 command reference, and SOUL statements, introduced in MQ/204 and SOUL statements, have many options that you can set. You can set options in the following ways:

Set an option when you define a queue manager or queue. An option set at this point applies to all users. In the following definition, responses to messages are sent to QB, not back to the sending queue, QA:
DEFINE QUEUE QA WITH SCOPE=SYSTEM QUEUEMANAGER=QM1 - REPLY_QUEUE=QB
Change an option in individual MQ/204 statements on the fly. An option set at this point applies to just the issuing user. For the following MQPUT statement, the response to the message is sent to QC, not back to the default reply queue, QB.
OPEN QA MQPUT MQ_BUFFER REPLY_QUEUE=QC
Modify an option after you have opened a queue. An option set at this point applies to just the issuing user. If you frequently change the reply queue on MQPUT statements, you can separately modify the reply queue before issuing the MQPUT statements:
MODIFY QUEUE QA REPLY_QUEUE=QC

The following figure illustrates the rules of inheritance, showing how the options are passed from the DEFINE QUEUE command to the OPEN and MQPUT1 statements. Options are then passed to the MQGET, MQPUT, and MODIFY QUEUE statements or you can change them in the same statements.

Rules of inheritance for passing options

The options correlate directly to options found in WebSphere MQ. See Options for MQ/204 commands and statements for a definition of each option and the command or statements that support it.

Reply queue and reply queue manager options

In MQ/204 you can indicate the reply queue and the reply queue manager in a DEFINE QUEUE command and OPEN QUEUE, MODIFY QUEUE, MQPUT, and MQPUT1 statements in one of the following ways:

Specify a reply queue and reply queue manager explicitly using REPLY_QUEUE=queue-name and REPLY_QMGR=queue-manager-name.
You can specify names as text strings, with or without quotation marks, of up to 48 characters or as a %variable containing text strings for SOUL statements. Use only external (real) names, as opposed to internal MQ/204 names that are specified in DEFINE QUEUE command and OPEN QUEUE statement.
Specify a reply queue internal name only, without using the REPLY_QMGR option, to let MQ/204 find the real reply queue and reply queue manager names. Define the internal reply queue name by issuing the DEFINE QUEUE command for local queues, or the OPEN QUEUE statement for remote queues. In this case, MQ/204 finds the corresponding external queue and queue manager names and sets them in MQMD (message descriptor) structure. You can achieve the same result using the REPLY_QMGR option with a zero-length name, for example, REPLY_QMGR = ''.

Let WebSphere MQ resolve a queue manager name by setting the reply queue manager name to one or more blanks and providing the external queue name. If the reply queue name is a local definition of a remote queue:

Then WebSphere MQ sets the field...	To the name of the...	Otherwise, this field is...
MQMD.ReplyToQ	Remote queue	Not changed.
MQMD.ReplyToQMgr	Queue manager that owns the remote queue	Set to the name of the queue manager to which your application is connected.

Note: Never mix internal and external queue names in your applications (either by explicitly specifying them or by inheriting and implicitly mixing them) because, if the value of the REPLY_QMGR option is a name of nonzero length, MQ/204 does not substitute the external reply queue name for the internal name and sends the internal reply queue name instead of the external name.

Using runtime options

You can code MQ/204 statement options explicitly on a statement, in which case they are parsed at compile time. Alternatively, you can code them as runtime options, specified in syntax descriptions as ?%variable, which are parsed each time the statement is evaluated. You can specify both explicitly coded options and runtime options together in the same statement. The following MQ/204 statements support ?%variables:

CLOSE QUEUE
MODIFY QUEUE
MQGET
MQPUT
MQPUT1
OPEN QUEUE

Runtime options are specified in the syntax descriptions as ?%variable. The following section lists the features that apply to all ?%variables; see the individual statements in MQ/204 and SOUL statements for an explanation of syntax.

Rules that govern ?%variables

Any option that is valid if specified at compilation can be specified in a run-time option variable.
the ?%variable must be a string variable.
At evaluation time, the ?%variable:
- Can be null.
- Can contain multiple options.
- Can contain options of the form keyword=%variable, however, the %variable must be a variable name in the program. It cannot be an image or a screen item.
- Cannot contain keywords specified as %variables. For example, %keyword=%variable is invalid, just as for options specified at compile time.
You can specify up to three runtime option variables on a statement, but each individual option specified at runtime must be wholly contained within one ?%variable and cannot span multiple ?%variables.
Options specified within the ?%variables must be consistent. If they are inconsistent, a $STATUS code of 41 or 42 is returned.
Examples of inconsistent use of options specified with a ?%variable are:
- Using WAIT and NO_WAIT options together
- Using the MODEL keyword without using the DYNAMICQNAME keyword.
Options specified within the ?%variable override those specified on the statement at compile time.

Example

The following example illustrates using two runtime options in an MQPUT statement:

%variable1 IS STRING LEN 255 %variable2 IS STRING LEN 255 %MSGTYPE IS STRING LEN 8 %variable1 = 'MSGTYPE=REPORT' %variable2 = 'MSGTYPE=%MSGTYPE MSGID=DEF' MQPUT 'MESSAGE' ON QUEUENAME MSGID=ABC ?%variable1 %MSGTYPE = 'REQUEST' MQPUT 'MESSAGE' ON QUEUENAME ?%variable2

Parameters and task management

Parameters allocate z/OS system subtasks and other system resources for MQ/204.To use MQ/204, you must set MQINTASK to at least 1. However, more tasks might be needed. For each concurrent user who accesses queues, you need one task for each queue manager that the user accesses concurrently.

Parameters

While the Online is operating, you can view the MQ/204 parameters listed in the following table.

MQ/204 parameters
Parameter	Description	Default	Discussion	Setting can be changed...
MQDEQMAN	Identifies the WebSphere MQ default queue manager.	System default is not set	If set, its value is the name of the queue manager to use as the default queue manager. If not set, remote queue support is disabled; you must enter the actual name. Value must be the name of a previously defined queue manager; can be reset only to a previously defined queue manager.	By system manager following a DEFINE QM command
MQINTASK	Subtasks created during system initialization for managing connections to WebSphere MQ queue managers.	0	Set the value of MQINTASK to 1 (or more) to use MQ/204.	At initialization time, in CCAIN parameters
MQMXTASK	Maximum number of subtasks to use for WebSphere MQ connections.	Same as MQINTASK	You can set it to a greater value. If the value is greater than the value of MQINTASK, additional tasks are created as needed.	At initialization time, in CCAIN parameters
MQWAIT	Milliseconds that an OPEN QUEUE statement or a START QUEUEMANAGER command waits for the next available subtask.	0, meaning do not wait for tasks	The parameter applies if no more subtasks can be allocated because MQMXTASK subtasks are already allocated.	At initialization time, in CCAIN parameters; or by a system manager
UBUFSZ	Initial bytes per buffer that hold messages.	1024 bytes	Buffers contain the data portion of messages, not the MQMD message descriptor. Buffers are enlarged as needed. No data buffer is smaller than the value of UBUFSZ.	At initialization time, in CCAIN parameters

Task management

When a user finishes using a task, the task remains connected to a queue manager anticipating the next user, unless its queue manager is draining (see STOP QUEUEMANAGER). This technique optimizes performance for the common case where the next user of the task requires the same queue manager. Often a system has only one queue manager.

Accessing queues and queue managers

The WebSphere MQ administrator defines the queues and queue managers to WebSphere MQ. A Model 204 programmer with system administrator privileges can then issue the MQ/204 DEFINE QUEUEMANAGER and DEFINE QUEUE commands. This may be done in the startup deck for Model 204.

An application can reply only to request messages that specify a queue and queue manager defined by the system administrator to the Online, unless remote queue support is in use or local dynamic queues are being used.

After a connection to a queue manager is established, the queue manager enforces user ID based security when queues are opened. See MODIFY QUEUE statement.

MQ/204 security access control

The security of MQ/204 is as follows:

SOUL programs can access a queue or queue manager after the system manager does one of the following:
- Issues DEFINE commands
- Enables remote queue support by setting the MQDEQMAN option
- Defines the model queues required to support local dynamic queues.
MQ/204 honors user-based security on queues that the WebSphere MQ system administrator set up outside Model 204.

WebSphere MQ API wait types access control

The WebSphere MQ API wait types, MQAPI and MQGWT, distinguish between waits for WebSphere MQ API execution and waits for a message to arrive on a queue:

MQAPI waits encompass just the execution of the WebSphere MQ API.
MQGWT waits include both WebSphere MQ API execution time and time spent waiting for a message to arrive on a queue.

Bumping users

A system manager can always displace a user who is waiting for a WebSphere MQ operation to complete or for a subtask to become available. MQ/204 waits are bumpable.

Triggering

Users can write their own trigger procedures by employing trigger queues and MQ/204 operators.

Queue security processing

When you open a queue, you undergo a user name authorization process. By default, with an z/OS batch WebSphere MQ connection, the job name is used. However, the MQOPEN facility permits you to pass an alternate user ID: the WebSphere MQ option MQOO_ALTERNATE_USER_AUTHORITY:

If your site uses an external security package with Model 204, such as ACF2, Security Server (formerly RACF), or CA-Top Secret, then the Model 204 user ID is passed and the MQOO_ALTERNATE_USER_AUTHORITY option is set.
If no security package is present, then the default mode of using the job name for security is used. The Model 204 user ID is not used unless it is authenticated by an external security package.
If the PASS_USER_CONTEXT option is used with an OPEN QUEUE statement or an MQPUT1 statement, then the Model 204 user ID is passed with the MQOO_ALTERNATE_USER_AUTHORITY option set.

MQ/204 queue management

Contents