The LDAP_SERVER_GET_STATS_OID control is used with an LDAP Search operation. The client must have the SE_DEBUG_PRIVILEGE in order to specify this control.

When sending this control to a DC running Windows 2000, the client omits the controlValue field. When sending this control to a DC running Windows Server 2003 or later, the client either omits the controlValue field or sets the controlValue field to one of the 32-bit unsigned integer values in the following table. The values are not BER-encoded.

Omitting the controlValue field is equivalent to specifying the SO_STATS value.

When the server receives a search request with the LDAP_SERVER_GET_STATS_OID control attached to it, it includes a response control in the search response. The controlType field of the returned Control structure is set to the OID of the LDAP_SERVER_GET_STATS_OID control. The controlValue field is included in the returned Control structure.

The response to this control contains information outside the state model. This control instructs the server to return internal data related to how the LDAP search was performed.

For Windows 2000 DCs, the returned controlValue is the BER encoding of the following ASN.1 structure:

SEQUENCE {
    threadCountTag            INTEGER
    threadCount               INTEGER
    coreTimeTag               INTEGER
    coreTime                  INTEGER
    callTimeTag               INTEGER
    callTime                  INTEGER
    searchSubOperationsTag    INTEGER
    searchSubOperations       INTEGER
}

where threadCountTag, coreTimeTag, callTimeTag, and searchSubOperationsTag are equal to 1, 2, 3, and 4, respectively. threadCount is the number of threads that were processing LDAP requests on the DC at the time the search operation was performed, coreTime is the time in milliseconds that the core logic in the DC spent processing the request, callTime is the overall time in milliseconds that the DC spent processing the request, and searchSubOperations is the number of individual operations that the DC performed in processing the request.

For Windows Server 2003 DCs, the controlValue of the response control is the BER encoding of the following ASN.1 structure.

SEQUENCE {
    threadCountTag        INTEGER
    threadCount           INTEGER
    callTimeTag           INTEGER
    callTime              INTEGER
    entriesReturnedTag    INTEGER
    entriesReturned       INTEGER
    entriesVisitedTag     INTEGER
    entriesVisited        INTEGER
    filterTag             INTEGER
    filter                OCTET STRING
    indexTag              INTEGER
    index                 OCTET STRING
}

In this structure, threadCountTag, threadCount, callTimeTag, and callTime are as in the Windows 2000 structure. entriesReturnedTag, entriesVisitedTag, filterTag, and indexTag are 5, 6, 7, and 8, respectively. entriesReturned is the number of objects returned in the search result. entriesVisited is the number of objects that the DC considered for inclusion in the search result. filter is a UTF-8 string that represents the optimized form of the search filter that is used by the DC to perform a search. index is a ANSI string that indicates which database indexes were used by the DC to perform the search.

For Windows Server 2008 DCs, the controlValue of the response control is the BER encoding of the following ASN.1 structure if the SO_EXTENDED_FMT flag is not specified.

SEQUENCE {
    threadCountTag        INTEGER
    threadCount           INTEGER
    callTimeTag           INTEGER
    callTime              INTEGER
    entriesReturnedTag    INTEGER
    entriesReturned       INTEGER
    entriesVisitedTag     INTEGER
    entriesVisited        INTEGER
    filterTag             INTEGER
    filter                OCTET STRING
    indexTag              INTEGER
    index                 OCTET STRING
    pagesReferencedTag    INTEGER
    pagesReferenced       INTEGER
    pagesReadTag          INTEGER
    pagesRead             INTEGER
    pagesPrereadTag       INTEGER
    pagesPreread          INTEGER
    pagesDirtiedTag       INTEGER
    pagesDirtied          INTEGER
    pagesRedirtiedTag     INTEGER
    pagesRedirtied        INTEGER
    logRecordCountTag     INTEGER
    logRecordCount        INTEGER
    logRecordBytesTag     INTEGER
    logRecordBytes        INTEGER
}

In this structure, fields with the same name as fields in the Windows Server 2003 structure are as in the Windows Server 2003 structure. pagesReferencedTag, pagesReadTag, pagesPrereadTag, pagesDirtiedTag, pagesRedirtiedTag, logRecordCountTag, and logRecordCountBytesTag are 9, 10, 11, 12, 13, 14, and 15, respectively. pagesReferenced is the number of database pages referenced by the DC in processing the search. pagesRead is the number of database pages read from disk, and pagesPreread is the number of database pages preread from disk by the DC in processing the search. pagesDirtied is the number of clean database pages modified by the DC in processing the search, while pagesRedirtied is the number of previously modified database pages that were modified by the DC in processing the search. logRecordCount and logRecordBytes are the number and size in bytes, respectively, of database log records generated by the DC in processing the search.

For Windows Server 2008 DCs, if the SO_EXTENDED_FMT flag is specified, an alternative format is used for the controlValue of the response control instead of the format shown previously. Unlike the previous formats in which each statistic is assigned a fixed position within the structure, in the alternative format the ordering of the statistics can change. Rather than relying on position, each statistic has an associated human-readable string that specifies what that statistic is. Additionally, the use of these associated strings alleviates the need to hard-code the positional information into the client-side parser of the response control, permitting the DC to be updated to return addition statistics without necessitating a corresponding client-side change.

When using the alternative format, the controlValue of the response control is the BER encoding of the following ASN.1 structure.

SEQUENCE OF SEQUENCE  {
    statisticName         OCTET STRING
    CHOICE {
        [0] intStatistic       INTEGER
        [1] stringStatistic    OCTET STRING
    }
}

Effectively, this is an array of statistics, in which each statistic has a human-readable name (the statisticName field) and a value. If it is an integer-valued statistic, the value is stored in the intStatistic field. If it is a string-valued statistic, the value is stored in the stringStatistic field.

When the SO_EXTENDED_FMT flag is specified, Windows Server 2008 DCs return the same statistics as if the flag was not specified. The only difference is the format used to return the statistics. The wording of the statisticName field is implementation-defined. Currently, the wording as it maps to each statistic as specified in the non-SO_EXTENDED_FMT version of the structure is as follows.

threadCount           "Thread count"
callTime              "Call time (in ms)"
entriesReturned       "Entries Returned"
entriesVisited        "Entries Visited"
filter                "Used Filter"
index                 "Used Indexes"
pagesReferenced       "Pages Referenced"
pagesRead             "Pages Read From Disk"
pagesPreread          "Pages Pre-read From Disk"
pagesDirtied          "Clean Pages Modified"
pagesRedirtied        "Dirty Pages Modified"
logRecordCount        "Log Records Generated"
logRecordBytes        "Log Record Bytes Generated"