MQ/204 options for commands and statements

From m204wiki
Revision as of 20:36, 11 November 2015 by ELowell (talk | contribs)
Jump to navigation Jump to search

Overview

The definition and activity of MQ/204 queue managers, queues, and messages can be defined and changed using options. For review of how options are changed and passed by MQ/204 statements and commands, see Rules of inheritance.

MQ/204 options

The options in the following table apply to the commands and statements listed.

Note: You cannot use option=%variable in a DEFINE QUEUE command.

Options for MQ/204 commands and statements
Option Purpose Discussion Can be set on...
ACCEPT_TRUNCATED_MSG If a message was truncated because the target was too small, removes it from the queue; or, if browsing, advances the browse cursor. Corresponds to the WebSphere MQ option MQGMO_ACCEPT_TRUNCATED_MSG. DEFINE QUEUE

MODIFY QUEUE
MQGET
OPEN QUEUE

NO_ACCEPT_TRUNCATED_MSG(default) Truncated message is not removed from the queue; the browse cursor is not advanced. This option is the alternate to ACCEPT_TRUNCATED_MSG option. DEFINE QUEUE

MODIFY QUEUE
MQGET
OPEN QUEUE

ACCOUNTINGTOKEN='value'

or =%variable

Sets the value of the Accounting Token portion of the identity context. String from 1 to 32 characters long. MQPUT

MQPUT1

ALL_MSGS_AVAILABLE Use on an MQGET call to retrieve only messages that belong to complete groups, as well as messages that do not belong to a group.   DEFINE QUEUE

MODIFY QUEUE
MQGET

OPEN QUEUE
NOT_ALL_MSGS_AVAILABLE (default) Use on an MQGET call to retrieve any message in the queue, including partial groups.   DEFINE QUEUE

MODIFY QUEUE
MQGET

OPEN QUEUE
ALLOW_PASS_ALL_CONTEXT Passes origin context information on all subsequent MQPUT calls. Corresponds to WebSphere MQ MQOO_PASS_ALL_CONTEXT.

Can be specified only if the OUTPUT option is also specified.

 OPEN QUEUE
ALLOW_PASS_IDENTITY_CONTEXT Passes identity context information on all subsequent MQPUT calls. Corresponds to WebSphere MQ MQOO_PASS_IDENTITY_CONTEXT.

Can be specified only if the OUTPUT option is also specified.

 OPEN QUEUE
ALLOW_SET_ALL_CONTEXT Sets origin context information on all subsequent MQPUT calls. Corresponds to WebSphere MQ MQOO_SET_IDENTITY_CONTEXT.

Can be specified only if the OUTPUT option is also specified.

 OPEN QUEUE
ALLOW_SET_IDENTITY_CONTEXT Sets identify context information on all subsequent MQPUT calls. Corresponds to WebSphere MQ MQOO_SET_IDENTITY_CONTEXT.

Can be specified only when the OUTPUT option is also specified.

 OPEN QUEUE
APPLIDENTITYDATA='value'
or =%variable		 Sets the value of the ApplIdentityData portion of the identity context. String from 1 to 32 characters long.

Defaults to blanks.

 MQPUT

MQPUT1

APPLORIGINDATA='value'
or =%variable		 Sets the value of the ApplOriginData portion of the origin context. String from 1 to 4 characters long.

Defaults to blanks.

 MQPUT

MQPUT1

BROWSE Examines messages without removing them from the queue. Corresponds to WebSphere MQ MQOO_BROWSE.

Compatible with all other access options.

 OPEN QUEUE
BROWSE_FIRST First message is retrieved, but not deleted from the queue:
  • If either MSGID or CORRELID is specified, the first matching message on the queue is browsed.
  • If neither MSGID nor CORRELID is specified, then the first message on the queue is browsed.
 Corresponds to WebSphere MQ MQGMO_BROWSE_FIRST; is mutually exclusive with BROWSE_NEXT.

You can specify this option only if the queue was opened in browse mode.

 MQGET
BROWSE_MSG_UNDER_CURSOR Reread the same message again. You would typically do this to unlock a locked message or vice versa.

See the LOCK and UNLOCK options later in this table.

 MQGET
BROWSE_NEXT Next message, relative to the current browse position, is retrieved, but not deleted from the queue:
  • If either MSGID nor CORRELID is specified, the next matching message on the queue is browsed.
  • If neither MSGID or CORRELID is specified, then the next message on the queue is browsed.
Corresponds to WebSphere MQ MQGMO_BROWSE_NEXT; is mutually exclusive with BROWSE_FIRST.

You can specify this option only if the queue was opened in browse mode.

 MQGET
BUFLEN=n or =%variable Specifies the maximum number of bytes to get or put. Resized according to size of BUFFER (formerly and still accepted MQ_BUFFER) area. MQGET

MQPUT

MQPUT1
CONTEXT=name or =%variable Passes name of a queue entity from which context information should be passed. Context can be passed only from a queue that is opened for input with the SAVE_ALL_CONTEXT option.

DEFINE QUEUE
MODIFY QUEUE
MQPUT
MQPUT1
OPEN QUEUE

CONVERT (default) Converts messages from one system to another for the convenience of the recipient; from EBCDIC to ASCII, for example. Corresponds to WebSphere MQ MQGMO_CONVERT. MQGET
CORRELID='msgid '
or =%variable		 Value to place in the correlation ID field of the message. On a reply message, the ID of the request being replied to (MQMD.MsgId) is often set in this field. However, the correlation ID might be set on any message type. String from 1 to 24 characters long containing a correlation ID to use as matching criterion.

Default is blanks.

Corresponds to WebSphere MQ MQMD.CorrelId.

You can specify the value as a %variable.

 MQGET

MQPUT

MQPUT1
DEFAULT_CONTEXT Message is put with the default context information. Corresponds to WebSphere MQ option MQPMO_DEFAULT_CONTEXT.

Mutually exclusive with:

  • NO_CONTEXT
  • PASS_ALL_CONTEXT
  • PASS_IDENTITY_CONTEXT
  • SET_ALL_CONTEXT
  • SET_IDENTITY_CONTEXT
 MQPUT

MQPUT1
DELETE Deletes a permanent local dynamic queue when there are no more messages on the queue and no uncommitted MQGET or MQPUT requests outstanding. Corresponds to WebSphere MQ option MQCO_DELETE. CLOSE QUEUE
DELETE_PURGE Deletes a temporary local dynamic queue and purges all outstanding messages and requests. Corresponds to WebSphere MQ option MQCO_DELETE_PURGE. CLOSE QUEUE
DESCRIPTOR=image (optional) Image in which to place the message descriptor (MQMD structure).
(See MQPUT statement.)		 A given application might not need the message descriptor. If the size of this image is less than the size of an MQMD, then the MQMD is truncated. MQGET

MQPUT
MQPUT1

DYNAMICQNAME=name
or =%variable		 Specifies the name of a preallocated WebSphere MQ model queue. Must be set with the MODEL option. MQOPEN
EXPIRY=n
or =UNLIMITED
or =%variable		 Expiration period of the message in tenths of a second. Corresponds to MQMD.Expiry field. The default is UNLIMITED (no expiration). DEFINE QUEUE

MODIFY QUEUE
MQPUT
MQPUT1

OPEN QUEUE
FAIL_IF_QUIESCING Operation fails if the queue manager is inactive. Corresponds to the WebSphere MQ MQGMO_FAIL_IF_QUIESCING option. DEFINE QUEUE

MODIFY QUEUE
MQGET
MQPUT
MQPUT1

OPEN QUEUE
NO_FAIL_IF_QUIESCING (default) Operation waits if the queue manager is inactive. This option is the alternate to FAIL_IF_QUIESCING option. DEFINE QUEUE

MODIFY QUEUE
MQGET
MQPUT
MQPUT1

OPEN QUEUE
FEEDBACK=NONE (default)

or =n
or =%variable

Feedback (or reason code) that accompanies a REPORT message.

This value is used only on a REPORT. Valid values are:

  • NONE
  • Integers between MQFB_APPL_FIRST (65536) and MQFB_APPL_LAST (999999999)
  • %variable

Corresponds to WebSphere MQ MQMD.Feedback.

MQPUT
MQPUT1

FORMAT=format

or =%variable

Name of the conversion exit set. String of 1 to 8 characters.

Conversion exit is invoked when the received message uses a different character set or number format than those specified in the message descriptor.

Corresponds to WebSphere MQ MQMD.Format field.

There is no default conversion exit set.

 DEFINE QUEUE

MODIFY QUEUE
MQPUT
MQPUT1
OPEN QUEUE

GROUPID The GROUPID is a 24-byte field that you specify when writing messages that belong to a group. You must specify GROUPID as a null string (or spaces) on the first message of any group. For MQGET, MQPUT, and MQPUT1 calls, the group identifier of the message is returned in the MQMD, not in the GROUPID field, which is always an input field only.

On an MQGET call, this is an input field when MATCH_GROUP_ID is specified.

 MQGET

MQPUT

MQPUT1

GSTATUS

= [ ' ' | 'G' | 'L']		 The one-byte GSTATUS field determines whether the message is part of a group. The possible values are:
  • 'G' (all messages in a group except the last or only one)
  • 'L' (the last or only logical message in a group)
  • Space or null (the message is not in a group)
On MQGET operations, this is an output %variable. If you are writing messages that belong to a group but are not in logical order, set this to 'L' for the message that has the highest sequence number.

The default, for MQPUT and MQPUT1 operations, is null--the message does not form part of a group.

 MQGET

MQPUT
MQPUT1

INPUT_AS_Q_DEF

(default for local queues)

Gets messages with shared or exclusive access based on the default selected when the queue was created. Corresponds to WebSphere MQ MQOO_INPUT_ AS_Q_DEF.

Mutually exclusive with:

  • INPUT_EXCLUSIVE
  • INPUT_SHARED
  • BROWSE
 OPEN QUEUE
INPUT_EXCLUSIVE Gets messages and deletes them from the queue, with exclusive access to the queue. Corresponds to WebSphere MQ MQOO_INPUT_EXCLUSIVE.

Mutually exclusive with:

  • BROWSE
  • INPUT_AS_Q_DEF
  • INPUT_EXCLUSIVE
 OPEN QUEUE
INPUT_SHARED Gets messages and deletes them from the queue, with shared access to the queue. Corresponds to WebSphere MQ MQOO_INPUT_SHARED.

Mutually exclusive with:

  • BROWSE
  • INPUT_AS_Q_DEF
  • INPUT_EXCLUSIVE
 OPEN QUEUE
LOCK LOCK lets you browse a queue and lock the current message so that other threads do not see it. The default is not to lock messages while browsing them. MQGET
UNLOCK UNLOCK lets you remove a lock from a previously-locked message. When you specify UNLOCK, the message itself is not returned, it is just unlocked. MQGET
LOGICAL_ORDER Write one group at a time and write messages in sequential order, starting at 1. This is the simpler way of writing a group of messages. However, it is not the default. DEFINE QUEUE

MODIFY QUEUE
MQGET
MQPUT
OPEN QUEUE

NOT_LOGICAL_ORDER (default) This option gives you more control over the writing of groups, but requires that you specify SEQUENCE and GROUPID for each message. You can also use this setting for messages that are not a group. DEFINE QUEUE

MODIFY QUEUE
MQGET
MQPUT
MQPUT1

OPEN QUEUE
MARK_SKIP_BACKOUT Messages taken from the queue under syncpoint control are not placed back on the queue if the user or the Online issues an MQBACK. Messages are placed back on the queue, if the MQBACK is issued by the WebSphere MQ system software.

Corresponds to WebSphere MQ MQGMO_MARK_SKIP_BACKOUT.

This option can be useful to prevent get, error, back out loops. See Removing messages that cause errors.

 MQGET
MATCH_CORREL_ID (default) Retrieve messages that match the specified CORRELID. If CORRELID is not specified, this option is ignored. MQGET
NOT_MATCH_CORREL_ID Retrieve any message in the queue, if CORRELID is specified.   MQGET
MATCH_MSG_GROUP_ID Retrieve messages that match the specified GROUPID. The queue must be indexed by GROUPID. MQGET
MATCH_MSG_ID (default) Retrieve messages that match the specified MSGID. If MSGID is not specified, this option is ignored. MQGET
NOT_MATCH_MSG_ID Retrieve any message in the queue, if MSGID is specified.   MQGET
MATCH_MSG_SEQ_NUMBER Retrieve the message that matches SEQUENCE for the current group. If there is no current group, the only valid value of SEQUENCE is 1. The queue must be indexed by GROUPID. MQGET
MATCH_MSG_TOKEN Use this to retrieve messages that match the specified MSGTOKEN The queue must be indexed by MSGTOKEN. MQGET
MODEL=name
or =%variable		 Specifies the internal, Model 204 name of the local dynamic queue. Must be set in the same statement with the DYNAMICQNAME option. MQOPEN

MSG_UNDER_CURSOR

Removes the message under the current browse position from the queue (a real MQGET). Corresponds to WebSphere MQ MQGMO_MSG_UNDER_CURSOR.

Specify only if the queue is in both browse and input modes: cannot be specified with BROWSE_FIRST or BROWSE_NEXT.

MQGET
MSGID='msgid '
or =%variable		 Message identifier to use as matching criterion. Value is either a %variable or a string from 1-24 characters that:
  • You enter

or

  • Queue manager automatically generates

Corresponds to WebSphere MQ MQMD.MsgId.

 MQGET

MQPUT

MQPUT1
MSGLEN=%variable Specifies an output variable in which to return the actual message length. Returned message length is less in the event of truncation. MQGET
MSGTOKEN You can select messages by 16-byte message token (MSGTOKEN) by specifying this field as an input field on MQGET statements with MATCH_MSG_TOKEN. This is also an output field, retrieving the message token that was assigned by the queue manager. (On the MQGET call, it can also be an input field, if MATCH_MSG_TOKEN is specified. MQGET

MQPUT

MQPUT1
MSGTYPE=DATAGRAM (default)

or =REPLY
or =REPORT
or =REQUEST
or =%variable

or = application-defined numeric value		 Specifies the type of message;
sets the MQMD.MsgType.		 Types specified by keyword are:
  • DATAGRAM, a simple message that needs no reply; corresponds to WebSphere MQ MQMT_DATAGRAM constant.
  • REPLY, a response to REQUEST; corresponds to WebSphere MQ MQMT_REPLY constant.
  • REPORT, a message that signifies an error condition or exception that is often requested in the report field of another message; corresponds to WebSphere MQ MQMT_REPORT constant.
  • REQUEST, a message that requires a reply; corresponds to WebSphere MQ MQMT_REQUEST constant.
 DEFINE QUEUE

MODIFY QUEUE
MQPUT
MQPUT1

OPEN QUEUE
NEW_CORREL_ID This option on the MQPUT statement tells the queue manager to generate a new correlation ID for the message. The CORRELID option should not be specified with this option, because the queue manager generates a unique correlation identifier, rather than taking it from the CORRELID option. MQPUT
MQPUT1
NO_CONTEXT Message is placed in the queue without any context information. Corresponds to WebSphere MQ option MQPMO_NO_CONTEXT.

Mutually exclusive with:

  • DEFAULT_CONTEXT
  • PASS_ALL_CONTEXT
  • PASS_IDENTITY_CONTEXT
  • SET_ALL_CONTEXT
  • SET_IDENTITY_CONTEXT
 MQPUT
MQPUT1
NO_CONVERT Specifies turning off MQGMO_CONVERT. Used in error-handling code to remove messages that did not convert from within the SOUL application and are now stuck on the queue.

See Removing messages that do not convert.

 MQGET
OUTPUT (default for remote queues) Puts messages. Corresponds to WebSphere MQ option MQOO_OUTPUT. OPEN QUEUE
PASS_ALL_CONTEXT All context information is passed through from an input queue. Corresponds to the WebSphere MQ option MQPMO_PASS_ALL_CONTEXT.

Mutually exclusive with:

  • DEFAULT_CONTEXT
  • NO_CONTEXT
  • PASS_IDENTITY_CONTEXT
  • SET_ALL_CONTEXT
  • SET_IDENTITY_CONTEXT
 MQPUT
MQPUT1
PASS_IDENTITY_CONTEXT Identity context information is passed through from an input queue. Corresponds to the WebSphere MQ option MQPMO_PASS_IDENTITY_CONTEXT.

Mutually exclusive with:

  • DEFAULT_CONTEXT
  • NO_CONTEXT
  • PASS_ALL_CONTEXT
  • SET_ALL_CONTEXT
  • SET_IDENTITY_CONTEXT
 MQPUT

MQPUT1

PASS_USER_CONTEXT Passes user context from the queue identified in the CONTEXT parameter. UserIdentifier field value from the last MQGET is passed along with the ALTERNATE_USER_AUTHORITY option. The queue is opened according to the authority granted. MQPUT1
OPEN QUEUE
PERSISTENT Persistent message that survives a restart of the queue manager. Corresponds to the WebSphere MQ option MQPER_PERSISTENT of the field MQMD.Persistence.

This option is an alternate to NOT_PERSISTENT and PERSISTENCE_AS_Q_DEF.

DEFINE QUEUE
MODIFY QUEUE
MQPUT
MQPUT1
OPEN QUEUE

NOT_PERSISTENT Message that does not survive restart of the queue manager. Corresponds to the WebSphere MQ option MQPER_NOT_PERSISTENT of the field MQMD.Persistence.

This option is an alternate to PERSISTENT and PERSISTENCE_AS_Q_DEF.

 DEFINE QUEUE

MODIFY QUEUE
MQPUT
MQPUT1
OPEN QUEUE

PERSISTENCE_AS_Q_DEF (default) Persistence of the message defaults to the persistence selected when the queue was defined. Corresponds to the WebSphere MQ option PERSISTENCE_AS_Q_DEF of the field MQMD.Persistence.

This option is tan alternate to PERSISTENT and NOT_PERSISTENT.

 DEFINE QUEUE

MODIFY QUEUE
MQPUT
MQPUT1

OPEN QUEUE
PRIORITY=n

or PRIORITY_AS_Q_DEF (default)
or =%variable

Priority of the message in the range from 0 to 9; zero is the lowest priority. Default is priority for the queue object as defined within WebSphere MQ.

Corresponds to MQMD.Priority field in a WebSphere MQ control block.

DEFINE QUEUE

MODIFY QUEUE
MQPUT
MQPUT1

OPEN QUEUE
PUTAPPLNAME='value'
or =%variable		 Sets the value of the PutApplName portion of the origin context. String from 1 to 28 characters long. MQPUT
MQPUT1
PUTAPPLTYPE=keyword

or =number

or =%variable		 Identifies the type of application that put the message. If the value is a %variable or a number, it must be within the range -1 to 999,999,999 inclusive.

Otherwise, the value is one of the following keywords:

  • AIX
  • CICS
  • CICS_VSE
  • DEFAULT
  • DOS
  • GUARDIAN
  • IMS
  • IMS_BRIDGE
  • z/OS
  • NO_CONTEXT
  • OS2
  • OS400
  • QMGR
  • UNIX
  • UNKNOWN
  • VMS
  • VOS
  • WINDOWS
  • WINDOWS_NT
  • XCF
 MQPUT
MQPUT1
PUTDATE=value
or =%variable		 Sets the value of the PutDate portion of the origin context. String from 1 to 8 characters long. MQPUT
MQPUT1
PUTTIME=value
or =%variable		 Sets the value of the PutTime portion of the origin context. String from 1 to 8 characters long. MQPUT
MQPUT1
REPLY_QMGR=name
or =%variable		 Name of queue manager for remote queue to place the reply in. Used only on MSGTYPE=REQUEST

No default.

Sets the value of MQMD.ReplyToMGR.

String of up to 48 characters.

 DEFINE QUEUE

MODIFY QUEUE
MQPUT
MQPUT1
OPEN QUEUE

REPLY_QUEUE=name
or =%variable		 Name of the queue to place the reply in. Used only on a MSGTYPE=REQUEST.

Default is the name of the queue that contained the request.

Sets the values of MQMD.ReplyToQ.

Sets the value of MQMD.ReplyToMGR if no REPLY_QMGR option is indicated.

String of up to 48 characters.

DEFINE QUEUE

MODIFY QUEUE
MQPUT
MQPUT1

OPEN QUEUE
REPORT=option+option...

or =n

or =%variable (numeric values only)		 Report options, which specify:
  • What conditions you want reported
  • How to construct the report message
 Options are keywords that you combine with plus signs. The available option keywords are the MQRO_ options.
  • Keywords cannot be specified in a %variable.
  • Keywords are specified without the MQRO_ prefix.

Alternatively, you can specify a numeric value, either as a literal or a %variable.

See WebSphere MQ documentation for the recommended WebSphere MQ documentation, which describes the acceptable numeric values.

No default report options are passed.

 DEFINE QUEUE

MODIFY QUEUE
MQPUT
MQPUT1

OPEN QUEUE
SAVE_ALL_CONTEXT Saves context information when messages are retrieved with MQGET. Corresponds to WebSphere MQ MQOO_SAVE_ALL_CONTEXT.

Can be specified only if one of the INPUT_* options is also specified.

 OPEN QUEUE
SEQUENCE=%variable For messages that are part of a group and NOT_LOGICAL_ORDER is specified (or is the default), this number specifies the logical position of the message within the group, which need not be the physical sequence in which the messages are written. The logical first message is message sequence 1.

On MQGET operations, this is an input variable used only with the MATCH_MSG_SEQ_NUMBER option.

On MQPUT and MQPUT1 operations, this is an input variable that specifies the logical position within the group of the message being written.

 This is a fixed %variable. To retrieve the logical sequence of a message in an MQGET operation, use the DESCRIPTOR option and get the sequence number from the returned MQMD image.

When using SEQUENCE with the MATCH_MSG_SEQ_NUMBER option, you can only match a SEQUENCE greater than 1 within the current group. You cannot, for example, do a repeated BROWSE_NEXT with SEQUENCE 2 to jump from one group to another.

 MQGET

MQPUT

MQPUT1
SET_ALL_CONTEXT Origin context information is set with values from the APPLORIGINDATA, PUTAPPLNAME, PUTAPPLTYPE, PUTDATE, and PUTTIME options. Corresponds to the WebSphere MQ option MQPMO_SET_ALL_CONTEXT.

Mutually exclusive with:

  • DEFAULT_CONTEXT
  • NO_CONTEXT
  • PASS_ALL_CONTEXT
  • PASS_IDENTITY_CONTEXT
  • SET_IDENTITY_CONTEXT
 MQPUT
MQPUT1
SET_IDENTITY_CONTEXT Identity context information is set with values from the ACCOUNTINGTOKEN, APPLIDENTITYDATA, and USERIDENTIFIER fields. Corresponds to the WebSphere MQ option MQPMO_SET_IDENTITY_CONTEXT.

Mutually exclusive with:

  • DEFAULT_CONTEXT
  • NO_CONTEXT
  • PASS_ALL_CONTEXT
  • PASS_IDENTITY_CONTEXT
  • SET_ALL_CONTEXT
 MQPUT
MQPUT1
SYNCPOINT (default) Get and put operations are under transaction control. Operates on updates for MQCMIT and MQBACK. DEFINE QUEUE

MODIFY QUEUE
MQGET
MQPUT
MQPUT1

OPEN QUEUE
NO_SYNCPOINT Get and put operations are not under transaction control. Does not operate on updates for MQCMIT and MQBACK. DEFINE QUEUE

MODIFY QUEUE
MQGET
MQPUT<
MQPUT1

OPEN QUEUE
SYNCPOINT_IF_PERSISTENT This option on the MQGET statement works like SYNCPOINT, but is effective only for persistent messages.   MQGET
USERIDENTIFIER='value'
or =%variable		 Sets the value of the User identifier portion of the identity context. String from 1 to 12 characters long. MQPUT
MQPUT1
WAIT Wait, if a message is unavailable. You can displace a wait.

This option is the alternate to NO_WAIT option.

The maximum waiting time is specified with WAIT_TIME.

DEFINE QUEUE

MODIFY QUEUE
MQGET

OPEN QUEUE
NO_WAIT (default) Do not wait, if a message is unavailable. Corresponds to the WebSphere MQ option MQGMO_NO_WAIT. DEFINE QUEUE

MODIFY QUEUE
MQGET

OPEN QUEUE
WAIT_TIME=n

or =UNLIMITED

or =%variable		 Maximum time to wait, in milliseconds, if the WAIT option is specified. Default is 0 milliseconds.

To wait forever, specify a value of UNLIMITED, which corresponds to WebSphere MQ MQWI_UNLIMITED.

 DEFINE QUEUE

MODIFY QUEUE
MQGET

OPEN QUEUE
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=MQ/204_options_for_commands_and_statements&oldid=81640"