MQZ_INQUIRE (Inquire authorization service) on IBM i

This function is provided by a MQZAS_VERSION_5 authorization service component, and is invoked by the queue manager to query the supported functionality. Where multiple service components are used, service components are called in reverse order to the order they were installed in.

The function identifier for this function (for MQZEP) is MQZID_INQUIRE.

Syntax

MQZ_INQUIRE: (QMgrName, SelectorCount, Selectors, IntAttrCount, IntAttrs, CharAttrLength, CharAttrs, SelectorReturned, ComponentData, Continuation, CompCode, Reason)

Parameters

The MQZ_INQUIRE call has the following parameters.

QMgrName (MQCHAR48) - input

Queue manager name.

The name of the queue manager calling the component. This name is padded with blanks to the full length of the parameter; the name is not terminated by a null character.

The queue manager name is passed to the component for information; the authorization service interface does not require the component to make use of it in any defined manner.

SelectorCount (MQLONG) - input

Number of selectors.

The number of selectors supplied in the Selectors parameter.

The value must be between zero and 256.

Selectors (MQLONG x SelectorCount) - input

Selectors.

Array of selectors. Each selector identifies a required attribute and must be of one of the following types:

MQIACF_* (integer)
MQCACF_* (character)

Selectors can be specified in any order. The number of selectors in the array is indicated by the SelectorCount parameter.

Integer attributes identified by selectors are returned in the IntAttrs parameter in the same order as they appear in Selectors.

Character attributes identified by selectors are returned in the CharAttrs parameter in the same order as they in appear Selectors.

IntAttrCount (MQLONG) - input

Number of integer attributes.

The number of integer attributes supplied in the IntAttrs parameter.

The value must be in the range 0 through 256.

IntAttrs (MQLONG x IntAttrCount) - output

Integer attributes.

Array of integer attributes. The integer attributes are returned in the same order as the corresponding integer selectors in the Selectors array.

CharAttrCount (MQLONG) - input

Length of the character attributes buffer.

The length in bytes of the CharAttrs parameter.

The value must at least sum of the lengths of the requested character attributes. If no character attributes are requested, zero is a valid value.

CharAttrs (MQLONG x CharAttrCount) - output

Character attributes buffer.

Buffer containing character attributes, concatenated together. The character attributes are returned in the same order as the corresponding character selectors in the Selectors array.

The length of the buffer is given by the CharAttrCount parameter.

SelectorReturned (MQLONGxSelectorCount) - input

Selector returned.

Array of values identifying which attributes have been returned from the set requested for by the selectors in the Selectors parameter. The number of values in this array is indicated by the SelectorCount parameter. Each value in the array relates to the selector from the corresponding position in the Selectors array. Each value is one of the following:

MQZSL_RETURNED: The attribute requested by the corresponding selector in the Selectors parameter has been returned.
MQZSL_NOT_RETURNED: The attribute requested by the corresponding selector in the Selectors parameter has not been returned.

The array is initialized with all values as MQZSL_NOT_RETURNED. When an authorization service component returns an attribute, it sets the appropriate value in the array to MQZSL_RETURNED. This allows any other authorization service components, to which the inquire call is made, to identify which attributes have already been returned.

ComponentData (MQBYTE x ComponentDataLength) - input/output

Component data.

This data is kept by the queue manager on behalf of this particular component; any changes made to it by any of the functions provided by this component are preserved, and presented the next time one of this component's functions is called.

The length of this data area is passed by the queue manager in the ComponentDataLength parameter of the MQZ_INIT_AUTHORITY call.

Continuation (MQLONG) - output

Continuation flag.

The following values can be specified:

MQZCI_DEFAULT: Continuation dependent on other components.
MQZCI_STOP: Do not continue with next component.

CompCode (MQLONG) - output

Completion code.

It is one of the following:

MQCC_OK: Successful completion.
MQCC_WARNING: Partial completion.
MQCC_FAILED: Call failed.

Reason (MQLONG) - output

Reason code qualifying CompCode.

If CompCode is MQCC_OK:

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

If CompCode is MQCC_WARNING:

MQRC_CHAR_ATTRS_TOO_SHORT: Not enough space for character attributes.
MQRC_INT_COUNT_TOO_SMALL: Not enough space for integer attributes.

If CompCode is MQCC_FAILED:

MQRC_SELECTOR_COUNT_ERROR: Number of selectors is not valid.
MQRC_SELECTOR_ERROR: Attribute selector not valid.
MQRC_SELECTOR_LIMIT_EXCEEDED: Too many selectors specified.
MQRC_INT_ATTR_COUNT_ERROR: Number of integer attributes is not valid.
MQRC_INT_ATTRS_ARRAY_ERROR: Integer attributes array not valid.
MQRC_CHAR_ATTR_LENGTH_ERROR: Number of character attributes is not valid.
MQRC_CHAR_ATTRS_ERROR: Character attributes string is not valid.
MQRC_SERVICE_ERROR: (2289, X'8F1') Unexpected error occurred accessing service.

C invocation

MQZ_INQUIRE (QMgrName, SelectorCount, Selectors, IntAttrCount,
                   &IntAttrs, CharAttrLength, &CharAttrs, 
                   SelectorReturned, ComponentData, &Continuation,
                   &CompCode, &Reason);

The parameters passed to the service are declared as follows:

MQCHAR48   QMgrName;              /* Queue manager name */
MQLONG     SelectorCount;         /* Selector count */
MQLONG     Selectors[n];          /* Selectors */
MQLONG     IntAttrCount;          /* IntAttrs count */
MQLONG     IntAttrs[n];           /* Integer attributes */
MQLONG     CharAttrCount;         /* CharAttrs count */
MQLONG     CharAttrs[n];          /* Chatacter attributes */
MQLONG     SelectorReturned[n];   /* Selector returned */
MQBYTE     ComponentData[n];      /* Component data */
MQLONG     Continuation;          /* Continuation indicator set by
                                      component */
MQLONG     CompCode;              /* Completion code */
MQLONG     Reason;                /* Reason code qualifying CompCode */