gtpc2m50 | C/C++ Language Support User's Guide |
This function returns an array of integers and a set of character strings
containing the attributes of a queue or queue manager.
Format
#include <cmqc.h>
void MQINQ(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 or queue manager for which
the attributes are required. The value of Hobj was returned
by a previous MQOPEN function call with the MQOO_INQUIRE option
specified.
- SelectorCount
- The number of attributes that are to be returned. 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 required.
You can specify the selectors in any order. Attribute values that
correspond to integer attribute selectors (MQIA selectors) are returned in
pIntAttrs in the same order that they are specified in
pSelectors. Attribute values that correspond to character
attribute selectors (MQCA selectors) are returned in pCharAttrs in
the same order that they are specified in pSelectors.
Integer and character selectors can be interleaved; only the relative
order in each type is important.
If all of the integer selectors occur first, you can use the same element
numbers to address corresponding elements in the pSelectors and
pIntAttrs arrays.
If the SelectorCount parameter is zero, pSelectors is
not used; for this condition, the parameter address passed by programs
can be NULL.
The following are selectors for the queue manager:
- MQCA_DEAD_LETTER_Q_NAME
- The name of the dead-letter queue. MQ_Q_NAME_LENGTH defines the
length (in bytes) of the resulting string in pCharAttrs.
- MQCA_Q_MGR_NAME
- The name of the local queue manager. MQ_Q_MGR_NAME_LENGTH defines
the length (in bytes) of the resulting string in pCharAttrs.
- MQIA_CODED_CHAR_SET_ID
- The coded character set identifier.
- MQIA_MAX_MSG_LENGTH
- The maximum message length (in bytes).
- MQIA_PLATFORM
- The platform on which the queue manager resides. This is always set
to MQPL_TPF.
The following are selectors for all types of queues:
- MQIA_Q_TYPE
- The queue type.
- MQIA_INHIBIT_PUT
- Indicates if messages can be added to the queue.
The following are selectors for local queues:
- MQCA_CREATION_DATE
- The date that the queue was created. MQ_CREATION_DATE_LENGTH
defines the length (in bytes) of the resulting string in
pCharAttrs.
- MQCA_CREATION_TIME
- The time that the queue was created. MQ_CREATION_TIME_LENGTH
defines the length (in bytes) of the resulting string in
pCharAttrs.
- MQIA_CURRENT_Q_DEPTH
- The number of messages on a queue.
- MQIA_INHIBIT_GET
- Indicates if messages can be retrieved from the queue.
- MQIA_MAX_MSG_LENGTH
- The maximum message length.
- MQIA_MAX_Q_DEPTH
- The maximum number of messages allowed on a queue.
- MQIA_Q_DEPTH_HIGH_LIMIT
- The maximum number of messages allowed on the queue before a warning is
sent to the console.
- MQIA_SHAREABILITY
- Indicates whether the queue can be opened by more than one application at
a time. This is always set to MQQA_SHAREABLE for the TPF system.
- 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).
- MQIA_USAGE
- Specifies whether the queue is a normal or a transmission queue.
The following are selectors for local definitions of remote queues:
- MQCA_PROCESS_NAME
- The name of the remote process definition. MQ_PROCESS_NAME_LENGTH
defines the length (in bytes) of the resulting string in
pCharAttrs.
- MQCA_REMOTE_Q_MGR_NAME
- The name of the remote queue manager. MQ_Q_MGR_NAME_LENGTH defines
the length (in bytes) of the resulting string in pCharAttrs.
- MQCA_REMOTE_Q_NAME
- The name of the remote queue. MQ_Q_NAME_LENGTH defines the length
(in bytes) of the resulting string in pCharAttrs.
- 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.
- MQCA_XMIT_Q_NAME
- The transmission queue name. MQ_Q_NAME_LENGTH defines the length
(in bytes) of the resulting string in pCharAttrs.
The following are selectors for alias queues:
- MQCA_BASE_Q_NAME
- The name of the queue to which the alias refers.
MQ_Q_MGR_NAME_LENGTH defines the length (in bytes) of the resulting string in
pCharAttrs.
- MQIA_INHIBIT_GET
- Indicates if messages can be retrieved from the queue.
- IntAttrCount
- The number of integer attributes. If there are no integer
attributes, specify zero.
- pIntAttrs
- A pointer to an array of IntAttrCount integer attribute
values. Integer attribute values are returned in the same order as the
integer 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 Hobj represents a queue, but an attribute selector is not
applicable to that type of queue, the value MQIAV_NOT_APPLICABLE is returned
for the corresponding element in the pIntAttrs array.
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_WARNING
- Partially 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_WARNING or 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_WARNING, the function completed partially
with one of the following reason codes:
- MQRC_CHAR_ATTRS_TOO_SHORT
- There is not enough space for the character attributes.
- MQRC_INT_ATTR_COUNT_TOO_SMALL
- There is not enough space for the integer attributes.
- MQRC_SELECTOR_NOT_FOR_TYPE
- The selector type is not applicable to the queue type.
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 attributes string is not valid.
- MQRC_CONNECTION_BROKEN
- The connection to the queue manager is lost.
- MQRC_HCONN_ERROR
- The connection handle is not valid.
- MQRC_HOBJ_ERROR
- The object handle 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_INQUIRE
- The queue is not open for the inquiry.
- MQRC_OBJECT_DAMAGED
- The object is damaged.
- MQRC_Q_DELETED
- The queue has been deleted.
- MQRC_Q_MGR_NAME_ERROR
- The queue manager name is not valid.
- MQRC_Q_MGR_NOT_ACTIVE
- The queue manager is not active.
- MQRC_Q_MGR_NOT_AVAILABLE
- The queue manager is not available for connection.
- 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.
Programming Considerations
- If the Hconn parameter is not for a local TPF MQSeries queue
manager, the MQINQ function call will be sent by TPF MQSeries
client 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.
- The values returned are a snapshot of the selected attributes.
There is no guarantee that the attributes will not change before the
application can use the returned values.
- If the MQINQ function call is directed to an alias queue, the
attributes returned are for those of the alias queue, not those of the base
queue to which the alias queue refers.
- If a number of attributes are to be requested, and subsequently some of
them are to be set using the MQSET function call, it may be
convenient to position the attributes that are to be set at the beginning of
the selector arrays so that the same arrays (with reduced counts) can be used
for the MQSET function.
- If more than one of the warning conditions occur, the reason code returned
is the first one in the following list that applies:
MQRC_SELECTOR_NOT_FOR_TYPE
MQRC_INT_ATTR_COUNT_TOO_SMALL
MQRC_CHAR_ATTRS_TOO_SHORT
Examples
The following example requests the queue type, the time and date that the
queue was created, and whether messages can be added to the queue.
#include <cmqc.h>
MQLONG Selectors[] = {MQIA_Q_TYPE, MQIA_INHIBIT_PUT,
MQCA_CREATION_DATE, MQCA_CREATION_TIME};
MQLONG IntAttrs[2];
const MQLONG ChrSize = MQ_CREATION_DATE_LENGTH +
MQ_CREATION_TIME_LENGTH;
char ChrAttrs[ChrSize + 1] = {0};
MQINQ(Hconn, Hobj, 4, Selectors, 2, IntAttrs, ChrSize, ChrAttrs,
&CompCode, &Reason);
if (CompCode == MQCC_OK)
{
printf("QType=%d\n", IntAttrs[0]);
printf("InhibitPut=%d\n", IntAttrs[1]);
printf("ChrAttrs=%s\n", ChrAttrs);
}
Related Information