DEFINE queues

Use the MQSC DEFINE command to define a local, model, or remote queue, or a queue alias, reply-to queue alias, or a queue manager alias.


Use MQSC commands

For information on how we use MQSC commands, see Performing local administration tasks using MQSC commands.

This section contains the following commands:

Define a reply-to queue or queue manager alias with the DEFINE QREMOTE command.

We can issue this command from sources 2CR. For an explanation of the source symbols, see Sources from which we can issue MQSC commands on z/OS .


Usage notes for DEFINE queues

  • Successful completion of the command does not mean that the action completed. To check for true completion, see the DEFINE queues step in Check that async commands for distributed networks have finished.
  • For local queues
    1. We can define a local queue with QSGDISP(SHARED) even though another queue manager in the queue sharing group already has a local version of the queue. However, when you try to access the locally defined queue, it fails with reason code MQRC_OBJECT_NOT_UNIQUE (2343). A local version of the queue with the same name can be of type QLOCAL, QREMOTE, or QALIAS and has the disposition, QSGDISP(QMGR).

      To resolve the conflict, we must delete one of the queues using the DELETE command. If the queue we want to delete contains messages, use the PURGE option or remove the messages first using the MOVE command.

      For example, to delete the QSGDISP(LOCAL) version, which contains messages, and copy those messages to the QSGDISP(SHARED) version, then issue the following commands: 
      MOVE QLOCAL(QUEUE.1) QSGDISP(PRIVATE) TOQLOCAL(QUEUE.1) TYPE(ADD)
DELETE QLOCAL(QUEUE.1) QSGDISP(QMGR)

  • For alias queues:
    1. DEFINE QALIAS( aliasqueue ) TARGET( otherqname ) CLUSTER( c ) advertises the queue otherqname by the name aliasqueue.
    2. DEFINE QALIAS( aliasqueue ) TARGET( otherqname ) allows a queue advertised by the name otherqname to be used on this queue manager by the name aliasqueue.
    3. TARGTYPE and TARGET are not cluster attributes, that is, they are not shared in a cluster environment.

  • For remote queues:
    1. DEFINE QREMOTE( rqueue ) RNAME( otherq ) RQMNAME( otherqm ) CLUSTER( cl ) advertises this queue manager as a store and forward gateway to which messages for queue rqueue can be sent. It has no effect as a reply-to queue alias, except on the local queue manager.

      DEFINE QREMOTE( otherqm ) RNAME() RQMNAME( anotherqm ) XMITQ( xq ) CLUSTER advertises this queue manager as a store and forward gateway to which messages for anotherqm can be sent.

    2. RQMNAME can itself be the name of a cluster queue manager within the cluster. We can map the advertised queue manager name to another name locally. The pattern is the same as with QALIAS definitions.
    3. It is possible for the values of RQMNAME and QREMOTE to be the same if RQMNAME is itself a cluster queue manager. If this definition is also advertised using a CLUSTER attribute, do not choose the local queue manager in the cluster workload exit. If you do so, a cyclic definition results.
    4. Remote queues do not have to be defined locally. The advantage of doing so is that applications can refer to the queue by a simple, locally defined name. If you do then the queue name is qualified by the name of the queue manager on which the queue resides. Using a local definition means that applications do not need to be aware of the real location of the queue.
    5. A remote queue definition can also be used as a mechanism for holding a queue manager alias definition, or a reply-to queue alias definition. The name of the definition in these cases is:

      • The queue manager name being used as the alias for another queue manager name (queue manager alias), or
      • The queue name being used as the alias for the reply-to queue (reply-to queue alias).


Parameter descriptions for DEFINE QUEUE and ALTER QUEUE

Table 1 shows the parameters that are relevant for each type of queue. There is a description of each parameter after the table.

Parameter Local queue Model queue Alias queue Remote queue
ACCTQ    
BOQNAME    
BOTHRESH    
CAPEXPRY
CFSTRUCT    
CLCHNAME      
CLUSNL  
CLUSTER  
CLWLPRTY  
CLWLRANK  
CLWLUSEQ      
CMDSCOPE
CUSTOM
DEFBIND  
DEFPRESP
DEFPRTY
DEFPSIST
DEFREADA  
DEFSOPT    
DEFTYPE      
DESCR
DISTL    
FORCE  
GET  
HARDENBO or NOHARDENBO    
IMGRCOVQ    
INDXTYPE    
INITQ    
LIKE
MAXDEPTH    
MAXFSIZE    
MAXMSGL    
MONQ    
MSGDLVSQ    
NOREPLACE
NPMCLASS    
PROCESS    
PROPCTL  
PUT
queue-name
QDEPTHHI    
QDEPTHLO    
QDPHIEV    
QDPLOEV    
QDPMAXEV    
QSGDISP
QSVCIEV    
QSVCINT    
REPLACE
RETINTVL    
RNAME      
RQMNAME      
SCOPE  
SHARE or NOSHARE    
STATQ    
STGCLASS    
TARGET      
TARGQ      
TARGTYPE      
TRIGDATA    
TRIGDPTH    
TRIGGER or NOTRIGGER    
TRIGMPRI    
TRIGTYPE    
USAGE    
XMITQ      

    queue-name
    Local name of the queue, except the remote queue where it is the local definition of the remote queue.
    See Rules for naming IBM MQ objects.

    ACCTQ
    Specifies whether accounting data collection is to be enabled for the queue. On z/OS, the data collected is class 3 accounting data (thread-level and queue-level accounting). In order for accounting data to be collected for this queue, accounting data for this connection must also be enabled. Turn on accounting data collection by setting either the ACCTQ queue manager attribute, or the options field in the MQCNO structure on the MQCONNX call.

      QMGR
      The collection of accounting data is based on the setting of the ACCTQ parameter on the queue manager definition.

      ON
      Accounting data collection is enabled for the queue unless the ACCTQ queue manager parameter has a value of NONE.
      On z/OS systems, we must enable class 3 accounting using the START TRACE command.

      OFF
      Accounting data collection is disabled for the queue.

    BOQNAME (queue-name)
    The excessive backout requeue name.

    This parameter is supported only on local and model queues.

    Use this parameter to set or change the back out queue name attribute of a local or model queue. Apart from allowing its value to be queried, the queue manager does nothing based on the value of this attribute. IBM MQ classes for JMS transfers a message that is backed out the maximum number of times to this queue. The maximum is specified by the BOTHRESH attribute.

    BOTHRESH(integer)
    The backout threshold.

    This parameter is supported only on local and model queues.

    Use this parameter to set or change the value of the back out threshold attribute of a local or model queue. Apart from allowing its value to be queried, the queue manager does nothing based on the value of this attribute. IBM MQ classes for JMS use the attribute to determine how many times back a message out. When the value is exceeded the message is transferred to the queue named by the BOQNAME attribute.

    Specify a value in the range 0 - 999,999,999.

    CFSTRUCT(structure-name)
    Specifies the name of the coupling facility structure where we want messages stored when we use shared queues.

    This parameter is supported only on z/OS for local and model queues.

    The name:

    • Cannot have more than 12 characters
    • Must start with an uppercase letter (A - Z)
    • Can include only the characters A - Z and 0 - 9

    The name of the queue sharing group to which the queue manager is connected is prefixed to the name you supply. The name of the queue sharing group is always four characters, padded with @ symbols if necessary. For example, if we use a queue sharing group named NY03 and you supply the name PRODUCT7, the resultant coupling facility structure name is NY03PRODUCT7. The administrative structure for the queue sharing group (in this case NY03CSQ_ADMIN) cannot be used for storing messages.

    For ALTER QLOCAL, ALTER QMODEL, DEFINE QLOCAL with REPLACE, and DEFINE QMODEL with REPLACE the following rules apply:

    • On a local queue with QSGDISP(SHARED), CFSTRUCT cannot change.

      If we change either the CFSTRUCT or QSGDISP value we must delete and redefine the queue. To preserve any of the messages on the queue we must offload the messages before you delete the queue. Reload the messages after you redefine the queue, or move the messages to another queue.

    • On a model queue with DEFTYPE(SHAREDYN), CFSTRUCT cannot be blank.
    • On a local queue with a QSGDISP other than SHARED, or a model queue with a DEFTYPE other than SHAREDYN, the value of CFSTRUCT does not matter.

    For DEFINE QLOCAL with NOREPLACE and DEFINE QMODEL with NOREPLACE, the coupling facility structure:

    • On a local queue with QSGDISP(SHARED) or a model queue with a DEFTYPE(SHAREDYN), CFSTRUCT cannot be blank.
    • On a local queue with a QSGDISP other than SHARED, or a model queue with a DEFTYPE other than SHAREDYN, the value of CFSTRUCT does not matter.

    Note: Before we can use the queue, the structure must be defined in the coupling facility Resource Management (CFRM) policy data set.

    CLCHNAME(channel name)

    This parameter is supported only on transmission queues.

    CLCHNAME is the generic name of the cluster-sender channels that use this queue as a transmission queue. The attribute specifies which cluster-sender channels send messages to a cluster-receiver channel from this cluster transmission queue.

    We can also set the transmission queue attribute CLCHNAME attribute to a cluster-sender channel manually. Messages that are destined for the queue manager connected by the cluster-sender channel are stored in the transmission queue that identifies the cluster-sender channel. They are not stored in the default cluster transmission queue. If you set the CLCHNAME attribute to blanks, the channel switches to the default cluster transmission queue when the channel restarts. The default queue is either SYSTEM.CLUSTER.TRANSMIT.ChannelName or SYSTEM.CLUSTER.TRANSMIT.QUEUE, depending on the value of the queue manager DEFCLXQ attribute.

    By specifying asterisks, " * ", in CLCHNAME, we can associate a transmission queue with a set of cluster-sender channels. The asterisks can be at the beginning, end, or any number of places in the middle of the channel name string. CLCHNAME is limited to a length of 48 characters, MQ_OBJECT_NAME_LENGTH. A channel name is limited to 20 characters: MQ_CHANNEL_NAME_LENGTH. If you specify an asterisk we must also set the SHARE attribute so that multiple channels can concurrently access the transmission queue.

    If you specify a " * " in CLCHNAME, to obtain a channel profile name, we must specify the channel profile name within quotation marks. If we do not specify the generic channel name within quotation marks you receive message CSQ9030E.

    The default queue manager configuration is for all cluster-sender channels to send messages from a single transmission queue, SYSTEM.CLUSTER.TRANSMIT.QUEUE. The default configuration can be modified by changing the queue manager attribute, DEFCLXQ. The default value of the attribute is SCTQ. We can change the value to CHANNEL. If you set the DEFCLXQ attribute to CHANNEL, each cluster-sender channel defaults to using a specific cluster transmission queue, SYSTEM.CLUSTER.TRANSMIT.ChannelName.

    On z/OS, if this parameter is set, the queue:

    • Must be shareable, by specifying the queue attribute SHARE.
    • Must be indexed on the correlation ID by specifying INDXTYPE(CORRELID).
    • Must not be a dynamic or a shared queue.

    CLUSNL(namelist name)
    The name of the namelist that specifies a list of clusters to which the queue belongs.

    This parameter is supported only on alias, local, and remote queues.

    Changes to this parameter do not affect instances of the queue that are already open.

    Only one of the resultant values of CLUSNL or CLUSTER can be nonblank; we cannot specify a value for both.

    On local queues, this parameter cannot be set for the following queues:

    • Transmission queues
    • SYSTEM.CHANNEL.xx queues
    • SYSTEM.CLUSTER.xx queues
    • SYSTEM.COMMAND.xx queues
    • On z/OS only, SYSTEM.QSG.xx queues

    This parameter is valid only on the following platforms:

    • UNIX, Linux, and Windows
    • z/OS

    CLUSTER(cluster name)
    The name of the cluster to which the queue belongs.

    This parameter is supported only on alias, local, and remote queues.

    The maximum length is 48 characters conforming to the rules for naming IBM MQ objects. Changes to this parameter do not affect instances of the queue that are already open.

    Only one of the resultant values of CLUSNL or CLUSTER can be nonblank; we cannot specify a value for both.

    On local queues, this parameter cannot be set for the following queues:

    • Transmission queues
    • SYSTEM.CHANNEL.xx queues
    • SYSTEM.CLUSTER.xx queues
    • SYSTEM.COMMAND.xx queues
    • On z/OS only, SYSTEM.QSG.xx queues

    This parameter is valid only on the following platforms:

    • UNIX, Linux, and Windows
    • z/OS

    CLWLPRTY(integer)
    Specifies the priority of the queue for the purposes of cluster workload distribution. This parameter is valid only for local, remote, and alias queues. The value must be in the range zero through 9 where zero is the lowest priority and 9 is the highest. For more information about this attribute, see CLWLPRTY queue attribute.

    CLWLRANK (integer)
    Specifies the rank of the queue for the purposes of cluster workload distribution. This parameter is valid only for local, remote, and alias queues. The value must be in the range zero through 9 where zero is the lowest rank and 9 is the highest. For more information about this attribute, see CLWLRANK queue attribute.

    CLWLUSEQ
    Specifies the behavior of an MQPUT operation when the target queue has a local instance and at least one remote cluster instance. The parameter has no effect when the MQPUT originates from a cluster channel. This parameter is valid only for local queues.

      QMGR
      The behavior is as specified by the CLWLUSEQ parameter of the queue manager definition.

      ANY
      The queue manager is to treat the local queue as another instance of the cluster queue for the purposes of workload distribution.

      LOCAL
      The local queue is the only target of the MQPUT operation.

    CMDSCOPE
    This parameter applies to z/OS only. It specifies where the command is run when the queue manager is a member of a queue sharing group. CMDSCOPE must be blank, or the local queue manager, if QSGDISP is set to GROUP or SHARED.

      ''
      The command runs on the queue manager on which it was entered.

      QmgrName
      The command runs on the queue manager you specify, providing the queue manager is active within the queue sharing group.

      We can specify a queue manager name, other than the queue manager on which the command was entered. We can specify another name, only if we are using a queue sharing group environment and if the command server is enabled.

      *
      The command runs on the local queue manager and is also passed to every active queue manager in the queue sharing group. The effect of * is the same as entering the command on every queue manager in the queue sharing group.

    CUSTOM(string)
    The custom attribute for new features.

    This attribute contains the values of attributes, as pairs of attribute name and value, separated by at least one space. The attribute name-value pairs have the form NAME(VALUE).

    The CUSTOM attribute is intended to be used with one of the following IBM MQ attributes.

      CAPEXPRY(integer)
      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.

      Specify a value for CAPEXPRY that is not valid, does not cause the command to fail. Instead the default value is used.

      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.

    DEFBIND
    Specifies the binding to be used when the application specifies MQOO_BIND_AS_Q_DEF on the MQOPEN call, and the queue is a cluster queue.

      OPEN
      The queue handle is bound to a specific instance of the cluster queue when the queue is opened.

      NOTFIXED
      The queue handle is not bound to any instance of the cluster queue. The queue manager selects a specific queue instance when the message is put using MQPUT. It changes that selection later, if the need arises.

      GROUP
      Allows an application to request that a group of messages is allocated to the same destination instance.

    Multiple queues with the same name can be advertised in a queue manager cluster. An application can send all messages to a single instance, MQOO_BIND_ON_OPEN. It can allow a workload management algorithm to select the most suitable destination on a per message basis, MQOO_BIND_NOT_FIXED. It can allow an application to request that a group of messages be all allocated to the same destination instance. The workload balancing reselects a destination between groups of messages, without requiring an MQCLOSE and MQOPEN of the queue.

    The MQPUT1 call always behaves as if NOTFIXED is specified.

    This parameter is valid on all platforms.

    DEFPRESP
    Specifies the behavior to be used by applications when the put response type, within the MQPMO options, is set to MQPMO_RESPONSE_AS_Q_DEF.

      SYNC
      Put operations to the queue specifying MQPMO_RESPONSE_AS_Q_DEF are issued as if MQPMO_SYNC_RESPONSE is specified instead.

      ASYNC
      Put operations to the queue specifying MQPMO_RESPONSE_AS_Q_DEF are issued as if MQPMO_ASYNC_RESPONSE is specified instead; see MQPMO options (MQLONG).

    DEFPRTY(integer)
    The default priority of messages put on the queue. The value must be in the range 0 - 9. Zero is the lowest priority, through to the MAXPRTY queue manager parameter. The default value of MAXPRTY is 9.

    DEFPSIST
    Specifies the message persistence to be used when applications specify the MQPER_PERSISTENCE_AS_Q_DEF option.

      NO
      Messages on this queue are lost across a restart of the queue manager.

      YES
      Messages on this queue survive a restart of the queue manager.

    On z/OS, N and Y are accepted as synonyms of NO and YES.

    DEFREADA
    Specifies the default read ahead behavior for non-persistent messages delivered to the client. Enabling read ahead can improve the performance of client applications consuming non-persistent messages.

      NO
      Non-persistent messages are not read ahead unless the client application is configured to request read ahead.

      YES
      Non-persistent messages are sent to the client before an application requests them. Non-persistent messages can be lost if the client ends abnormally or if the client does not delete all the messages it is sent.

      DISABLED
      Read ahead of non-persistent messages in not enabled for this queue. Messages are not sent ahead to the client regardless of whether read ahead is requested by the client application.

    DEFSOPT
    The default share option for applications opening this queue for input:

      EXCL
      The open request is for exclusive input from the queue.
      On z/OS, EXCL is the default value.

      SHARED
      The open request is for shared input from the queue.
      On Multiplatforms, SHARED is the default value.

    DEFTYPE
    Queue definition type. This parameter is supported only on model queues.

      PERMDYN
      A permanent dynamic queue is created when an application issues an MQOPEN MQI call with the name of this model queue specified in the object descriptor (MQOD).

      On z/OS, the dynamic queue has a disposition of QMGR.

      SHAREDYN
      This option is available on z/OS only.

      A permanent dynamic queue is created when an application issues an MQOPEN API call with the name of this model queue specified in the object descriptor (MQOD).

      The dynamic queue has a disposition of SHARED.

      TEMPDYN
      A temporary dynamic queue is created when an application issues an MQOPEN API call with the name of this model queue specified in the object descriptor (MQOD).

      On z/OS, the dynamic queue has a disposition of QMGR.

      Do not specify this value for a model queue definition with a DEFPSIST parameter of YES.

      If you specify this option, do not specify INDXTYPE(MSGTOKEN).

    DESCR(string)
    Plain-text comment. It provides descriptive information about the object when an operator issues the DISPLAY QUEUE command.

    It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

    Note: Use characters that are in the coded character set identifier (CCSID) of this queue manager. If we do not do so and if the information is sent to another queue manager, they might be translated incorrectly.

    DISTL
    DISTL sets whether distribution lists are supported by the partner queue manager.

      YES
      Distribution lists are supported by the partner queue manager.

      NO
      Distribution lists are not supported by the partner queue manager.

    Note: You do not normally change this parameter, because it is set by the MCA. However we can set this parameter when defining a transmission queue if the distribution list capability of the destination queue manager is known.

    This parameter is valid only on UNIX, Linux, and Windows.

    FORCE
    This parameter applies only to the ALTER command on alias, local and remote queues.

    Specify this parameter to force completion of the command in the following circumstances.

    For an alias queue, if both of the following statements are true:

    • The TARGQ parameter is specified
    • An application has this alias queue open

    For a local queue, if both of the following statements are true:

    • The NOSHARE parameter is specified
    • More than one application has the queue open for input

    FORCE is also needed if both of the following statements are true:

    • The USAGE parameter is changed
    • Either one or more messages are on the queue, or one or more applications have the queue open

    Do not change the USAGE parameter while there are messages on the queue; the format of messages changes when they are put on a transmission queue.

    For a remote queue, if both of the following statements are true:

    • The XMITQ parameter is changed
    • One or more applications has this queue open as a remote queue

    FORCE is also needed if both of the following statements are true:

    • Any of the RNAME, RQMNAME, or XMITQ parameters are changed
    • One or more applications has a queue open that resolved through this definition as a queue manager alias

    Note: FORCE is not required if this definition is in use as a reply-to queue alias only.

    If FORCE is not specified in the circumstances described, the command is unsuccessful.

    GET
    Specifies whether applications are to be permitted to get messages from this queue:

      ENABLED
      Messages can be retrieved from the queue, by suitably authorized applications.

      DISABLED
      Applications cannot retrieve messages from the queue.

    This parameter can also be changed using the MQSET API call.

    HARDENBO & NOHARDENBO
    Specifies whether the count of the number of times that a message was backed out is hardened. When the count is hardened, the value of the BackoutCount field of the message descriptor is written to the log before the message is returned by an MQGET operation. Writing the value to the log ensures that the value is accurate across restarts of the queue manger.

    This parameter is supported only on local and model queues.

    When the backout count is hardened, the performance of MQGET operations for persistent messages on this queue is impacted.

      HARDENBO
      The message backout count for messages on this queue is hardened to ensure that the count is accurate.

      NOHARDENBO
      The message backout count for messages on this queue is not hardened and might not be accurate over queue manager restarts.

    Note: This parameter affects only IBM MQ for z/OS. We can set this parameter on Multiplatforms but it is ineffective.

    IMGRCOVQ
    Specifies whether a local or permanent dynamic queue object is recoverable from a media image, if linear logging is being used. Possible values are:

      YES
      These queue objects are recoverable.

      NO
      The rcdmqimg (record media image) andrcrmqobj (re-create object) commands are not permitted for these objects, and automatic media images, if enabled, are not written for these objects.

      QMGR
      If you specify QMGR, and the IMGRCOVQ attribute for the queue manager specifies YES, these queue objects are recoverable.

      If you specify QMGR and the IMGRCOVQ attribute for the queue manager specifies NO, the rcdmqimg (record media image) andrcrmqobj (re-create object) commands are not permitted for these objects, and automatic media images, if enabled, are not written for these objects.

      QMGR is the default value.

    This parameter is not valid on z/OS.

    INDXTYPE
    The type of index maintained by the queue manager to expedite MQGET operations on the queue. For shared queues, the type of index determines the type of MQGET operations that can be used.

    This parameter is supported only on z/OS. On other platforms, all queues are automatically indexed.

    This parameter is supported only on local and model queues.

    Messages can be retrieved using a selection criterion only if an appropriate index type is maintained, as the following table shows:

    Retrieval selection criterion Index type required
      Shared queue Other queue
    None (sequential retrieval) Any Any
    Message identifier MSGID or NONE Any
    Correlation identifier CORRELID Any
    Message and correlation identifiers MSGID or CORRELID Any
    Group identifier GROUPID Any
    Grouping GROUPID GROUPID
    Message token Not allowed MSGTOKEN
    where the value of INDXTYPE parameter has the following values:

      NONE
      No index is maintained. Use NONE when messages are typically retrieved sequentially or use both the message identifier and the correlation identifier as a selection criterion on the MQGET call.

      MSGID
      An index of message identifiers is maintained. Use MSGID when messages are typically retrieved using the message identifier as a selection criterion on the MQGET call with the correlation identifier set to NULL.

      CORRELID
      An index of correlation identifiers is maintained. Use CORRELID when messages are typically retrieved using the correlation identifier as a selection criterion on the MQGET call with the message identifier set to NULL.

      GROUPID
      An index of group identifiers is maintained. Use GROUPID when messages are retrieved using message grouping selection criteria. Note:
      1. We cannot set INDXTYPE to GROUPID if the queue is a transmission queue.
      2. The queue must use a CF structure at CFLEVEL(3), to specify a shared queue with INDXTYPE(GROUPID).

      MSGTOKEN
      An index of message tokens is maintained. Use MSGTOKEN when the queue is a WLM-managed queue that we are using with the Workload Manager functions of z/OS. Note: We cannot set INDXTYPE to MSGTOKEN if:

      • The queue is a model queue with a definition type of SHAREDYN
      • The queue is a temporary dynamic queue
      • The queue is a transmission queue
      • You specify QSGDISP(SHARED)

    For queues that are not shared and do not use grouping or message tokens, the index type does not restrict the type of retrieval selection. However, the index is used to expedite GET operations on the queue, so choose the type that corresponds to the most common retrieval selection.

    If we are altering or replacing an existing local queue, we can change the INDXTYPE parameter only in the cases indicated in the following table:

    Queue type NON-SHARED SHARED
    Queue state Uncommitted activity No uncommitted activity, messages present No uncommitted activity, and empty Open or messages present Not open, and empty
    Change INDXTYPE from: To: Change allowed?
    NONE MSGID No Yes Yes No Yes
    NONE CORRELID No Yes Yes No Yes
    NONE MSGTOKEN No No Yes - -
    NONE GROUPID No No Yes No Yes
    MSGID NONE No Yes Yes No Yes
    MSGID CORRELID No Yes Yes No Yes
    MSGID MSGTOKEN No No Yes - -
    MSGID GROUPID No No Yes No Yes
    CORRELID NONE No Yes Yes No Yes
    CORRELID MSGID No Yes Yes No Yes
    CORRELID MSGTOKEN No No Yes - -
    CORRELID GROUPID No No Yes No Yes
    MSGTOKEN NONE No Yes Yes - -
    MSGTOKEN MSGID No Yes Yes - -
    MSGTOKEN CORRELID No Yes Yes - -
    MSGTOKEN GROUPID No No Yes - -
    GROUPID NONE No No Yes No Yes
    GROUPID MSGID No No Yes No Yes
    GROUPID CORRELID No No Yes No Yes
    GROUPID MSGTOKEN No No Yes - -

    INITQ(string)
    The local name of the initiation queue on this queue manager, to which trigger messages relating to this queue are written; see Rules for naming IBM MQ objects.

    This parameter is supported only on local and model queues.

    LIKE(qtype-name)
    The name of a queue, with parameters that are used to model this definition.

    If this field is not completed, the values of undefined parameter fields are taken from one of the following definitions. The choice depends on the queue type:

    Queue type Definition
    Alias queue SYSTEM.DEFAULT.ALIAS.QUEUE
    Local queue SYSTEM.DEFAULT.LOCAL.QUEUE
    Model queue SYSTEM.DEFAULT.MODEL.QUEUE
    Remote queue SYSTEM.DEFAULT.REMOTE.QUEUE
    For example, not completing this parameter is equivalent to defining the following value of LIKE for an alias queue: 
    LIKE(SYSTEM.DEFAULT.ALIAS.QUEUE)

    If you require different default definitions for all queues, alter the default queue definitions instead of using the LIKE parameter.

    On z/OS, the queue manager searches for an object with the name and queue type you specify with a disposition of QMGR, COPY, or SHARED. The disposition of the LIKE object is not copied to the object we are defining. Note:
    1. QSGDISP(GROUP) objects are not searched.
    2. LIKE is ignored if QSGDISP(COPY) is specified.

    MAXDEPTH(integer)
    The maximum number of messages allowed on the queue.

    This parameter is supported only on local and model queues.

    On the following platforms, specify a value in the range zero through 999999999:

    • UNIX, Linux, and Windows
    • z/OS

    On any other IBM MQ platform, specify a value in the range zero through 640000.

    Other factors can still cause the queue to be treated as full, for example, if there is no further hard disk space available.

    If this value is reduced, any messages that are already on the queue that exceed the new maximum remain intact.

    MAXFSIZE
    The maximum size, in megabytes, that a queue file can grow to. It is possible for a queue file to exceed this size if you have configured the value to be lower than the current queue file size.
    If that happens the queue file no longer accepts new messages, but allows existing messages to be consumed. When the queue file size has dropped below the configured value, new messages can be put to the queue. Note: This figure can differ from the value of the attribute configured on the queue, because internally the queue manager might need to use a larger block size to reach the chosen size. See Modifying IBM MQ queue files for more information on changing the size of queue files and block size and granularity. When the granularity needs changing because this attribute has been increased, warning message AMQ7493W Granularity changed is written to the AMQERR logs. This gives you an indication that we need to plan for the queue to be emptied, in order for IBM MQ to adopt the new granularity.

    The default value for this attribute is DEFAULT, which equates to a hard-coded value of 2,088,960 MB, the maximum for a queue in versions of IBM MQ prior to IBM MQ Version 9.1.5.

    MAXMSGL(integer)
    The maximum length (in bytes) of messages on this queue.

    This parameter is supported only on local and model queues.

    On UNIX, Linux, and Windows, specify a value in the range zero to the maximum message length for the queue manager. See the MAXMSGL parameter of the ALTER QMGR command, ALTER QMGR MAXMSGL.

    On z/OS, specify a value in the range zero through 100 MB (104 857 600 bytes).

    Message length includes the length of user data and the length of headers. For messages put on the transmission queue, there are additional transmission headers. Allow an additional 4000 bytes for all the message headers.

    If this value is reduced, any messages that are already on the queue with length that exceeds the new maximum are not affected.

    Applications can use this parameter to determine the size of buffer for retrieving messages from the queue. Therefore, the value can be reduced only if it is known that this reduction does not cause an application to operate incorrectly.

    Note that by adding the digital signature and key to the message, Advanced Message Security increases the length of the message.

    MONQ
    Controls the collection of online monitoring data for queues.

    This parameter is supported only on local and model queues.

      QMGR
      Collect monitoring data according to the setting of the queue manager parameter MONQ.

      OFF
      Online monitoring data collection is turned off for this queue.

      LOW
      If the value of the MONQ parameter of the queue manager is not NONE, online monitoring data collection is turned on for this queue.

      MEDIUM
      If the value of the MONQ parameter of the queue manager is not NONE, online monitoring data collection is turned on for this queue.

      HIGH
      If the value of the MONQ parameter of the queue manager is not NONE, online monitoring data collection is turned on for this queue.

    There is no distinction between the values LOW, MEDIUM, and HIGH. These values all turn data collection on, but do not affect the rate of collection.

    When this parameter is used in an ALTER queue command, the change is effective only when the queue is next opened.

    MSGDLVSQ
    Message delivery sequence.

    This parameter is supported only on local and model queues.

      PRIORITY
      Messages are delivered (in response to MQGET API calls) in first-in-first-out (FIFO) order within priority.

      FIFO
      Messages are delivered (in response to MQGET API calls) in FIFO order. Priority is ignored for messages on this queue.

    The message delivery sequence parameter can be changed from PRIORITY to FIFO while there are messages on the queue. The order of the messages already on the queue is not changed. Messages added to the queue later take the default priority of the queue, and so might be processed before some of the existing messages.

    If the message delivery sequence is changed from FIFO to PRIORITY, the messages put on the queue while the queue was set to FIFO take the default priority.

    Note: If INDXTYPE(GROUPID) is specified with MSGDLVSQ(PRIORITY), the priority in which groups are retrieved is based on the priority of the first message within each group. The priorities 0 and 1 are used by the queue manager to optimize the retrieval of messages in logical order. The first message in each group must not use these priorities. If it does, the message is stored as if it was priority two.

    NPMCLASS
    The level of reliability to be assigned to non-persistent messages that are put to the queue:

      NORMAL
      Non-persistent messages are lost after a failure, or queue manager shutdown. These messages are discarded on a queue manager restart.

      HIGH
      The queue manager attempts to retain non-persistent messages on this queue over a queue manager restart or switch over.

    We cannot set this parameter on z/OS.

    PROCESS(string)
    The local name of the IBM MQ process.

    This parameter is supported only on local and model queues.

    This parameter is the name of a process instance that identifies the application started by the queue manager when a trigger event occurs; see Rules for naming IBM MQ objects.

    The process definition is not checked when the local queue is defined, but it must be available for a trigger event to occur.

    If the queue is a transmission queue, the process definition contains the name of the channel to be started. This parameter is optional for transmission queues on the following platforms:

    • IBM i
    • UNIX, Linux, and Windows
    • z/OS

    If we do not specify it, the channel name is taken from the value specified for the TRIGDATA parameter.

    PROPCTL
    Property control attribute. The attribute is optional. It is applicable to local, alias, and model queues.
    PROPCTL options are as follows. The options do not affect message properties in the MQMD or MQMD extension.

      ALL

      Set ALL so that an application can read all the properties of the message either in MQRFH2 headers, or as properties of the message handle.

      The ALL option enables applications that cannot be changed to access all the message properties from MQRFH2 headers. Applications that can be changed, can access all the properties of the message as properties of the message handle.

      In some cases, the format of data in MQRFH2 headers in the received message might be different to the format in the message when it was sent.

      COMPAT

      Set COMPAT so that unmodified applications that expect JMS-related properties to be in an MQRFH2 header in the message data continue to work as before. Applications that can be changed, can access all the properties of the message as properties of the message handle.

      If the message contains a property with a prefix of mcd., jms., usr., or mqext., all message properties are delivered to the application. If no message handle is supplied, properties are returned in an MQRFH2 header. If a message handle is supplied, all properties are returned in the message handle.

      If the message does not contain a property with one of those prefixes, and the application does not provide a message handle, no message properties are returned to the application. If a message handle is supplied, all properties are returned in the message handle.

      In some cases, the format of data in MQRFH2 headers in the received message might be different to the format in the message when it was sent.

      FORCE

      Force all applications to read message properties from MQRFH2 headers.

      Properties are always returned in the message data in an MQRFH2 header regardless of whether the application specifies a message handle.

      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 using the message handle.

      In some cases, the format of data in MQRFH2 headers in the received message might be different to the format in the message when it was sent.

      NONE

      If a message handle is supplied, all the properties are returned in the message handle.

      All message properties are removed from the message body before it is delivered to the application.

    PUT
    Specifies whether messages can be put on the queue.

      ENABLED
      Messages can be added to the queue (by suitably authorized applications).

      DISABLED
      Messages cannot be added to the queue.

    This parameter can also be changed using the MQSET API call.

    QDEPTHHI(integer)
    The threshold against which the queue depth is compared to generate a Queue Depth High event.

    This parameter is supported only on local and model queues.

    For more information about the effect that shared queues on z/OS have on this event; see Shared queues and queue depth events on z/OS.

    This event indicates that an application put a message on a queue resulting in the number of messages on the queue becoming greater than or equal to the queue depth high threshold. See the QDPHIEV parameter.

    The value is expressed as a percentage of the maximum queue depth (MAXDEPTH parameter), and must be in the range zero through 100 and no less than QDEPTHLO.

    QDEPTHLO(integer)
    The threshold against which the queue depth is compared to generate a Queue Depth Low event.

    This parameter is supported only on local and model queues.

    For more information about the effect that shared queues on z/OS have on this event; see Shared queues and queue depth events on z/OS.

    This event indicates that an application retrieved a message from a queue resulting in the number of messages on the queue becoming less than or equal to the queue depth low threshold. See the QDPLOEV parameter.

    The value is expressed as a percentage of the maximum queue depth (MAXDEPTH parameter), and must be in the range zero through 100 and no greater than QDEPTHHI.

    QDPHIEV
    Controls whether Queue Depth High events are generated.

    This parameter is supported only on local and model queues.

    A Queue Depth High event indicates that an application put a message on a queue resulting in the number of messages on the queue becoming greater than or equal to the queue depth high threshold. See the QDEPTHHI parameter.

      ENABLED
      Queue Depth High events are generated.

      DISABLED
      Queue Depth High events are not generated.

    Note: The value of this parameter can change implicitly.

    On z/OS, shared queues affect the event.

    For more information about this event, see Queue Depth High.

    QDPLOEV
    Controls whether Queue Depth Low events are generated.

    This parameter is supported only on local and model queues.

    A Queue Depth Low event indicates that an application retrieved a message from a queue resulting in the number of messages on the queue becoming less than or equal to the queue depth low threshold. See the QDEPTHLO parameter.

      ENABLED
      Queue Depth Low events are generated.

      DISABLED
      Queue Depth Low events are not generated.

    Note: The value of this parameter can change implicitly.

    On z/OS, shared queues affect the event.

    For more information about this event, see Queue Depth Low.

    QDPMAXEV
    Controls whether Queue Full events are generated.

    This parameter is supported only on local and model queues.

    A Queue Full event indicates that a put to a queue was rejected because the queue is full. The queue depth reached its maximum value.

      ENABLED
      Queue Full events are generated.

      DISABLED
      Queue Full events are not generated.

    Note: The value of this parameter can change implicitly.

    On z/OS, shared queues affect the event.

    For more information about this event, see Queue Full.

    QSGDISP
    This parameter applies to z/OS only.

    Specifies the disposition of the object within the group.

    QSGDISP DEFINE
    COPY The object is defined on the page set of the queue manager that executes the command using the QSGDISP(GROUP) object of the same name as the LIKE object.

    For local queues, messages are stored on the page sets of each queue manager and are available only through that queue manager.

    GROUP The object definition resides in the shared repository but only if there is a shared queue manager environment. If the definition is successful, the following command is generated. The command is sent to all active queue managers to attempt to make or refresh local copies on page set zero: 
    DEFINE QUEUE(q-name)
REPLACE QSGDISP(COPY)
    The DEFINE command for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
    PRIVATE Not permitted.
    QMGR The object is defined on the page set of the queue manager that executes the command. For local queues, messages are stored on the page sets of each queue manager and are available only through that queue manager.
    SHARED This option applies only to local queues. The object is defined in the shared repository. Messages are stored in the coupling facility and are available to any queue manager in the queue sharing group. We can specify SHARED only if:

    • CFSTRUCT is nonblank
    • INDXTYPE is not MSGTOKEN
    • The queue is not:

      • SYSTEM.CHANNEL.INITQ
      • SYSTEM.COMMAND.INPUT

    If the queue is clustered, a command is generated. The command is sent to all active queue managers in the queue sharing group to notify them of this clustered, shared queue.

    QSVCIEV
    Controls whether Service Interval High or Service Interval OK events are generated.

    This parameter is supported only on local and model queues and is ineffective if it is specified on a shared queue.

    A Service Interval High event is generated when a check indicates that no messages were retrieved from the queue for at least the time indicated by the QSVCINT parameter.

    A Service Interval OK event is generated when a check indicates that messages were retrieved from the queue within the time indicated by the QSVCINT parameter.

    Note: The value of this parameter can change implicitly. For more information, see the description of the Service Interval High and Service Interval OK events in Queue Service Interval High and Queue Service Interval OK.

      HIGH
      Service Interval High events are generated

      OK
      Service Interval OK events are generated

      NONE
      No service interval events are generated

    QSVCINT(integer)
    The service interval used for comparison to generate Service Interval High and Service Interval OK events.

    This parameter is supported only on local and model queues and is ineffective if it is specified on a shared queue.

    See the QSVCIEV parameter.

    The value is in units of milliseconds, and must be in the range zero through 999999999.

    REPLACE & NOREPLACE
    This option controls whether any existing definition is to be replaced with this one. Note: On IBM MQ for z/OS, an existing definition is replaced only if it is of the same disposition. Any object with a different disposition is not changed.

      REPLACE
      If the object does exist, the effect is like issuing the ALTER command without the FORCE parameter and with all the other parameters specified. In particular, note that any messages that are on the existing queue are retained.

      There is a difference between the ALTER command without the FORCE parameter, and the DEFINE command with the REPLACE parameter. The difference is that ALTER does not change unspecified parameters, but DEFINE with REPLACE sets all the parameters. If we use REPLACE, unspecified parameters are taken either from the object named on the LIKE parameter, or from the default definition, and the parameters of the object being replaced, if one exists, are ignored.

      The command fails if both of the following statements are true:

      • The command sets parameters that would require the use of the FORCE parameter if you were using the ALTER command
      • The object is open

      The ALTER command with the FORCE parameter succeeds in this situation.

      If SCOPE(CELL) is specified on UNIX, Linux, or Windows, and there is already a queue with the same name in the cell directory, the command fails, even if REPLACE is specified.

      NOREPLACE
      The definition must not replace any existing definition of the object.

    RETINTVL(integer)
    The number of hours from when the queue was defined, after which the queue is no longer needed. The value must be in the range 0 - 999,999,999.

    This parameter is supported only on local and model queues.

    The CRDATE and CRTIME can be displayed using the DISPLAY QUEUE command.

    This information is available for use by an operator or a housekeeping application to delete queues that are no longer required.

    Note: The queue manager does not delete queues based on this value, nor does it prevent queues from being deleted if their retention interval is not expired. It is the responsibility of the user to take any required action.

    RNAME(string)
    Name of remote queue. This parameter is the local name of the queue as defined on the queue manager specified by RQMNAME. This parameter is supported only on remote queues.

    • If this definition is used for a local definition of a remote queue, RNAME must not be blank when the open occurs.
    • If this definition is used for a queue manager alias definition, RNAME must be blank when the open occurs.

      In a queue manager cluster, this definition applies only to the queue manager that made it. To advertise the alias to the whole cluster, add the CLUSTER attribute to the remote queue definition.

    • If this definition is used for a reply-to queue alias, this name is the name of the queue that is to be the reply-to queue.

    The name is not checked to ensure that it contains only those characters normally allowed for queue names; see Rules for naming IBM MQ objects.

    RQMNAME(string)
    The name of the remote queue manager on which the queue RNAME is defined. This parameter is supported only on remote queues.

    • If an application opens the local definition of a remote queue, RQMNAME must not be blank or the name of the local queue manager. When the open occurs, if XMITQ is blank there must be a local queue of this name, which is to be used as the transmission queue.
    • If this definition is used for a queue manager alias, RQMNAME is the name of the queue manager that is being aliased. It can be the name of the local queue manager. Otherwise, if XMITQ is blank, when the open occurs there must be a local queue of this name, which is to be used as the transmission queue.
    • If RQMNAME is used for a reply-to queue alias, RQMNAME is the name of the queue manager that is to be the reply-to queue manager.

    The name is not checked to ensure that it contains only those characters normally allowed for IBM MQ object names; see Rules for naming IBM MQ objects.

    SCOPE
    Specifies the scope of the queue definition. This parameter is supported only on alias, local, and remote queues.

      QMGR
      The queue definition has queue manager scope. This means that the definition of the queue does not extend beyond the queue manager that owns it. We can open a queue for output that is owned by another queue manager in either of two ways:
      1. Specify the name of the owning queue manager.
      2. Open a local definition of the queue on the other queue manager.

      CELL
      The queue definition has cell scope. Cell scope means that the queue is known to all the queue managers in the cell. A queue with cell scope can be opened for output merely by specifying the name of the queue. The name of the queue manager that owns the queue need not be specified.

      If there is already a queue with the same name in the cell directory, the command fails. The REPLACE option does not affect this situation.

      This value is valid only if a name service supporting a cell directory is configured. Restriction: The DCE name service is no longer supported.

    This parameter is valid only on UNIX, Linux, and Windows.

    SHARE and NOSHARE
    Specifies whether multiple applications can get messages from this queue. This parameter is supported only on local and model queues.

      SHARE
      More than one application instance can get messages from the queue.

      NOSHARE
      Only a single application instance can get messages from the queue.

    STATQ
    Specifies whether statistics data collection is enabled:

      QMGR
      Statistics data collection is based on the setting of the STATQ parameter of the queue manager.

      ON
      If the value of the STATQ parameter of the queue manager is not NONE, statistics data collection for the queue is enabled.

      OFF
      Statistics data collection for the queue is disabled.

    If this parameter is used in an ALTER queue command, the change is effective only for connections to the queue manager made after the change to the parameter.

    This parameter is valid only on Multiplatforms.

    STGCLASS(string)
    The name of the storage class.

    This parameter is supported only on local and model queues.

    Note: We can change this parameter only if the queue is empty and closed.

    This parameter is an installation-defined name. The first character of the name must be uppercase A through Z, and subsequent characters either uppercase A through Z or numeric 0 through 9.

    This parameter is valid only on z/OS; see Storage classes.

    TARGET(string)
    The name of the queue or topic object being aliased; See Rules for naming IBM MQ objects. The object can be a queue or a topic as defined by TARGTYPE. The maximum length is 48 characters.

    This parameter is supported only on alias queues.

    This object needs to be defined only when an application process opens the alias queue.

    This parameter is a synonym of the parameter TARGQ; TARGQ is retained for compatibility. If you specify TARGET, we cannot also specify TARGQ.

    TARGTYPE(string)
    The type of object to which the alias resolves.

      QUEUE
      The alias resolves to a queue.

      TOPIC
      The alias resolves to a topic.

    TRIGDATA(string)
    The data that is inserted in the trigger message. The maximum length of the string is 64 bytes.

    This parameter is supported only on local and model queues.

    For a transmission queue, we can use this parameter to specify the name of the channel to be started.

    This parameter can also be changed using the MQSET API call.

    TRIGDPTH(integer)
    The number of messages that have to be on the queue before a trigger message is written, if TRIGTYPE is DEPTH. The value must be in the range 1 - 999,999,999.

    This parameter is supported only on local and model queues.

    This parameter can also be changed using the MQSET API call.

    TRIGGER & NOTRIGGER
    Specifies whether trigger messages are written to the initiation queue, named by the INITQ parameter, to trigger the application, named by the PROCESS parameter:

      TRIGGER
      Triggering is active, and trigger messages are written to the initiation queue.

      NOTRIGGER
      Triggering is not active, and trigger messages are not written to the initiation queue.

      This parameter is supported only on local and model queues.

    This parameter can also be changed using the MQSET API call.

    TRIGMPRI(integer)
    The message priority number that triggers this queue. The value must be in the range zero through to the MAXPRTY queue manager parameter; see DISPLAY QMGR for details.

    This parameter can also be changed using the MQSET API call.

    TRIGTYPE
    Specifies whether and under what conditions a trigger message is written to the initiation queue. The initiation queue is (named by the INITQ parameter. This parameter is supported only on local and model queues.

      FIRST
      Whenever the first message of priority equal to or greater than the priority specified by the TRIGMPRI parameter of the queue arrives on the queue.

      EVERY
      Every time a message arrives on the queue with priority equal to or greater than the priority specified by the TRIGMPRI parameter of the queue.

      DEPTH
      When the number of messages with priority equal to or greater than the priority specified by TRIGMPRI is equal to the number indicated by the TRIGDPTH parameter.

      NONE
      No trigger messages are written.

    This parameter can also be changed using the MQSET API call.

    USAGE
    Queue usage. This parameter is supported only on local and model queues.

      NORMAL
      The queue is not a transmission queue.

      XMITQ
      The queue is a transmission queue, which is used to hold messages that are destined for a remote queue manager. When an application puts a message to a remote queue, the message is stored on the appropriate transmission queue. It stays there, awaiting transmission to the remote queue manager.

      If you specify this option, do not specify values for CLUSTER and CLUSNL.

      Additionally, on z/OS, do not specify INDXTYPE(MSGTOKEN) or INDXTYPE(GROUPID).

    XMITQ(string)
    The name of the transmission queue to be used for forwarding messages to the remote queue. XMITQ is used with either remote queue or queue manager alias definitions.

    This parameter is supported only on remote queues.

    If XMITQ is blank, a queue with the same name as RQMNAME is used as the transmission queue.

    This parameter is ignored if the definition is being used as a queue manager alias and RQMNAME is the name of the local queue manager.

    It is also ignored if the definition is used as a reply-to queue alias definition.

  • DEFINE QALIAS
    Use DEFINE QALIAS to define a new alias queue, and set its parameters.
  • DEFINE QLOCAL
    Use DEFINE QLOCAL to define a new local queue, and set its parameters.
  • DEFINE QMODEL
    Use DEFINE QMODEL to define a new model queue, and set its parameters.
  • DEFINE QREMOTE
    Use DEFINE QREMOTE to define a new local definition of a remote queue, a queue manager alias, or a reply-to queue alias, and to set its parameters.

Parent topic: MQSC commands


Related information