OM_private_object bound_session, context, name; { DS_status status; OM_private_object changes; status = ds_remove_entry(bound_session, DS_DEFAULT_CONTEXT, name, changes, NULL); if (status == DS_SUCCESS) { printf("REMOVE_ENTRY was successful\n"); } else { printf("REMOVE_ENTRY failed\n"); } return status; }

The above example shows a synchronous call to the Remove Entry function. The operation being performed is the same as that shown in Example 1, the only difference being that this operation completes immediately and the result is contained in the Status argument. The Invoke-ID argument is not needed and is therefore set to NULL.

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)

C Binding

DS_status ds_search(session, context, name, subset, filter, search_aliases, selection, result_return, invoke_id_return)

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)

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

The filter is used to prevent unwanted entries being returned in the results of the search. Information is returned only 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. Note that Digital's X.500 DSA does not honor this control; it assumes the value is false and does not dereference aliases.

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.

Note CDS does not support the Search function. It returns with the Service-Error unwilling-to-perform.

Return Values

Possible return values are as follows:

Return	Description
DS_SUCCESS	The target object was located, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously.
DS_NO_WORKSPACE	A workspace has not been set up by a call to the Initialize function.

If neither of these constants is 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 reported only 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.

{ 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; } } }

The above example 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.

  { 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 {...} }

  
  The above example 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.

Shuts down the interface and closes the workspace.

Syntax

Status = ds_shutdown(Workspace)

C Binding

DS_status ds_shutdown(workspace)

DS_status ds_shutdown (
OM_workspace workspace)

Arguments

Workspace

Specifies the workspace (obtained from a call to the Initialize function) that is to be deleted.

Description

This function shuts down the interface previously established by Initialize and enables the service to release resources.

After this function has been called, no OM objects or other data values associated with the workspace are valid, with the exception of client-generated public objects. You should call the Unbind function for all sessions in this workspace. You must not subsequently call any X.500 API functions that operate on OM objects in this workspace.

In order to ensure that resources are freed, applications should release all private objects by calling the OM Delete function for all top-level OM private objects before calling this function. This is not necessary for subobjects. Applications should also release all service-generated public objects by calling the OM Delete function. You can do this either before or after the calling of this function.

Return Values

Possible return values are as follows:

Return	Description
DS_SUCCESS	The shutdown was completed, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously.
DS_NO_WORKSPACE	A workspace has not been set up by a call to the Initialize function.

This function does not return any error objects.

Errors

None.

Examples

The following code extract shows an example call to the Shutdown function:

OM_workspace workspace; { DS_status status; /* Finally, close down the workspace */ ds_status = ds_shutdown(workspace); }

The Shutdown function closes down the workspace identified in the Workspace argument. The workspace identity is obtained from the Initialize function.

This function closes a directory session.

Syntax

Status = ds_unbind(Session)

C Binding

DS_status ds_unbind(session)

DS_status ds_unbind (
OM_private_object session)

Arguments

Session

The directory session that is to be unbound. This argument must be the Session OM private object that was returned by the Bind function, identifying the directory session. If the function succeeds, the value of the File-Descriptor OM attribute is No-Valid-File-Descriptor. The other OM attributes are unchanged.

Description

This function terminates the given directory session and makes the argument unavailable for use with all other interface functions except Bind.

The results of any outstanding asynchronous operations that were initiated using the given Session can no longer be received, and it is not possible to find out if they succeeded. It is therefore recommended that you obtain the results of all outstanding asynchronous operations by calling the Receive-Result function before calling Unbind.

It is possible to use the unbound session again as an argument to Bind, perhaps after modification by the Object Management functions.

Return Values

Possible return values are as follows:

Return	Description
DS_SUCCESS	The operation completed successfully.
DS_NO_WORKSPACE	A workspace has not been set up by a call to the Initialize function.

If neither of these constants is 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 object:

• Library-Error, with problem attribute values of bad-session or miscellaneous

Examples

The following code extract shows an example call to the Unbind function.

{ OM_private_object bound_session; DS_status status; status = ds_unbind(bound_session); if (status == DS_SUCCESS) { printf("UNBIND was successful\n"); } else { printf("UNBIND failed\n"); } }

The Unbind function closes down a session established by the Bind function. The Bound_Session argument identifies the session to be closed.

Negotiates the features of the interface and service.

Syntax

Status = ds_version(Feature-List, Workspace)

C Binding

DS_status ds_version(feature_list, workspace)

DS_status ds_version (
DS_featuare feature_list
OM_workspace workspace)

Arguments

Feature-List

An ordered sequence of features, each represented by an object identifier. The sequence is terminated by an object identifier having no components (that is, a length of zero, and any value of the data pointer in the C representation).

Workspace

Specifies the workspace (obtained from a call to the Initialize function) for which the features are to be negotiated. The features will be in effect for operations that use the workspace or directory sessions associated with the workspace.

Description

This function negotiates features of the interface that are represented by object identifiers. Features are negotiated after a workspace has been initialized.

Negotiable features include the Basic-Directory-Contents Package, the Strong-Authentication Package, and the MHS Directory User Package.

Compaq's implementation of this function does not support the features listed above, but supports one extension, DSX-RET-X500-BIND-ERR-FTR. This feature guarantees that the Bind function will always return an error if it fails to connect to an X.500 directory. This feature is useful if the system where your application runs is capable of simultaneous connections to both CDS and X.500 directories in the same XDS session. In other circumstances, this feature is not needed.

Return Values

Possible return values are as follows:

Return	Description
DS_SUCCESS	The features were successfully negotiated.
DS_NO_WORKSPACE	A workspace has not been set up by a call to the Initialize function.

If neither of these constants is 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 miscellaneous or bad-workspace
• System-Error

Examples

The following code extract shows an example call to the Version function.

{ OM_workspace workspace; DS_feature feature_list[]; DS_status status; status = ds_version(feature_list, workspace); if (status == DS_SUCCESS) { printf("VERSION was successful\n"); } else { printf("VERSION failed\n"); } }