ds_remove_entry(3xds) — Subroutines
(c) Digital Equipment Corporation. 1994. All rights reserved.
Name
ds_remove_entry − Removes an entry from the Directory Information Tree (DIT).
Syntax
Status = ds_remove_entry(Session, Context, Name, 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} Invoke-ID@Integer@T{ write T} Status@T{ DS_status T}
C Binding
DS_status ds_remove_entry(session, context, name, invoke_id_return)
OM_private_object@T{ session T} OM_private_object@T{ context T} OM_object@T{ name 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 directory context to be used for this operation. The Size-Limit and Dont-Dereference-Aliases Context parameters do not apply to 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. Any aliases in the name will not be dereferenced.
Invoke-ID
The Invoke-ID of an asynchronous directory operation.
Description
This function is used to remove an entry from the Directory. This may be an object entry or an alias entry. The entry must not have any subordinate entries.
DCE Notes
Ideally, the user does not know whether X.500 or CDS is actually handling the DCE naming operations. There are, however, some situations where naming results will differ depending on which service is handling the operation. (The intro reference page for XDS functions describes the general differences between operations on X.500 and CDS.)
Note the following issues for the Remove Entry function:
•All CDS operations are synchronous. If a CDS operation is attempted and the Context parameter Asynchronous has been set true, a Library-Error, not-supported, is returned.
•When a CDS name is passed to XDS and DCE is not installed, a Library-Error, not-supported, is returned. This error is also returned when an X.500 name is passed to XDS, and X.500 is not installed.
•
In CDS, the name parameter supplied to theRemove Entry function must ultimately resolve to the name of a leaf (that is, a CDS Object) entry; otherwise, the Name-Error no-such-object is returned. The function never interprets the name parameter as the name of a CDS Directory entry.
Return Value
The entry was removed, 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, not-supported or too-many-operations
Name-Error, no-such-object
Referral
Security-Error
Service-Error
Update-Error
Communications-Error
Examples
The following code extracts show an example call to the Remove Entry function. The Remove Entry function is used to remove an existing directory entry.
There are two examples. The first example shows how to perform an asynchronous Remove Entry operation. The second example shows how to perform a synchronous Remove Entry 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, including an example of a CDS 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;
{
DS_status status;
OM_sint invoke_id;
OM_uint completion_flag;
DS_status operation_status;
OM_private_object remove_entry_result;
/∗ Call the Remove Entry function ∗/
status = ds_remove_entry(bound_session, context, name,
&invoke_id);
if (status == DS_SUCCESS)
{
printf("REMOVE ENTRY request was successful0);
}
else
{
printf("REMOVE ENTRY request failed0);
}
/∗ now wait for the response... ∗/
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,
&remove_entry_result,
&invoke_id);
if (status == DS_SUCCESS)
{
switch (completion_flag)
{
case DS_COMPLETED_OPERATION:
/∗ we have a completed operation ∗/
/∗ check operation_status ∗/
break;
case DS_OUTSTANDING_OPERATIONS:
...
break;
case DS_NO_OUTSTANDING_OPERATION:
...
break;
}
}
} }
Example 1 removes the directory entry, identified in the Name argument, from the directory. Since the operation is executed asynchronously, an invoke identifier is returned in the Invoke-ID argument. This uniquely identifies this specific operation and is therefore used in the subsequent Receive Result function to obtain the result of the operation.
Exhibit 0-0.
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 successful0);
}
else
{
printf("REMOVE_ENTRY failed0);
}
return status;
}
Example 2 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.