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, and on IBM® i for applications running in compatibility mode, the MQCONN call can be omitted, and the following value specified forHconn
:- MQHC_DEF_HCONN
- Default connection handle.
Important: If you are still using compatibility mode, consider recompiling your application and using static bound calls instead. See Compatibility mode for RPG applications on IBM i - 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 inSelectors
. Attribute values that correspond to character attribute selectors (MQCA_* selectors) must be specified inCharAttrs
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.You 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:- 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.
- If all the MQIA_* selectors occur first, the same element numbers can be used to address corresponding elements in the
Selectors
andIntAttrs
arrays. - 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.Table 1. MQSET attribute selectors for queues 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:- Supported only on AIX®, HP-UX, IBM i, Solaris, Linux®, Windows, plus IBM MQ MQI clients connected to these systems.
- 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.
- 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 theSelectors
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 theSelectors
array.If the
IntAttrCount
orSelectorCount
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 theSelectors
array. Zero is a valid value if there are no MQCA_* selectors inSelectors
. - CharAttrs
- Type: MQCHARxCharAttrLength - 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 inCharAttrs
to the right with blanks to make the attribute value match the defined length of the attribute.If the
CharAttrLength
orSelectorCount
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
.IfCompCode
is MQCC_OK:- MQRC_NONE
- (0, X'000') No reason to report.
IfCompCode
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 Messages and reason codes.
Usage notes
- Using 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.
- 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.
- 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).
- You 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, you can use the MQSET call to set the attributes of the dynamic local queue that is created by the MQOPEN call.
- If the object being set is a cluster queue, there must be a local instance of the cluster queue for the open to succeed.
C invocation
MQSET (Hconn, Hobj, SelectorCount, Selectors, IntAttrCount, IntAttrs,
CharAttrLength, CharAttrs, &CompCode, &Reason);
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.
** 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);
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)
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
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'