Virtual list view control

Edit online

The Virtual list view control explains its use with the server and provides the results.

Description
The Virtual list view control extends the regular LDAP search operation and includes a server-side sorting control. With this control, the server returns a contiguous subset of entries that are taken from an ordered result set that match a criteria of a target entry, rather than returning the complete set of searchResultEntry messages.
Request
OID
2.16.840.1.113730.3.4.9
Syntax
VirtualListViewRequest ::= SEQUENCE { 
     beforeCount   INTEGER (0..maxInt), 
     afterCount    INTEGER (0..maxInt), 
     target      CHOICE { 
              byOffset       [0] SEQUENCE {
                   offset          INTEGER (1 .. maxInt), 
                   contentCount    INTEGER (0 .. maxInt) },
              greaterThanOrEqual [1] AssertionValue }, 
     contextID	OCTET STRING OPTIONAL }
where,
  • beforeCount - Indicates the number of entries before the target entry that the client wants the server to send.
  • afterCount - Indicates the number of entries after the target entry that the client wants the server to send.
  • offset - Used to identify the target entry in the Virtual list view request control by determining the target entry that is offset within the list. The server examines the contentCount and offset given by the client and computes the corresponding offset within the list by using following formula: 
             Si = Sc * (Ci / Cc)
    where,
    • Si is the actual list offset that is used by the server
    • Sc is the server estimate for content count
    • Ci is the client submitted offset
    • Cc is the client submitted content count
  • contentCount - Used to identify the target entry.
  • greaterThanOrEqual - Indicates a matching rule assertion value. If present, its value is used to determine the target entry by comparing with the attribute values specified as the primary sort key.
  • contextID - Contains a value for the most recently received contextID field for the same list view from the Virtual list view response control.
Response
OID
2.16.840.1.113730.3.4.10
Syntax
VirtualListViewResponse ::= SEQUENCE { 
      targetPosition	INTEGER (0 .. maxInt), 
      contentCount	INTEGER (0 .. maxInt), 
      virtualListViewResult ENUMERATED { 
           success (0), 
           operationsError (1), 
           protocolError (2), 
           unwillingToPerform (53), 
           insufficientAccessRights (50), 
           timeLimitExceeded (3), 
           adminLimitExceeded (11), 
           innapropriateMatching (18), 
           sortControlMissing (60), 
           offsetRangeError (61), 
           other(80), 
           ... }, 
      contextID	OCTET STRING OPTIONAL }
where,
  • targetPosition - Indicates the offset list for the target entry.
  • contentCount - Indicates the number of entries in the list that is based on the server estimate. The value of the count depends on the access rights over all the entries for the user who is bound to the directory server.
  • contextID - Server defined octet string.
  • virtualListViewResult - Contains error messages that are related to the Virtual list view operation. For example, insufficientAccessRights indicates that the server denies the client the permission to run the Virtual list view operation.
Behavior

The Virtual list view control extends the regular LDAP Search operation and includes a server-side sorting control. In this operation, the server returns a contiguous subset of entries that are taken from an ordered result set that match a criteria of a target entry, rather than returning the complete set of searchResultEntry messages.

When you send this control, it must have an accompanying server-side sorting control. If server-side sorting control is not specified, the request is rejected with the LDAP_SORT_CONTROL_MISSING error.

IBM® Verify Directory, version 6.2 or later server versions recognize the Virtual list view request control that is sent along with a search request. The search request is then passed to the RDBM back-end from which the result set is fetched. Then, the cursor is positioned at the required offset in the search result set.

All users are authorized to use this control. This control can be enabled or disabled on a server by using a configuration option.

This control has the following possible return codes:
  • LDAP_SUCCESS
  • LDAP_OPERATIONS_ERROR
  • LDAP_PROTOCOL_ERROR
  • LDAP_UNWILLING_TO_PERFORM
  • LDAP_INSUFFICIENT_ACCESS
  • LDAP_TIMELIMIT_EXCEEDED
  • LDAP_ADMINLIMIT_EXCEEDED
  • LDAP_INAPPROPRIATE_MATCHING
  • LDAP_SORT_CONTROL_MISSING
  • LDAP_INDEX_RANGE_ERROR
  • LDAP_OTHER
The Administrator Server does not support this control.
Scope
This control lasts only for one search operation.