MQZ_ENUMERATE_AUTHORITY_DATA - Enumerate authority data

This function is provided by an MQZAS_VERSION_4 authorization service component, and is started repeatedly by the queue manager to retrieve all of the authority data that matches the selection criteria specified on the first invocation.

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

Syntax

Parameters

QMgrName

Type: 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 use it in any defined manner.

StartEnumeration

Type: MQLONG - input Flag indicating whether call can start enumeration. This indicates whether the call can start the enumeration of authority data, or continue the enumeration of authority data started by a previous call to MQZ_ENUMERATE_AUTHORITY_DATA. The value is one of the following values:

MQZSE_START

Start enumeration. The call is started with this value to start the enumeration of authority data. The Filter parameter specifies the selection criteria to be used to select the authority data returned by this and successive calls.

MQZSE_CONTINUE

Continue enumeration. The call is started with this value to continue the enumeration of authority data. The Filter parameter is ignored in this case, and can be specified as the null pointer (the selection criteria are determined by the Filter parameter specified by the call that had StartEnumeration set to MQZSE_START).

Filter

Type: MQZAD - input

Filter. If StartEnumeration is MQZSE_START, Filter specifies the selection criteria to be used to select the authority data to return. If Filter is the null pointer, no selection criteria are used, that is, all authority data is returned. See MQZAD - Authority data for details of the selection criteria that can be used.

If StartEnumeration is MQZSE_CONTINUE, Filter is ignored, and can be specified as the null pointer.

AuthorityBufferLength

Type: MQLONG - input

Length of AuthorityBuffer. This is the length in bytes of the AuthorityBuffer parameter. The authority buffer must be large enough to accommodate the data to be returned.

AuthorityBuffer

Type: MQZAD - output

Authority data. This is the buffer in which the authority data is returned. The buffer must be large enough to accommodate an MQZAD structure, an MQZED structure, plus the longest entity name and longest domain name defined.

Note: Note: This parameter is defined as an MQZAD, as the MQZAD always occurs at the start of the buffer. However, if the buffer is declared as an MQZAD, the buffer will be too small - it must be bigger than an MQZAD so that it can accommodate the MQZAD, MQZED, plus entity and domain names.

AuthorityDataLength

Type: MQLONG - output

Length of data returned in AuthorityBuffer. If the authority buffer is too small, AuthorityDataLength is set to the length of the buffer required, and the call returns completion code MQCC_FAILED and reason code MQRC_BUFFER_LENGTH_ERROR.

ComponentData

Type: 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 these component 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

Type: MQLONG - output Continuation indicator set by component. The following values can be specified:

MQZCI_DEFAULT

Continuation dependent on queue manager.

For MQZ_ENUMERATE_AUTHORITY_DATA, this has the same effect as MQZCI_CONTINUE.

MQZCI_CONTINUE

Continue with next component.

MQZCI_STOP

Do not continue with next component.

CompCode

Type: MQLONG - output Completion code. It must be one of the following values:

MQCC_OK

Successful completion.

MQCC_FAILED

Call failed.

Reason

Type: MQLONG - output

Reason code qualifying CompCode.

If CompCode is MQCC_OK:

MQRC_NONE

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

If CompCode is MQCC_FAILED:

MQRC_BUFFER_LENGTH_ERROR

(2005, X'7D5') Buffer length parameter not valid.

MQRC_NO_DATA_AVAILABLE

(2379, X'94B') No data available.

MQRC_SERVICE_ERROR

(2289, X'8F1') Unexpected error occurred accessing service.

For more information about these reason codes, see API reason codes.

C invocation

MQZ_ENUMERATE_AUTHORITY_DATA (QMgrName, StartEnumeration, &Filter,
                             AuthorityBufferLength,
                             &AuthorityBuffer,
                             &AuthorityDataLength, ComponentData,
                             &Continuation, &CompCode,
                             &Reason);

MQCHAR48  QMgrName;               /* Queue manager name */
MQLONG    StartEnumeration;       /* Flag indicating whether call should
                                     start enumeration */
MQZAD     Filter;                 /* Filter */
MQLONG    AuthorityBufferLength;  /* Length of AuthorityBuffer */
MQZAD     AuthorityBuffer;        /* Authority data */
MQLONG    AuthorityDataLength;    /* Length of data returned in
                                     AuthorityBuffer */
MQBYTE    ComponentData[n];       /* Component data */
MQLONG    Continuation;           /* Continuation indicator set by
                                     component */
MQLONG    CompCode;               /* Completion code */
MQLONG    Reason;                 /* Reason code qualifying CompCode */