gtpc2m54 | C/C++ Language Support User's Guide |
This function changes the attributes of an MQSeries queue.
Format
#include <cmqc.h>
void MQSET(MQHCONN Hconn,
MQHOBJ Hobj,
MQLONG SelectorCount,
PMQLONG pSelectors,
MQLONG IntAttrCount,
PMQLONG pIntAttrs,
MQLONG CharAttrLength,
PMQCHAR pCharAttrs,
PMQLONG pCompCode,
PMQLONG pReason);
- Hconn
- The connection handle, which represents the connection to the TPF MQSeries
queue manager. The value of Hconn was returned by a previous
MQCONN call.
- Hobj
- The object handle, which represents the queue whose attributes are to be
set. The value of Hobj was returned by a previous
MQOPEN function call with the MQOO_SET option specified.
- SelectorCount
- The number of attributes that are to be set. Specify a value from 0
to 256.
- pSelectors
- A pointer to an array of SelectorCount attribute
selectors. Each selector identifies an integer or character attribute
whose value is to be set.
You can specify the selectors in any order. Attribute values that
correspond to integer attribute selectors (MQIA selectors) must be specified
in pIntAttrs in the same order that they are specified in
pSelectors.
If you specify the same selector twice, the last value specified for a
given selector is the one that is used.
If the SelectorCount parameter is zero, pSelectors is
not used; for this condition, the parameter address passed by programs
can be NULL.
You can specify the following selectors:
- MQIA_INHIBIT_PUT
- Specifies if messages can be added to the queue. You can specify
this selector for any type of queue.
- MQIA_INHIBIT_GET
- Specifies if messages can be retrieved from the queue. You can
specify this selector only for local or alias queues.
- MQIA_TRIGGER_CONTROL
- Indicates whether to trigger or not. You can specify this selector
only for local normal queues.
- MQIA_TRIGGER_TYPE
- Indicates the type of trigger (FIRST, EVERY, OR NONE). You can
specify this selector only for local normal queues.
- MQCA_TRIGGER_DATA
- The name of the remote process definition. MQ_TRIGGER_DATA_LENGTH
defines the length (in bytes) of the resulting string in
pCharAttrs.
- IntAttrCount
- The number of integer attributes. You must specify at least the
number of integer attribute selectors that are specified in
pSelectors. If there are no integer attributes, specify
zero.
- pIntAttrs
- A pointer to an array of IntAttrCount integer attribute
values. Specify these values in the same order as the integer attribute
selectors (MQIA selectors) in the pSelectors parameter. If
the array contains more elements than the number of integer selectors, the
additional elements are unchanged.
If the IntAttrCount or SelectorCount parameter is
zero, pIntAttrs is not used; for this condition, the parameter
address passed by programs can be NULL.
- CharAttrLength
- The length (in bytes) of the character attributes buffer. Specify a
value that is at least the sum of the lengths of the character attributes
specified in pSelectors. If there are no character
attributes, specify zero.
- pCharAttrs
- A pointer to the buffer in which the character attributes are
returned. The attributes are concatenated and returned in the same
order as the character selectors (MQCA selectors) specified in the
pSelectors parameter. The length of each attribute string is
fixed for each attribute, and the value returned is padded to the right with
blanks if necessary. If the buffer is larger than that needed to
contain all the requested character attributes (including padding), the bytes
beyond the last attribute value returned are unchanged.
If Hobj represents a queue, but an attribute selector is not
applicable to that type of queue, a character string consisting of all
asterisks (*) is returned as the value of that attribute in
pCharAttrs.
If the CharAttrLength or SelectorCount parameter is
zero, pCharAttrs is not used; for this condition, the
parameter address passed by programs can be NULL.
- pCompCode
- A pointer to the location to store the completion code, which is one of
the following:
- MQCC_OK
- Successfully completed.
- MQCC_FAILED
- The call failed.
- pReason
- A pointer to the location to store the reason code that qualifies the
completion code.
If the completion code is MQCC_OK, the reason code is MQRC_NONE, which
indicates a normal return.
If the completion code is MQCC_FAILED, see Error Return for the corresponding reason codes.
See MQSeries Application Programming Reference
and MQSeries Message Queue Interface Technical
Reference for more information about MQSeries data types and
parameters.
Normal Return
- MQCC_OK
- Completion code completed successfully.
- MQRC_NONE
- Reason code completed successfully.
Error Return
If the completion code is MQCC_FAILED, the function failed with one of the
following reason codes:
- MQRC_CHAR_ATTR_LENGTH_ERROR
- The length of the character attributes is not valid.
- MQRC_CHAR_ATTRS_ERROR
- The character attribtues string is not valid.
- MQRC_CONNECTION_BROKEN
- The connection to the queue manager is lost.
- MQRC_CONNECTION_STOPPING
- The connection is shutting down.
- MQRC_HCONN_ERROR
- The connection handle is not valid.
- MQRC_HOBJ_ERROR
- The object handle is not valid.
- MQRC_INHIBIT_VALUE_ERROR
- The value to be set for MQIA_INHIBIT_GET or MQIA_INHIBIT_PUT is not
valid.
- MQRC_INT_ATTR_COUNT_ERROR
- The number of integer attributes is not valid.
- MQRC_INT_ATTRS_ARRAY_ERROR
- The integer attributes array is not valid.
- MQRC_NOT_OPEN_FOR_SET
- The queue is not open for the set request.
- MQRC_Q_DELETED
- The queue has been deleted.
- MQRC_Q_MGR_NAME_ERROR
- The queue manager name is not valid.
- MQRC_Q_MGR_NOT_AVAILABLE
- The queue manager is not available for connection.
- MQRC_Q_MGR_NOT_ACTIVE
- The queue manager is not active.
- MQRC_Q_MGR_STOPPING
- The queue manager is stopping.
- MQRC_SELECTOR_COUNT_ERROR
- The number of selectors is not valid.
- MQRC_SELECTOR_ERROR
- The attribute selector is not valid.
- MQRC_SELECTOR_LIMIT_EXCEEDED
- The number of selectors is too large.
- MQRC_STORAGE_NOT_AVAILABLE
- There is not enough storage available.
- MQRC_TRIGGER_CONTROL_ERROR
- The value of the trigger-control attribute is not valid.
- MQRC_TRIGGER_TYPE_ERROR
- The value of the trigger-type attribute is not valid.
- MQRC_UNEXPECTED_ERROR
- An unexpected error occurred.
Programming Considerations
- If the Hconn parameter is not for a local TPF MQSeries queue
manager, the MQSET function call will be sent by TPF MQSeries
support to the remote queue manager for processing. The options
supported by the remote queue manager can differ from the options specified
for the local TPF MQSeries queue manager.
- When using this function call, the application program can specify an
array of integer attributes. The attributes specified are all set
simultaneously if no errors occur. If an error does occur (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.
- Use the MQINQ function to determine the values of the
attributes.
- Note:
- There are some attributes whose values you can request with the
MQINQ function that cannot be set using the MQSET
function. For example, you cannot set any queue manager
attributes.
- Attribute changes are preserved across restarts of the queue
manager.
Examples
The following example specifies that messages can be added to the
queue.
#include <cmqc.h>
MQLONG SelectorsSet[] = {MQIA_INHIBIT_PUT};
MQLONG IntAttrsSet[] = {MQQA_PUT_ALLOWED};
MQSET(Hconn, Hobj, 1, SelectorsSet, 1, IntAttrsSet, 0, NULL,
&CompCode, &Reason);
Related Information