gtpc2m54C/C++ Language Support User's Guide

MQSET-Set Object Attributes

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

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