Change, Copy, and Create Queue

The Change Queue PCF 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.

[z/OS] 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.

CapExpiry (MQCFIN)

Capped message expiry processing (parameter identifier MQIA_CAP_EXPIRY) which can be an integer value or can take the value of MQCEX_NOLIMIT.

Specifies a lifetime limit for messages put using the object, expressed in 10ths of a second. A value of -1, displayed as NOLIMIT, has no effect on processing.

For more information on message expiry processing, see CAPEXPRY: Limit message expiry time

CapExpiry provides, or limits, the value in the MQMD Expiry field of any message put.

An application provided MQMD Expiry that is less than any resolved CapExpiry value is passed. This value is not replaced by that resolved CapExpiry value.

This process allows an IBM MQ administrator to limit the life of messages put by an application that overlooked (or was unable to provide, in the case of MQTT) message expiration criteria.

However, this option does not allow an administrator to override application behavior where the required lifetime of messages was under-estimated.

If more than one object is used on the resolution path, for example, alias queue-> remote queue-> transmission queue, then the smallest of all their non-zero CapExpiry values is used as the upper limit for expiry.

The new capped value for expiry is used during the put processing as if it had been provided by the application in the MQMD structure.

The capped value is evaluated for each put being performed,and so is sensitive to the resolution of the put operation. For example, in a cluster, where the put operation is performed with BIND NOT FIXED, messages might pick up different expiry values depending on the CapExpiry value set for the transmission queue used by the channel.

[z/OS] You cannot specify an integer value for the CAPEXPRY attribute on a queue object with QSGDISP(SHARED|GROUP|COPY) that resides in a queue sharing group that contains queue managers running any version of IBM MQ for z/OS below 9.4.0. If you attempt to do so, the object is not modified and messages CSQM532I and CSQM533I are issued to identify the queue managers that do not support CAPEXPRY.

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 you 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 you 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 you use the Create Queue command with a value of MQRP_YES in the Replace parameter. The rules also apply if you use the Change Queue command.

On a local queue with a value of MQQSGD_SHARED in the QSGDisposition parameter, CFStructure cannot change.
If you need to change either the CFStructure or QSGDisposition value, you must delete and redefine the queue. To preserve any of the messages on the queue you 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 you 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 you 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.)

You 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, you 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. You 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; you 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; you 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 Configuring 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, you 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 CAPEXPRY: Limit message expiry time.

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.

Specifying 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:

Table 1. Retrieval selection criteria and index types
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 you 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 AIX®, Linux®, Windows, IBM i, and z/OS, 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 you 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 20, 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 you 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 you are applying the command (that is, where it is defined and how it behaves). The value can be any of the following values:

Table 2. QSGDisposition: Where objects are defined and how they behave
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. It uses 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. You 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.; This is the default value on z/OS.
MQMON_Q_MGR: The value of the queue manager's QueueMonitoring parameter is inherited by the queue.
MQMON_LOW: The rate of data collection is low for this queue.; If the value of the queue manager QueueMonitoring parameter is not MQMON_NONE, online monitoring data collection is turned on.
MQMON_MEDIUM: The rate of data collection is moderate for this queue.; If the value of the queue manager QueueMonitoring parameter is not MQMON_NONE, online monitoring data collection is turned on.
MQMON_HIGH: The rate of data collection is high for this queue.; If the value of the queue manager QueueMonitoring parameter is not MQMON_NONE, online monitoring data collection is turned on.

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; On z/OS systems, you must enable class 5 statistics using the START TRACE command.

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 you 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 AIX and Linux, 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.

StreamQ (MQCFST)

Name of the streaming queue (parameter identifier: MQCA_STREAM_QUEUE_NAME)

Note: If the user setting the Streamq attribute does not have change authority on the chosen stream queue, the command fails with error message AMQ8135E Not Authorized, or the equivalent message CSQ9016E on z/OS.

In addition, if the stream queue does not exist, error message AMQ8135E is returned instead of AMQ8147E IBM MQ object not found or message CSQM125I on z/OS.

StreamQService (MQCFIN)

Quality of service used when delivering messages to Streamq (parameter identifier: MQIA_STREAM_QUEUE_QOS)

The value can be:

MQST_BEST_EFFORT: If the original message can be delivered, but the streamed message cannot, the original message is still delivered to its queue.; This is the default value.
MQST_MUST_DUP: The queue manager ensures that both the original message and the streamed message are successfully delivered to their queues.; If, for some reason, the streamed message cannot be delivered to its queue, the original message is not delivered to its queue either.

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.
MQRCCF_STREAMQ_CONFLICT: This queue has one or more attributes which are incompatible with having the STREAMQ attribute set on it.
MQRCCF_STREAMQ_DEST_CONFLICT: The STREAMQ attribute refers to a queue that has one or more attributes which are incompatible with being a streaming queue.
MQRCCF_STREAMQ_DEST_NOT_SUPP: The STREAMQ attribute refers to a queue that cannot be used as a streaming queue.
MQRCCF_STREAMQ_NOT_SUPPORTED: This queue cannot have the STREAMQ attribute set on it.