Name

ds_search - Finds entries of interest in a part of the DIT

Synopsis

#include <xom.h>
#include <xds.h> DS_status ds_search(
OM_private_object session,
OM_private_object context,
OM_object name,
OM_sint subset,
OM_object filter,
OM_boolean search_aliases,
OM_object selection,
OM_private_object ∗result_return,
OM_sint ∗invoke_id_return);

Parameters

Input

session(Object(DS_C_SESSION)).  The directory session against which this operation is performed.  This must be a private object. 

context(Object(DS_C_CONTEXT)).  The directory context to be used for this operation.  This parameter must be a private object or the DS_DEFAULT_CONTEXT constant. 

name(Object(DS_C_NAME)).  The name of the object entry that forms the base of ds_search().  Any aliases in the name are dereferenced, unless dereferencing is prohibited by the DS_­DONT_­DEREFERENCE_­ALIASES service control attribute of the DS_­C_­CONTEXT object. 

subset(Integer).  Specifies the portion of the DIT to be searched.  Its value must be one of the following:

       •DS_BASE_OBJECT
Searches just the given object entry.

       •DS_ONE_LEVEL
Searches just the immediate subordinates of the given object entry.

       •DS_WHOLE_SUBTREE
Searches the given object and all its subordinates.

filter(Object(DS_C_FILTER)).  The filter is used to eliminate entries from the search that are not wanted.  Information is only returned on entries that satisfy the filter.  The DS_NO_FILTER constant can be used as the value of this parameter if all entries are searched and none eliminated.  This corresponds to a filter with a DS_FILTER_TYPE value of DS_AND and no values of the DS_FILTER or DS_FILTER_ITEM OM attributes. 

search_aliases
(Boolean).  Any aliases in the subordinate entries being searched are dereferenced if the value of this parameter is OM_TRUE, and they are not dereferenced if its value is OM_FALSE. 

selection(Object(DS_C_ENTRY_INFO_SELECTION)).  Specifies what information from the entry is requested.  Information about no attributes, all attributes, or just for a named set can be chosen.  Attribute types are always returned, but the attribute values need not be.  The possible values of this parameter are listed in the OSF DCE Application Development Guide—Directory Services. 

Output

result_return(Object(DS_C_SEARCH_RESULT)).  If completion is successful, the result contains the requested information from each object in the search space that satisfied the filter.  The DN of the target object is present if an alias is dereferenced.  In addition, there may be a partial outcome qualifier, which indicates that the result is incomplete.  It also explains why it is not complete and how it could be completed. 

invoke_id_return
(Integer).  Not supported.

Description

The ds_search() function is used to search a portion of the directory and return selected information from entries of interest.  The information may be incomplete in some circumstances; for example, if the results exceed DS_SIZE_LIMIT. 

Notes

CDS does not support ds_search(), and it returns with DS_­C_­SERVICE_­ERROR (DS_­E_­UNWILLING_­TO_­PERFORM). 

Return Values

DS_statusTakes the value DS_SUCCESS if the named object is located and takes an error value if not. 

Errors

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

This function can return a DS_C_SYSTEM_ERROR or one of the following DS_C_LIBRARY_ERROR errors:

       •DS_E_BAD_ARGUMENT

       •DS_E_BAD_CONTEXT

       •DS_E_BAD_NAME

       •DS_E_BAD_SESSION

       •DS_E_MISCELLANEOUS

       •DS_E_MISSING_TYPE

       •DS_E_TOO_MANY_OPERATIONS

The following directory errors can be returned by the function:

       •DS_C_ATTRIBUTE_ERROR

       •DS_C_NAME_ERROR

       •DS_C_REFERRAL

       •DS_C_SECURITY_ERROR

       •DS_C_SERVICE_ERROR

Note that an unfiltered search of just the base object succeeds even if none of the requested attributes are found, while the ds_read() call fails with the same selected attributes. 

A DS_C_SECURITY_ERROR (DS_E_INSUFFICIENT_ACCESS_RIGHTS) is only reported where access rights preclude the reading of all requested attribute values. 

This function can return a DS_C_COMMUNICATIONS_ERROR, as well as the error constant DS_NO_WORKSPACE.