MQ/204 command reference

Overview

MQ/204 commands support the following tasks:

• DEFINE commands identify queue managers and queues with defaults for various get and put options.
• The system manager uses the BUMP, START, and STOP commands to control access to the queue managers.

If an MQ/204 command is issued but MQ/204 is not linked with Model 204, the following error message is issued:

M204.1039: FEATURE NOT LINKED IN

BUMP QUEUEMANAGER: Disconnecting queue manager users

Privileges

System manager or User 0

Function

Disconnects all users who have connections to the specified queue manager.

Syntax

BUMP {QUEUEMANAGER | QM} name

Where

name identifies a queue manager created with a DEFINE QUEUEMANAGER command.

Usage

When you want to disconnect users from a queue manager, follow these steps:

1. Issue a STOP QUEUEMANAGER command to prevent additional access to the queue manager.
2. Issue a BUMP QUEUEMANAGER command. Any active WebSphere MQ transactions for bumped users are backed out.

If the queue manager does not exist or has not been started, an error message is issued.

DEFINE QUEUE: Identifying a WebSphere MQ queue

Privileges

System manager or User 0

Function

Identifies a z/OS-WebSphere MQ queue in a queue manager where applications can put (MQPUT and MQPUT1) and get (MQGET) messages. The queue must have been previously defined by the WebSphere MQ administrator.

Syntax

DEFINE {QUEUE | Q} name [LIKE previousname] WITH SCOPE=SYSTEM {QUEUEMANAGER | QM}=qmanentityname [{QUEUENAME | QNAME}=externalqueuename] [options...]

Where

• name identifies the queue referred to in the Online. name must be:
  • unique, or an error is issued
  • 1-48 characters long and begin with a letter, followed by letters, numbers, periods, or underscores
• QUEUEMANAGER (or QM) clause names the queue manager for the queue, and must refer to a queue manager previously defined by the WebSphere MQ administrator.

  Use the optional QUEUENAME (or QNAME) clause, if the external name of the queue (as defined to WebSphere MQ) differs from the name you refer to in the Online. External queue names can be up to 48 characters in length. The external queue name is validated when the queue is actually opened. If you omit QUEUENAME (or QNAME), the external name of the queue is assumed to be name.

• options are default characteristics that are used to manipulate the queues.
  • ACCEPT_TRUNCATED_MSG or NO_ACCEPT_TRUNCATED_MSG (default)
  • ALL_MSGS_AVAILABLE or NOT_ALL_MSGS_AVAILABLE (default)
  • FAIL_IF_QUIESCING or NO_FAIL_IF_QUIESCING (default)
  • CONTEXT
  • EXPIRY
  • FORMAT
  • LOGICAL_ORDER or NOT_LOGICAL_ORDER (default)
  • MSGTYPE
  • PERSISTENT, NOT_PERSISTENT, or PERSISTENCE_AS_Q_DEF (default)
  • PRIORITY or PRIORITY_AS_Q_DEF (default)
  • REPLY_QMGR
  • REPLY_QUEUE
  • REPORT
  • SYNCPOINT (default) or NO_SYNCPOINT
  • WAIT or NO_WAIT (default)
  • WAIT_TIME

Usage

The queue definition has system scope.

Note: Remote queues do not require a DEFINE QUEUE command. Local dynamic queues require a DEFINE QUEUE command only if they were not created by MQ/204 in the current Online job.

DEFINE QUEUE can be omitted if the MQDEQMAN keyword is supplied. (See Parameters and task management for a description of MQDEQMAN.)

When a queue is known to the default queue manager, as specified by the MQDEQMAN keyword, it is possible to omit an explicit DEFINE QUEUE command. Instead MQPUT and MQGET processing can specify the external queue name.

If MQDEQMAN is not specified or the supplied queue name is not valid, the MQPUT or MQGET statement is rejected with the message:

M204.0630: IMPLICIT DEFINE COMMAND REJECTED

Defining local dynamic queues

When a local dynamic queue is created using an MQOPEN statement, it is created with SCOPE=SYSTEM. Model 204 sets up control blocks as if you had defined the queue using the DEFINE command.

If the Online is cycled and the permanent local dynamic queue still exists, to access it in a subsequent run, you must issue a DEFINE QUEUE command with the full name of the local dynamic queue, even if the queue manager created the name when the local dynamic queue was originally defined.

Security considerations

Applications creating local dynamic queues via the OPEN QUEUE statement cannot reference model queues unless the system manager defines the model queues.

DEFINE QUEUEMANAGER: Identifying a WebSphere MQ queue manager

Privileges

System manager and User 0

Function

Identifies a z/OS-WebSphere MQ queue manager that you want to connect to from Model 204. The queue manager must have been previously defined by the z/OS-WebSphere MQ administrator.

Syntax

DEFINE {QUEUEMANAGER | QM} name [LIKE previousname] WITH SCOPE=SYSTEM [{QUEUEMANAGERNAME | QMNAME}=externalqmanname]

Where

• name identifies the queue manager referred to in the Online. name must be:
  • unique or an error is issued
  • 1-48 characters long and begin with a letter, followed by letters, numbers, periods, or underscores
• Use the optional QUEUEMANAGERNAME (or QMNAME) clause if the external name of the queue manager (as defined to WebSphere MQ) differs from the name you refer to in the Online. If you omit QUEUEMANAGERNAME (or QMNAME), the external name of the queue manager is assumed to be name.

Usage

The external name of the queue manager is validated when a system manager or User 0 issues a START QUEUEMANAGER command. The queue manager has system scope.

You must define a queue manager before you define a queue.

MODIFY QUEUE statement

Function

Alters the current default option(s) for an open queue for the issuing user.

Syntax

MODIFY QUEUE {%variable | name | external_qmanager:external_queue} {[option...] [?%variable...]}

Where

• Queue to operate on is specified as:

Queue as...	Specifies
%variable	Queue name
name	Literal without quotation marks
external_qmanager:external_queue	External name of a queue manager that contains the remote queue to process and the external name of the remote queue

• option is one or more of the following options:
  • ACCEPT_TRUNCATED_MSG or NO_ACCEPT_TRUNCATED_MSG
  • ALL_MSGS_AVAILABLE or NOT_ALL_MSGS_AVAILABLE (default)
  • CONTEXT
  • EXPIRY
  • FAIL_IF_QUIESCING or NO_FAIL_IF_QUIESCING
  • FORMAT
  • LOGICAL_ORDER or NOT_LOGICAL_ORDER (default)
  • MSGTYPE
  • PERSISTENT or NOT_PERSISTENT
  • PERSISTENCE_AS_Q_DEF
  • SYNCPOINT or NO_SYNCPOINT
  • PRIORITY or PRIORITY_AS_Q_DEF
  • REPLY_QMGR
  • REPLY_QUEUE
  • REPORT
  • WAIT or NO_WAIT
  • WAIT_TIME
• ?%variable specifies option(s) of the MODIFY QUEUE statement to compile at evaluation time. For more information on ?%variables, see Using runtime options.

Usage

Options that apply to MQGET, MQPUT, and MQPUT1 statements can be specified in the DEFINE QUEUE command, and defaults for MQGET and MQPUT statements can be specified in an OPEN QUEUE statement.

You can override defined options by specifying the desired options directly on an MQGET, MQPUT, or MQPUT1 statement.

If you are repeatedly overriding DEFINE QUEUE command options, you might prefer to alter the current options for an open queue using the MODIFY QUEUE statement.

MONITOR MQ: Monitoring MQ/204

Privileges

System manager or User 0

Function

Aids the system manager in controlling an Online that is using MQ/204. The MQ option provides information on the MQ/204 features.

Syntax

MONITOR MQ [(QUEUEMANAGER | QM) qmanager_entity_name | (QUEUE | Q) queue_entity_name] [SUBTASKS] [SUMMARY] [EVERY n]

Where

• QUEUEMANAGER (or QM) and QUEUE (or Q) can be used to filter the output of MONITOR MQ:
  • If a QUEUEMANAGER clause is specified, output is restricted to that queue manager.
  • If a QUEUE clause is specified, output is restricted to the specified queue.

  The QUEUEMANAGER, QUEUE, and SUBTASK clauses are mutually exclusive. To monitor the clauses in succession, you must issue a separate MONITOR MQ command for each clause.

• SUBTASKS produces a report of WebSphere MQ subtask activity. The report includes the following numeric output about subtasks:
  • Allocated
  • Currently in use
  • Free, but connected to a queue manger
  • Free and unconnected

  This report also lists the queue managers to which subtasks are currently connected and indicates how many are connected to each.

• SUMMARY limits the output produced by MONITOR MQ:
  • If SUMMARY is specified, the list of users who have each queue open is omitted from the report.
  • If both SUBTASKS and SUMMARY are specified, the list of queue managers and count of subtasks connected to each are omitted from the subtask report.
• EVERY n clause provides the command refresh capability.

Usage

Output from the MONITOR MQ command goes to USE output, if USE is active.

The MONITOR MQ command lists defined queue managers by both entity and external name, and whether they have been stopped or started. After each queue manager, a list of all queues for that queue manager is displayed, also by entity and external name. After each queue name, a list of the current users is displayed with the following data:

• User number.
• User name.
• Last WebSphere MQ API call made.
• CompCode and Reason display headings for the last call separated by a slash (/) or the word PENDING, if the call has not yet completed. CompCode and Reason values are returned by all WebSphere MQ API calls.
• Number of bytes of data transferred on the last put or get.

Examples

The following example shows output from a MONITOR MQ command:

> MONITOR MQ QUEUEMANAGER: PRODUCTION EXTERNAL NAME: SYS1.PRODUCTION STATUS: STARTED QUEUE: INCOMING EXTERNAL NAME: INQUEUE.FOR.WORK USER USERID LASTCALL STATUS DATALEN ------ ---------- -------- ------- ------- 25 JOE MQGET 0/0 50 QUEUE: OUTGOING EXTERNAL NAME: OUTQUEUE.FOR.WORK USER USERID LASTCALL STATUS DATALEN ------ ---------- -------- ------- ------- 25 JOE MQPUT 0/0 50 56 FRED MQPUT1 PENDING 50 QUEUEMANAGER: TEST EXTERNAL NAME: SYS1.TEST STATUS: STOPPED QUEUE: INBOX EXTERNAL NAME: TEST.INBOX USER USERID LASTCALL STATUS DATALEN ------ ---------- -------- ------- ------- 15 SALLY MQGET 0/0 1000 23 MIKE MQGET 2/2033 0 QUEUE: OUTBOX EXTERNAL NAME: TEST.OUTBOX QUEUEMANAGER: TEST2 EXTERNAL NAME: SYS1.TEST2 STATUS: DEFINED QUEUE: INBOX2 EXTERNAL NAME: TEST2.INBOX QUEUE: OUTBOX2 EXTERNAL NAME: TEST2.OUTBOX >

START QUEUEMANAGER: Making queues accessible

Privileges

System manager or User 0

Function

Validates the existence of a queue manager and marks it available for use.

Syntax

START {QUEUEMANAGER | QM} name

Where

name identifies a queue manager created with the DEFINE QUEUEMANAGER command.

Usage

If the specified queue manager is already started, the command is ignored.

Once this command has been issued successfully, queues that belong to this queue manager can be opened with the OPEN QUEUE statement or the MQPUT1 statement.

STOP QUEUEMANAGER: Put a queue manager in drain state

Privileges

System manager or User 0

Function

Places a queue manager in a drain state.

Syntax

STOP {QUEUEMANAGER | QM} name

Where

name identifies a queue manager created with a DEFINE QUEUEMANAGER command.

Usage

If the queue manager does not exist, or has not been started, an error message is issued. If it has already been stopped, the command is ignored.

Once the command is issued, you cannot open any queues for this queue manager. Attempts to open such queues fail with a $STATUS return code of six (6). However, any current users with open connections to the queue manager are not impacted. You can make the queue manager available again by issuing the START QUEUEMANAGER command.

See also

• MQ/204 overview
• MQ/204 architecture and environment
• MQ/204 queue management
• MQ/204 data conversion and handling
• MQ/204 messages
• MQ/204 monitoring and troubleshooting
• MQ/204 command reference
• MQ/204 and SOUL statements
• MQ/204 options for commands and statements
• MQ/204 functions reference
• MQ/204 programming