Change, Copy, and Create Queue

The Change Queue command changes existing queue definitions. The Copy and Create Queue commands create new queue definitions - the Copy command uses attribute values of an existing queue definition.

The Change Queue command MQCMD_CHANGE_Q changes the specified attributes of an existing IBM MQ queue. For any optional parameters that are omitted, the value does not change.

The Copy Queue command MQCMD_COPY_Q creates a queue definition of the same type. For attributes not specified in the command, it uses the attribute values of an existing queue definition.

The Create Queue command MQCMD_CREATE_Q creates a queue definition with the specified attributes. All attributes that are not specified are set to the default value for the type of queue that is created.


Required parameters (Change and Create Queue)

    QName (MQCFST)
    Queue name (parameter identifier: MQCA_Q_NAME).

    The name of the queue to be changed. The maximum length of the string is MQ_Q_NAME_LENGTH.


Required parameters (Copy Queue)

    FromQName (MQCFST)
    From queue name (parameter identifier: MQCACF_FROM_Q_NAME).

    Specifies the name of the existing queue definition.

    On z/OS, the queue manager searches for an object with the name you specify and a disposition of MQQSGD_Q_MGR, MQQSGD_COPY, or MQQSGD_SHARED to copy from. This parameter is ignored if a value of MQQSGD_COPY is specified for QSGDisposition . In this case, an object with the name specified by ToQName and the disposition MQQSGD_GROUP is searched for to copy from.

    The maximum length of the string is MQ_Q_NAME_LENGTH.

    ToQName (MQCFST)
    To queue name (parameter identifier: MQCACF_TO_Q_NAME).

    Specifies the name of the new queue definition.

    The maximum length of the string is MQ_Q_NAME_LENGTH.

    Queue names must be unique; if a queue definition exists with the name and type of the new queue, Replace must be specified as MQRP_YES. If a queue definition exists with the same name as and a different type from the new queue, the command fails.


Required parameters (all commands)

    QType (MQCFIN)
    Queue type (parameter identifier: MQIA_Q_TYPE).

    The value specified must match the type of the queue being changed.

    The value can be any of the following values:

      MQQT_ALIAS
      Alias queue definition.

      MQQT_LOCAL
      Local queue.

      MQQT_REMOTE
      Local definition of a remote queue.

      MQQT_MODEL
      Model queue definition.


Optional parameters (Change, Copy, and Create Queue)

    BackoutRequeueName (MQCFST) - see MQSC BOQNAME
    Excessive backout requeue name (parameter identifier: MQCA_BACKOUT_REQ_Q_NAME).

    Specifies the name of the queue to which a message is transferred if it is backed out more times than the value of BackoutThreshold. The queue does not have to be a local queue.

    The backout queue does not need to exist at this time but it must exist when the BackoutThreshold value is exceeded.

    The maximum length of the string is MQ_Q_NAME_LENGTH.

    BackoutThreshold (MQCFIN)
    Backout threshold (parameter identifier: MQIA_BACKOUT_THRESHOLD).

    The number of times a message can be backed out before it is transferred to the backout queue specified by BackoutRequeueName.

    If the value is later reduced, messages that are already on the queue that were backed out at least as many times as the new value remain on the queue. Those messages are transferred if they are backed out again.

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

    BaseObjectName (MQCFST)
    Name of the object to which the alias resolves (parameter identifier: MQCA_BASE_OBJECT_NAME).

    This parameter is the name of a queue or topic that is defined to the local queue manager.

    The maximum length of the string is MQ_OBJECT_NAME_LENGTH.

    BaseQName (MQCFST)
    Queue name to which the alias resolves (parameter identifier: MQCA_BASE_Q_NAME).

    This parameter is the name of a local or remote queue that is defined to the local queue manager.

    The maximum length of the string is MQ_Q_NAME_LENGTH.

    CFStructure (MQCFST)
    Coupling facility structure name (parameter identifier: MQCA_CF_STRUC_NAME). This parameter applies to z/OS only. Specifies the name of the coupling facility structure where we want to store messages when you use shared 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 maximum length of the string is MQ_CF_STRUC_NAME_LENGTH.

    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. Note the administrative structure for the queue sharing group (in this case NY03CSQ_ADMIN) cannot be used for storing messages.

    For local and model queues, the following rules apply. The rules apply if we use the Create Queue command with a value of MQRP_YES in the Replace parameter. The rules also apply if we use the Change Queue command.

    • On a local queue with a value of MQQSGD_SHARED in the QSGDisposition parameter, CFStructure cannot change.

      For to change either the CFStructure or QSGDisposition 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 a value of MQQDT_SHARED_DYNAMIC in the DefinitionType parameter, CFStructure cannot be blank.
    • On a local queue with a value other than MQQSGD_SHARED in the QSGDisposition parameter, the value of CFStructure does not matter. The value CFStructure also does not matter for a model queue with a value other than MQQDT_SHARED_DYNAMIC in the DefinitionType parameter.

    For local and model queues, when we use the Create Queue command with a value of MQRP_NO in the Replace parameter, the coupling facility structure:

    • On a local queue with a value of MQQSGD_SHARED in the QSGDisposition parameter, or a model queue with a value of MQQDT_SHARED_DYNAMIC in the DefinitionType parameter, CFStructure cannot be blank.
    • On a local queue with a value other than MQQSGD_SHARED in the QSGDisposition parameter, the value of CFStructure does not matter. The value CFStructure also does not matter for a model queue with a value other than MQQDT_SHARED_DYNAMIC in the DefinitionType parameter.

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

    ClusterChannelName (MQCFST)

    This parameter is supported only on transmission queues.

    ClusterChannelName 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. (Parameter identifier: MQCA_CLUS_CHL_NAME.)

    We can also set the transmission queue attribute ClusterChannelName 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 ClusterChannelName 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 DefClusterXmitQueueType attribute.

    By specifying asterisks, *, in ClusterChannelName, 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. ClusterChannelName is limited to a length of 20 characters: MQ_CHANNEL_NAME_LENGTH.

    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 changed by modified by changing the queue manager attribute, DefClusterXmitQueueType. The default value of the attribute is SCTQ. We can change the value to CHANNEL. If you set the DefClusterXmitQueueType attribute to CHANNEL, each cluster-sender channel defaults to using a specific cluster transmission queue, SYSTEM.CLUSTER.TRANSMIT.ChannelName.

    ClusterName (MQCFST)
    Cluster name (parameter identifier: MQCA_CLUSTER_NAME).

    The name of the cluster to which the queue belongs.

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

    Only one of the resultant values of ClusterName and ClusterNamelist can be nonblank; we cannot specify a value for both.

    The maximum length of the string is MQ_CLUSTER_NAME_LENGTH.

    ClusterNamelist (MQCFST)
    Cluster namelist (parameter identifier: MQCA_CLUSTER_NAMELIST).

    The name of the namelist, that specifies a list of clusters to which the queue belongs.

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

    Only one of the resultant values of ClusterName and ClusterNamelist can be nonblank; we cannot specify a value for both.

    CLWLQueuePriority (MQCFIN)
    Cluster workload queue priority (parameter identifier: MQIA_CLWL_Q_PRIORITY).

    Specifies the priority of the queue in cluster workload management; see Configure a queue manager cluster. The value must be in the range 0 - 9, where 0 is the lowest priority and 9 is the highest.

    CLWLQueueRank (MQCFIN)
    Cluster workload queue rank (parameter identifier: MQIA_CLWL_Q_RANK).

    Specifies the rank of the queue in cluster workload management. The value must be in the range 0 - 9, where 0 is the lowest priority and 9 is the highest.

    CLWLUseQ (MQCFIN)
    Cluster workload use remote queue (parameter identifier: MQIA_CLWL_USEQ). Specifies whether remote and local queues are to be used in cluster workload distribution. The value can be any of the following values:

      MQCLWL_USEQ_AS_Q_MGR
      Use the value of the CLWLUseQ parameter on the definition of the queue manager.

      MQCLWL_USEQ_ANY
      Use remote and local queues.

      MQCLWL_USEQ_LOCAL
      Do not use remote queues.

    CommandScope (MQCFST)
    Command scope (parameter identifier: MQCACF_COMMAND_SCOPE). This parameter applies to z/OS only. Specifies how the command is run when the queue manager is a member of a queue sharing group. You can specify one of the following values:

    • Blank, or omit the parameter altogether. The command is run on the queue manager on which it was entered.
    • A queue manager name. The command is run on the queue manager you specify, providing it is active within the queue sharing group. If you specify a queue manager name other than the queue manager on which it was entered, we must be using a queue sharing group environment. The command server must be enabled.
    • An asterisk (*). The command is executed on the local queue manager and is also passed to every active queue manager in the queue sharing group.

    The maximum length is MQ_QSG_NAME_LENGTH.

    Custom (MQCFST)
    Custom attribute for new features (parameter identifier: MQCA_CUSTOM). 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). Single quotation marks must be escaped with another single quotation mark.

      CAPEXPRY (integer )
      The maximum time, expressed in tenths of a second, until a message put using an object handle, opened using this object on the resolution path, remains in the system until it becomes eligible for expiry processing.

      For more information on message expiry processing, see Enforcing lower expiration times.

      The value can be one of the following:

        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.

    DefaultPutResponse (MQCFIN)
    Default put response type definition (parameter identifier: MQIA_DEF_PUT_RESPONSE_TYPE). The parameter specifies the type of response to be used for put operations to the queue when an application specifies MQPMO_RESPONSE_AS_Q_DEF. The value can be any of the following values:

      MQPRT_SYNC_RESPONSE
      The put operation is issued synchronously, returning a response.

      MQPRT_ASYNC_RESPONSE
      The put operation is issued asynchronously, returning a subset of MQMD fields.

    DefBind (MQCFIN)
    Bind definition (parameter identifier: MQIA_DEF_BIND). The parameter specifies the binding to be used when MQOO_BIND_AS_Q_DEF is specified on the MQOPEN call. The value can be any of the following values:

      MQBND_BIND_ON_OPEN
      The binding is fixed by the MQOPEN call.

      MQBND_BIND_NOT_FIXED
      The binding is not fixed.

      MQBND_BIND_ON_GROUP
      Allows an application to request that a group of messages are all allocated to the same destination instance.

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

    DefinitionType (MQCFIN)
    Queue definition type (parameter identifier: MQIA_DEFINITION_TYPE). The value can be any of the following values:

      MQQDT_PERMANENT_DYNAMIC
      Dynamically defined permanent queue.

      MQQDT_SHARED_DYNAMIC
      Dynamically defined shared queue. This option is available on z/OS only.

      MQQDT_TEMPORARY_DYNAMIC
      Dynamically defined temporary queue.

    DefInputOpenOption (MQCFIN)
    Default input open option (parameter identifier: MQIA_DEF_INPUT_OPEN_OPTION).

    Specifies the default share option for applications opening this queue for input.

    The value can be any of the following values:

      MQOO_INPUT_EXCLUSIVE
      Open queue to get messages with exclusive access.

      MQOO_INPUT_SHARED
      Open queue to get messages with shared access.

    DefPersistence (MQCFIN)
    Default persistence (parameter identifier: MQIA_DEF_PERSISTENCE).

    Specifies the default for message-persistence on the queue. Message persistence determines whether messages are preserved across restarts of the queue manager.

    The value can be any of the following values:

      MQPER_PERSISTENT
      Message is persistent.

      MQPER_NOT_PERSISTENT
      Message is not persistent.

    DefPriority (MQCFIN)
    Default priority (parameter identifier: MQIA_DEF_PRIORITY).

    Specifies the default priority of messages put on the queue. The value must be in the range zero through to the maximum priority value that is supported (9).

    DefReadAhead (MQCFIN)
    Default read ahead (parameter identifier: MQIA_DEF_READ_AHEAD).

    Specifies the default read ahead behavior for non-persistent messages delivered to the client.

    The value can be any of the following values:

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

      MQREADA_YES
      Non-persistent messages are sent ahead 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 consume all the messages it is sent.

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

    DistLists (MQCFIN)
    Distribution list support (parameter identifier: MQIA_DIST_LISTS).

    Specifies whether distribution-list messages can be placed on the queue.

    Note: This attribute is set by the sending message channel agent (MCA). The sending MCA removes messages from the queue each time it establishes a connection to a receiving MCA on a partner queue manager. The attribute is not normally set by administrators, although it can be set if the need arises.

    This parameter is supported on Multiplatforms.

    The value can be any of the following values:

      MQDL_SUPPORTED
      Distribution lists supported.

      MQDL_NOT_SUPPORTED
      Distribution lists not supported.

    Force (MQCFIN)
    Force changes (parameter identifier: MQIACF_FORCE). Specifies whether the command must be forced to complete when conditions are such that completing the command would affect an open queue. The conditions depend upon the type of the queue that is being changed:

      QALIAS
      BaseQName is specified with a queue name and an application has the alias queue open.

      QLOCAL
      Either of the following conditions indicates that a local queue would be affected:

      • Shareability is specified as MQQA_NOT_SHAREABLE and more than one application has the local queue open for input.
      • The Usage value is changed and one or more applications has the local queue open, or there are one or more messages on the queue. (The Usage value must not normally be changed while there are messages on the queue. The format of messages changes when they are put on a transmission queue.)

      QREMOTE
      Either of the following conditions indicates that a remote queue would be affected:

      • If XmitQName is specified with a transmission-queue name, or blank, and an application has a remote queue open that would be affected by this change.
      • If any of the following parameters are specified with a queue or queue manager name, and one or more applications has a queue open that resolved through this definition as a queue manager alias. The parameters are:
        1. RemoteQName
        2. RemoteQMgrName
        3. XmitQName

      QMODEL
      This parameter is not valid for model queues.

    Note: A value of MQFC_YES is not required if this definition is in use as a reply-to queue definition only. The value can be any of the following values:

      MQFC_YES
      Force the change.

      MQFC_NO
      Do not force the change.

    HardenGetBackout (MQCFIN)
    Harden the backout count, or not (parameter identifier: MQIA_HARDEN_GET_BACKOUT). 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.Note: IBM MQ for IBM i always hardens the count, regardless of the setting of this attribute.

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

    The value can be any of the following values:

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

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

    ImageRecoverQueue (MQCFST)
    Specifies whether a local or permanent dynamic queue object is recoverable from a media image, if linear logging is being used (parameter identifier: MQIA_MEDIA_IMAGE_RECOVER_Q). This parameter is not valid on z/OS. Possible values are:

      MQIMGRCOV_YES
      These queue objects are recoverable.

      MQIMGRCOV_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.

      MQIMGRCOV_AS_Q_MGR
      If you specify MQIMGRCOV_AS_Q_MGR, and the ImageRecoverQueue attribute for the queue manager specifies MQIMGRCOV_YES, these queue objects are recoverable.

      If you specify MQIMGRCOV_AS_Q_MGR and the ImageRecoverQueue attribute for the queue manager specifies MQIMGRCOV_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.

      MQIMGRCOV_AS_Q_MGR is the default value.

    IndexType (MQCFIN)
    Index type (parameter identifier: MQIA_INDEX_TYPE). This parameter applies to z/OS only. Specifies the type of index maintained by the queue manager to expedite MQGET operations on the queue. For shared queues, the type of index determines what type of MQGET calls can be used. The value can be any of the following values:

      MQIT_NONE
      No index.

      MQIT_MSG_ID
      The queue is indexed using message identifiers.

      MQIT_CORREL_ID
      The queue is indexed using correlation identifiers.

      MQIT_MSG_TOKEN
      Important: This index type should only be used for queues used with the IBM MQ Workflow for z/OS product.
      The queue is indexed using message tokens.

      MQIT_GROUP_ID
      The queue is indexed using group identifiers.

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

    Retrieval selection criterion IndexType required
      Shared queue Other queue
    None (sequential retrieval) Any Any
    Message identifier MQIT_MSG_ID or MQIT_NONE Any
    Correlation identifier MQIT_CORREL_ID Any
    Message and correlation identifiers MQIT_MSG_ID or MQIT_CORREL_ID Any
    Group identifier MQIT_GROUP_ID Any
    Grouping MQIT_GROUP_ID MQIT_GROUP_ID
    Message token Not allowed MQIT_MSG_TOKEN

    InhibitGet (MQCFIN)
    Get operations are allowed or inhibited (parameter identifier: MQIA_INHIBIT_GET). The value can be:

      MQQA_GET_ALLOWED
      Get operations are allowed.

      MQQA_GET_INHIBITED
      Get operations are inhibited.

    InhibitPut (MQCFIN)
    Put operations are allowed or inhibited (parameter identifier: MQIA_INHIBIT_PUT).

    Specifies whether messages can be put on the queue.

    The value can be any of the following values:

      MQQA_PUT_ALLOWED
      Put operations are allowed.

      MQQA_PUT_INHIBITED
      Put operations are inhibited.

    InitiationQName (MQCFST)
    Initiation queue name (parameter identifier: MQCA_INITIATION_Q_NAME).

    The local queue for trigger messages relating to this queue. The initiation queue must be on the same queue manager.

    The maximum length of the string is MQ_Q_NAME_LENGTH.

    MaxMsgLength (MQCFIN)
    Maximum message length (parameter identifier: MQIA_MAX_MSG_LENGTH).

    The maximum length for messages on the queue. Applications might use the value of this attribute to determine the size of buffer they need to retrieve messages from the queue. If we change this value it might cause an application to operate incorrectly.

    Do not set a value that is greater than the MaxMsgLength attribute of a queue manager.

    The lower limit for this parameter is 0. The upper limit depends on the environment:

    • On z/OS HP Integrity NonStop Server, IBM i, UNIX, Linux, and Windows, the maximum message length is 100 MB (104,857,600 bytes).
    • On other UNIX systems, the maximum message length is 4 MB (4,194,304 bytes).

    MaxQDepth (MQCFIN)
    Maximum queue depth (parameter identifier: MQIA_MAX_Q_DEPTH). The maximum number of messages allowed on the queue. Note: Other factors might cause the queue to be treated as full. For example, it appears to be full if there is no storage available for a message.

    Specify a value greater than or equal to 0, and less than or equal to 999,999,999.

    MaxQFileSize (MQCFIN)
    Maximum queue depth (parameter identifier: MQIA_MAX_Q_FILE_SIZE).

    The maximum size, in megabytes, that a queue file can grow to.

    It is possible for a queue file to exceed the maximum size, if it is configured to a value 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 are allowed to be put to the queue.

    When displayed in queue status, this attribute indicates the current maximum size the queue file can grow to. 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.

    Specify a value greater than or equal to 0, and less than or equal to 267,386,880.

    MsgDeliverySequence (MQCFIN)
    Messages are delivered in priority order or sequence (parameter identifier: MQIA_MSG_DELIVERY_SEQUENCE). The value can be any of the following values:

      MQMDS_PRIORITY
      Messages are returned in priority order.

      MQMDS_FIFO
      Messages are returned in FIFO order (first in, first out).

    NonPersistentMessageClass (MQCFIN)
    The level of reliability to be assigned to non-persistent messages that are put to the queue (parameter identifier: MQIA_NPM_CLASS). The value can be:

      MQNPM_CLASS_NORMAL
      Non-persistent messages persist as long as the lifetime of the queue manager session. They are discarded in the event of a queue manager restart. This value is the default value.

      MQNPM_CLASS_HIGH
      The queue manager attempts to retain non-persistent messages for the lifetime of the queue. Non-persistent messages might still be lost in the event of a failure.

    This parameter is valid only on local and model queues. It is not valid on z/OS.

    ProcessName (MQCFST)
    Name of process definition for the queue (parameter identifier: MQCA_PROCESS_NAME). Specifies the local name of the IBM MQ process that identifies the application to be started when a trigger event occurs.

    • 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. If we do not specify it, the channel name is taken from the value specified for the TriggerData parameter.
    • In other environments, the process name must be nonblank for a trigger event to occur, although it can be set after creating the queue.

    The maximum length of the string is MQ_PROCESS_NAME_LENGTH.

    PropertyControl (MQCFIN)
    Property control attribute (parameter identifier: MQIA_PROPERTY_CONTROL). Specifies how message properties are handled when messages are retrieved from queues using the MQGET call with the MQGMO_PROPERTIES_AS_Q_DEF option. The value can be any of the following values:

      MQPROP_COMPATIBILITY
      If the message contains a property with a prefix of mcd., jms., usr. or mqext., all message properties are delivered to the application in an MQRFH2 header. Otherwise all properties of the message, except those properties contained in the message descriptor (or extension), are discarded and are no longer accessible to the application.
      This value is the default value. It allows applications which expect JMS-related properties to be in an MQRFH2 header in the message data to continue to work unmodified.

      MQPROP_NONE
      All properties of the message are removed from the message before the message is sent to the remote queue manager. Properties in the message descriptor, or extension, are not removed.

      MQPROP_ALL
      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.

      MQPROP_FORCE_MQRFH2
      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.

      MQPROP_V6COMPAT
      Any application MQRFH2 header is received as it was sent. Any properties set using MQSETMP must be retrieved using MQINQMP. They are not added to the MQRFH2 created by the application. Properties that were set in the MQRFH2 header by the sending application cannot be retrieved using MQINQMP.

    This parameter is applicable to Local, Alias, and Model queues.

    QDepthHighEvent (MQCFIN)
    Controls whether Queue Depth High events are generated (parameter identifier: MQIA_Q_DEPTH_HIGH_EVENT).

    A Queue Depth High event indicates that an application put a message on a queue. This event caused the number of messages on the queue to become greater than or equal to the queue depth high threshold. See the QDepthHighLimit parameter.

    Note: The value of this attribute can change implicitly; see Definitions of the Programmable Command Formats. The value can be:

      MQEVR_DISABLED
      Event reporting disabled.

      MQEVR_ENABLED
      Event reporting enabled.

    QDepthHighLimit (MQCFIN)
    High limit for queue depth (parameter identifier: MQIA_Q_DEPTH_HIGH_LIMIT).

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

    This event indicates that an application put a message to a queue. This event caused the number of messages on the queue to become greater than or equal to the queue depth high threshold. See the QDepthHighEvent parameter.

    The value is expressed as a percentage of the maximum queue depth, MaxQDepth. It must be greater than or equal to 0 and less than or equal to 100.

    QDepthLowEvent (MQCFIN)
    Controls whether Queue Depth Low events are generated (parameter identifier: MQIA_Q_DEPTH_LOW_EVENT).

    A Queue Depth Low event indicates that an application retrieved a message from a queue. This event caused the number of messages on the queue to become less than or equal to the queue depth low threshold. See the QDepthLowLimit parameter.

    Note: The value of this attribute can change implicitly. See Definitions of the Programmable Command Formats. The value can be:

      MQEVR_DISABLED
      Event reporting disabled.

      MQEVR_ENABLED
      Event reporting enabled.

    QDepthLowLimit (MQCFIN)
    Low limit for queue depth (parameter identifier: MQIA_Q_DEPTH_LOW_LIMIT).

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

    This event indicates that an application retrieved a message from a queue. This event caused the number of messages on the queue to become less than or equal to the queue depth low threshold. See the QDepthLowEvent parameter.

    Specify the value as a percentage of the maximum queue depth (MaxQDepth attribute), in the range 0 through 100.

    QDepthMaxEvent (MQCFIN)
    Controls whether Queue Full events are generated (parameter identifier: MQIA_Q_DEPTH_MAX_EVENT).

    A Queue Full event indicates that an MQPUT call to a queue was rejected because the queue is full. That is, the queue depth reached its maximum value.

    Note: The value of this attribute can change implicitly; see Definitions of the Programmable Command Formats. The value can be:

      MQEVR_DISABLED
      Event reporting disabled.

      MQEVR_ENABLED
      Event reporting enabled.

    QDesc (MQCFST)
    Queue description (parameter identifier: MQCA_Q_DESC).

    Text that briefly describes the object.

    The maximum length of the string is MQ_Q_DESC_LENGTH.

    Use characters from the character set identified by the coded character set identifier (CCSID) for the message queue manager on which the command is executing. This choice ensures that the text is translated correctly if it is sent to another queue manager.

    QServiceInterval (MQCFIN)
    Target for queue service interval (parameter identifier: MQIA_Q_SERVICE_INTERVAL).

    The service interval used for comparison to generate Queue Service Interval High and Queue Service Interval OK events. See the QServiceIntervalEvent parameter.

    Specify a value in the range 0 through 999 999 999 milliseconds.

    QServiceIntervalEvent (MQCFIN)
    Controls whether Service Interval High or Service Interval OK events are generated (parameter identifier: MQIA_Q_SERVICE_INTERVAL_EVENT).

    A Queue Service Interval High event is generated when a check indicates that no messages were retrieved from, or put to, the queue for at least the time indicated by the QServiceInterval attribute.

    A Queue Service Interval OK event is generated when a check indicates that a message was retrieved from the queue within the time indicated by the QServiceInterval attribute.

    Note: The value of this attribute can change implicitly; see Definitions of the Programmable Command Formats. The value can be any of the following values:

      MQQSIE_HIGH
      Queue Service Interval High events enabled.

      • Queue Service Interval High events are enabled and
      • Queue Service Interval OK events are disabled.

      MQQSIE_OK
      Queue Service Interval OK events enabled.

      • Queue Service Interval High events are disabled and
      • Queue Service Interval OK events are enabled.

      MQQSIE_NONE
      No queue service interval events enabled.

      • Queue Service Interval High events are disabled and
      • Queue Service Interval OK events are also disabled.

    QSGDisposition (MQCFIN)
    Disposition of the object within the group (parameter identifier: MQIA_QSG_DISP ). This parameter applies to z/OS only. Specifies the disposition of the object to which we are applying the command (that is, where it is defined and how it behaves). The value can be any of the following values:

    QSGDisposition Change Copy, Create
    MQQSGD_COPY The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameter MQQSGD_COPY. Any object residing in the shared repository, or any object defined using a command that had the parameters MQQSGD_Q_MGR, is not affected by this command. The object is defined on the page set of the queue manager that executes the command using the MQQSGD_GROUP object of the same name as the ToQName object (for Copy) or the QName object (for Create). For local queues, messages are stored on the page sets of each queue manager and are available only through that queue manager.
    MQQSGD_GROUP The object definition resides in the shared repository. The object was defined using a command that had the parameter MQQSGD_GROUP. Any object residing on the page set of the queue manager that executes the command (except a local copy of the object) is not affected by this command. If the command is successful, the following MQSC command is generated and sent to all active queue managers in the queue sharing group to attempt to refresh local copies on page set zero: 
    DEFINE QUEUE(q-name)
REPLACE QSGDISP(COPY)
    The Change for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.     		The object definition resides in the shared repository. This value is allowed only in a shared queue manager environment. If the definition is successful, the following MQSC command is generated and 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 Copy or Create for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
    MQQSGD_PRIVATE The object resides on the page set of the queue manager that executes the command, and was defined with MQQSGD_Q_MGR or MQQSGD_COPY. Any object residing in the shared repository is unaffected. Not permitted.
    MQQSGD_Q_MGR The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameter MQQSGD_Q_MGR. Any object residing in the shared repository, or any local copy of such an object, is not affected by this command. This value is the default value. The object is defined on the page set of the queue manager that executes the command. This value is the default value. For local queues, messages are stored on the page sets of each queue manager and are available only through that queue manager.
    MQQSGD_SHARED This value applies only to local queues. The object definition resides in the shared repository. The object was defined by a command using the parameter MQQSGD_SHARED. Any object residing on the page set of the queue manager that executes the command, or any object defined by a command using the parameter MQQSGD_GROUP, is not affected by this command. 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 MQQSGD_SHARED only if:

    • CFStructure is nonblank
    • IndexType is not MQIT_MSG_TOKEN
    • The queue is not one of the following:

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

    QueueAccounting (MQCFIN)
    Controls the collection of accounting data (parameter identifier: MQIA_ACCOUNTING_Q). The value can be:

      MQMON_Q_MGR
      The collection of accounting data for the queue is performed based upon the setting of the QueueAccounting parameter on the queue manager.

      MQMON_OFF
      Accounting data collection is disabled for the queue.

      MQMON_ON
      If the value of the queue manager's QueueAccounting parameter is not MQMON_NONE, accounting data collection is enabled for the queue.

    QueueMonitoring (MQCFIN)
    Online monitoring data collection (parameter identifier: MQIA_MONITORING_Q). Specifies whether online monitoring data is to be collected and, if so, the rate at which the data is collected. The value can be any of the following values:

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

      MQMON_Q_MGR
      The value of the queue manager's QueueMonitoring parameter is inherited by the queue.

      MQMON_LOW
      If the value of the queue manager QueueMonitoring parameter is not MQMON_NONE, online monitoring data collection is turned on. The rate of data collection is low for this queue.

      MQMON_MEDIUM
      If the value of the queue manager QueueMonitoring parameter is not MQMON_NONE, online monitoring data collection is turned on. The rate of data collection is moderate for this queue.

      MQMON_HIGH
      If the value of the queue manager QueueMonitoring parameter is not MQMON_NONE, online monitoring data collection is turned on. The rate of data collection is high for this queue.

    QueueStatistics (MQCFIN)
    Statistics data collection (parameter identifier: MQIA_STATISTICS_Q). Specifies whether statistics data collection is enabled. The value can be any of the following values:

      MQMON_Q_MGR
      The value of the queue manager's QueueStatistics parameter is inherited by the queue.

      MQMON_OFF
      Statistics data collection is disabled

      MQMON_ON
      If the value of the queue manager's QueueStatistics parameter is not MQMON_NONE, statistics data collection is enabled

    This parameter is valid only on IBM i, UNIX, and Windows.

    RemoteQMgrName (MQCFST)
    Name of remote queue manager (parameter identifier: MQCA_REMOTE_Q_MGR_NAME).

    If an application opens the local definition of a remote queue, RemoteQMgrName must not be blank or the name of the queue manager the application is connected to. If XmitQName is blank there must be a local queue called RemoteQMgrName. That queue is used as the transmission queue.

    If this definition is used for a queue manager alias, RemoteQMgrName is the name of the queue manager. The queue manager name can be the name of the connected queue manager. If XmitQName is blank, when the queue is opened there must be a local queue called RemoteQMgrName. That queue is used as the transmission queue.

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

    The maximum length of the string is MQ_Q_MGR_NAME_LENGTH.

    RemoteQName (MQCFST)
    Name of remote queue as known locally on the remote queue manager (parameter identifier: MQCA_REMOTE_Q_NAME).

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

    If this definition is used for a queue manager alias definition, RemoteQName must be blank when the open occurs.

    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 maximum length of the string is MQ_Q_NAME_LENGTH.

    Replace (MQCFIN)
    Replace attributes (parameter identifier: MQIACF_REPLACE). This parameter is not valid on a Change Queue command.

    If the object exists, the effect is like issuing the Change Queue command. It is like a Change Queue command without the MQFC_YES option on the Force parameter, and with all of the other attributes specified. In particular, note that any messages which are on the existing queue are retained.

    The Change Queue command without MQFC_YES on the Force parameter, and the Create Queue command with MQRP_YES on the Replace parameter, are different. The difference is that the Change Queue command does not change unspecified attributes. Create Queue with MQRP_YES sets all the attributes. If we use MQRP_YES, unspecified attributes are taken from the default definition, and the attributes of the object being replaced, if one exists, are ignored.)

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

    • The command sets attributes that would require the use of MQFC_YES on the Force parameter if you were using the Change Queue command.
    • The object is open.

    The Change Queue command with MQFC_YES on the Force parameter succeeds in this situation.

    If MQSCO_CELL is specified on the Scope parameter on UNIX, and there is already a queue with the same name in the cell directory, the command fails. The command fails even if MQRP_YES is specified.

    The value can be any of the following values:

      MQRP_YES
      Replace existing definition.

      MQRP_NO
      Do not replace existing definition.

    RetentionInterval (MQCFIN)
    Retention interval (parameter identifier: MQIA_RETENTION_INTERVAL).

    The number of hours for which the queue might be needed, based on the date and time when the queue was created.

    This information is available to a housekeeping application or an operator and can be used to determine when a queue is no longer required. The queue manager does not delete queues 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.

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

    Scope (MQCFIN)
    Scope of the queue definition (parameter identifier: MQIA_SCOPE).

    Specifies whether the scope of the queue definition extends beyond the queue manager which owns the queue. It does so if the queue name is contained in a cell directory, so that it is known to all the queue managers within the cell.

    If this attribute is changed from MQSCO_CELL to MQSCO_Q_MGR, the entry for the queue is deleted from the cell directory.

    Model and dynamic queues cannot be changed to have cell scope.

    If it is changed from MQSCO_Q_MGR to MQSCO_CELL, an entry for the queue is created in the cell directory. If there is already a queue with the same name in the cell directory, the command fails. The command also fails if no name service supporting a cell directory is configured.

    The value can be:

      MQSCO_Q_MGR
      Queue manager scope.

      MQSCO_CELL
      Cell scope.

      This value is not supported on IBM i.

    This parameter is not available on z/OS.

    Shareability (MQCFIN)
    The queue can be shared, or not (parameter identifier: MQIA_SHAREABILITY).

    Specifies whether multiple instances of applications can open this queue for input.

    The value can be any of the following values:

      MQQA_SHAREABLE
      Queue is shareable.

      MQQA_NOT_SHAREABLE
      Queue is not shareable.

    StorageClass (MQCFST)
    Storage class (parameter identifier: MQCA_STORAGE_CLASS). This parameter applies to z/OS only.

    Specifies the name of the storage class.

    The maximum length of the string is MQ_STORAGE_CLASS_LENGTH.

    TargetType (MQCFIN)
    Target type (parameter identifier: MQIA_BASE_TYPE).

    Specifies the type of object to which the alias resolves.

    The value can be any of the following values:

      MQOT_Q
      The object is a queue.

      MQOT_TOPIC
      The object is a topic.

    TriggerControl (MQCFIN)
    Trigger control (parameter identifier: MQIA_TRIGGER_CONTROL).

    Specifies whether trigger messages are written to the initiation queue.

    The value can be:

      MQTC_OFF
      Trigger messages not required.

      MQTC_ON
      Trigger messages required.

    TriggerData (MQCFST)
    Trigger data (parameter identifier: MQCA_TRIGGER_DATA).

    Specifies user data that the queue manager includes in the trigger message. This data is made available to the monitoring application that processes the initiation queue and to the application that is started by the monitor.

    The maximum length of the string is MQ_TRIGGER_DATA_LENGTH.

    TriggerDepth (MQCFIN)
    Trigger depth (parameter identifier: MQIA_TRIGGER_DEPTH).

    Specifies (when TriggerType is MQTT_DEPTH) the number of messages that initiates a trigger message to the initiation queue. The value must be in the range 1 through 999 999 999.

    TriggerMsgPriority (MQCFIN)
    Threshold message priority for triggers (parameter identifier: MQIA_TRIGGER_MSG_PRIORITY).

    Specifies the minimum priority that a message must have before it can cause, or be counted for, a trigger event. The value must be in the range of priority values that is supported (0 through 9).

    TriggerType (MQCFIN)
    Trigger type (parameter identifier: MQIA_TRIGGER_TYPE).

    Specifies the condition that initiates a trigger event. When the condition is true, a trigger message is sent to the initiation queue.

    The value can be any of the following values:

      MQTT_NONE
      No trigger messages.

      MQTT_EVERY
      Trigger message for every message.

      MQTT_FIRST
      Trigger message when queue depth goes from 0 to 1.

      MQTT_DEPTH
      Trigger message when depth threshold exceeded.

    Usage (MQCFIN)
    Usage (parameter identifier: MQIA_USAGE).

    Specifies whether the queue is for normal usage or for transmitting messages to a remote message queue manager.

    The value can be any of the following values:

      MQUS_NORMAL
      Normal usage.

      MQUS_TRANSMISSION
      Transmission queue.

    XmitQName (MQCFST)
    Transmission queue name (parameter identifier: MQCA_XMIT_Q_NAME).

    Specifies the local name of the transmission queue to be used for messages destined for either a remote queue or for a queue manager alias definition.

    If XmitQName is blank, a queue with the same name as RemoteQMgrName is used as the transmission queue.

    This attribute is ignored if the definition is being used as a queue manager alias and RemoteQMgrName is the name of the connected queue manager.

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

    The maximum length of the string is MQ_Q_NAME_LENGTH.


Error codes (Change, Copy, and Create Queue)

This command might return the following errors in the response format header, in addition to the values shown on in Error codes applicable to all commands.

    Reason (MQLONG)
    The value can be any of the following values:

      MQRCCF_CELL_DIR_NOT_AVAILABLE
      Cell directory is not available.

      MQRCCF_CLUSTER_NAME_CONFLICT
      Cluster name conflict.

      MQRCCF_CLUSTER_Q_USAGE_ERROR
      Cluster usage conflict.

      MQRCCF_DYNAMIC_Q_SCOPE_ERROR
      Dynamic queue scope error.

      MQRCCF_FORCE_VALUE_ERROR
      Force value not valid.

      MQRCCF_Q_ALREADY_IN_CELL
      Queue exists in cell.

      MQRCCF_Q_TYPE_ERROR
      Queue type not valid.

Parent topic: Definitions of the Programmable Command Formats