MQSUB - Register subscription

Use the MQSUB call to register the applications subscription to a particular topic.


Syntax

MQSUB (Hconn, SubDesc, Hobj, Hsub, Compcode, Reason)


Parameters

    Hconn
    Type: MQHCONN - input

    This handle represents the connection to the queue manager. The value of Hconn was returned by a previous MQCONN or MQCONNX call.

    On z/OS® for CICS® applications the MQCONN call can be omitted, and the following value specified for Hconn :

      MQHC_DEF_HCONN
      Default connection handle.

    SubDesc
    Type: MQSD - input/output

    This is a structure that identifies the object in use that is being registered by the application. See MQSD - Subscription descriptor for more information.

    Hobj
    Type: MQHOBJ - input/output

    This handle represents the access that has been established to obtain the messages sent to this subscription. These messages can either be stored on a specific queue or the queue manager can manage their storage without using a specific queue.

    To use a specific queue, you must associate it with the subscription when the subscription is created. We can do this in two ways:

    • By using the DEFINE SUB MQSC command and provided that command with the name of a queue object.
    • By providing this handle when calling MQSUB with the MQSO_CREATE If this handle is provided as an input parameter on the call, it must be a valid object handle returned from a previous MQOPEN call of a queue using at least one of the following options:

      • MQOO_INPUT_*
      • MQOO_BROWSE
      • MQOO_OUTPUT (if the queue is a remote queue)
      If this is not the case, the call fails with MQRC_HOBJ_ERROR. It cannot be an object handle to an alias queue that resolves to a topic object. If so, the call fails with MQRC_HOBJ_ERROR.

    If the queue manager is to manage the storage of messages sent to this subscription, this should be set when you create the subscription, by using the MQSO_MANAGED option. The queue manager then returns this handle as an output parameter on the call. The handle that is returned is known as a managed handle. If MQHO_NONE is specified but MQSO_MANAGED is not specified, the call fails with MQRC_HOBJ_ERROR.

    When a managed handle is returned to you by the queue manager, we can use it on an MQGET or MQCB call with or without browse options, on an MQINQ call, or on MQCLOSE. We cannot use it on MQPUT, MQSUB, MQSET; attempting to do so fails with MQRC_NOT_OPEN_FOR_OUTPUT, MQRC_HOBJ_ERROR, or MQRC_NOT_OPEN_FOR_SET.

    If this subscription is being resumed using the MQSO_RESUME option in the MQSD structure, the handle can be returned to the application in this parameter by setting MQSO_MANAGED to MQHO_NONE. We can do this whether the subscription is using a managed handle or not and it can be useful to provide subscriptions created using DEFINE SUB with the handle to the subscription queue defined on that command. In the case where an administratively created subscription is being resumed, the queue opens with MQOO_INPUT_AS_Q_DEF and MQOO_BROWSE. If you need to specify other options, the application must open the subscription queue explicitly and provide the object handle on the call. If there is a problem opening the queue the call fails with MQRC_INVALID_DESTINATION. If the Hobj is provided, it must be equivalent to the Hobj in the original MQSUB call. This means if an object handle returned from an MQOPEN call is being provided, the handle must be to the same queue as previously used. If it is not the same queue, the call fails with MQRC_HOBJ_ERROR.

    If this subscription is being altered using the MQSO_ALTER option in the MQSD structure, then a different Hobj can be provided. Any publications that have been delivered to the queue and were previously identified through this parameter stay on that queue and it is the responsibility of the application to retrieve those messages if the Hobj parameter now represents a different queue.

    The table summarizes the use of this parameter with various subscription options:
    Options Hobj Description
    MQSO_CREATE + MQSO_MANAGED Ignored on input Creates a subscription with storage of messages managed by the queue manager
    MQSO_CREATE A valid object handle Creates a subscription providing a specific queue as the destination for messages.
    MQSO_RESUME MQHO_NONE Resumes a previously created subscription whether it was managed or not, and has the queue manager return the object handle for use by the application.
    MQSO_RESUME A valid, matching, object handle Resumes a previously created subscription that uses a specific queue as the destination for messages and use an object handle with specific open options.
    MQSO_ALTER + MQSO_MANAGED MQHO_NONE Alters an existing subscription that was previously using a specific queue, so it is now a managed subscription. The class of destination (managed or not) cannot be changed.
    MQSO_ALTER A valid object handle Alters an existing subscription, whether it was managed or not, so that it now uses a specific queue. When the MQSO_MANAGED option is not used, the queue provided can be changed, but the class of destination (managed or not) cannot be changed.

    Whether it was provided or returned, Hobj must be specified on subsequent MQGET or MQCB calls that want to receive the publication messages sent to this subscription.

    The Hobj handle is no longer valid when the MQCLOSE call is issued on it, or when the unit of processing that defines the scope of the handle terminates (until the application disconnects). The scope of the object handle returned is the same as that of the connection handle specified on the call. See Hconn (MQHCONN) - output for information about handle scope. An MQCLOSE of the Hobj handle does not affect the Hsub handle.

    Hsub
    Type: MQHOBJ - output This handle represents the subscription that has been made. It can be used for two further operations:

    • It can be used on a subsequent MQSUBRQ call to request that publications be sent when the MQSO_PUBLICATIONS_ON_REQUEST option has been used when making the subscription.
    • It can be used on a subsequent MQCLOSE call to remove the subscription that has been made. The Hsub handle ceases to be valid when the MQCLOSE call is issued, or when the unit of processing that defines the scope of the handle terminates. The scope of the object handle returned is the same as that of the connection handle specified on the call. An MQCLOSE of the Hsub handle does not affect the Hobj handle.

    This handle cannot be passed to an MQGET or MQCB call. You must use the Hobj parameter. We cannot use this handle on any IBM MQ call other than MQCLOSE or MQSUBRQ. Passing this handle to any other IBM MQ call results in MQRC_HOBJ_ERROR.

    CompCode
    Type: MQLONG - output The completion code; it is one of the following:

      MQCC_OK
      Successful completion

      MQCC_WARNING
      Warning (partial completion)

      MQCC_FAILED
      Call failed

    Reason
    Type: MQLONG - output

    The reason code qualifying CompCode.

    If CompCode is MQCC_OK, the reason code is as follows:

      MQRC_NONE
      (0, X'000') No reason to report.

    If CompCode is MQCC_FAILED, the reason code is one of the following:

      MQRC_CLUSTER_RESOLUTION_ERROR
      (2189, X'88D') Cluster name resolution failed.

      MQRC_DURABILITY_NOT_ALLOWED
      2436 (X'0984') An MQSUB call using the MQSO_DURABLE option failed.

      MQRC_FUNCTION_NOT_SUPPORTED
      2298 (X'08FA') The function requested is not available in the current environment.

      MQRC_HOBJ_ERROR
      2019 (X'07E3') Object handle Hobj not valid.

      MQRC_IDENTITY_MISMATCH
      2434 (X'0982') Subscription name matches existing subscription.

      MQRC_NOT_AUTHORIZED
      2035 (X'07F3') The user is not authorized to perform the operation.

      MQRC_NO_SUBSCRIPTION
      2428 (X'097C') The identified subscription name does not exist.

      MQRC_OBJECT_STRING_ERROR
      2441 (X'0989') Objectstring field not valid.

      MQRC_OPTIONS_ERROR
      2046 (X'07FE') Options parameter or field contains options that are not valid, or a combination of options that is not valid.

      MQRC_Q_MGR_QUIESCING
      2161 (X'0871') Queue manager quiescing.

      MQRC_RECONNECT_Q_MGR_REQD
      2555 (X'09FB'X) The MQCNO_RECONNECT_Q_MGR option is required.

      MQRC_RETAINED_MSG_Q_ERROR
      2525 (X'09DD') Retained publications which exist for the subscribed topic string, cannot be retrieved.

      MQRC_RETAINED_NOT_DELIVERED
      2526 (X'09DE') The retained publications which exist for the subscribed topic string, cannot be delivered to the subscription destination queue, and cannot be delivered to the dead-letter queue.

      MQRC_SD_ERROR
      2424 (X'0978') Subscription descriptor (MQSD) not valid.

      MQRC_SELECTION_NOT_AVAILABLE
      2551 (X'09F7') The selection string does not follow the IBM MQ selector syntax and no extended message selection provider was available.

      MQRC_SELECTION_STRING_ERROR
      2519 (X'09D7') The selection string must be specified as described in the MQCHARV structure documentation.

      MQRC_SELECTOR_SYNTAX_ERROR
      2459 (X'099B') An MQOPEN, MQPUT1, or MQSUB call was issued but a selection string was specified which contained a syntax error.

      MQRC_SUB_USER_DATA_ERROR
      2431 (X'097F') SubUserData field not valid.

      MQRC_SUB_NAME_ERROR
      2440 (X'0988') SubName field not valid.

      MQRC_SUB_ALREADY_EXISTS
      2432 (X'0980') Subscription already exists.

      MQRC_SUB_USER_DATA_ERROR
      2431 (X'097F') SubUserData field not valid.

      MQRC_TOPIC_STRING_ERROR
      2425 (X'0979') Topic string is not valid.

      MQRC_UNKNOWN_OBJECT_NAME
      2085 (X'0825') Object identified in the MQSD ObjectName field cannot be found.

      MQRC_SUB_JOIN_NOT_ALTERABLE
      29440 (X'7300') Subscription sharing mode is incompatible with existing subscription. This error could be returned when attempting to resume a JMS 2.0 shared subscription in a non-JMS application.

    For detailed information about these codes, see Reason codes.


Usage notes

  • The subscription is made to a topic, named either using the short name of a pre-defined topic object, the full name of the topic string, or it is formed by the concatenation of two parts. See the description of ObjectName and ObjectString in MQSD - Subscription descriptor.
  • The queue manager performs security checks when an MQSUB call is issued, to verify that the user identifier under which the application is running has the appropriate level of authority before access is permitted. The appropriate topic object is located in the topic hierarchy and an authority check is made on this topic object to ensure authority to subscribe is set. If the MQSO_MANAGED option is not used, an authority check is made on the destination queue to ensure that authority for output is set. If the MQSO_MANAGED option is used, no authority check is made on the managed queue for output or inquire access.
  • If we do not provide an Hobj as input, the MQSUB call allocates two handles, an object handle (Hobj) and a subscription handle (Hsub).
  • The Hobj returned on the MQSUB call when the MQSO_MANAGED option is used, can be inquired in order to find out attributes such as the Backout threshold and the Excessive backout requeue name. We can also inquire the name of the managed queue, but you must not attempt to directly open this queue.
  • Subscriptions can be grouped allowing only a single publication to be delivered to the group of subscriptions even where more than one of the group matched the publication. Subscriptions are grouped using the MQSO_GROUP_SUB option and in order to group subscriptions they must be

    • using the same named queue (that is not using the MQSO_MANAGED option) on the same queue manager - represented by the Hobj parameter on the MQSUB call
    • share the same SubCorrelId
    • be of the same SubLevel
    These attributes define the set of subscriptions considered to be in the group, and are also the attributes that cannot be altered if a subscription is grouped. Alteration of SubLevel results in MQRC_SUBLEVEL_NOT_ALTERABLE, and alteration of any of the others (which can be changed if a subscription is not grouped) results in MQRC_GROUPING_NOT_ALTERABLE.
  • Successful completion of the MQSUB call does not mean that the action completed. To check that this call has completed, see the DEFINE SUB step in Checking that async commands for distributed networks have finished.
  • Fields in the MQSD are filled in on return from an MQSUB call which uses the MQSO_RESUME option. The MQSD returned can be passed directly into an MQSUB call which uses the MQSO_ALTER option with any changes you need to make to the subscription applied to the MQSD. Some fields have special considerations as noted in the table. MQSD output from MQSUB
    Field name in MQSD Special considerations
    Access or creation options Some of the options can be reset on return from the MQSUB call. If you then reuse the MQSD in an MQSUB call, the option you require must be explicitly set.
    Durability options, Destination options, Registration Options & Wildcard options These options are set as appropriate
    Publication options These options are set as appropriate, except for MQSO_NEW_PUBLICATIONS_ONLY which is only applicable to MQSO_CREATE.
    Other options These options are unchanged on return from an MQSUB call. They control how the API call is issued and are not stored with the subscription. They must be set as required on any subsequent MQSUB call reusing the MQSD.
    ObjectName This input only field is unchanged on return from an MQSUB call.
    ObjectString This input only field is unchanged on return from an MQSUB call. The Full topic name used is returned in the ResObjectString field, if a buffer is provided.
    AlternateUserId and AlternateSecurityId These input only fields are unchanged on return from an MQSUB call. They control how the API call is issued and are not stored with the subscription. They must set as required on any subsequent MQSUB call reusing the MQSD.
    SubExpiry On return from an MQSUB call using the MQSO_RESUME option, this field is set to the original expiry of the subscription and not the remaining expiry time. If you then reuse the MQSD in an MQSUB call using the MQSO_ALTER option you reset the expiry of the subscription to start counting down again.
    SubName This field is an input field on an MQSUB call and is not changed on output.
    SubUserData and SelectionString

    These variable length fields are returned on output from an MQSUB call using the MQSO_RESUME option, if a buffer is provided, and also a positive buffer length in VSBufSize. If no buffer is provided only the length 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 you then reuse the MQSD in an MQSUB call using the MQSO_ALTER option and a buffer is not provided but a non-zero VSLength is provided, if that length matches the existing length of the field, no alteration is made to the field.

    SubCorrelId and PubAccountingToken

    If we do not use MQSO_SET_CORREL_ID, then the SubCorrelId is generated by the queue manager. If we do not use MQSO_SET_IDENTITY_CONTEXT, then the PubAccountingToken is generated by the queue manager.

    These fields are returned in the MQSD from an MQSUB call using the MQSO_RESUME option. If they are generated by the queue manager, the generated value is returned on an MQSUB call using the MQSO_CREATE or MQSO_ALTER option.

    PubPriority, SubLevel & PubApplIdentityData These fields are returned in the MQSD.
    ResObjectString This output only field is returned in the MQSD if a buffer is provided.


C invocation

MQSUB (Hconn, &SubDesc, &Hobj, &Hsub, &CompCode, &Reason)
Declare the parameters as follows: 
MQHCONN Hconn;    /* Connection handle */
MQSD    SubDesc;  /* Subscription descriptor */
MQHOBJ  Hobj;     /* Object handle */
MQHOBJ  Hsub;     /* Subscription handle */
MQLONG  CompCode; /* Completion code */
MQLONG  Reason;   /* Reason code qualifying CompCode */


COBOL invocation

CALL 'MQSUB' USING HCONN, SUBDESC, HOBJ, HSUB, COMPCODE, REASON.
Declare the parameters as follows: 
**   Connection handle
 01  HCONN    PIC S9(9) BINARY.
**   Subscription descriptor
 01  SUBDESC.
     COPY CMQSDV.
**   Object handle
 01  HOBJ     PIC S9(9) BINARY.
**   Subscription handle
 01  HSUB     PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON   PIC S9(9) BINARY.


PL/I invocation

call MQSUB (Hconn, SubDesc, Hobj, Hsub, CompCode, Reason)
Declare the parameters as follows: 
dcl Hconn    fixed bin(31); /* Connection handle */
dcl SubDesc  like MQSD;     /* Subscription descriptor */
dcl Hobj     fixed bin(31); /* Object handle */
dcl Hsub     fixed bin(31); /* Subscription handle */
dcl CompCode fixed bin(31); /* Completion code */
dcl Reason   fixed bin(31); /* Reason code qualifying CompCode */


High Level Assembler invocation

CALL MQSUB,(HCONN,SUBDESC,HOBJ,HSUB,COMPCODE,REASON)
Declare the parameters as follows: 
HCONN    DS      F  Connection handle
SUBDESC  CMQSDA  ,  Subscription descriptor
HOBJ     DS      F  Object handle
HSUB     DS      F  Subscription handle
COMPCODE DS      F  Completion code
REASON   DS      F  Reason code qualifying COMPCODE