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

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


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);
The parameters passed to the service are declared as follows:
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 */
Parent topic: Installable services interface reference information