MQINQ (Inquire about object attributes) on IBM i

The MQINQ call returns an array of integers and a set of character strings containing the attributes of an object.

The following types of object are valid:

• Queue
• Namelist
• Process definition
• Queue manager

• Syntax
• Usage notes
• Parameters
• RPG Declaration

Syntax

MQINQ (HCONN, HOBJ, SELCNT, SELS, IACNT, INTATR, CALEN, CHRATR, CMPCOD, REASON)

Usage notes

1. The values returned are a snapshot of the selected attributes. There is no guarantee that the attributes are not changed before the application can act upon the returned values.
2. When you open a model queue, a dynamic local queue is created. This is true even if you open the model queue to inquire about its attributes. The attributes of the dynamic queue (with certain exceptions) are the same as those of the model queue at the time the dynamic queue is created. If you then use the MQINQ call on this queue, the queue manager returns the attributes of the dynamic queue, and not those of the model queue. See Table 1 for details of which attributes of the model queue are inherited by the dynamic queue.
3. If the object being inquired is an alias queue, the attribute values returned by the MQINQ call are those of the alias queue, and not those of the base queue to which the alias resolves.
4. If the object being inquired is a cluster queue, the attributes that can be inquired depend on how the queue is opened:
   • If the cluster queue is opened for inquire plus one or more of input, browse, or set, there must be a local instance of the cluster queue in order for the open to succeed. In this case the attributes that can be inquired are those valid for local queues.
   • If the cluster queue is opened for inquire alone, or inquire and output, only the following attributes can be inquired; the QType attribute has the value QTCLUS in this case:
     • CAQD
     • CAQN
     • IADBND
     • IADPER
     • IADPRI
     • IAIPUT
     • IAQTYP

     If the cluster queue is opened with no fixed binding (that is, OOBNDN specified on the MQOPEN call, or OOBNDQ specified when the DefBind attribute has the value BNDNOT), successive MQINQ calls for the queue might inquire different instances of the cluster queue, although typically all of the instances have the same attribute values.

   For more information about cluster queues, see Configure a queue manager cluster.

5. If a number of attributes are to be inquired, and then some of them are to be set using the MQSET call, it might be convenient to position at the beginning of the selector arrays the attributes that are to be set, so that the same arrays (with reduced counts) can be used for MQSET.
6. If more than one of the warning situations arise (see the CMPCOD parameter), the reason code returned is the first one in the following list that applies:
   1. RC2068
   2. RC2022
   3. RC2008

7. For more information about object attributes, see:
   • Attributes for queues
   • Attributes for namelists
   • Attributes for process definitions on IBM i
   • Attributes for the queue manager on IBM i

8. A new local queue SYSTEM.ADMIN.COMMAND.EVENT is used for queuing messages that are generated whenever commands are issued. Messages are put onto this queue for most commands, depending on how the CMDEV queue manager attribute is set:
   • ENABLED - command event messages are generated and put onto the queue for all successful commands.
   • NODISPLAY - command event messages are generated and put onto the queue for all successful commands other than the DISPLAY (MQSC) command, and the Inquire (PCF) command.
   • DISABLED - command event messages are not generated (this is the queue manager's initial default value).

Parameters

The MQINQ call has the following parameters:

HCONN (10 digit signed integer) - input

Connection handle.

This handle represents the connection to the queue manager. The value of HCONN was returned by a previous MQCONN or MQCONNX call.

HOBJ (10 digit signed integer) - input

Object handle.

This handle represents the object (of any type) with attributes that are required. The handle must have been returned by a previous MQOPEN call that specified the OOINQ option.

SELCNT (10 digit signed integer) - input

Count of selectors.

This is the count of selectors that are supplied in the SELS array. It is the number of attributes that are to be returned. Zero is a valid value. The maximum number allowed is 256.

SELS (10 digit signed integer x SELCNT) - input

Array of attribute selectors.

This is an array of SELCNT attribute selectors; each selector identifies an attribute (integer or character) with a value that is required.

Each selector must be valid for the type of object that HOBJ represents, otherwise the call fails with completion code CCFAIL and reason code RC2067.

In the special case of queues:

• If the selector is not valid for queues of any type, the call fails with completion code CCFAIL and reason code RC2067.
• If the selector is applicable only to queues of type or types other than that of the object, the call succeeds with completion code CCWARN and reason code RC2068.
• If the queue being inquired is a cluster queue, the selectors that are valid depend on how the queue was resolved; see usage note 4 for further details.

Selectors can be specified in any order. Attribute values that correspond to integer attribute selectors (IA* selectors) are returned in INTATR in the same order in which these selectors occur in SELS. Attribute values that correspond to character attribute selectors (CA* selectors) are returned in CHRATR in the same order in which those selectors occur. IA* selectors can be interleaved with the CA* selectors; only the relative order within each type is important. Note:

1. The integer and character attribute selectors are allocated within two different ranges; the IA* selectors reside within the range IAFRST through IALAST, and the CA* selectors within the range CAFRST through CALAST.

   For each range, the constants IALSTU and CALSTU define the highest value that the queue manager accepts.

2. If all the IA* selectors occur first, the same element numbers can be used to address corresponding elements in the SELS and INTATR arrays.

The attributes that can be inquired are listed in the following tables. For the CA* selectors, the constant that defines the length in bytes of the resulting string in CHRATR is given in parentheses.

Selector	Description	Note
CAALTD	Date of most recent alteration (LNDATE).	1
CAALTT	Time of most recent alteration (LNTIME).	1
CABRQN	Excessive backout-requeue name (LNQN).	5
CABASQ	Name of queue that alias resolves to (LNQN).
CACFSN	Coupling-facility structure name (LNCFSN).	3
CACLN	Cluster name (LNCLUN).	1
CACLNL	Cluster namelist (LNNLN).	1
CACRTD	Queue creation date (LNCRTD).
CACRTT	Queue creation time (LNCRTT).
CAINIQ	Initiation queue name (LNQN).
CAPRON	Name of process definition (LNPRON).
CAQD	Queue description (LNQD).
CAQN	Queue name (LNQN).
CARQMN	Name of remote queue manager (LNQMN).
CARQN	Name of remote queue as known on remote queue manager (LNQN).
CATRGD	Trigger data (LNTRGD).	5
CAXQN	Transmission queue name (LNQN).
IABTHR	Backout threshold.	5
IACDEP	Number of messages on queue.
IADBND	Default binding.	1
IADINP	Default open-for-input option.	5
IADPER	Default message persistence.
IADPRI	Default message priority.	5
IADEFT	Queue definition type.
IADIST	Distribution list support.	2
IAHGB	Whether to harden backout count.	5
IAIGET	Whether get operations are allowed.
IAIPUT	Whether put operations are allowed.
IAMLEN	Maximum message length.
IAMDEP	Maximum number of messages allowed on queue.
IAMDS	Whether message priority is relevant.	5
IAOIC	Number of MQOPEN calls that have the queue open for input.
IAOOC	Number of MQOPEN calls that have the queue open for output.
IAQDHE	Control attribute for queue depth high events.	4, 5
IAQDHL	High limit for queue depth.	4, 5
IAQDLE	Control attribute for queue depth low events.	4, 5
IAQDLL	Low limit for queue depth.	4, 5
IAQDME	Control attribute for queue depth max events.	4, 5
IAQSI	Limit for queue service interval.	4, 5
IAQSIE	Control attribute for queue service interval events.	4, 5
IAQTYP	Queue type.
IAQSGD	Queue sharing group disposition.	3
IARINT	Queue retention interval.	5
IASCOP	Queue definition scope.	4, 5
IASHAR	Whether queue can be shared for input.
IATRGC	Trigger control.
IATRGD	Trigger depth.	5
IATRGP	Threshold message priority for triggers.	5
IATRGT	Trigger type.
IAUSAG	Usage.
CLWLUSEQ	Use remote queues.

Note:

1. Supported on the following platforms:
   • AIX
   • IBM i
   • Windows
   • z/OS

   and for IBM MQ MQI clients connected to these systems.

2. Supported on the following platforms:
   • AIX
   • IBM i
   • Windows

   and for IBM MQ clients connected to these systems.

3. Supported on z/OS.
4. Not supported on z/OS.
5. Not supported on VSE/ESA.

Selector	Description	Note
CAALTD	Date of most recent alteration (LNDATE)	1
CAALTT	Time of most recent alteration (LNTIME)	1
CALSTD	Namelist description (LNNLD)	1
CALSTN	Name of namelist object (LNNLN)	1
CANAMS	Names in the namelist (LNQN x Number of names in the list)	1
IANAMC	Number of names in the namelist	1
IAQSGD	Queue sharing group disposition	3

Selector	Description	Note
CAALTD	Date of most recent alteration (LNDATE)	1
CAALTT	Time of most recent alteration (LNTIME)	1
CAAPPI	Application identifier (LNPROA)	5
CAENVD	Environment data (LNPROE)	5
CAPROD	Description of process definition (LNPROD)	5
CAPRON	Name of process definition (LNPRON)	5
CAUSRD	User data (LNPROU)	5
IAAPPT	Application type	5
IAQSGD	Queue sharing group disposition	3

Selector	Description	Note
CAALTD	Date of most recent alteration (LNDATE)	1
CAALTT	Time of most recent alteration (LNTIME)	1
CACADX	Automatic channel definition exit name (LNEXN)	1
CACLWD	Data passed to cluster workload exit (LNEXDA)	1
CACLWX	Name of cluster workload exit (LNEXN)	1
CACMDQ	System command input queue name (LNQN)	5
CADLQ	Name of dead-letter queue (LNQN)	5
CADXQN	Default transmission queue name (LNQN)	5
CAQMD	Queue manager description (LNQMD)	5
CAQMID	Queue manager identifier (LNQMID)	1
CAQMN	Name of local queue manager (LNQMN)	5
CAQSGN	Queue sharing group name (LNQSGN)	3
CARPN	Name of cluster for which queue manager provides repository services (LNQMN)	1
CARPNL	Name of namelist object containing names of clusters for which queue manager provides repository services (LNNLN)	1
CMDEV	Control attribute that determines whether messages generated when commands are issued, are put onto a queue	8
IAAUTE	Control attribute for authority events	4, 5
IACAD	Control attribute for automatic channel definition	2
IACADE	Control attribute for automatic channel definition events	2
IACLXQ	Default cluster transmission queue type	4
IACLWL	Cluster workload length	1
IACCSI	Coded character set identifier	5
IACMDL	Command level supported by queue manager	5
IACFGE	Control attribute for configuration events	3
IADIST	Distribution list support	2
IAINHE	Control attribute for inhibit events	4, 5
IALCLE	Control attribute for local events	4, 5
IAMHND	Maximum number of handles	5
IAMLEN	Maximum message length	5
IAMPRI	Maximum priority	5
IAMUNC	Maximum number of uncommitted messages within a unit of work	5
IAPFME	Control attribute for performance events	4, 5
IAPLAT	Platform on which the queue manager resides	5
IARMTE	Control attribute for remote events	4, 5
IASSE	Control attribute for start stop events	4, 5
IASYNC	Sync point availability	5
IATRLFT	Lifetime of unused non-administrative topics
IATRGI	Trigger interval	5

IACNT (10 digit signed integer) - input

Count of integer attributes.

This is the number of elements in the INTATR array. Zero is a valid value.

If this is at least the number of IA* selectors in the SELS parameter, all integer attributes requested are returned.

INTATR (10 digit signed integer x IACNT) - output

Array of integer attributes.

This is an array of IACNT integer attribute values.

Integer attribute values are returned in the same order as the IA* selectors in the SELS parameter. If the array contains more elements than the number of IA* selectors, the excess elements are unchanged.

If HOBJ represents a queue, but an attribute selector is not applicable to that type of queue, the specific value IAVNA is returned for the corresponding element in the INTATR array.

CALEN (10 digit signed integer) - input

Length of character attributes buffer.

This is the length in bytes of the CHRATR parameter.

This must be at least the sum of the lengths of the requested character attributes (see SELS). Zero is a valid value.

CHRATR (1 byte character string x CALEN) - output

Character attributes.

This is the buffer in which the character attributes are returned, concatenated together. The length of the buffer is given by the CALEN parameter.

Character attributes are returned in the same order as the CA* selectors in the SELS parameter. The length of each attribute string is fixed for each attribute (see SELS), and the value in it is padded to the right with blanks if necessary. If the buffer is larger than that needed to contain all of 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 entirely of asterisks (*) is returned as the value of that attribute in CHRATR.

CMPCOD (10 digit signed integer) - output

Completion code.

It is one of the following:

CCOK

Successful completion.

CCWARN

Warning (partial completion).

CCFAIL

Call failed.

REASON (10 digit signed integer) - output

Reason code qualifying CMPCOD.

If CMPCOD is CCOK:

RCNONE

(0, X'000') No reason to report.

If CMPCOD is CCWARN:

RC2008

(2008, X'7D8') Not enough space allowed for character attributes.

RC2022

(2022, X'7E6') Not enough space allowed for integer attributes.

RC2068

(2068, X'814') Selector not applicable to queue type.

If CMPCOD is CCFAIL:

RC2219

(2219, X'8AB') MQI call reentered before previous call complete.

RC2006

(2006, X'7D6') Length of character attributes not valid.

RC2007

(2007, X'7D7') Character attributes string not valid.

RC2009

(2009, X'7D9') Connection to queue manager lost.

RC2018

(2018, X'7E2') Connection handle not valid.

RC2019

(2019, X'7E3') Object handle not valid.

RC2021

(2021, X'7E5') Count of integer attributes not valid.

RC2023

(2023, X'7E7') Integer attributes array not valid.

RC2038

(2038, X'7F6') Queue not open for inquire.

RC2041

(2041, X'7F9') Object definition changed since opened.

RC2101

(2101, X'835') Object damaged.

RC2052

(2052, X'804') Queue has been deleted.

RC2058

(2058, X'80A') Queue manager name not valid or not known.

RC2059

(2059, X'80B') Queue manager not available for connection.

RC2162

(2162, X'872') Queue manager shutting down.

RC2102

(2102, X'836') Insufficient system resources available.

RC2065

(2065, X'811') Count of selectors not valid.

RC2067

(2067, X'813') Attribute selector not valid.

RC2066

(2066, X'812') Count of selectors too large.

RC2071

(2071, X'817') Insufficient storage available.

RC2195

(2195, X'893') Unexpected error occurred.

RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQINQ(HCONN : HOBJ : SELCNT :
     C                                     SELS(1) : IACNT : INTATR(1) :
     C                                     CALEN : CHRATR : CMPCOD :
     C                                     REASON)

The prototype definition for the call is:

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     DMQINQ            PR                  EXTPROC('MQINQ')
     D* Connection handle
     D HCONN                         10I 0 VALUE
     D* Object handle
     D HOBJ                          10I 0 VALUE
     D* Count of selectors
     D SELCNT                        10I 0 VALUE
     D* Array of attribute selectors
     D SELS                          10I 0
     D* Count of integer attributes
     D IACNT                         10I 0 VALUE
     D* Array of integer attributes
     D INTATR                        10I 0
     D* Length of character attributes buffer
     D CALEN                         10I 0 VALUE
     D* Character attributes
     D CHRATR                          *   VALUE
     D* Completion code
     D CMPCOD                        10I 0
     D* Reason code qualifying CMPCOD
     D REASON                        10I 0

Parent topic: Function calls on IBM i