SortKeyRequest

Name: SortKeyRequest
Description: Used on a SearchRequest message to specify the criteria that a server should use to sort the results of an LDAP search request.
Assigned object identifier: 1.2.840.113556.1.4.473
Target of control: Server
Control criticality: Critical at client's option
Values: The following ASN.1 (Abstract Syntax Notation One) syntax describes the BER (Basic Encoding Rules) encoding of the control value:
```
ControlValue ::= SEQUENCE OF SEQUENCE {
   attributeType          AttributeDescription,
   orderingRule      [0]  MatchingRuleId OPTIONAL,
   reverseOrder      [1]  BOOLEAN DEFAULT FALSE
}
```
where,
- attributeType - Specifies an attribute name that the server should use to sort the search results.
- orderingRule - An optional field that specifies the name or OID of a matching rule that the server should use when sorting by attributeType.
- reverseOrder - An optional boolean field that determines whether to do the sort in reverse order.
Detailed description: Sorted search results provide sort capabilities for LDAP client applications that have limited or no sort functionality. Sorted search results allow z/OS® LDAP client applications to receive search results sorted based on a list of criteria, where each criterion is a sort key that includes an attribute type and optional matching rule and descending order. The server uses the criteria to sort search results before returning them.
The SortKeyRequest server control is valid when sent on a client's SearchRequest message. Support is provided in the z/OS LDAP client to create the sort list and the control. See the ldap_create_sort_keylist(), ldap_create_sort_control(), and ldap_free_sort_keylist() APIs and the ldapsearch client utility in z/OS IBM Tivoli Directory Server Client Programming for z/OS for more information.

See RFC 2891 and SortKeyResponse for more information about the sorted search controls.
Server behavior: By default, the ibm-slapdSortKeyLimit dynamic configuration attribute in the cn=configuration entry is set to 0 which indicates that sorted searches are not allowed. Therefore, the ibm-slapdSortKeyLimit attribute must be set to a nonzero value to allow sorted searches. The ibm-slapdSortSrchAllowNonAdmin and ibm-slapdSortKeyLimit dynamic configuration attributes in the cn=configuration entry can be used to limit server resources used by sorted searches. The PersistentSearch and SortKeyRequest server controls cannot both be specified on a search request. See cn=configuration for more information about the dynamic configuration attributes in the cn=configuration entry.
The following describes the server handling of the sort keys:
1. A NULL attribute value is always treated as being a larger value than all other valid values when sorting.
2. An entry that matches the search criteria but does not contain a matching sort key attribute is sorted as if it has a single NULL value.
3. If an entry matches the search criteria but the bound user does not have read access to a matching sort key attribute, the attribute is treated as if it has a single NULL value.
4. With the exception of SDBM entries, sorting can even be performed on attribute values in the entry which are not requested in the return data. An example would be where the search request sorts on the sn attribute, but only specifies that the cn and objectclass attributes be returned. Another example is when the search request specifies that only attribute types and not values are to be returned. For SDBM entries returned on a search request, sorting is only performed on attribute values included in the returned data.
5. If a sort is performed on a multi-valued attribute that contains multiple values, the sort is performed on the least value.
6. The ibm-slapdDN attribute is specified in a sort key to sort search results by entry DN.
7. If an orderingRule value is specified in a sort key, the server checks that the value identifies an ordering rule that is valid for the syntax of the attribute specified in the sort key, but the server might not use the rule. Instead, the server always uses the ordering rule associated with the definition of the attribute in the schema. See LDAP directory schema for more information about ordering rules.