MQSUB (Register Subscription) on IBM i

The MQSUB call registers the applications subscription to a particular topic.


Syntax

MQSUB (HCONN, SUBDSC, HOBJ, HSUB, CMPCOD, REASON)


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, as described in Use topic strings.
  • 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 either by a short name being provided in the call, or the nearest short name object in the topic hierarchy being found if a long name is provided. An authority check is made on this topic object to ensure authority to subscribe is set and on the destination queue to ensure that authority for output is set. If the SDMAN option is used, this means that an authority check is made on the managed queue name associated with this topic object, and if a non-managed queue is provided, this means that an authority check is made on the queue represented by the HOBJ parameter.
  • The HOBJ returned on the MQSUB call when the SOMAN 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 we should 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 SOGRP option and in order to group subscriptions they must:

    • be using the same named queue (that is not using the SOMAN option) on the same queue manager - represented by the HOBJ parameter on the MQSUB call
    • share the same SDCID
    • be of the same SDSL

    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 SDSL results in RC2512, and alteration of any of the others (which can be changed if a subscription is not grouped) results in RC2515.

  • Fields in the MQSD are completed on return from an MQSUB call which uses the SORES option. The MQSD returned can be passed directly into an MQSUB call which uses the SOALT option with any changes we need to make to the subscription applied to the MQSD. Some fields have special considerations as noted in the table.

    Field name in MQSD Special considerations
    Access or creation options None of these options are set on return from the MQSUB call. If you later 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 will be set as appropriate
    Publication options These options will be set as appropriate, except for SONEWP which is only applicable to SOCRE.
    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 SDRO 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 SORES option this field will be 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 SOALT option we will 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 will be returned on output from an MQSUB call using the SORES option, if a buffer is provided, and also a positive buffer length in VCHRP. If no buffer is provided only the length will be returned in the VCHRL field of the MQCHARV.If the buffer provided is smaller than the space required to return the field, only VCHRP bytes are returned in the provided buffer.

    If you later reuse the MQSD in an MQSUB call using the SOALT option and a buffer is not provided but a non-zero VCHRL is provided, if that length matches the existing length of the field, no alteration will made to the field.

    SubCorrelId and PubAccountingToken

    If we do not use SOSCID, then the SDCID will be generated by the queue manager. If we do not use SOSETI, then the SDACC will be generated by the queue manager.

    These fields will be returned in the MQSD from an MQSUB call using the SORES option. If they are generated by the queue manager, the generated value will be returned on an MQSUB call using the SOCRE or SOALT option.

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


Parameters

The MQSUB call has the following parameters:

    HCONN (10-digit signed integer) - input

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

    SUBDSC (MQSD) - input/output

    This is a structure that identifies the object with use that is being registered by the application. See MQSD (Subscription descriptor) on IBM i for more information.

    HOBJ (10-digit signed integer) - 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 be asked to manage their storage without the need for a specific queue.

    Object handle.

    If a specific queue is to be used it must be associated with the subscription at creation time. This can be done in two ways:

    • By providing this handle when calling MQSUB with the SDCRT option. 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 OOINP*, OOOUT (if a remote queue for example), or OOBRW option. If this is not the case, the call fails with RC2019. It cannot be an object handle to an alias queue which resolves to a topic object. If so, the call fails with RC2019
    • By using the DEFINE SUB MQSC command and provided that command with the name of a queue object.

    If the queue manager is to manage the storage of messages sent to this subscription, we should indicate this when the subscription is created, by using the SOMAN option and setting the parameter value to HONONE. The queue manager returns the handle as an output parameter on the call, and the handle that is returned is known as a managed handle. If HONONE is specified and SOMAN is not also specified, the call fails with RC2019.

    A managed handle that is returned by the queue manager can be used on an MQGET or MQCB call, with or without browse options, on an MQINQ call, or on MQCLOSE. It cannot be used on MQPUT, MQSET, or on a subsequent MQSUB; attempting to do so fails with RC2039 for MQPUT, RC2040 for MQSET, or RC2038 for MQSUB.

    If the SORES option in the OPTS field in the MQSD structure is used to resume this subscription, the handle can be returned to the application in this parameter if HONONE is specified. We can use this whether the subscription is using a managed handle or not. It can be useful for subscriptions created using DEFINE SUB if we want the handle to the subscription queue defined on the DEFINE SUB command. In the case where an administratively created subscription is being resumed, the queue is opened with OOINPQ and OOBRW. If other options are needed, 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 will fail with RC2522. 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 or the call fails with RC2019.

    If this subscription is being altered, by using the SOALT option in the OPTS field in the MQSD structure, then a different HOBJ can be provided. Any publications that have been delivered to the queue previously identified through this parameter remain 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 use of this parameter with various subscription options is summarized in the following table:

    Options Hobj Description
    SOCRT + SOMAN Ignored on input Creates a subscription with queue manager managed storage of messages.
    SOCRT Valid object handle Creates a subscription providing a specific queue as the destination for messages.
    SORES HONONE Resumes a previously created subscription (managed or not) and have the queue manager return the object handle for use by the application.
    SORES Valid, matching, object handle Resumes a previously created subscription which uses a specific queue as the destination for messages and use an object handle with specific open options.
    SOALT + SOMAN HONONE Alters an existing subscription which was previously using a specific queue, to now be managed.
    SOALT Valid object handle Alters an existing subscription to use a specific queue (either from managed, or from a different specific queue).

    Whether it was provided or returned, HOBJ must be specified on subsequent MQGET calls that we need to receive the publications.

    The HOBJ handle ceases to be valid when the MQCLOSE call is issued on it, 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. See HCONN for information about handle scope. An MQCLOSE of the HOBJ handle has no effect on the HSUB handle.

    HSUB (10-digit signed integer) - 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 SOPUBR 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 has no effect on the HOBJ handle.

    This handle cannot be passed to an MQGET or MQCB call. We must use the HOBJ parameter. Passing this handle to any other IBM MQ call results in RC2019.

    CMPCOD (10-digit signed integer) - output
    The completion code; it is one of the following:

      CCOK
      Successful completion

      CCWARN
      Warning (partial completion)

      CCFAIL
      Call failed

    REASON (10-digit signed integer) - output

    The reason code qualifying CMPCOD.

    If CMPCOD is CCOK:

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

    If CMPCOD is CCFAIL:

      RC2019
      (2019 X'07E3') Object handle not valid

      RC2046
      (2046 X'07FE') Options not valid or not consistent

      RC2085
      (2085 X'0825') Object identified cannot be found

      RC2161
      (2161 X'0871') Queue manager quiescing

      RC2298
      (2298 X'08FA') Function not supported.

      RC2424
      (2424 X'0978') Subscription descriptor (MQSD) not valid

      RC2425
      (2441 X'979') Topic string not valid

      RC2428
      (2428 X'097C') Subscription name specified does not match existing subscriptions

      RC2429
      (2429 X'097D') Subscription name exists and is in use by another application

      RC2431
      (2431 X'097F') SubUserData field not valid

      RC2432
      (2432 X'0980') Subscription exists

      RC2434
      (2434 X'0982') Subscription name matches existing subscription

      RC2440
      (2440 X'0988') SubName field not valid

      RC2441
      (2441 X'0989') Objectstring field not valid

      RC2435
      (2435 X'0983') Attribute cannot be changed using SDALT, or subscription was created with SDIMM.

      RC2436
      (2436 X'0984') SODUR option not valid

      RC2459
      (2459, X'99B') Selection string syntax error.

      RC2503
      (2503 X'09C7') MQSUB calls are currently inhibited for the topics subscribed to.

      RC2519
      (2519, X'9D7') The selection string is not as specified in the description of how to use an MQCHARV structure.

      RC2551
      (2551, X'9F7') Specified selection string is not available.


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQSUB(HCONN : SUBDSC : HOBJ :
     C                                     HSUB : CMPCOD : REASON)
The prototype definition for the call is: 
     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     DMQSUB            PR                  EXTPROC('MQSUB')
     D* Connection handle
     D HCONN                         10I 0 VALUE
     D* Subscription descriptor
     D SUBDSC                       400A
     D* Object handle for queue
     D HOBJ                          10I 0
     D* Subscription object handle
     D HSUB                          10I 0
     D* Completion code
     D CMPCOD                        10I 0
     D* Reason code qualifying CompCode
     D REASON                        10I 0
Parent topic: Function calls on IBM i