MQSET (Set object attributes) on IBM i

The MQSET call is used to change the attributes of an object represented by a handle. The object must be a queue.


Syntax

MQSET (HCONN, HOBJ, SELCNT, SELS, IACNT, INTATR, CALEN, CHRATR, CMPCOD, REASON)


Usage notes

  1. Use this call, the application can specify an array of integer attributes, or a collection of character attribute strings, or both. If no errors occur, the attributes specified are all set simultaneously. If an error occurs (for example, if a selector is not valid, or an attempt is made to set an attribute to a value that is not valid), the call fails and no attributes are set.
  2. The values of attributes can be determined using the MQINQ call ; see MQINQ (Inquire about object attributes) on IBM i for details. Note: Not all attributes with values that can be inquired upon using the MQINQ call can have their values changed using the MQSET call. For example, no process-object or queue manager attributes can be set with this call.
  3. Attribute changes are preserved across restarts of the queue manager (other than alterations to temporary dynamic queues, which do not survive restarts of the queue manager).
  4. We cannot change the attributes of a model queue using the MQSET call. However, if you open a model queue using the MQOPEN call with the MQOO_SET option, we can use the MQSET call to set the attributes of the dynamic local queue that is created by the MQOPEN call.
  5. If the object being set is a cluster queue, there must be a local instance of the cluster queue for the open to succeed.

For more information about object attributes, see:


Parameters

The MQSET call has the following parameters:

    HCONN (10-digit signed integer) - input

    Connection handle.

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

    HOBJ (10-digit signed integer) - input

    Object handle.

    This handle represents the queue object with attributes that are to be set. The handle was returned by a previous MQOPEN call that specified the OOSET option.

    SELCNT (10-digit signed integer) - input

    Count of selectors.

    This is the count of selectors that are supplied in the SELS array. It is the number of attributes that are to be set. Zero is a valid value. The maximum number allowed is 256.

    SELS (10-digit signed integer x SELCNT) - input

    Array of attribute selectors.

    This is an array of SELCNT attribute selectors; each selector identifies an attribute (integer or character) with a value that is to be set.

    Each selector must be valid for the type of queue that HOBJ represents. Only certain IA* and CA* values are allowed; these values are listed later in this section.

    Selectors can be specified in any order. Attribute values that correspond to integer attribute selectors (IA* selectors) must be specified in INTATR in the same order in which these selectors occur in SELS. Attribute values that correspond to character attribute selectors (CA* selectors) must be specified in CHRATR in the same order in which those selectors occur. IA* selectors can be interleaved with the CA* selectors; only the relative order within each type is important.

    It is not an error to specify the same selector more than once; if this is done, the last value specified for a particular selector is the one that takes effect. Note:
    1. The integer and character attribute selectors are allocated within two different ranges; the IA* selectors reside within the range IAFRST through IALAST, and the CA* selectors within the range CAFRST through CALAST.

      For each range, the constants IALSTU and CALSTU define the highest value that the queue manager will accept.

    2. If all the IA* selectors occur first, the same element numbers can be used to address corresponding elements in the SELS and INTATR arrays.

    The attributes that can be set are listed in the following table. No other attributes can be set using this call. For the CA* attribute selectors, the constant that defines the length in bytes of the string that is required in CHRATR is provided in parentheses.

    Selector Description Note
    CATRGD Trigger data (LNTRGD). 2
    IADIST Distribution list support. 1
    IAIGET Whether get operations are allowed.  
    IAIPUT Whether put operations are allowed.  
    IATRGC Trigger control. 2
    IATRGD Trigger depth. 2
    IATRGP Threshold message priority for triggers. 2
    IATRGT Trigger type. 2
    Notes:
    1. Supported only on the following platforms:

      • AIX
      • IBM i
      • Windows

      and for IBM MQ clients connected to these systems.

    2. Not supported on VSE/ESA.

    IACNT (10-digit signed integer) - input

    Count of integer attributes.

    This is the number of elements in the INTATR array, and must be at least the number of IA* selectors in the SELS parameter. Zero is a valid value if there are none.

    INTATR (10-digit signed integ x rxIACNT) - input

    Array of integer attributes.

    This is an array of IACNT integer attribute values. These attribute values must be in the same order as the IA* selectors in the SELS array.

    CALEN (10-digit signed integer) - input

    Length of character attributes buffer.

    This is the length in bytes of the CHRATR parameter, and must be at least the sum of the lengths of the character attributes specified in the SELS array. Zero is a valid value if there are no CA* selectors in SELS.

    CHRATR (1-byte character string x CALEN) - input

    Character attributes.

    This is the buffer containing the character attribute values, concatenated together. The length of the buffer is given by the CALEN parameter.

    The characters attributes must be specified in the same order as the CA* selectors in the SELS array. The length of each character attribute is fixed (see SELS). If the value to be set for an attribute contains fewer nonblank characters than the defined length of the attribute, the value in CHRATR must be padded to the right with blanks to make the attribute value match the defined length of the attribute.

    CMPCOD (10-digit signed integer) - output

    Completion code.

    It is one of the following:

      CCOK
      Successful completion.

      CCFAIL
      Call failed.

    REASON (10-digit signed integer) - output

    Reason code qualifying CMPCOD.

    If CMPCOD is CCOK:

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

    If CMPCOD is CCFAIL:

      RC2219
      (2219, X'8AB') MQI call reentered before previous call complete.

      RC2006
      (2006, X'7D6') Length of character attributes not valid.

      RC2007
      (2007, X'7D7') Character attributes string not valid.

      RC2009
      (2009, X'7D9') Connection to queue manager lost.

      RC2018
      (2018, X'7E2') Connection handle not valid.

      RC2019
      (2019, X'7E3') Object handle not valid.

      RC2020
      (2020, X'7E4') Value for inhibit-get or inhibit-put queue attribute not valid.

      RC2021
      (2021, X'7E5') Count of integer attributes not valid.

      RC2023
      (2023, X'7E7') Integer attributes array not valid.

      RC2040
      (2040, X'7F8') Queue not open for set.

      RC2041
      (2041, X'7F9') Object definition changed since opened.

      RC2101
      (2101, X'835') Object damaged.

      RC2052
      (2052, X'804') Queue has been deleted.

      RC2058
      (2058, X'80A') Queue manager name not valid or not known.

      RC2059
      (2059, X'80B') Queue manager not available for connection.

      RC2162
      (2162, X'872') Queue manager shutting down.

      RC2102
      (2102, X'836') Insufficient system resources available.

      RC2065
      (2065, X'811') Count of selectors not valid.

      RC2067
      (2067, X'813') Attribute selector not valid.

      RC2066
      (2066, X'812') Count of selectors too large.

      RC2071
      (2071, X'817') Insufficient storage available.

      RC2075
      (2075, X'81B') Value for trigger-control attribute not valid.

      RC2076
      (2076, X'81C') Value for trigger-depth attribute not valid.

      RC2077
      (2077, X'81D') Value for trigger-message-priority attribute not valid.

      RC2078
      (2078, X'81E') Value for trigger-type attribute not valid.

      RC2195
      (2195, X'893') Unexpected error occurred.


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQSET(HCONN : HOBJ : SELCNT :
     C                                     SELS(1) : IACNT : INTATR(1) :
     C                                     CALEN : CHRATR : CMPCOD :
     C                                     REASON)
The prototype definition for the call is: 
     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     DMQSET            PR                  EXTPROC('MQSET')
     D* Connection handle
     D HCONN                         10I 0 VALUE
     D* Object handle
     D HOBJ                          10I 0 VALUE
     D* Count of selectors
     D SELCNT                        10I 0 VALUE
     D* Array of attribute selectors
     D SELS                          10I 0
     D* Count of integer attributes
     D IACNT                         10I 0 VALUE
     D* Array of integer attributes
     D INTATR                        10I 0
     D* Length of character attributes buffer
     D CALEN                         10I 0 VALUE
     D* Character attributes
     D CHRATR                          *   VALUE
     D* Completion code
     D CMPCOD                        10I 0
     D* Reason code qualifying CMPCOD
     D REASON                        10I 0
Parent topic: Function calls on IBM i