Change, Copy, and Create Topic

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

The Change Topic (MQCMD_CHANGE_TOPIC) command changes the specified attributes of an existing IBM MQ administrative topic definition. For any optional parameters that are omitted, the value does not change.

The Copy Topic (MQCMD_COPY_TOPIC) command creates an IBM MQ administrative topic definition by using, for attributes not specified in the command, the attribute values of an existing topic definition.

The Create Topic (MQCMD_CREATE_TOPIC) command creates an IBM MQ administrative topic definition. Any attributes that are not defined explicitly are set to the default values on the destination queue manager.


Required parameter (Change Topic)


Required parameters (Copy Topic)

    FromTopicName (MQCFST)
    The name of the administrative topic object definition to be copied from (parameter identifier: MQCACF_FROM_TOPIC_NAME).

    On z/OS, the queue manager searches for an object with the name you specify and a disposition of MQQSGD_Q_MGR or MQQSGD_COPY 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 ToTopicName and the disposition MQQSGD_GROUP is searched for to copy from.

    The maximum length of the string is MQ_TOPIC_NAME_LENGTH.

    TopicString (MQCFST)
    The topic string (parameter identifier: MQCA_TOPIC_STRING). This string uses the forward slash (/) character as a delimiter for elements within the topic tree.

    The maximum length of the string is MQ_TOPIC_STR_LENGTH.

    ToTopicName (MQCFST)
    The name of the administrative topic definition to copy to (parameter identifier: MQCACF_TO_TOPIC_NAME).

    The maximum length of the string is MQ_TOPIC_NAME_LENGTH.


Required parameters (Create Topic)

    TopicString (MQCFST)
    The topic string (parameter identifier: MQCA_TOPIC_STRING).

    This parameter is required and cannot contain the empty string. The "/" character within this string has a special meaning. It delimits the elements in the topic tree. A topic string can start with the "/" character but is not required to. A string starting with the "/" character is not the same as a string that does not start with the "/" character. A topic string cannot end with the "/" character.

    The maximum length of the string is MQ_TOPIC_STR_LENGTH.


Optional parameters (Change, Copy, and Create Topic)

    ClusterName (MQCFST)
    The name of the cluster to which this topic belongs. (parameter identifier: MQCA_CLUSTER_NAME). The maximum length of the string is MQ_CLUSTER_NAME_LENGTH. Setting this parameter to a cluster that this queue manager is a member of makes all queue managers in the cluster aware of this topic. Any publication to this topic or a topic string below it put to any queue manager in the cluster is propagated to subscriptions on any other queue manager in the cluster. For more details, see Distributed publish/subscribe networks. The value can be any of the following values:

      Blank
      If no topic object above this topic in the topic tree has set this parameter to a cluster name, then this topic does not belong to a cluster. Publications and subscriptions for this topic are not propagated to publish/subscribe cluster-connected queue managers. If a topic node higher in the topic tree has a cluster name set, publications and subscriptions to this topic are also propagated throughout the cluster.
      This value is the default value for this parameter if no value is specified.

      String
      The topic belongs to this cluster. It is not recommended that this is set to a different cluster from a topic object above this topic object in the topic tree. Other queue managers in the cluster will honor this object's definition unless a local definition of the same name exists on those queue managers.
      Additionally, if PublicationScope or SubscriptionScope are set to MQSCOPE_ALL, this value is the cluster to be used for the propagation of publications and subscriptions, for this topic, to publish/subscribe cluster-connected queue managers.

    ClusterPubRoute (MQCFIN)
    The routing behavior of publications between queue managers in a cluster (parameter identifier: MQIA_CLUSTER_PUB_ROUTE). The value can be any of the following values:

      MQCLROUTE_DIRECT
      When you configure a direct routed clustered topic on a queue manager, all queue managers in the cluster become aware of all other queue managers in the cluster. When performing publish and subscribe operations, each queue manager can connect direct to any other queue manager in the cluster.

      MQCLROUTE_TOPIC_HOST
      When we use topic host routing, all queue managers in the cluster become aware of the cluster queue managers that host the routed topic definition (that is, the queue managers on which you have defined the topic object). When performing publish and subscribe operations, queue managers in the cluster connect only to these topic host queue managers, and not directly to each other. The topic host queue managers are responsible for routing publications from queue managers on which publications are published to queue managers with matching subscriptions.

    After a topic object has been clustered (through setting the CLUSTER property) we cannot change the value of the CLROUTE property. The object must be un-clustered (CLUSTER set to ' ') before we can change the value. Un-clustering a topic converts the topic definition to a local topic, which results in a period during which publications are not delivered to subscriptions on remote queue managers; this should be considered when performing this change. See The effect of defining a non-cluster topic with the same name as a cluster topic from another queue manager. If you try to change the value of the CLROUTE property while it is clustered, the system generates an MQRCCF_CLROUTE_NOT_ALTERABLE exception.

    See also Routing for publish/subscribe clusters: Notes on behavior and Designing publish/subscribe clusters.

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

    • blank (or omit the parameter altogether). The command is executed on the queue manager on which it was entered.
    • a queue manager name. The command is executed 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, and 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.

    CommunicationInformation (MQCFST)
    The Multicast communication information object (parameter identifier: MQCA_COMM_INFO_NAME).

    The maximum length of the string is MQ_COMM_INFO_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 published to a topic which inherits properties from this object, 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.

        ASPARENT
        The maximum message expiry time is based on the setting of the closest parent administrative topic object in the topic tree. 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.

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

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

    The value can be any of the following values:

      MQPER_PERSISTENCE_AS_PARENT
      The default persistence is based on the setting of the closest parent administrative topic object in the topic tree.

      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 published to the topic.

    Specify either:

      integer
      The default priority to be used, in the range zero through to the maximum priority value that is supported (9).

      MQPRI_PRIORITY_AS_PARENT
      The default priority is based on the setting of the closest parent administrative topic object in the topic tree.

    DefPutResponse (MQCFIN)
    Default put response (parameter identifier: MQIA_DEF_PUT_RESPONSE_TYPE). The value can be:

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

      MQPRT_RESPONSE_AS_PARENT
      The default put response is based on the setting of the closest parent administrative topic object in the topic tree.

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

    DurableModelQName (MQCFST)
    Name of the model queue to be used for durable subscriptions (parameter identifier: MQCA_MODEL_DURABLE_Q).

    The maximum length of the string is MQ_Q_NAME_LENGTH.

    DurableSubscriptions (MQCFIN)
    Whether applications are permitted to make durable subscriptions (parameter identifier: MQIA_DURABLE_SUB). The value can be:

      MQSUB_DURABLE_AS_PARENT
      Whether durable subscriptions are permitted is based on the setting of the closest parent administrative topic object in the topic tree.

      MQSUB_DURABLE_ALLOWED
      Durable subscriptions are permitted.

      MQSUB_DURABLE_INHIBITED
      Durable subscriptions are not permitted.

    InhibitPublications (MQCFIN)
    Whether publications are allowed for this topic (parameter identifier: MQIA_INHIBIT_PUB). The value can be:

      MQTA_PUB_AS_PARENT
      Whether messages can be published to this topic is based on the setting of the closest parent administrative topic object in the topic tree.

      MQTA_PUB_INHIBITED
      Publications are inhibited for this topic.

      MQTA_PUB_ALLOWED
      Publications are allowed for this topic.

    InhibitSubscriptions (MQCFIN)
    Whether subscriptions are allowed for this topic (parameter identifier: MQIA_INHIBIT_SUB). The value can be:

      MQTA_SUB_AS_PARENT
      Whether applications can subscribe to this topic is based on the setting of the closest parent administrative topic object in the topic tree.

      MQTA_SUB_INHIBITED
      Subscriptions are inhibited for this topic.

      MQTA_SUB_ALLOWED
      Subscriptions are allowed for this topic.

    Multicast (MQCFIN)
    Whether multicast is allowable in the topic tree (parameter identifier: MQIA_MULTICAST). The value can be:

      MQMC_AS_PARENT
      Whether multicast is allowed on this topic is based on the setting of the closest parent administrative topic object in the topic tree.

      MQMC_ENABLED
      Multicast is allowed on this topic.

      MQMC_DISABLED
      Multicast is not allowed on this topic.

      MQMC_ONLY
      Only subscriptions and publications made using multicast are allowed on this topic.

    NonDurableModelQName (MQCFST)
    Name of the model queue to be used for non-durable subscriptions (parameter identifier: MQCA_MODEL_NON_DURABLE_Q).

    The maximum length of the string is MQ_Q_NAME_LENGTH.

    NonPersistentMsgDelivery (MQCFIN)
    The delivery mechanism for non-persistent messages published to this topic (parameter identifier: MQIA_NPM_DELIVERY). The value can be:

      MQDLV_AS_PARENT
      The delivery mechanism used is based on the setting of the first parent administrative node found in the topic tree relating to this topic.

      MQDLV_ALL
      Non-persistent messages must be delivered to all subscribers, irrespective of durability for the MQPUT call to report success. If a delivery failure to any subscriber occurs, no other subscribers receive the message and the MQPUT fails.

      MQDLV_ALL_DUR
      Non-persistent messages must be delivered to all durable subscribers. Failure to deliver a non-persistent message to any non-durable subscribers does not return an error to the MQPUT call. If a delivery failure to a durable subscriber occurs, no other subscribers receive the message and the MQPUT fails.

      MQDLV_ALL_AVAIL
      Non-persistent messages are delivered to all subscribers that can accept the message. Failure to deliver the message to any subscriber does not prevent other subscribers from receiving the message.

    PersistentMsgDelivery (MQCFIN)
    The delivery mechanism for persistent messages published to this topic (parameter identifier: MQIA_PM_DELIVERY). The value can be:

      MQDLV_AS_PARENT
      The delivery mechanism used is based on the setting of the first parent administrative node found in the topic tree relating to this topic.

      MQDLV_ALL
      Persistent messages must be delivered to all subscribers, irrespective of durability for the MQPUT call to report success. If a delivery failure to any subscriber occurs, no other subscribers receive the message and the MQPUT fails.

      MQDLV_ALL_DUR
      Persistent messages must be delivered to all durable subscribers. Failure to deliver a persistent message to any non-durable subscribers does not return an error to the MQPUT call. If a delivery failure to a durable subscriber occurs, no other subscribers receive the message and the MQPUT fails.

      MQDLV_ALL_AVAIL
      Persistent messages are delivered to all subscribers that can accept the message. Failure to deliver the message to any subscriber does not prevent other subscribers from receiving the message.

    ProxySubscriptions (MQCFIN)
    Whether a proxy subscription is to be sent for this topic to directly connected queue managers, even if no local subscriptions exist (parameter identifier: MQIA_PROXY_SUB). The value can be:

      MQTA_PROXY_SUB_FORCE
      A proxy subscription is sent to connected queue managers even if no local subscriptions exist. Note: The proxy subscription is sent when this value is set on Create or Change of the topic.

      MQTA_PROXY_SUB_FIRSTUSE
      For each unique topic string at or below this topic object, a proxy subscription is asynchronously sent to all neighboring queue managers in the following scenarios:

      • When a local subscription is created.
      • When a proxy subscription is received that must be propagated to further directly connected queue managers.

      This value is the default value for this parameter if no value is specified.

    PublicationScope (MQCFIN)
    Whether this queue manager propagates publications for this topic, to queue managers as part of a hierarchy or as part of a publish/subscribe cluster (parameter identifier: MQIA_PUB_SCOPE). The value can be:

      MQSCOPE_AS_PARENT
      Whether this queue manager propagates publications, for this topic, to queue managers as part of a hierarchy or as part of a publish/subscribe cluster is based on the setting of the first parent administrative node found in the topic tree relating to this topic.

      This value is the default value for this parameter if no value is specified.

      MQSCOPE_QMGR
      Publications for this topic are not propagated to other queue managers.

      MQSCOPE_ALL
      Publications for this topic are propagated to hierarchically connected queue managers and to publish/subscribe cluster-connected queue managers.

    Note: This behavior can be over-ridden on a publication-by-publication basis, by using MQPMO_SCOPE_QMGR on the Put Message Options.

    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 by using a command that had the parameter MQQSGD_COPY. Any object residing in the shared repository, or any object defined by 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 by using the MQQSGD_GROUP object of the same name as the ToTopicName object (for Copy) or TopicName object (for Create).
    MQQSGD_GROUP The object definition resides in the shared repository. The object was defined by 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 so that they refresh local copies on page set zero: 
    DEFINE TOPIC(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 definition is allowed only if the queue manager is in a queue sharing group. If the definition is successful, the following MQSC command is generated and sent to all active queue managers in the queue sharing group so that they make or refresh local copies on page set zero: 
    DEFINE TOPIC(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.

    Replace (MQCFIN)
    Replace attributes (parameter identifier: MQIACF_REPLACE). If a topic definition with the same name as ToTopicName exists, this parameter specifies whether it is to be replaced. The value can be as follows:

      MQRP_YES
      Replace existing definition.

      MQRP_NO
      Do not replace existing definition.

    SubscriptionScope (MQCFIN)
    Whether this queue manager propagates subscriptions for this topic, to queue managers as part of a hierarchy or as part of a publish/subscribe cluster (parameter identifier: MQIA_SUB_SCOPE). The value can be:

      MQSCOPE_AS_PARENT
      Whether this queue manager propagates subscriptions, for this topic, to queue managers as part of a hierarchy or as part of a publish/subscribe-cluster is based on the setting of the first parent administrative node found in the topic tree relating to this topic.

      This value is the default value for this parameter if no value is specified.

      MQSCOPE_QMGR
      Subscriptions for this topic are not propagated to other queue managers.

      MQSCOPE_ALL
      Subscriptions for this topic are propagated to hierarchically connected queue managers and to publish/subscribe cluster-connected queue managers.

    Note: This behavior can be over-ridden on a subscription-by-subcription basis, by using MQSO_SCOPE_QMGR on the Subscription Descriptor or SUBSCOPE(QMGR) on DEFINE SUB.

    TopicDesc (MQCFST)
    Topic description (parameter identifier: MQCA_TOPIC_DESC).

    Text that briefly describes the object

    The maximum length is MQ_TOPIC_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 to ensure that the text is translated correctly if it is sent to another queue manager.

    TopicType (MQCFIN)
    Topic type (parameter identifier: MQIA_TOPIC_TYPE). The value specified must match the type of the topic being changed. The value can be:

      MQTOPT_LOCAL
      Local topic object

    UseDLQ (MQCFIN)
    Determines whether the dead-letter queue is used when publication messages cannot be delivered to their correct subscriber queue (parameter identifier: MQIA_USE_DEAD_LETTER_Q). The value can be any of the following values:

      MQUSEDLQ_AS_PARENT
      Determines whether to use the dead-letter queue using the setting of the closest administrative topic object in the topic tree. This value is the default supplied with IBM MQ, but your installation might have changed it.

      MQUSEDLQ_NO
      Publication messages that cannot be delivered to their correct subscriber queue are treated as a failure to put the message. The MQPUT of an application to a topic fails in accordance with the settings of MQIA_NPM_DELIVERY and MQIA_PM_DELIVERY.

      MQUSEDLQ_YES
      If the DEADQ queue manager attribute provides the name of a dead-letter queue then it is used, otherwise the behavior is as for MQUSEDLQ_NO.

    WildcardOperation (MQCFIN)
    Behavior of subscriptions including wildcards made to this topic (parameter identifier: MQIA_WILDCARD_OPERATION). The value can be:

      MQTA_PASSTHRU
      A less specific wildcard subscription is a subscription made by using wildcard topic names that are less specific than the topic string at this topic object. MQTA_PASSTHRU lets less specific wildcard subscriptions receive publications made to this topic and to topic strings more specific than this topic. This value is the default supplied with IBM MQ.

      MQTA_BLOCK
      A less specific wildcard subscription is a subscription made by using wildcard topic names that are less specific than the topic string at this topic object. MQTA_BLOCK stops less specific wildcard subscriptions receiving publications made to this topic or to topic strings more specific than this topic.

    This value of this attribute is used when subscriptions are defined. If you alter this attribute, the set of topics covered by existing subscriptions is not affected by the modification. This value applies also, if the topology is changed when topic objects are created or deleted; the set of topics matching subscriptions created following the modification of the WildcardOperation attribute is created by using the modified topology. To force the matching set of topics to be re-evaluated for existing subscriptions, we must restart the queue manager.

Parent topic: Definitions of the Programmable Command Formats