MQINQ: Inquire about object attributes

This function returns an array of integers and a set of character strings containing the attributes of a process, queue, or queue manager.

Last updated

  • Changed for PUT11.
  • Changed for PUT09.
  • Changed for PUT06.
  • Changed for PUT00.

Format

LIBS := see programming considerations
#include  <tpf/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 z/TPF IBM® MQ queue manager. The value of Hconn was returned by a previous MQCONN call.
Hobj
The object handle, which represents the process, 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 a process:
MQCA_ALTERATION_DATE
Date of most-recent alteration.
MQCA_ALTERATION_TIME
Time of most-recent alteration.
MQCA_APPL_ID
Application identifier.
MQCA_ENV_DATA
Environment data.
MQCA_PROCESS_DESC
Description of process definition.
MQCA_PROCESS_NAME
Name of process definition.
MQCA_USER_DATA
User data.
MQIA_APPL_TYPE
Application type.
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_IDENTIFIER
The system-unique name for the queue manager. MQ_Q_MGR_IDENTIFIER_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_INHIBIT_EVENT
The control attribute for inhibit events.
MQIA_LOCAL_EVENT
The control attribute for local events.
MQIA_MAX_MSG_LENGTH
The maximum message length (in bytes).
MQIA_PERFORMANCE_EVENT
The control attribute for performance events.
MQIA_PLATFORM
The platform on which the queue manager resides. This is always set to MQPL_TPF.
MQIA_REMOTE_EVENT
The control attribute for remote events.
MQIA_SSL_EVENT
The control attribute for Secure Sockets Layer (SSL) events.
MQIA_START_STOP_EVENT
The control attribute for start and stop events.
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_EVENT
The control attribute for queue depth high events.
MQIA_Q_DEPTH_HIGH_LIMIT
The number of messages allowed on the queue before a high queue depth event is generated or a warning is sent to the console.
MQIA_Q_DEPTH_LOW_EVENT
The control attribute for queue depth low events.
MQIA_Q_DEPTH_LOW_LIMIT
The low limit for queue depth.
MQIA_Q_DEPTH_MAX_EVENT
The control attribute for queue depth max events.
MQIA_Q_SERVICE_INTERVAL
The limit for the queue service interval.
MQIA_Q_SERVICE_INTERVAL_EVENT
The control attribute for queue service interval events.
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 z/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.

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

  • The library that is required to use this function is determined by the following situations:
    • If the application will exclusively access a remote queue manager rather than the local z/TPF IBM MQ queue manager, you can include the CMQI library in the makefile and add the -D_TPF_CLIENTONLY option to the CFLAGS_PGMX or CXXFLAGS_PGMY statement to improve the application performance.
    • If the queue manager that the application will access is not known, or if the application is accessing the local z/TPF IBM MQ queue manager, you must include the CMQS library in the makefile and not add the -D_TPF_CLIENTONLY option to the CFLAGS_PGMX or CXXFLAGS_PGMY statement.
  • If the Hconn parameter is not for a local z/TPF IBM MQ queue manager, the MQINQ function call will be sent by z/TPF IBM MQ 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 z/TPF IBM MQ queue manager.
  • The following selectors can only be specified for processor-unique queues (queues that were defined by using the ZMQSC DEFINE QL command with the COMMON - NO parameter specified):
    • MQIA_MAX_Q_DEPTH
    • MQIA_Q_DEPTH_HIGH_LIMIT
    • MQIA_Q_DEPTH_LOW_LIMIT
    • MQIA_Q_DEPTH_MAX_EVENT
    • MQIA_Q_DEPTH_HIGH_EVENT
    • MQIA_Q_DEPTH_LOW_EVENT
    • MQIA_Q_SERVICE_INTERVAL_EVENT
    • MQIA_Q_SERVICE_INTERVAL.
    If one of these selectors is specified for a processor-shared queue, the completion code returned is MQRC_SELECTOR_NOT_FOR_TYPE, and the value returned for the field is -1 (MQIAV_NOT_APPLICABLE).
  • 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 <tpf/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);
}
The following example requests the alteration date, process description, and application type for a process. 
#include <cmqc.h>
MQLONG Selectors[] = {MQCA_ALTERATION_DATE,
                 MQCA_PROCESS_DESC, MQIA_APPL_TYPE};
MQLONG IntAttrs[1];
const MQLONG ChrSize = MQ_DATE_LENGTH + MQ_PROCESS_DESC_LENGTH;
char ChrAttrs[ChrSize + 1] = {0};
MQINQ(Hconn, Hobj, 3, Selectors, 1, IntAttrs, ChrSize, ChrAttrs,
      &CompCode, &Reason);
 
if (CompCode == MQCC_OK)
{
  printf("ApplType=%d\n", IntAttrs[0]);
  printf("ChrAttrs=%s\n", ChrAttrs);
}