MQSD (Subscription descriptor) on IBM i

The MQSD structure is used to specify details about the subscription being made.


Overview

    Purpose
    The structure is an input/output parameter on the MQSUB call.

    Managed subscriptions
    If an application has no specific need to use a particular queue as the destination for those publications that match its subscription, it can use the managed subscription feature. If an application elects to use a managed subscription, the queue manager informs the subscriber about the destination where published messages are sent, by providing an object handle as an output from the MQSUB call. For more information, see HOBJ (10-digit signed integer) - input/output. When the subscription is removed, the queue manager also undertakes to clean up messages that have not been retrieved from the managed destination, in the following situations:

    • When the subscription is removed - by use of MQCLOSE with CORMSB - and the managed Hobj is closed.
    • By implicit means when the connection is lost to an application using a non-durable subscription (SONDUR)
    • By expiration when a subscription is removed because it has expired and the managed Hobj is closed.

    We must use managed subscriptions with non-durable subscriptions, so that the clean up can occur, and so that messages for closed non-durable subscriptions do not take up space in your queue manager. Durable subscriptions can also use managed destinations.

    Character set and encoding
    Data in MQSD must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by ENNAT. However, if the application is running as an IBM MQ client, the structure must be in the character set and encoding of the client.


Fields

The MQSD structure contains the following fields; the fields are described in alphabetical order:

    SDAID (32 byte character string)

    This value is in the MDAID field of the Message Descriptor (MQMD) of all publication messages matching this subscription. SDAID is part of the identity context of the message. For more information about message context, see Message context.

    For more information about MDAID see MDAID.

    If the SOSETI option is not specified, the MDAID which is set in each message published for this subscription is blanks, as default context information.

    If the SOSETI option is specified, the SDAID is being generated by the user and this field is an input field which contains the MDAID to be set in each publication for this subscription.

    The length of this field is given by LNAIDD. The initial value of this field is 32 blank characters.

    If altering an existing subscription using the SOALT option, the SDAID of any future publication messages can be changed.

    On return from an MQSUB call using SORES, this field is set to the current MDAID being used for the subscription.

    SDACC (32 byte character string)

    This value is in the MDACC field of the Message Descriptor (MQMD) of all publication messages matching this subscription. MDACC is part of the identity context of the message. For more information about message context, see Message context.

    For more information about MDACC see MDACC.

    We can use the following special value for the SDACC field:

      ACNONE
      No accounting token is specified.
      The value is binary zero for the length of the field.

    If the SOSETI option is not specified, the accounting token is generated by the queue manager as default context information and this field is an output field which contains the MDACC which is set in each message published for this subscription.

    If the SOSETI option is specified, the accounting token is being generated by the user and this field is an input field which contains the MDACC to be set in each publication for this subscription.

    The length of this field is given by LNACCT. The initial value of this field is ACNONE.

    If altering an existing subscription using the SOALT option, the value of MDACC in any future publication messages can be changed.

    On return from an MQSUB call using SORES, this field is set to the current MDACC being used for the subscription.

    SDASI (40 byte bit string)

    This is a security identifier that is passed with the SDAU to the authorization service to allow appropriate authorization checks to be performed.

    SDASI is used only if SOALTU is specified, and the SDAU field is not entirely blank up to the first null character or the end of the field.

    On return from an MQSUB call using SORES, this field is unchanged.

    See the description of ODASI in the MQOD data type for more information.

    SDAU (12 byte character string)

    If you specify SOALTU, this field contains an alternate user identifier that is used to check the authorization for the subscription and for output to the destination queue (specified in the Hobj parameter of the MQSUB call), in place of the user identifier that the application is currently running under.

    If successful, the user identifier specified in this field is recorded as the subscription owning user identifier in place of the user identifier that the application is currently running under.

    If SOALTU is specified and this field is entirely blank up to the first null character or the end of the field, the subscription can succeed only if no user authorization is needed to subscribe to this topic with the options specified or the destination queue for output.

    If SOALTU is not specified, this field is ignored.

    On return from an MQSUB call using SORES, this field is unchanged.

    This is an input field. The length of this field is given by LNUID. The initial value of this field is 12 blank characters.

    SDCID (24 byte bit string)

    All publications sent to match this subscription contain this correlation identifier in the message descriptor. If multiple subscriptions use the same queue to get their publications from, using MQGET by correlation ID allows only publications for a specific subscription to be obtained. This correlation identifier can either be generated by the queue manager or by the user.

    If the SOSCID option is not specified, the correlation identifier is generated by the queue manager and this field is an output field which contains the correlation identifier which is set in each message published for this subscription.

    If the SOSCID option is specified, the correlation identifier is being generated by the user and this field is an input field which contains the correlation identifier to be set in each publication for this subscription. In this case, if the field contains CINONE, the correlation identifier which is set in each message published for this subscription is the correlation identifier that was created by the original put of the message.

    If the SOGRP option is specified and the correlation identifier specified is the same as an existing grouped subscription using the same queue and an overlapping topic string, only the most significant subscription in the group is provided with a copy of the publication.

    The length of this field is given by LNCID. The initial value of this field is CINONE.

    If altering an existing subscription using the SOALT option, and this field is an input field, then the subscription correlation ID can be changed, unless the subscription has been created using the SOGRP option.

    On return from an MQSUB call using SORES, this field is set to the current correlation ID for the subscription.

    SDEXP (10 digit signed integer)

    This is the time expressed in tenths of a second after which the subscription expires. No more publications will match this subscription after this interval has passed. This is also used as the value in the MDEXP field in the MQMD of the publications sent to this subscriber.

    The following special value is recognized:

      EIULIM
      The subscription has an unlimited expiration time.

    If altering an existing subscription using the SOALT option, the expiry of the subscription can be changed.

    On return from an MQSUB call using the SORES option this field is set to the original expiry of the subscription and not the remaining expiry time.

    SDON (48 byte character string)

    This is the name of the topic object as defined on the local queue manager.

    The name can contain the following characters:

    • Uppercase alphabetic characters (A through Z)
    • Lowercase alphabetic characters (a through z)
    • Numeric digits (0 through 9)
    • Period (.), forward slash (/), underscore (_), percent (%)

    The name must not contain leading or embedded blanks, but can contain trailing blanks. Use a null character to indicate the end of significant data in the name; the null and any characters following it are treated as blanks. The following restrictions apply:

    • On systems that use EBCDIC Katakana, lowercase characters cannot be used.
    • Names containing lowercase characters, forward slash, or percent, must be enclosed in quotation marks when specified on commands. These quotation marks must not be specified for names that occur as fields in structures or as parameters on calls.

    The SDON is used to form the Full topic name.

    The full topic name can be built from two different fields: SDON and SDOS. For details of how these two fields are used, see Use topic strings.

    On return from an MQSUB call using the SORES option this field is unchanged.

    The length of this field is given by LNTOPN. The initial value of this field is 48 blank characters.

    If altering an existing subscription using the SDALT option, the name of the topic object subscribed to cannot be changed. This field and SDOS can be omitted. If they are provided they must resolve to the same full topic name or the call fails with RC2510 .

    SDOPT (10 digit signed integer)

    We must specify at least one of the following options:

    • SOALT
    • SORES
    • SOCRT

    The values can be added. Do not add the same constant more than once. The table shows how we can combine these options: Combinations that are not valid are noted; any other combinations are valid.

      Access or creation options
      Access and creation options control whether a subscription is created, or whether an existing subscription is returned or altered. We must specify at least one of these options. The table displays valid combinations of access or creation options.

    Combination of options Notes
    SOCRT Creates a subscription if one does not exist; fails if the subscription exists.
    SORES Resumes an existing subscription, fails if no subscription exists.
    SOCRT + SORES Creates a subscription if one does not exist and resumes a matching one, if it does exist. Useful combination if used in an application that might be run a number of times.
    SORES + SOALT (see note) Resumes an existing subscription, altering any fields to match those specified in the MQSD, fails if no subscription exists.
    SOCRT + SOALT (see note) Creates a subscription if one does not exist and resumes a matching one, if it does exist, altering any fields to match those specified in the MQSD. Useful combination if used in an application that wants to ensure that its subscription is in a certain state before proceeding.
    Note:

    Options specifying SOALT can also specify SORES, but this combination has no additional effect to specifying SOALT alone. SOALT implies SORES, because calling MQSUB to alter a subscription implies that the subscriptions are also resumed. The opposite is not true, however: resuming a subscription does not imply it is to be altered.

      SOCRT

      Create a subscription for the topic specified. If a subscription using the same SDSN exists, the call fails with RC2432 . This failure can be avoided by combining the SOCRT option with SORES. The SDSN is not always necessary. For more details, see the description of that field.

      Combining SOCRT with SORES first checks whether there is an existing subscription for the specified SDSN, and if there is returns a handle to that preexisting subscription; but if there is no existing subscription, a new one is created using all the fields provided in the MQSD.

      SOCRT can also be combined with SOALT to similar effect (see details about SOALT later in this topic).

      SORES

      Return a handle to a preexisting subscription which matches those specified by SDSN. No changes are made to the matching subscription attributes, and they are returned on output in the MQSD structure. Most of the contents of the MQSD are not used: The fields used are SDSID, SDVER, SDOPT, SDAID and SDASI, and SDSN.

      The call fails with reason code RC2428 if a subscription does not exist matching the full subscription name. This failure can be avoided by combining the SOCRT option with SORES. For details about SOCRT, see SOCRT.

      The user ID of the subscription is the user ID that created the subscription, or if it has been later altered by a different user ID, it is the user ID of the most recent, successful alteration. If an SDAID is used, and use of alternate user IDs is allowed for that user, SDAID is recorded as the user ID that created the subscription instead of the user ID under which the subscription was made.

      The user ID that created the subscription is recorded as SDAU if that field is used, and the use of alternate user IDs is allowed for that user.

      If a matching subscription exists which was created without the SOAUID option and the user ID of the subscription is different from that of the application requesting a handle to the subscription, the call fails with reason code RC2434 .

      If a matching subscription exists and is currently in use by another application, the call fails with reason code RC2429 . If it is currently in use by the same connection, the call does not fail and a handle to the subscription is returned.

      If the subscription named in SubName is not a valid subscription to resume or alter from an application, the call fails with RC2523 .

      SORES is implied by SOALT and so is not required to be combined with that option, however, it is not an error if those two options are combined.

      SOALT

      Return a handle to a preexisting subscription with the full subscription name matching those specified in SDSN. Any attributes of the subscription that are different from those specified in the MQSD is altered in the subscription unless alteration is disallowed for that attribute. Details are noted in the description of each attribute and are summarized in the following table. If you try to alter an attribute that cannot be changed, the call fails with the reason code shown in the following table.

      The call fails with reason code RC2428 if a subscription does not exist matching the full subscription name. This failure can be avoided by combining the SOCRT option with SOALT.

      Combining SOCRT with SOALT first checks whether there is an existing subscription for the specified full subscription name, and if there is returns a handle to that preexisting subscription with alterations made as previously detailed; but if there is no existing subscription, a new one is created using all the fields provided in the MQSD.

      The user ID of the subscription is the user ID that created the subscription, or if it has been later altered by a different user ID, it is the user ID of the most recent successful alteration. If SDAU is used (and use of alternate user IDs is allowed for that user), then the alternate user ID is recorded as the user ID that created the subscription instead of the user ID under which the subscription was made.

      If a matching subscription exists that was created without the option SOAUID and the user ID of the subscription is different from that of the application requesting a handle to the subscription, the call fails with reason code RC2434 .

      If a matching subscription exists and is currently in use by another application, the call fails with RC2429 . If it is currently in use by the same connection the call does not fail and a handle to the subscription is returned.

      If the subscription named in SubName is not a valid subscription to resume or alter from an application, the call fails with RC2523 .

    The following tables show the subscription attributes that can be altered by SOALT.

    Data type descriptor or function call Field name Can this attribute be altered using SOALT? Reason code
    MQSD Durability options No RC2509
    MQSD Destination Options Yes None
    MQSD Registration options Yes (see note 1 ) RC2515 if you try to alter SOGRP
    MQSD Publication options Yes (see note 2 ) None
    MQSD Wildcard options No RC2510
    MQSD Other options No (see note 3 ) None
    MQSD ObjectName No RC2510
    MQSD SDAU No (see note 4 ) None
    MQSD SDASI No (see note 4 ) None
    MQSD SDEXP Yes None
    MQSD SDOS No RC2510
    MQSD SDSN No (see note 5 ) None
    MQSD SDSUD Yes None
    MQSD SDCID Yes (see note 6 ) RC2515 when in a grouped subscription
    MQSD SDPRI Yes None
    MQSD SDACC Yes None
    MQSD SDAID Yes None
    MQSD SDSL No RC2512
    MQSUB Hobj Yes (see note 6 ) RC2515 when in a grouped subscription
    Notes:
    1. SOGRP cannot be altered.
    2. SONEWP cannot be altered because it is not part of the subscription
    3. These options are not part of the subscription
    4. This attribute is not part of the subscription
    5. This attribute is the identity of the subscription being altered
    6. Alterable except when part of a grouped sub ( SOGRP )

    Durability options: The following options control how durable the subscription is. We can specify only one of these options. If we are altering an existing subscription using the SOALT option, we cannot change the durability of the subscription. On return from an MQSUB call using SORES, the appropriate durability option is set.

      SODUR
      Request that the subscription to this topic remains until it is explicitly removed using MQCLOSE with the CORMSB option. If this subscription is not explicitly removed it will remain even after this application connects to the queue manager is closed.
      If a durable subscription is requested to a topic that is defined as not allowing durable subscriptions, the call fails with RC2436 .

      SONDUR
      Request that the subscription to this topic is removed when the application connection to the queue manager is closed, if it has not already been explicitly removed. SONDUR is the opposite of the SODUR option, and is defined to aid program documentation. It is the default if neither is specified.

    Destination options: The following options control the destination that publications for a topic that has been subscribed to are sent to. If altering an existing subscription using the SOALT option, the destination used for publications for the subscription can be changed. On return from an MQSUB call using SORES, this option is set if appropriate.

      SOMAN

      Request that the destination that the publications are sent to is managed by the queue manager.

      The object handle returned in HOBJ represents a queue manager managed queue, and is for use with subsequent MQGET, MQCB, MQINQ, or MQCLOSE calls.

      An object handle returned from a previous MQSUB call cannot be provided in the Hobj parameter when SOMAN is not specified.

    Registration options: The following options control the details of the registration that is made to the queue manager for this subscription. If altering an existing subscription using the SOALT option, these registration options can be changed. On return from an MQSUB call using SORES the appropriate registration options is set.

      SOGRP

      This subscription is grouped with other subscriptions of the same SDSL using the same queue and specifying the same correlation ID so that any publications to topics that would cause more than one publication message to be provided to the group of subscriptions, due to an overlapping set of topic strings being used, only causes one message to be delivered to the queue. If this option is not used, then each unique subscription (identified by SDSN) that matches is provided with a copy of the publication which might mean that more than one copy of the publication might be placed on the queue shared by a number of subscriptions.

      Only the most significant subscription in the group is provided with a copy of the publication. The most significant subscription is based on the Full topic name up to the point where a wildcard is found. If a mixture of wildcard schemes is used within the group, only the position of the wildcard is important. You are advised not to combine different wildcard schemes within a group of subscriptions that share the same queue.

      When creating a new grouped subscription it must still have a unique SDSN, but if it matches the full topic name of an existing subscription in the group, the call fails with RC2514 .

      If the most significant subscription in group also specifies SONOLC and this is a publication from the same application, then no publication is delivered to the queue.

      When altering a subscription made with this option, the fields which imply the grouping, Hobj on the MQSUB call (representing the queue and queue manager name), and the SDCID cannot be changed. Attempting to alter them causes the call to fail with RC2515 .

      This option must be combined with SOSCID with a SDCID that is not set to CINONE, and cannot be combined with SOMAN.

      SOAUID

      When SOAUID is specified, the identity of the subscriber is not restricted to a single user ID. This allows any user to alter or resume the subscription when they have suitable authority. Only a single user can have the subscription at any one time. An attempt to resume use of a subscription currently in use by another application causes the call to fail with RC2429 .

      To add this option to an existing subscription, the MQSUB call, using SOALT, must come from the same user ID as the original subscription itself.

      If an MQSUB call references an existing subscription with SOAUID set, and the user ID differs from the original subscription, the call succeeds only if the new user ID has authority to subscribe to the topic. On successful completion, future publications to this subscriber are put to the subscriber's queue with the new user ID set in the publication message.

      Do not specify both SOAUID and SOFUID. If neither is specified, the default is SOFUID.

      SOFUID

      When SOFUID is specified, the subscription can be altered or resumed by only the last user ID to alter the subscription. If the subscription has not been altered, it is the user ID that created the subscription.

      If an MQSUB verb references an existing subscription with SOAUID set and alters the subscription using SOALT to use the SOFUID, the user ID of the subscription is now fixed at this new user ID. The call succeeds only if the new user ID has authority to subscribe to the topic.

      If a user ID other than the one recorded as owning a subscription tries to resume or alter an SOFUID subscription, the call fails with RC2434 . The owning user ID of a subscription can be viewed using the DISPLAY SBSTATUS command.

      Do not specify both SOAUID and SOFUID. If neither is specified, the default is SOFUID.

    Publication options: The following options control the way publications are sent to this subscriber. If altering an existing subscription using the SOALT option, these publication options can be changed.

      SONOLC
      Tells the broker that the application does not want to see any of its own publications. Publications are considered to have originated from the same application if the connection handles are the same. On return from an MQSUB call using SORES this option is set if appropriate.

      SONEWP
      No currently retained publications are to be sent, when this subscription is created, only new publications. This option only applies when SOCRE is specified. Any subsequent changes to a subscription do not alter the flow of publications and so any publications that have been retained on a topic, has already been sent to the subscriber as new publications.
      If this option is specified without SOCRE it causes the call to fail with RC2046 . On return from an MQSUB call using SORES this option is not set even if the subscription was created using this option.
      If this option is not used, previously retained messages are sent to the destination queue provided. If this action fails due to an error, either RC2525 or RC2526 , the creation of the subscription fails.
      This option is not valid in combination with SOPUBR.

      SOPUBR
      Set this option indicates that the subscriber requests information specifically when required. The queue manager does not send unsolicited messages to the subscriber. The retained publication (or possibly multiple publications if a wildcard is specified in the topic) is sent to the subscriber each time an MQSUBRQ call is made using the Hsub handle from a previous MQSUB call. No publications are sent as a result of the MQSUB call using this option. On return from an MQSUB call using SORES this option is set if appropriate.
      This option is not valid in combination with SONEWP.

    Wildcard options: The following options control how wildcards are interpreted in the string provided in the SDOS field of the MQSD. We can specify only one of these options. If altering an existing subscription using the SOALT option, these wildcard options cannot be changed. On return from an MQSUB call using SORES the appropriate wildcard option is set.

      SOWCHR
      Wildcards only operate on characters within the topic string. The SOWCHR field treats forward slash (/) as just another character with no special significance.
      The behavior defined by SOWCHR is shown in the following table:

      Special Character Behavior
      * Wildcard, zero or more characters
      ? Wildcard, one character
      % Escape character to allow the characters '*', '?', or '%' to be used in a string and not be interpreted as a special character, for example, '%*', '%?' or '%%'.
      For example, publishing on the following topic: 
      /level0/level1/level2/level3/level4
      matches subscribers using the following topics: 
      *
/*
/ level0/level1/level2/level3/*
/ level0/level1/*/level3/level4
/ level0/level1/le?el2/level3/level4
      Note: This use of wildcards supplies exactly the meaning provided in IBM MQ V6 and WebSphere MB V6 when using MQRFH1 formatted messages for Publish/Subscribe. It is recommended that this is not used for newly written applications and is only used for applications that were previously running against that version and have not been changed to use the default wildcard behavior as described in SOWTOP.

      SOWTOP

      Wildcards only operate on topic elements within the topic string. This is the default behavior if none is chosen.

      The behavior required by SOWTOP is shown in the following table:

      Special Character Behavior
      / Topic level separator
      # Wildcard: multiple topic level
      + Wildcard: single topic level
      Note: The '+' and '#' are not treated as wildcards if they are mixed in with other characters (including themselves) within a topic level. In the following string, the '#' and '+' characters are treated as ordinary characters. 
      level0/level1/#+/level3/level#
      For example, publishing on the following topic: 
      /level0/level1/level2/level3/level4
      matches subscribers using the following topics: 
      #
/#
/ level0/level1/level2/level3/#
/ level0/level1/+/level3/level4
      Note: This use of wildcards supplies the meaning provided in WebSphere Message Broker Version 6 when using MQRFH2 formatted messages for Publish/Subscribe.

      Other options: The following options control the way the API call is issued rather than the subscription. On return from an MQSUB call using SORES these options are unchanged.

        SOALTU
        The SDAU field contains a user identifier to use to validate this MQSUB call. The call can succeed only if this SDAU is authorized to open the object with the specified access options, regardless of whether the user identifier under which the application is running is authorized to do so.

        SOSCID
        The subscription is to use the correlation identifier supplied in the SDCID field. If this option is not specified, a correlation identifier is automatically created by the queue manager at subscription time and is returned to the application in the SDCID field. See SDCID (24-byte bit string)SDCID for more information.

        SOSETI

        The subscription is to use the accounting token and application identity data supplied in the SDACC and SDAID fields.

        If this option is specified, the same authorization check is carried out as if the destination queue was accessed using an MQOPEN call with OOSETI, except in the case where the SOMAN option is also used in which case there is no authorization check on the destination queue.

        If this option is not specified, the publications sent to this subscriber has default context information associated with them as follows:

        Field in MQMD Value used
        MDUID The user ID associated with the subscription at the time the subscription was made.
        MDACC Determined from the environment if possible; Set to ACNONE if not.
        MDAID Set to blanks

        This option is only valid with SOCRE and SOALT. If used with SORES, the SDACC and SDAID fields are ignored, so this option has no effect.

        If a subscription is altered without using this option where previously the subscription had supplied identity context information, default context information is generated for the altered subscription.

        If a subscription allowing different user IDs to use it with option SOAUID, is resumed by a different user ID, default identity context is generated for the new user ID now owning the subscription and any subsequent publications are delivered containing the new identity context.

        SOFIQ
        The MQSUB call fails if the queue manager is in quiescing state. On z/OS, for a CICS or IMS application, this option also forces the MQSUB call to fail if the connection is in quiescing state.

    SDAU (12 byte character string)

    If you specify SOALTU, this field contains an alternate user identifier that is used to check the authorization for the subscription and for output to the destination queue (specified in the Hobj parameter of the MQSUB call), in place of the user identifier that the application is currently running under.

    If successful, the user identifier specified in this field is recorded as the subscription owning user identifier in place of the user identifier that the application is currently running under.

    If SOALTU is specified and this field is entirely blank up to the first null character or the end of the field, the subscription can succeed only if no user authorization is must subscribe to this topic with the options specified or the destination queue for output.

    If SOALTU is not specified, this field is ignored.

    On return from an MQSUB call using SORES, this field is unchanged.

    This is an input field. The length of this field is given by LNUID. The initial value of this field is 12 blank characters.

    SDPRI (10 digit signed integer)

    This is the value that is in the MQPRI field of the Message Descriptor (MQMD) of all publication messages matching this subscription. For more information about the MQPRI field in the MQMD, see MDPRI.

    The value must be greater than or equal to zero; zero is the lowest priority. The following special values can also be used:

      PRQDEF

      When a subscription queue is provided in the Hobj field in the MQSUB call, and is not a managed handle, then the priority for the message is taken from the DefPriority attribute of this queue. If the queue so identified is a cluster queue or there is more than one definition in the queue-name resolution path then the priority is determined when the publication message is put to the queue as described for MDPRI.

      If the MQSUB call uses a managed handle, the priority for the message is taken from the DefPriority attribute of the model queue associated with the topic subscribed to.

      PRPUB
      The priority for the message is the priority of the original publication. This is the initial value of the field.

    If altering an existing subscription using the SOALT option, the MQPRI of any future publication messages can be changed.

    On return from an MQSUB call using SORES, this field is set to the current priority being used for the subscription.

    SDRO (MQCHARV)

    SDRO is the long object name after the queue manager resolves the name provided in SDON.

    If the long object name is provided in SDOS and nothing is provided in SDON, the value returned in this field is the same as provided in SDOS.

    If this field is omitted (that is SDRO.VSBufSize is zero), the SDRO is not returned, but the length is returned in SDRO.VSLength. If the length is shorter than the full SDRO, it is truncated and returns as many of the rightmost characters as can fit in the provided length.

    If SDRO is specified incorrectly, according to the description of how to use the MQCHARV structure, or if it exceeds the maximum length, the call fails with reason code RC2520 .

    SDSID (4 byte character string)
    This is the structure identifier; the value must be:

      SDSIDV
      Identifier for Subscription Descriptor structure.

    This is always an input field. The initial value of this field is SDSIDV

    SDSL (10 digit signed integer)

    This is the level associated with the subscription. Publications are only delivered to this subscription if it is in the set of subscriptions with the highest SDSL value less than or equal to the PubLevel used at publication time.

    The value must be in the range zero to 9. Zero is the lowest level.

    The initial value of this field is 1.

    If altering an existing subscription using the SOALT option, then SDSL cannot be changed.

    SDSN (MQCHARV)

    SDSN specifies the subscription name.

    This field is required only if SDOPT specifies the SODUR option, but if it is provided it is used by the queue manager for SONDUR as well. If specified, SDSN must be unique within the queue manager, because it is the field used to identify subscriptions.

    The maximum length of SDSN is 10240.

    This field serves two purposes. For a SODUR subscription, it is the means by which you identify a subscription to resume it after it has been created, if you have either closed the handle to the subscription (using the COKPSB option) or have been disconnected from the queue manager. Identifying a subscription to remove it after it has been created is done using the MQSUB call with the SORES option. The SDSN field is also displayed in the administration view of subscriptions in the SDSN field in DISPLAY SBSTATUS.

    If SDSN is specified incorrectly, according to the description of how to use the MQCHARV structure, or if it exceeds the maximum length, or if it is omitted when it is required (that is SDSN. VCHRL is zero), or if it exceeds the maximum length, the call fails with reason code RC2440 .

    This is an input field. The initial values of the fields in this structure are the same as those in the MQCHARV structure.

    If altering an existing subscription using the SOALT option, the subscription name cannot be changed, because it is the field used to identify the subscription. It is not changed on output from an MQSUB call with the SORES option.

    SDSS (MQCHARV)

    SDSS is the string that provides the selection criteria used when subscribing for messages from a topic.

    This variable length field is returned on output from an MQSUB call using the SORES option, if a buffer is provided, and if there is also a positive buffer length in VSBufSize. If no buffer is provided on the call, only the length of the selection string is returned in the VSLength field of the MQCHARV. If the buffer provided is smaller than the space required to return the field, only VSBufSize bytes are returned in the provided buffer.

    If SDSS is specified incorrectly, according to the description of how to use the MQCHARV structure, or if it exceeds the maximum length, the call fails with reason code RC2519 .

    SDSUD (MQCHARV)

    The data provided on the subscription in this field is included as the mq.SubUserData message property of every publication sent to this subscription.

    The maximum length of SDSUD is 10240.

    If SDSUD is specified incorrectly, according to the description of how to use the MQCHARV structure, or if it exceeds the maximum length, the call fails with reason code RC2431.

    This is an input field. The initial values of the fields in this structure are the same as those in the MQCHARV structure.

    If altering an existing subscription using the SOALT option, the subscription user data can be changed.

    This variable length field is returned on output from an MQSUB call using the SORES option, if a buffer is provided and there is a positive buffer length in VSBufLen. If no buffer is provided on the call, only the length of the subscription user data is returned in the VCHRL field of the MQCHARV. If the buffer provided is smaller than the space required to return the field, only VSBufLen bytes are returned in the provided buffer.

    SDVER (10 digit signed integer)
    This is the structure version number; the value must be:

      SDVER1
      Version-1 Subscription Descriptor structure.

    The following constant specifies the version number of the current version:

      SDVERC
      Current version of Subscription Descriptor structure.

    This is always an input field. The initial value of the field is SDVER1.


Initial values

Field name Name of constant Value of constant
SDSID SDSIDV 'SD¬¬'
SDVER SDVER1 1
SDOPT SONDUR 0
SDON None Blanks
SDAU None Blanks
SDASI SINONE Nulls
SDEXP EIULIM -1
SDOS Names and values as defined for MQCHARV  
SDSN Names and values as defined for MQCHARV  
SDSUD Names and values as defined for MQCHARV  
SDCID CINONE Nulls
SDPRI PRQDEF -3
SDACC ACNONE Nulls
SDAID None Blanks
SDSL None 1
SDRO Names and values as defined in MQCHARV  
Note:
  1. The symbol ¬ represents a single blank character.


RPG declaration

D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
D* MQSD Structure
D*
D* Structure identifier
D  SDSID                  1      4
D* Structure version number
D  SDVER                  5      8I 0
D* Options associated with subscribing
D  SDOPT                  9     12I 0
D* Object name
D  SDON                  13     60
D* Alternate user identifier
D  SDAU                  61     72
D* Alternate security identifier
D  SDASI                 73    112
D* Expiry of Subscription
D  SDEXP                113    116I 0
D* Object Long name
D SDOSP                 117    132*
D SDOSO                 133    136I 0
D SDOSS                 137    140I 0
D SDOSL                 141    144I 0
D SDOSC                 145    148I 0
D* Subscription name
D SDSNP                 149    164*
D SDSNO                 165    168I 0
D SDSNS                 169    172I 0
D SDSNL                 173    176I 0
D SDSNC                 177    180I 0
D* Subscription User data
D SDSUDP                181    196*
D SDSUDO                197    200I 0
D SDSUDS                201    204I 0
D SDSUDL                205    208I 0
D SDSUDC                209    212I 0
D* Correlation Id related to this subscription
D SDCID                 213    236
D* Priority set in publications
D SDPRI                 237    240I 0
D* Accounting Token set in publications 
D SDACC                 241    272
D* Appl Identity Data set in publications
D SDAID                 273    304
D* Message Selector
D SDSSP                 305    320*
D SDSSO                 321    324I 0
D SDSSS                 325    328I 0
D SDSSL                 329    332I 0
D SDSSC                 333    336
D* Subscription level
D SDSL                  337    340  0
D* Resolved Long object name
D SDROP                 341    356*
D SDROO                 357    360I 0
D SDROS                 361    364I 0
D SDROL                 365    368I 0
D SDROC                 369    372I 0
Parent topic: Data type descriptions on IBM i