Change, Copy, and Create Subscription

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

The Change Subscription (MQCMD_CHANGE_SUBSCRIPTION) command changes the specified attributes of an existing IBM MQ subscription. For any optional parameters that are omitted, the value does not change.

The Copy Subscription (MQCMD_COPY_SUBSCRIPTION) command creates an IBM MQ subscription, using, for attributes not specified in the command, the attribute values of an existing subscription.

The Create Subscription (MQCMD_CREATE_SUBSCRIPTION) command creates an IBM MQ administrative subscription so that existing applications can participate in publish/subscribe application.


Required parameters (Change Subscription)

    SubName (MQCFST)
    The name of the subscription definition to be changed (parameter identifier: MQCACF_SUB_NAME).

    The maximum length of the string is MQ_SUB_NAME_LENGTH.

    or

    SubId (MQCFBS)
    The unique identifier of the subscription definition to be changed (parameter identifier: MQBACF_SUB_ID).

    The maximum length of the string is MQ_CORREL_ID_LENGTH.


Required parameters (Copy Subscription)

    ToSubscriptionName (MQCFBS)
    The name of the subscription to copy to (parameter identifier: MQCACF_TO_SUB_NAME).

    The maximum length of the string is MQ_SUBSCRIPTION_NAME_LENGTH.

You require at least one of FromSubscriptionName or SubId.

    FromSubscriptionName (MQCFST)
    The name of the subscription definition to be copied from (parameter identifier: MQCACF_FROM_SUB_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 ToSubscriptionName and the disposition MQQSGD_GROUP is used.

    The maximum length of the string is MQ_SUBSCRIPTION_NAME_LENGTH.

    SubId (MQCFBS)
    The unique identifier of the subscription definition to be changed (parameter identifier: MQBACF_SUB_ID).

    The maximum length of the string is MQ_CORREL_ID_LENGTH.


Required parameters (Create Subscription)

You must provide the SubName.

    SubName (MQCFST)
    The name of the subscription definition to be changed (parameter identifier: MQCACF_SUB_NAME).

    The maximum length of the string is MQ_SUB_NAME_LENGTH.

You require at least one of TopicObject or TopicString.

    TopicObject (MQCFST)
    The name of a previously defined topic object from which is obtained the topic name for the subscription (parameter identifier: MQCA_TOPIC_NAME). Although the parameter is accepted, the value specified cannot be different from the original value for Change Subscription.

    The maximum length of the string is MQ_TOPIC_NAME_LENGTH.

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

    The maximum length of the string is MQ_TOPIC_STR_LENGTH.


Optional parameters (Change, Copy, and Create Subscription)

    CommandScope (MQCFST)
    Command scope (parameter identifier: MQCACF_COMMAND_SCOPE). This parameter applies to z/OS only. Specifies how the command is processed 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 processed on the queue manager on which it was entered.
    • a queue manager name. The command is processed 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, and the command server must be enabled.
    • an asterisk (*). The command is processed 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.

    Destination (MQCFST)
    Destination (parameter identifier: MQCACF_DESTINATION).

    Specifies the name of the alias, local, remote, or cluster queue to which messages for this subscription are put.

    This parameter is mandatory if DestinationClass is set to MQDC_PROVIDED, but is not applicable if DestinationClass is set to MQDC_MANAGED.

    DestinationClass (MQCFIN)
    Destination class (parameter identifier: MQIACF_DESTINATION_CLASS).

    Specifies whether the destination is managed.

    Specify either:

      MQDC_MANAGED
      The destination is managed.

      MQDC_PROVIDED
      The destination queue is as specified in the Destination field.

    Although the parameter is accepted, the value specified cannot be different from the original value for Change Subscription.

    DestinationCorrelId (MQCFBS)
    Destination correlation identifier (parameter identifier: MQBACF_DESTINATION_CORREL_ID).

    Provides a correlation identifier that is placed in the CorrelId field of the message descriptor for all the messages sent to this subscription.

    The maximum length is MQ_CORREL_ID_LENGTH.

    DestinationQueueManager (MQCFST)
    Destination queue manager (parameter identifier: MQCACF_DESTINATION_Q_MGR).

    Specifies the name of the destination queue manager, either local or remote, to which messages for the subscription are forwarded.

    The maximum length of the string is MQ_Q_MGR_NAME_LENGTH.

    Expiry (MQCFIN)
    The time, in tenths of a second, at which a subscription expires after its creation date and time (parameter identifier: MQIACF_EXPIRY).

    The default value of MQEI_UNLIMITED means that the subscription never expires.

    After a subscription has expired it becomes eligible to be discarded by the queue manager and receives no further publications.

    PublishedAccountingToken (MQCFBS)
    Value of the accounting token used in the AccountingToken field of the message descriptor (parameter identifier: MQBACF_ACCOUNTING_TOKEN).

    The maximum length of the string is MQ_ACCOUNTING_TOKEN_LENGTH.

    PublishedApplicationIdentifier (MQCFST)
    Value of the application identity data used in the ApplIdentityData field of the message descriptor (parameter identifier: MQCACF_APPL_IDENTITY_DATA.

    The maximum length of the string is MQ_APPL_IDENTITY_DATA_LENGTH.

    PublishPriority (MQCFIN)
    The priority of the message sent to this subscription (parameter identifier: MQIACF_PUB_PRIORITY). The value can be:

      MQPRI_PRIORITY_AS_PUBLISHED
      Priority of messages sent to this subscription is taken from the priority supplied to the published message. This value is the supplied default value.

      MQPRI_PRIORITY_AS_QDEF
      Priority of messages sent to this subscription is determined by the default priority of the queue defined as a destination.

      0-9
      An integer value providing an explicit priority for messages sent to this subscription.

    PublishSubscribeProperties (MQCFIN)
    Specifies how publish/subscribe related message properties are added to messages sent to this subscription (parameter identifier: MQIACF_PUBSUB_PROPERTIES). The value can be:

      MQPSPROP_COMPAT
      If the original publication is a PCF message, then the publish/subscribe properties are added as PCF attributes. Otherwise, publish/subscribe properties are added within an MQRFH version 1 header. This method is compatible with applications coded for use with previous versions of IBM MQ.

      MQPSPROP_NONE
      Do not add publish/subscribe properties to the messages. This value is the supplied default value.

      MQPSPROP_RFH2
      Publish/subscribe properties are added within an MQRFH version 2 header. This method is compatible with applications coded for use with IBM Integration Bus, formerly known as WebSphere Message Broker.

    Selector (MQCFST)
    Specifies the selector applied to messages published to the topic (parameter identifier: MQCACF_SUB_SELECTOR). Although the parameter is accepted, the value specified cannot be different from the original value for Change Subscription.

    Only those messages that satisfy the selection criteria are put to the destination specified by this subscription.

    The maximum length of the string is MQ_SELECTOR_LENGTH.

    SubscriptionLevel (MQCFIN)
    The level within the subscription interception hierarchy at which this subscription is made (parameter identifier: MQIACF_SUB_LEVEL). To ensure that an intercepting application receives messages before any other subscribers, make sure that it has the highest subscription level of all subscribers. The value can be:

      0 - 9
      An integer in the range 0-9. The default value is 1. Subscribers with a subscription level of 9 intercept publications before they reach subscribers with lower subscription levels.

    SubscriptionScope (MQCFIN)
    Determines whether this subscription is passed to other queue managers in the network (parameter identifier: MQIACF_SUBSCRIPTION_SCOPE). Although the parameter is accepted, the value specified cannot be different from the original value for Change Subscription. The value can be:

      MQTSCOPE_ALL
      The subscription is forwarded to all queue managers directly connected through a publish/subscribe collective or hierarchy. This value is the supplied default value.

      MQTSCOPE_QMGR
      The subscription only forwards messages published on the topic within this queue manager.

    SubscriptionUser (MQCFST)
    The userid that 'owns' this subscription. This parameter is either the userid associated with the creator of the subscription, or, if subscription takeover is permitted, the userid which last took over the subscription. (parameter identifier: MQCACF_SUB_USER_ID).

    The maximum length of the string is MQ_USER_ID_LENGTH.

    TopicString (MQCFST)
    The resolved topic string (parameter identifier: MQCA_TOPIC_STRING). Although the parameter is accepted, the value specified cannot be different from the original value for Change Subscription.

    The maximum length of the string is MQ_TOPIC_STR_LENGTH.

    Userdata (MQCFST)
    User data (parameter identifier: MQCACF_SUB_USER_DATA).

    Specifies the user data associated with the subscription

    The maximum length of the string is MQ_USER_DATA_LENGTH.

    VariableUser (MQCFST)
    Specifies whether a user other than the one who created the subscription, that is, the user shown in SubscriptionUser can take over the ownership of the subscription (parameter identifier: MQIACF_VARIABLE_USER_ID). The value can be:

      MQVU_ANY_USER
      Any user can take over the ownership. This value is the supplied default value.

      MQVU_FIXED_USER
      No other user can take over the ownership.

    WildcardSchema (MQCFIN)
    Specifies the schema to be used when interpreting any wildcard characters contained in the TopicString (parameter identifier: MQIACF_WILDCARD_SCHEMA). Although the parameter is accepted, the value specified cannot be different from the original value for Change Subscription. The value can be:

      MQWS_CHAR
      Wildcard characters represent portions of strings for compatibility with IBM MQ V6.0 broker.

      MQWS_TOPIC
      Wildcard characters represent portions of the topic hierarchy for compatibility with IBM Integration Bus. This value is the supplied default value.