IBM MQ queue properties

The properties that you can set for a queue depend on the type of queue. Different types of IBM® MQ queues have different properties. Some of the properties do not apply to all types of queue, some properties are specific to cluster queues, and some properties are specific to z/OS® queues.

The following tables list the properties that you can set for all types of queues:

For each property, there is a brief description of when you might need to configure the property. The tables also give the equivalent MQSC parameter for the DEFINE, ALTER and DISPLAY QUEUE commands. For more information about MQSC commands, see The MQSC Commands.

General page

The following table lists the properties you can set on the General page of the Queue properties dialog.

Property Description MQSC parameter
Queue name Read-only. You cannot change the name of the queue after it has been created. QNAME
Queue type Read-only. You cannot change the type of the queue after it has been created. QTYPE
QSG disposition (z/OS shared queue only) Read-only. The queue sharing group disposition of the queue. Specifies the disposition of the object (where it is defined and how it behaves). You cannot change the disposition of a queue after it has been created. Queue manager means that the object definition is available only to the queue manager that hosts it; Group means that the object definition is stored on the shared repository and each queue manager in the queue sharing group has a copy of the definition; Copy means that the object definition is the queue manager's copy of a definition in the shared repository; Shared means that the object definition is stored on the queue sharing group's coupling facility and is available to all the queue managers in the queue sharing group. QSGDISP
Description Type a meaningful description of the purpose of the queue. See Strings in property dialogs. DESCR
Put messages To enable messages to be put on the queue, select Allowed; to prevent messages from being put on the queue, select Inhibited. PUT
Get messages To enable messages to be got from the queue, select Allowed; to prevent messages being got from the queue, select Inhibited. GET
Default priority Type the default priority, from 0 - 9, of messages that are put on the queue; 0 is the lowest priority. DEFPRTY
Default persistence The default persistence of a new queue is Not persistent. Select Persistent to specify that messages created by applications that use MQPER_PERSISTENCE_AS_Q_DEF become persistent. Select Not Persistent to specify that messages created by applications that use MQPER_PERSISTENCE_AS_Q_DEF become non persistent. DEFPSIST
Scope To put the queue in the cell directory and make the queue known to all the queue managers within the cell, select Cell; to restrict the queue's scope so it does not extend beyond its queue manager, select Queue Manager. SCOPE
Usage To make the queue a local queue, select Normal; to make the queue a transmission queue, select Transmission. Do not change the Usage property while there are messages on the queue. USAGE
Base type Select the type of object (Queue or Topic) to which the alias queue resolves. The default value is Queue. TARGTYPE
Remote queue Type the name of the queue to which the remote queue definition points. RNAME
Remote queue manager Type the name of the queue manager that hosts the remote queue. RQMNAME
Transmission queue Type the name of the transmission queue that the local queue manager uses to send messages to the remote queue manager. XMITQ

Extended page

The following table lists the properties you can set on the Extended page of the Queue properties dialog.

Property Description MQSC parameter
Max queue depth Type the maximum number of messages that are allowed on the queue. Specify a value from 0 - 999999999. MAXDEPTH
Max message length Type the maximum length of a message, in bytes, that is allowed on the queue. On all platforms other than z/OS, specify a value from 0 to the maximum message length for the queue manager. See the Maximum message length property in Queue manager properties. On z/OS, specify a value from 0 - 100 MB. MAXMSGL
Shareability To share the queue so that more than one instance of an application can open this queue for input, select Shareable; to restrict the queue so that only one instance of an application can open the queue at a time, select Not Shareable. SHARE
Default input open option To allow applications that open the queue for input to have exclusive access to the messages on the queue, select Exclusive; to allow any number of applications that open the queue for input to access the messages on the queue, select Shared. DEFSOPT
Message delivery sequence To specify to get messages from the queue in order of their priority, select Priority. To specify to get messages from the queue in the order that they were put on the queue, select FIFO (first in, first out). MSGDLVSQ
Retention interval Type the number of hours from the date and time when it was created (from 0 - 999999999) that the queue might be needed. You can use this information to determine when the queue is no longer required. The queue will not be deleted when it is no longer required. RETINTVL
Index type To specify the type of index that the queue manager maintains to increase the speed of MQGET operations on the queue, select one of these five options:

None: No index is maintained. Use this when retrieving messages sequentially. This is the default.

Group ID: An index of group identifiers is maintained. You must use this index type if you want logical ordering of message groups.

Correl ID: An index of correlation identifiers is maintained. Use this when retrieving messages using the CorrelId field as a selection criterion on the MQGET call.

Message ID: An index of message identifiers is maintained. Use this when retrieving messages using the MsgId field as a selection criterion on the MQGET call.

Message token: An index of message tokens is maintained.

 
Definition type For local queues, this property is read-only: Predefined means that the queue was created by an operator or an authorized application sending a command message to the service queue; Permanent dynamic means that the queue was created by an application issuing an MQOPEN call with the name of a model queue specified in the object descriptor (MQOD) and the queue is permanent; Temporary dynamic means that the queue was created by an application issuing an MQOPEN call, but the queue is temporary; Shared dynamic (z/OS only) also means that the queue was created by an application issuing an MQOPEN call, but the queue is permanent and has the queue sharing group disposition of Shared.

For model queues, this property is editable; To specify that a permanent dynamic queue is created from this model queue, select Permanent dynamic (on z/OS, the dynamic queue has a disposition of Queue manager); to specify that a temporary dynamic queue is created, select Temporary dynamic (on z/OS, the dynamic queue has a disposition of Queue manager); on z/OS only, to specify that a permanent dynamic queue is created with a disposition of Shared, select Shared dynamic.

DEFTYPE
Default read ahead To configure read ahead at the queue level, select Yes. Non-persistent messages are automatically read ahead by the client, ahead of the application requesting them. Non-persistent messages might be lost if the client ends abnormally or if the client application does not consume all the messages it is sent.

To configure the queue so that non-persistent messages are not automatically read ahead by the client, select No. This is the default value. Messages are not automatically read ahead by the client ahead of an application requesting them. Messages are only read ahead if requested by the client. A maximum of one non-persistent message might be lost if the client ends abnormally.

To disable read ahead at the queue level, select Disabled. Messages are not read ahead by the client ahead of an application requesting them, regardless of whether read ahead is requested by the client application.

DEFREADA
Default put response type The default response type for message puts. To specify that the response is put synchronously, select Synchronous. To specify that the response is put asynchronously, select Asynchronous. DEFPRESP
Distribution lists To allow distribution list messages to be put on the queue, select Enabled. To prevent distribution list messages being put on the queue, select Disabled. DISTL
Property control

(Only on Local queues, Alias queues, and Model queues)

This defines what happens to properties of messages that are retrieved from queues using the MQGET command when the MQGMO_PROPERTIES_AS_Q_DEF option is specified.

To contain all the properties of the message, except those contained in the message descriptor (or extension), select All. The All value means that all properties of the message are included with the message when it is sent to the remote queue manager. The properties, except those properties in the message descriptor (or extension), are placed in one or more MQRFH2 headers in the message data.

To allow applications that expect JMS related properties to be in an MQRFH2 in the message data to continue to work unmodified, select Compatibility. This is the default value. Compatibility means that if the message contains a property with a prefix of mcd., jms., usr., or mqext. then all message properties are delivered to the application in an MQRFH2 header. Otherwise all properties of the message, except those contained in the message descriptor (or extension), are discarded and are no longer accessible to the application.

To ensure that properties are always returned in the message data in an MQRFH2 header, regardless of whether the application specifies a message handle, select Force MQRFH2. A valid message handle supplied in the MsgHandle field of the MQGMO structure on the MQGET call is ignored. Properties of the message are not accessible via the message handle.

To discard all the properties of a message, except those contained in the message descriptor (or extension), select None. This value prevents applications that do not support message properties from being affected by the inclusion of any property in a message.

V6COMPAT - MQRFH2 headers are not modified by the properties code. If message properties have been provided and are not contained in the original MQRFH2 headers, they are returned in a message handle or otherwise discarded. This behavior can be overridden by supplying one of the MQGMO_PROPERTIES options.

Note: For a transmission queue, which is a local queue with Usage set to Transmission, the Property Control property of the queue is irrelevant and it is the Property Control property on the corresponding channel object that controls the message property behavior.
PROPCTL
Custom The Custom parameter is included for IBM use only, reserved for the configuration of new features before separate properties have been introduced. The possible values are a list of zero or more properties-value pairs, in MQSC-style syntax, separated by at least one space.
The property names and values are case-sensitive, and must be specified in uppercase. The values can contain spaces, parentheses and single-quotes (which must be escaped with another single-quote). Other characters, including nested parentheses (), can be included by enclosing them in two single-quotes on either side. Examples of valid syntax are:
  • CUSTOM('')
  • CUSTOM('A(B)')
  • CUSTOM('C(D) E(F)')
  • CUSTOM('G(5000) H(''9.20.4.6(1415)'')')

The queue manager parses the value, but if the string cannot be parsed according to these rules, or if it contains properties or values that are not recognized, the queue manager ignores the errors.

CUSTOM
Cluster channel names Set the Cluster channel names parameter on a cluster transmit queue to override the default association of cluster-sender channels with cluster transmission queues. You can specify which cluster-sender channels transfer messages from this transmission queue.

The default is for all cluster-sender channels to transfer messages from a single cluster transmission queue, SYSTEM.CLUSTER.TRANSMIT.QUEUE. You can change the default for the queue manager, so that all cluster-sender channels transfer messages from separate transmission queues. The queue manager property is Default cluster transmission queue. The queue manager creates separate transmission queues automatically, when they are required. The queue manager does not set the Cluster channel name parameter

Set the Cluster channel names parameter to the name of a single cluster-sender channel, or to a generic name. A generic name associates multiple cluster-sender channels with this transmission queue. A generic name has wildcard characters, *, in any positions in the name. All cluster-sender channels that match the name transfer messages from this transmission queue and no other.

On z/OS, if this parameter is set, the queue must be shareable, be indexed by correlation ID, and must not be a dynamic or a shared queue.

CLCHNAME
[MQ 9.3.1 Oct 2022]Cap expiry The maximum time, expressed in tenths of a second, until a message put using an object handle with this object in the resolution path, becomes eligible for expiry processing.
For more information on message expiry processing, see Enforcing lower expiration times.
integer
The value must be in the range one through to 999 999 999.
NOLIMIT
There is no limit on the expiry time of messages put using this object. This is the default value.

Note that existing messages in the queue, prior to a change in CAPEXPRY, are not affected by the change (that is, their expiry time remains intact). Only new messages that are put into the queue after the change in CAPEXPRY have the new expiry time.

CAPEXPRY

Cluster page

The following table lists the properties you can set on the Cluster page of the Queue properties dialog. To share the queue in one or more clusters, edit the properties on the Cluster page.

Property Description MQSC parameter
Not shared in cluster To specify that this queue is not available to other queue managers via cluster connections, select this option. (Not applicable.)
Shared in cluster To make this queue available to other queue managers in just one cluster, select this option, then type the name of the cluster. CLUSTER
Shared in a list of clusters To make this queue available to other queue managers in more than one cluster, select this option, then type the name of the namelist that contains the list of clusters. CLUSNL
Default bind type This property specifies the binding to be used when the application specifies MQ00_BIND_AS_Q_DEF on the MQOPEN call, and the queue is a cluster queue. To bind the queue handle to a specific instance of the cluster queue when the queue is opened, select On open; to allow the queue manager to select a specific queue instance when the message is put using MQPUT, and to change that selection subsequently if necessary, select Not fixed. DEFBIND
CLWL Queue rank This property is the Cluster Workload (CLWL) queue rank. Type the ranking of the queue in the cluster, from 0 - 9; 0 is the lowest priority. For more information, see Distributed queuing and clusters. CLWLRANK
CLWL Queue priority This property is the Cluster Workload (CLWL) queue priority. Type the priority of the queue in the cluster, from 0 - 9; 0 is the lowest priority. For more information, see Distributed queuing and clusters. CLWLPRTY
CLWL use queue The Cluster Workload (CLWL) use queue property. It defines the behavior of an MQPUT when the target queue has both a local instance and at least one remote cluster instance. If the put originates from a cluster channel, this property does not apply. Select one of the following options:

Select Queue manager to use the value specified by the CLWL use queue property of the queue manager that the selected queue belongs to. This is the default value.

Select Any to use local and remote queues.

Select Local to use only local queues

For more information, see Distributed queuing and clusters.

CLWLUSEQ

Triggering page

The following table lists the properties you can set on the Triggering page of the Queue properties dialog. To configure the queue for triggering, edit the properties on the Triggering page.

Property Description MQSC parameter
Trigger control To enable triggering on the queue, select On, then configure the other trigger properties for the queue; to disable triggering on the queue, select Off. TRIGGER
Trigger type To trigger an event when the current depth of the queue goes from 0 - 1, select First; to trigger an event when the queue depth threshold is exceeded, select Depth; to trigger an event every time a message is put on the queue, select Every. TRIGTYPE
Trigger depth Type the number of messages that must be put on the queue to trigger an event. TRIGDEPTH
Trigger message priority Type the minimum priority, from 1 - 9, that a message must have for it to count towards a trigger event. The queue manager ignores messages with a lesser priority when it determines whether to create a trigger message. To count all messages towards a trigger event, type 0. TRIGMPRI
Trigger data Type free-form data for the queue manager to insert into the trigger message when the trigger event is caused by this queue. The data has no significance to the queue manager. The data is meaningful to either the trigger monitor application that processes the initiation queue, or to the application that is started by the trigger monitor. TRIGDATA
Initiation queue Type the name of the initiation queue. When the criteria for a trigger event are met, the queue manager puts a trigger message on the initiation queue. INITQ
Process name The local name of the IBM MQ process. This parameter is supported only on local and model queues.

This is the name of a process instance that identifies the application started by the queue manager when a trigger event occurs. The process does not have to be defined when the local queue is defined, but it must be available for a trigger event to occur.

If the queue is a transmission queue, then the process definition contains the name of the channel to be started. This parameter is optional, and if you do not specify a process name, then the channel name is taken from the value specified for the TRIGDATA parameter.
PROCESS

Events page

The following table lists the properties you can set on the Events page of the Queue properties dialog. To configure the queue manager to generate events in response to certain criteria on the queue, edit the properties on the Events page.

Property Description MQSC parameter
Queue depth max events To generate a Queue Full event when a message is put to the queue, but is rejected because the queue is already full, select Enabled. QDPMAXEV
Queue depth high events To generate a Queue Depth High event when a message is put to the queue causing the queue depth to be greater than or equal to the value of the Queue depth high limit property, select Enabled. QDPHIEV
Queue depth high limit This is the percentage value of the maximum queue depth that is used as the queue depth high limit. Type the maximum queue depth limit percentage with which the queue manager compares the current queue depth to determine whether to generate a Queue Depth High event. QDEPTHHI
Queue depth low events To generate a Queue Depth Low event when a message is retrieved from the queue causing the queue depth to be less than or equal to the value of the Queue depth low limit property, select Enabled. QDPLOEV
Queue depth low limit This is the percentage value of the maximum queue depth that is used as the queue depth low limit. Type the minimum queue depth limit percentage with which the queue manager compares the current queue depth to determine whether to generate a Queue Depth Low event. QDEPTHLO
Queue service interval events To generate a Queue Service Interval High event when a check indicates that no messages have been retrieved from the queue for at least the time indicated by the Queue service interval property, select High; to generate a Queue Service Interval OK event when a check indicates that messages have been retrieved from the queue within the time indicated by the Queue service interval property, select OK; to disable Queue Service Interval events, select None. QSVCIEV
Queue service interval Type the service interval, in milliseconds, from 0 - 999999999. The queue manager uses this value to determine whether to generate Queue Service Interval High or Queue Service Interval OK events. QSVCINT

Storage page

The following table lists the properties you can set on the Storage page of the Queue properties dialog. To configure how IBM MQ deals with messages that are backed out, edit the properties on the Storage page.

Property Description MQSC parameter
Backout requeue queue Type the name of the queue to which a message is transferred if it is backed out more than the number of times specified in the Backout threshold property. BOQNAME
Backout threshold Type the number of times that the message can be backed out before it is transferred to the backout queue you specified in the Backout requeue queue property. BOTHRESH
Harden get backout To ensure that the backout count (the number of times the message has been retrieved by the MQGET call and then subsequently backed out) is accurately retained if the queue manager is restarted, select Hardened. Hardening the count has a detrimental effect on performance, so select Hardened only if it is essential that the count is accurate. If it is not essential that the count is accurate, select Not hardened. HARDENBO
NPM class This property specifies the circumstances under which non-persistent messages on the queue are discarded. To specify that non-persistent messages are discarded when the queue manager is restarted, select Normal; this is valid only for non-shared queues. To specify that the queue manager should try to persist non-persistent messages for the lifetime of the queue, select High; this is valid for non-shared and shared queues; the non-persistent messages might still be lost in the event of a failure. NPMCLASS
Storage class name This is the name of the storage class that maps the queue to a page set. The queue's messages are stored on that page set. You can change this property but the queue must first be empty and closed. The storage class name must be entered in uppercase. STGCLASS
Coupling facility structure name (z/OS shared queue only) This is the name of the coupling facility structure on which the queue's messages are stored. You can change this property but the queue must first be empty and closed. CFSTRUCT
[UNIX, Linux, Windows, IBM i]Maximum queue file size The maximum size that the queue's file can grow to (in megabytes). When the queue file reaches this limit new messages cannot be put to the queue until some are removed. MAXFSIZE

Statistics page

The following table lists the properties on the Statistics page of the Queue properties dialog. The Statistics page displays information about the history of the queue. Not all of the properties can be edited.

Property Description MQSC parameter
Creation date Read-only. This is the date when the queue was created. CRDATE
Creation time Read-only. This is the time at which the queue was created. CRTIME
Open input count Read-only. This is the number of applications that are currently connected to the queue to get messages from the queue. IPPROCS
Open output count Read-only. This is the number of applications that are currently connected to the queue to put messages on the queue. OPPROCS
Current queue depth Read-only. This is the number of messages currently on the queue. CURDEPTH
Alteration date Read-only. This is the date on which the queue's properties were last altered. ALTDATE
Alteration time Read-only. This is the time at which the queue's properties were last altered. ALTTIME
Queue monitoring

You can configure IBM MQ to collect online monitoring data about the current performance of the queue. To inherit the value of the queue manager's Queue monitoring property (see Queue manager properties), select Queue manager. If the queue manager's Queue monitoring property is None, the queue's Queue monitoring property is ignored.

If the queue manager's Queue monitoring property is not None:
  • To override the queue manager's settings and prevent data collection for this queue, select Off.
  • To collect data at a low rate, select Low.
  • To collect data at a medium rate, select Medium.
  • To collect data at a high rate, select High.

For more information, see Monitoring and performance.

MONQ
Queue statistics You can configure IBM MQ to collect statistics data about the activity of the queue. To inherit the value of the queue manager's Queue statistics property (see Queue manager properties), select Queue manager. If the queue manager's Queue statistics property is None, the queue's Queue statistics property is ignored. If the queue manager's Queue statistics property is not None: to override the queue manager's settings and prevent data collection for this queue, select Off; to override the queue manager's settings and collect data, select On. For more information, see Monitoring and performance. STATQ
Queue accounting You can configure IBM MQ to collect statistics data about the activity of connections for this queue. To inherit the value of the queue manager's Queue accounting property (see Queue manager properties), select Queue manager. If the queue manager's Queue accounting property is None, the queue's Queue accounting property is ignored. If the queue manager's Queue accounting property is not None: to override the queue manager's settings and prevent data collection for this queue, select Off; to override the queue manager's settings and collect data, select On. For more information, see Monitoring and performance. ACCTQ