ds_search(3xds) — Subroutines
(c) Digital Equipment Corporation. 1994. All rights reserved.
Name
ds_search − Finds entries of interest in a portion of the Directory.
Syntax
Status = ds_search(Session, Context, Name, Subset, Filter, Search_Aliases, Selection, Result, Invoke-ID)
Argument@Data Type@Access
Session@OM_private_object@T{ read T} Context@OM_private_object@T{ read T} Name@OM_object@T{ read T} Subset@Integer@T{ read T} Filter@OM_object@T{ read T} Search_Aliases@OM_boolean@T{ read T} Selection@OM_object@T{ read T} Result@OM_private_object@T{ write T} Status@DS_status@T{ write T} Invoke-ID@T{ Integer T}
C Binding
DS_status ds_search(session, context, name, subset, filter, search_aliases, selection, result_return, invoke_id_return)
OM_private_object@T{ session T} OM_private_object@T{ context T} OM_object@T{ name T} OM_sint@T{ subset T} OM_object@T{ filter T} OM_boolean@T{ search_aliases T} OM_object@T{ selection T} OM_private_object@T{ ∗result_return T} OM_sint@T{ ∗invoke_id_return T}
Arguments
Session
The Session OM private object that was returned by the Bind function, identifying the directory session to be used.
Context
The Context parameters to be used for this operation. This argument must be a Context OM private object or the constant Default-Context.
Name
A Name OM object containing the name of the target entry, which forms the base of the search. Any aliases in the name will be dereferenced unless prohibited by the Dont-Dereference-Aliases Context parameter.
Subset
The search limit that specifies a portion of the Directory to be searched. Its value must be one of:
•base-object, meaning search just the target entry
•one-level, meaning search just the immediate subordinates of the target entry
•whole-subtree, meaning search the target entry and all its subordinates
Filter
A Filter OM object, specifying a filter to prevent unwanted entries being returned in the results of the search. Information is only returned on entries that satisfy the filter. The constant No-Filter can be used as the value of this argument if you want to search all entries. This corresponds to a filter with a value of and for the attribute Filter-Type, and no values of the attributes Filters or Filter-Items.
Search-Aliases
Any aliases in the subordinate entries being searched are dereferenced if the value of this argument is true. They are not dereferenced if its value is false.
Selection
An Entry-Information-Selection OM object or a constant specifying what information from the named entry is requested. Information about no attributes, all attributes, or just a named set can be chosen. Attribute types are always returned, but the attribute values need not be. The following constants can be used:
•Select-No-Attributes, to verify the existence of an entry
•Select-All-Types, to return just the types of all attributes
•Select-All-Types-And-Values, to return the types and values of all attributes
Result
A Search-Result OM private object, passed by reference, containing the requested information from each object in the search space that satisfied the filter. The distinguished name of the target object is present if an alias was dereferenced. Additionally there may be a partial outcome qualifier that indicates the result is incomplete. It also explains why it is not complete and how it could be completed.
Invoke-ID
The Invoke-ID of an asynchronous operation.
Description
This function is used to search a portion of the directory and return selected information from the entries of interest. It is possible that the information will be incomplete in some circumstances.
If this function is called asynchronously, then the result can be abandoned by calling the Abandon function.
DCE Notes
CDS does not support the Search function. It returns with the Service-Error unwilling-to-perform.
Return Value
The target object was located, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously. T} DS_NO_WORKSPACE@T{ A workspace has not been set up by a call to the Initialize function. T}
If neither of these constants are returned, then the function returns a pointer to an error object of one of the classes listed below.
Errors
This function can return pointers to the following error objects:
Library-Error, with Problem attribute values of bad-argument, bad-context, bad-name, bad-session, miscellaneous, missing-type, or too-many-operations
Attribute-Error
Name-Error
Referral
Security-Error
Service-Error
Communications-Error
An unfiltered search of just the base object succeeds even if none of the requested attributes is found while Read fails with the same selected attributes.
A Security-Error, insufficient-access-rights, is only reported where access rights prohibit the reading of all requested attribute values.
Examples
The following code extract shows an example call to the Search function. The Search function is used to search the directory for a specific entry and then extract the values of the Surname and the Title attributes from that entry.
There are two examples. The first example shows how to perform an asynchronous Search operation. The second example shows how to perform a synchronous Search operation.
The Bound_Session argument contains the identity of a session returned from an earlier call to the Bind function. This object identifies the session through which the request should be issued. The Name argument and the Context argument are assumed to have been previously defined. Examples of how to define a Name argument are shown in the Read function. An example of how to define a Context argument is shown in the Add Entry function.
Exhibit 0-0.
{
OM_private_object bound_session, context, name;
OM_workspace workspace;
OM_descriptor cpub_eis[5];
OM_value_position desc_count;
DS_status status;
OM_private_object search_result;
OM_sint invoke_id;
OM_uint completion_flag;
DS_status operation_status;
OM_return_code om_status;
OM_public_object spub_result;
OM_value_position desc_count;
OM_private_object selection;
/∗ create a descriptor list for surname and title of class ∗/
/∗ entry information selection ∗/
OMX_CLASS_DESC( cpub_eis[0], DS_C_ENTRY_INFO_SELECTION);
OMX_ATTR_TYPE_DESC( cpub_eis[1], DS_ATTRIBUTES_SELECTED,
DS_A_SURNAME);
OMX_ATTR_TYPE_DESC( cpub_eis[2], DS_ATTRIBUTES_SELECTED,
DS_A_TITLE);
OMX_ENUM_DESC( cpub_eis[3], DS_INFO_TYPE,
DS_TYPES_ONLY);
OMX_OM_NULL_DESC( cpub_eis[4]);
/∗ Create an OM private object called selection ∗/
om_status = om_create(DS_C_ENTRY_INFO_SELECTION,OM_FALSE,
workspace, &selection);
/∗ Object created, now put in the attributes from cpub_eis ∗/
om_status = om_put(selection, OM_REPLACE_ALL, cpub_eis ,0,0,0);
/∗ now start the search using selection as a parameter∗/
status = ds_search(bound_session, context, name, DS_ONE_LEVEL,
DS_NO_FILTER, OM_FALSE, selection,
&search_result, &invoke_id);
completion_flag = DS_OUTSTANDING_OPERATIONS;
/∗ loop around calls to receive_result() until we get one back ∗/
while ((status == DS_SUCCESS) &&
(completion_flag == DS_OUTSTANDING_OPERATIONS))
{
status = ds_receive_result(bound_session, &completion_flag,
&operation_status, &search_result,
&invoke_id);
if (status == DS_SUCCESS)
{
switch (completion_flag)
{
case DS_COMPLETED_OPERATION:
/∗ we have a completed operation ∗/
/∗ now see what we have got back ... ∗/
if (operation_status == DS_SUCCESS)
{
om_status = om_get(search_result, OM_NO_EXCLUSIONS,
0, 0, 0, OM_ALL_VALUES,
&spub_result, &desc_count);
if (om_status == OM_SUCCESS)
{
/∗ results now available as a public object ∗/
/∗ check desc_count != 0 ∗/
/∗ delete the search result... ∗/
om_status = om_delete(search_result);
}
else
{
/∗ error getting results ∗/
/∗ search_result not deleted ∗/
}
}
else
{...}
break;
case DS_COMPLETED_OPERATION:
...
break;
case DS_COMPLETED_OPERATION:
...
break;
}
} }
Example 1 shows the following:
•How to define an Entry-Information-Selection OM public object (cpub_eis) containing details of the information that is to be returned from the search.
•How to use the OM Create function to create a private object (selection) and how to use the OM Put function to copy the details of the required information from the Entry-Information-Selection OM public object (cpub_eis) into the newly-created Entry-Information-Selection OM private object (selection).
•How to obtain the result of the Search function using the Receive Result function.
•How to use the OM Get function to copy the attributes of the Search-Result OM private object into the Search-Result OM public object (Spub_Result) for examination.
The OM Create, OM Put, OM Get and OM Delete functions are assumed to succeed.
Exhibit 0-0.
{
OM_private_object bound_session, context, name;
OM_value_position desc_count;
DS_status status;
OM_private_object search_result;
OM_private_object selection;
OM_public_object spub_result;
/∗ start the search using selection as a parameter ∗/
status = ds_search(bound_session, DS_DEFAULT_CONTEXT, name,
DS_ONE_LEVEL, DS_NO_FILTER, OM_FALSE,
selection, &search_result, NULL);
if (status == DS_SUCCESS)
{
/∗ now see what we have got back ... ∗/
om_status = om_get(search_result, OM_NO_EXCLUSIONS,
0, 0, 0, OM_ALL_VALUES,
&spub_result, &desc_count);
if (om_status == OM_SUCCESS)
{
/∗ results now available as a public object ∗/
/∗ check desc_count != 0 ∗/
/∗ delete the search result... ∗/
om_status = om_delete(search_result);
}
else
{
/∗ error getting results ∗/
/∗ search_result not deleted ∗/
}
}
else
{...} }
Example 2 shows how to perform a synchronous Search operation. Note that the Invoke-ID argument is not needed and NULL is used. This example assumes that the Selection argument has been defined as shown in Example 1.