gtpc2m50C/C++ Language Support User's Guide

MQINQ-Inquire about Object Attributes

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

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