MQSET - Set object attributes

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


Syntax

MQSET (Hconn, Hobj, SelectorCount, Selectors, IntAttrCount, IntAttrs, CharAttrLength, CharAttrs, 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.

    Hobj
    Type: MQHOBJ - input

    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 MQOO_SET option.

    SelectorCount
    Type: MQLONG - input

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

    Selectors
    Type: MQLONGxSelectorCount - input

    This is an array of SelectorCount 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 MQIA_* and MQCA_* values are allowed; as listed later.

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

    We can specify the same selector more than once; if you do, 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 MQIA_* selectors reside within the range MQIA_FIRST through MQIA_LAST, and the MQCA_* selectors within the range MQCA_FIRST through MQCA_LAST.

      For each range, the constants MQIA_LAST_USED and MQCA_LAST_USED define the highest value that the queue manager accepts.

    2. If all the MQIA_* selectors occur first, the same element numbers can be used to address corresponding elements in the Selectors and IntAttrs arrays.
    3. If the SelectorCount parameter is zero, Selectors is not referred to; in this case, the parameter address passed by programs written in C or System/390 assembler might be null.

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

    Selector Description Note
    MQCA_TRIGGER_DATA Trigger data (MQ_TRIGGER_DATA_LENGTH).  
    MQIA_DIST_LISTS Distribution list support. 1
    MQIA_INHIBIT_GET Whether get operations are allowed.  
    MQIA_INHIBIT_PUT Whether put operations are allowed.  
    MQIA_TRIGGER_CONTROL Trigger control.  
    MQIA_TRIGGER_DEPTH Trigger depth.  
    MQIA_TRIGGER_MSG_PRIORITY Threshold message priority for triggers.  
    MQIA_TRIGGER_TYPE Trigger type.  
    Note:
    1. Supported only on the following platforms:

      • AIX
      • IBM i
      • Linux
      • Windows

      and for IBM MQ MQI clients connected to these systems.

    IntAttrCount
    Type: MQLONG - input

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

    IntAttrs
    Type: MQLONGxIntAttrCount - input

    This is an array of IntAttrCount integer attribute values. These attribute values must be in the same order as the MQIA_* selectors in the Selectors array.

    If the IntAttrCount or SelectorCount parameter is zero, IntAttrs is not referred to; in this case, the parameter address passed by programs written in C or System/390 assembler might be null.

    CharAttrLength
    Type: MQLONG - input

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

    CharAttrs
    Type: MQCHAR x CharAttrLength - input

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

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

    If the CharAttrLength or SelectorCount parameter is zero, CharAttrs is not referred to; in this case, the parameter address passed by programs written in C or System/390 assembler might be null.

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

      MQCC_OK
      Successful completion.

      MQCC_FAILED
      Call failed.

    Reason
    Type: MQLONG - output

    The reason code qualifying CompCode.

    If CompCode is MQCC_OK:

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

    If CompCode is MQCC_FAILED:

      MQRC_ADAPTER_NOT_AVAILABLE
      (2204, X'89C') Adapter not available.

      MQRC_ADAPTER_SERV_LOAD_ERROR
      (2130, X'852') Unable to load adapter service module.

      MQRC_API_EXIT_ERROR
      (2374, X'946') API exit failed.

      MQRC_API_EXIT_LOAD_ERROR
      (2183, X'887') Unable to load API exit.

      MQRC_ASID_MISMATCH
      (2157, X'86D') Primary and home ASIDs differ.

      MQRC_CALL_IN_PROGRESS
      (2219, X'8AB') MQI call entered before previous call complete.

      MQRC_CF_NOT_AVAILABLE
      (2345, X'929') Coupling facility not available.

      MQRC_CF_STRUC_FAILED
      (2373, X'945') Coupling-facility structure failed.

      MQRC_CF_STRUC_IN_USE
      (2346, X'92A') Coupling-facility structure in use.

      MQRC_CF_STRUC_LIST_HDR_IN_USE
      (2347, X'92B') Coupling-facility structure list-header in use.

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

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

      MQRC_CICS_WAIT_FAILED
      (2140, X'85C') Wait request rejected by CICS.

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

      MQRC_CONNECTION_NOT_AUTHORIZED
      (2217, X'8A9') Not authorized for connection.

      MQRC_CONNECTION_STOPPING
      (2203, X'89B') Connection shutting down.

      MQRC_DB2_NOT_AVAILABLE
      (2342, X'926') Db2 subsystem not available.

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

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

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

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

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

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

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

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

      MQRC_PAGESET_ERROR
      (2193, X'891') Error accessing page-set data set.

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

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

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

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

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

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

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

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

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

      MQRC_SUPPRESSED_BY_EXIT
      (2109, X'83D') Call suppressed by exit program.

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

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

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

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

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

    For detailed information about these codes, see Reason codes.


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 object attributes for details. Note: Not all attributes with values that can be inquired 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:


C invocation

MQSET (Hconn, Hobj, SelectorCount, Selectors, IntAttrCount, IntAttrs,
      CharAttrLength, CharAttrs, &CompCode, &Reason);
Declare the parameters as follows: 
MQHCONN  Hconn;           /* Connection handle */
MQHOBJ   Hobj;            /* Object handle */
MQLONG   SelectorCount;   /* Count of selectors */
MQLONG   Selectors[n];    /* Array of attribute selectors */
MQLONG   IntAttrCount;    /* Count of integer attributes */
MQLONG   IntAttrs[n];     /* Array of integer attributes */
MQLONG   CharAttrLength;  /* Length of character attributes buffer */
MQCHAR   CharAttrs[n];    /* Character attributes */
MQLONG   CompCode;        /* Completion code */
MQLONG   Reason;          /* Reason code qualifying CompCode */


COBOL invocation

CALL 'MQSET' USING HCONN, HOBJ, SELECTORCOUNT, SELECTORS-TABLE,
                    INTATTRCOUNT, INTATTRS-TABLE, CHARATTRLENGTH,
                    CHARATTRS, COMPCODE, REASON.
Declare the parameters as follows: 
**   Connection handle
 01  HCONN            PIC S9(9) BINARY.
**   Object handle
 01  HOBJ             PIC S9(9) BINARY.
**   Count of selectors
 01  SELECTORCOUNT    PIC S9(9) BINARY.
**   Array of attribute selectors
 01  SELECTORS-TABLE.
  02  SELECTORS        PIC S9(9) BINARY OCCURS n TIMES.
**   Count of integer attributes
 01  INTATTRCOUNT     PIC S9(9) BINARY.
**   Array of integer attributes
 01  INTATTRS-TABLE.
  02  INTATTRS         PIC S9(9) BINARY OCCURS n TIMES.
**   Length of character attributes buffer
 01  CHARATTRLENGTH   PIC S9(9) BINARY.
**   Character attributes
 01  CHARATTRS        PIC X(n).
**   Completion code
 01  COMPCODE         PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON           PIC S9(9) BINARY.


PL/I invocation

call MQSET (Hconn, Hobj, SelectorCount, Selectors, IntAttrCount,
           IntAttrs, CharAttrLength, CharAttrs, CompCode, Reason);
Declare the parameters as follows: 
dcl Hconn           fixed bin(31);  /* Connection handle */
dcl Hobj            fixed bin(31);  /* Object handle */
dcl SelectorCount   fixed bin(31);  /* Count of selectors */
dcl Selectors(n)    fixed bin(31);  /* Array of attribute selectors */
dcl IntAttrCount    fixed bin(31);  /* Count of integer attributes */
dcl IntAttrs(n)     fixed bin(31);  /* Array of integer attributes */
dcl CharAttrLength  fixed bin(31);  /* Length of character attributes
                                       buffer */
dcl CharAttrs       char(n);        /* Character attributes */
dcl CompCode        fixed bin(31);  /* Completion code */
dcl Reason          fixed bin(31);  /* Reason code qualifying
                                       CompCode */


High Level Assembler invocation

CALL MQSET,(HCONN,HOBJ,SELECTORCOUNT,SELECTORS,INTATTRCOUNT,  X
             INTATTRS,CHARATTRLENGTH,CHARATTRS,COMPCODE,REASON)
Declare the parameters as follows: 
HCONN           DS  F      Connection handle
HOBJ            DS  F      Object handle
SELECTORCOUNT   DS  F      Count of selectors
SELECTORS       DS  (n)F   Array of attribute selectors
INTATTRCOUNT    DS  F      Count of integer attributes
INTATTRS        DS  (n)F   Array of integer attributes
CHARATTRLENGTH  DS  F      Length of character attributes buffer
CHARATTRS       DS  CL(n)  Character attributes
COMPCODE        DS  F      Completion code
REASON          DS  F      Reason code qualifying COMPCODE


Visual Basic invocation

MQSET Hconn, Hobj, SelectorCount, Selectors, IntAttrCount, IntAttrs,
      CharAttrLength, CharAttrs, CompCode, Reason
Declare the parameters as follows: 
Dim Hconn          As Long   'Connection handle'
Dim Hobj           As Long   'Object handle'
Dim SelectorCount  As Long   'Count of selectors'
Dim Selectors      As Long   'Array of attribute selectors'
Dim IntAttrCount   As Long   'Count of integer attributes'
Dim IntAttrs       As Long   'Array of integer attributes'
Dim CharAttrLength As Long   'Length of character attributes buffer'
Dim CharAttrs      As String 'Character attributes'
Dim CompCode       As Long   'Completion code'
Dim Reason         As Long   'Reason code qualifying CompCode'
Parent topic: Function calls