mq topic
Overview
This resource allows you to manage a MQ topic.
Here is an example on how you should use this:
mq_topic { 'QM1/EM_TEST_TOPIC':
ensure => 'present',
topicstr => 'b_topic',
defprty => '5',
defpsist => 'ASPARENT',
dursub => 'ASPARENT',
mcast => 'ASPARENT',
npmsgdlv => 'ASPARENT',
pmsgdlv => 'ASPARENT',
proxysub => 'FIRSTUSE',
pub => 'ASPARENT',
pubscope => 'ASPARENT',
sub => 'ASPARENT',
subscope => 'ASPARENT',
ttype => 'LOCAL',
usedlq => 'ASPARENT',
wildcard => 'PASSTHRU',
}
If you want to play and experiment with this type, please take a look at our playgrounds. At our playgrounds, we provide you with a pre-installed environment, where you experiment with these Puppet types.
Look at our playgrounds here
Attributes
Attribute Name | Short Description |
---|---|
cluster | The name of the cluster to which this topic belongs. |
cmdscope | This parameter applies to z/OS only and specifies how the command is executed when the queue manager is a member of a queue-sharing group. |
comminfo | The name of the Multicast communication information object associated with this topic object. |
custom | The custom attribute for new features. |
defpresp | Specifies the put response to be used when applications specify the MQPMO_RESPONSE_AS_DEF option. |
defprty | The default priority of messages published to the topic. |
defpsist | Specifies the message persistence to be used when applications specify the MQPER_PERSISTENCE_AS_TOPIC_DEF option. |
descr | Plain-text comment. |
disable_corrective_change | Disable the modification of a resource when Puppet decides it is a corrective change. |
disable_corrective_ensure | Disable the creation or removal of a resource when Puppet decides is a corrective change. |
dursub | Specifies whether applications are permitted to make durable subscriptions on this topic. |
ensure | The basic property that the resource should be in. |
like | The name of a topic. |
mcast | Specifies whether multicast is allowable in the topic tree. |
mdurmdl | The name of the model queue to be used for durable subscriptions that request that the queue manager manages the destination of its publications (see Rules for naming IBM WebSphere MQ objects). |
mndurmdl | The name of the model queue to be used for non-durable subscriptions that request that the queue manager manages the destination of its publications (see Rules for naming IBM WebSphere MQ objects). |
name | The full name of the topic. |
npmsgdlv | - ASPARENT The delivery mechanism used is based on the setting of the first parent administrative node found in the topic tree relating to this topic. |
pmsgdlv | - ASPARENT The delivery mechanism used is based on the setting of the first parent administrative node found in the topic tree relating to this topic. |
provider | resource. |
proxysub | Controls when a proxy subscription is sent for this topic, or topic strings below this topic, to neighboring queue managers when in a publish/subscribe cluster or hierarchy. |
pub | Controls whether messages can be published to this topic. |
pubscope | Determines whether this queue manager propagates publications to queue managers as part of a hierarchy or as part of a publish/subscribe cluster. |
qmgr | The name of the queue manager containing the specfied queue. |
sub | Controls whether applications are to be permitted to subscribe to this topic. |
subscope | Determines whether this queue manager subscribes to publications in this queue manager or in the network of connected queue managers. |
topic | The name of the topic. |
topicstr | The topic string represented by this topic object definition. |
ttype | The topic type to manage. |
usedlq | Determines whether the dead-letter queue is used when publication messages cannot be delivered to their correct subscriber queue. |
wildcard | he behavior of wildcard subscriptions with respect to this topic. |
cluster
The name of the cluster to which this topic belongs. 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. ‘ ‘ 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. 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 honour this object’s definition unless a local definition of the same name exists on those queue managers. To prevent all subscriptions and publications being propagated throughout a cluster, leave this parameter blank on the system topics SYSTEM.BASE.TOPIC and SYSTEM.DEFAULT.TOPIC, except in special circumstances, for example, to support migration, documented elsewhere.
cmdscope
This parameter applies to z/OS only and specifies how the command is executed when the queue manager is a member of a queue-sharing group. CMDSCOPE must be blank, or the local queue manager, if QSGDISP is set to GROUP. ‘ ‘ The command is executed on the queue manager on which it was entered. qmgr-name The command is executed on the queue manager you specify, providing the queue manager is active within the queue-sharing group. You can specify a queue manager name other than the queue manager on which it was entered, only if you are using a shared queue environment and if the command server is enabled.
* The command is executed on the local queue manager and is also passed to every active queue manager in the queue-sharing group. The effect of * is the same as entering the command on every queue manager in the queue-sharing group.
comminfo
The name of the Multicast communication information object associated with this topic object.
custom
The custom attribute for new features. This attribute is reserved for the configuration of new features before separate attributes have been introduced. It can contain the values of zero or more attributes as pairs of attribute name and value, separated by at least one space. The attribute name and value pairs have the form NAME(VALUE). Single quotes must be escaped with another single quote.
This description will be updated when features using this attribute are introduced. At the moment there are no possible values for Custom.
defpresp
Specifies the put response to be used when applications specify the MQPMO_RESPONSE_AS_DEF option.
Valid values are:
- ASPARENT The default put response is based on the setting of the closest parent administrative topic object in the topic tree.
- SYNC Put operations to the queue that specify MQPMO_RESPONSE_AS_Q_DEF are issued as if MQPMO_SYNC_RESPONSE had been specified instead. Fields in the MQMD and MQPMO are returned by the queue manager to the application.
- ASYNC Put operations to the queue that specify MQPMO_RESPONSE_AS_Q_DEF are always issued as if MQPMO_ASYNC_RESPONSE had been specified instead. Some fields in the MQMD and MQPMO are not returned by the queue manager to the application; but an improvement in performance might be seen for messages put in a transaction and any non-persistent messages
Valid values are ASPARENT
, SYNC
, ASYNC
.
defprty
The default priority of messages published to the topic. (integer) The value must be in the range zero (the lowest priority), through to the MAXPRTY queue manager parameter (MAXPRTY is 9). ASPARENT The default priority is based on the setting of the closest parent administrative topic object in the topic tree.
defpsist
Specifies the message persistence to be used when applications specify the MQPER_PERSISTENCE_AS_TOPIC_DEF option. ASPARENT The default persistence is based on the setting of the closest parent administrative topic object in the topic tree.
- NO Messages on this queue are lost during a restart of the queue manager.
- YES Messages on this queue survive a restart of the queue manager.
On z/OS, N and Y are accepted as synonyms of NO and YES.
Valid values are NO
, YES
.
descr
Plain-text comment. It provides descriptive information about the object when an operator issues the DISPLAY TOPIC command. It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).
disable_corrective_change
Disable the modification of a resource when Puppet decides it is a corrective change.
(requires easy_type V2.11.0 or higher)
When using a Puppet Server, Puppet knows about adaptive and corrective changes. A corrective change is when Puppet notices that the resource has changed, but the catalog has not changed. This can occur for example, when a user, by accident or willingly, changed something on the system that Puppet is managing. The normal Puppet process then repairs this and puts the resource back in the state as defined in the catalog. This process is precisely what you want most of the time, but not always. This can sometimes also occur when a hardware or network error occurs. Then Puppet cannot correctly determine the current state of the system and thinks the resource is changed, while in fact, it is not. Letting Puppet recreate remove or change the resource in these cases, is NOT wat you want.
Using the disable_corrective_change
parameter, you can disable corrective changes on the current resource.
Here is an example of this:
crucial_resource {'be_carefull':
...
disable_corrective_change => true,
...
}
When a corrective ensure does happen on the resource Puppet will not modify the resource and signal an error:
Error: Corrective change present requested by catalog, but disabled by parameter disable_corrective_change
Error: /Stage[main]/Main/Crucial_resource[be_carefull]/parameter: change from '10' to '20' failed: Corrective change present requested by catalog, but disabled by parameter disable_corrective_change. (corrective)
disable_corrective_ensure
Disable the creation or removal of a resource when Puppet decides is a corrective change.
(requires easy_type V2.11.0 or higher)
When using a Puppet Server, Puppet knows about adaptive and corrective changes. A corrective change is when Puppet notices that the resource has changed, but the catalog has not changed. This can occur for example, when a user, by accident or willingly, changed something on the system that Puppet is managing. The normal Puppet process then repairs this and puts the resource back in the state as defined in the catalog. This process is precisely what you want most of the time, but not always. This can sometimes also occur when a hardware or network error occurs. Then Puppet cannot correctly determine the current state of the system and thinks the resource is changed, while in fact, it is not. Letting Puppet recreate remove or change the resource in these cases, is NOT wat you want.
Using the disable_corrective_ensure
parameter, you can disable corrective ensure present or ensure absent actions on the current resource.
Here is an example of this:
crucial_resource {'be_carefull':
ensure => 'present',
...
disable_corrective_ensure => true,
...
}
When a corrective ensure does happen on the resource Puppet will not create or remove the resource and signal an error:
Error: Corrective ensure present requested by catalog, but disabled by parameter disable_corrective_ensure.
Error: /Stage[main]/Main/Crucial_resource[be_carefull]/ensure: change from 'absent' to 'present' failed: Corrective ensure present requested by catalog, but disabled by parameter disable_corrective_ensure. (corrective)
dursub
Specifies whether applications are permitted to make durable subscriptions on this topic. ASPARENT Whether durable subscriptions can be made on this topic is based on the setting of the closest parent administrative topic object in the topic tree.
- NO - Durable subscriptions cannot be made on this topic.
- YES - Durable subscriptions can be made on this topic.
Valid values are NO
, YES
.
ensure
The basic property that the resource should be in.
Valid values are present
, absent
.
like
The name of a topic. The topic parameters are used to model this definition. If this field is not completed, and you do not complete the parameter fields related to the command, the values are taken from the default definition for topics on this queue manager.
mcast
Specifies whether multicast is allowable in the topic tree. The values are:
- ASPARENT The multicast attribute of the topic is inherited from the parent.
- DISABLED No multicast traffic is allowed at this node.
- ENABLED Multicast traffic is allowed at this node.
- ONLY Only subscriptions from a multicast capable client are allowed.
Valid values are ASPARENT
, DISABLED
, ENABLED
, ONLY
.
mdurmdl
The name of the model queue to be used for durable subscriptions that request that the queue manager manages the destination of its publications (see Rules for naming IBM WebSphere MQ objects). The maximum length is 48 characters. If MDURMDL is blank, it operates in the same way as ASPARENT values on other attributes. The name of the model queue to be used is based on the closest parent administrative topic object in the topic tree with a value set for MDURMDL.
The dynamic queue created from this model has a prefix of SYSTEM.MANAGED.DURABLE
mndurmdl
The name of the model queue to be used for non-durable subscriptions that request that the queue manager manages the destination of its publications (see Rules for naming IBM WebSphere MQ objects). The maximum length is 48 characters. If MNDURMDL is blank, it operates in the same way as ASPARENT values on other attributes. The name of the model queue to be used is based on the closest parent administrative topic object in the topic tree with a value set for MNDURMDL.
The dynamic queue created from this model has a prefix of SYSTEM.MANAGED.NDURABLE.
name
The full name of the topic. A topic’s full name constists of the name of the Queue manager a slash and then the name of the topic. Here is an example:
QMGR1/MY.FIRST.TOPIC
npmsgdlv
The delivery mechanism for non-persistent messages published to this topic:
- ASPARENT The delivery mechanism used is based on the setting of the first parent administrative node found in the topic tree relating to this topic.
- 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 call fails.
- ALLAVAIL 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.
- ALLDUR 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 subscribers receive the message and the MQPUT calls fails.
Valid values are ASPARENT
, ALL
, ALLAVAIL
, ALLDUR
.
pmsgdlv
The delivery mechanism for persistent messages published to this topic:
- ASPARENT The delivery mechanism used is based on the setting of the first parent administrative node found in the topic tree relating to this topic.
- 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 call fails.
- ALLAVAIL 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.
- ALLDUR 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 subscribers receive the message and the MQPUT calls fails.
Valid values are ASPARENT
, ALL
, ALLAVAIL
, ALLDUR
.
provider
The specific backend to use for this mq_topic
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform.Available providers are:
- simple
- Manage MQ Topics
proxysub
Controls when a proxy subscription is sent for this topic, or topic strings below this topic, to neighboring queue managers when in a publish/subscribe cluster or hierarchy. For more details, see More on routing mechanisms.
- 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.
- FORCE A wildcard proxy subscription that matches all topic strings at and below this point in the topic tree is sent to neighboring queue managers even if no local subscriptions exist. Note The proxy subscription is sent when this value is set on DEFINE or ALTER. When set on a clustered topic, all queue managers in the cluster issue the wildcard proxy subscription to all other queue managers in the cluster.
Valid values are FIRSTUSE
, FORCE
.
pub
Controls whether messages can be published to this topic.
- ASPARENT Whether messages can be published to the topic is based on the setting of the closest parent administrative topic object in the topic tree.
- ENABLED Messages can be published to the topic (by suitably authorized applications).
- DISABLED Messages cannot be published to the topic.
Valid values are ASPARENT
, ENABLED
, DISABLED
.
pubscope
Determines whether this queue manager propagates publications to queue managers as part of a hierarchy or as part of a publish/subscribe cluster. Note You can restrict the behavior on a publication-by-publication basis, using MQPMO_SCOPE_QMGR on the Put Message options.
- ASPARENT Determines whether this queue manager propagates publications to queue managers as part of a hierarchy or as part of a publish/subscribe cluster. This is based on the setting of the first parent administrative node found in the topic tree that relates to this topic.
- QMGR Publications for this topic are not propagated to connected queue managers.
- ALL Publications for this topic are propagated to hierarchically connected queue managers and to publish/subscribe cluster-connected queue managers.
Valid values are ASPARENT
, QMGR
, ALL
.
qmgr
The name of the queue manager containing the specfied queue.
This is a puppet parameter and not a managed property. Therefor it is only used during creation of the resource. Changes to this parameter in your manifest, do NOT result in modifications on the system.
sub
Controls whether applications are to be permitted to subscribe to this topic.
- ASPARENT Whether applications can subscribe to the topic is based on the setting of the closest parent administrative topic object in the topic tree.
- ENABLED Subscriptions can be made to the topic (by suitably authorized applications).
- DISABLED Applications cannot subscribe to the topic.
Valid values are ASPARENT
, ENABLED
, DISABLED
.
subscope
Determines whether this queue manager subscribes to publications in this queue manager or in the network of connected queue managers. If subscribing to all queue managers, the queue manager propagates subscriptions to them as part of a hierarchy or as part of a publish/subscribe cluster. Note You can restrict the behavior on a subscription-by-subscription basis, using MQPMO_SCOPE_QMGR on the Subscription Descriptor or SUBSCOPE(QMGR) on DEFINE SUB. Individual subscribers can override the SUBSCOPE setting of ALL by specifying the MQSO_SCOPE_QMGR subscription option when creating a subscription.
- ASPARENT Whether this queue manager subscribes to publications in the same way as the setting of the first parent administrative node found in the topic tree relating to this topic.
- QMGR Only publications that are published on this queue manager reach the subscriber.
- ALL A publication made on this queue manager or on another queue manager reaches the subscriber. Subscriptions for this topic are propagated to hierarchically connected queue managers and to publish/subscribe cluster-connected queue managers.
Valid values are ASPARENT
, QMGR
, ALL
.
topic
The name of the topic.
This is a puppet parameter and not a managed property. Therefor it is only used during creation of the resource. Changes to this parameter in your manifest, do NOT result in modifications on the system.
topicstr
The topic string represented by this topic object definition. This parameter is required and cannot contain the empty string. The topic string must not be the same as any other topic string already represented by a topic object definition. The maximum length of the string is 10,240 characters.
ttype
The topic type to manage.
This is an immutable property. So you cannot change it.
This is a puppet parameter and not a managed property. Therefor it is only used during creation of the resource. Changes to this parameter in your manifest, do NOT result in modifications on the system.
usedlq
Determines whether the dead-letter queue is used when publication messages cannot be delivered to their correct subscriber queue.
- ASPARENT 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 WebSphere MQ, but your installation might have changed it.
- 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 NPMSGDLV and PMSGDLV.
- YES When the DEADQ queue manager attribute provides the name of a dead-letter queue, then it is used. If the queue manager does not provide the name of a dead-letter queue, then the behavior is as for NO.
Valid values are ASPARENT
, NO
, YES
.
wildcard
he behavior of wildcard subscriptions with respect to this topic.
- PASSTHRU Subscriptions made to a wildcarded topic less specific than the topic string at this topic object receive publications made to this topic and to topic strings more specific than this topic.
-
BLOCK Subscriptions made to a wildcarded topic less specific than the topic string at this topic object do not receive publications made to this topic or to topic strings more specific than this topic.
The 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 scenario 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 WILDCARD attribute is created using the modified topology. If you want to force the matching set of topics to be re-evaluated for existing subscriptions, you must restart the queue manager.
Valid values are PASSTHRU
, BLOCK
.