NAME

SYNOPSIS

#include <xom.h>
#include <xds.h>

DS_status ds_modify_rdn(
        OM_private_object session,
        OM_private_object context,
        OM_object name,
        OM_object new_RDN,
        OM_boolean delete_old_RDN,
        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. Note that DS_SIZE_LIMIT and DS_DONT_DEREFERENCE_ALIASES do not apply to this operation. This parameter must be a private object or the DS_DEFAULT_CONTEXT constant.

name

(Object(DS_C_NAME)). The current name of the target leaf entry. Any aliases in the name are not dereferenced. The immediate superior must not have any nonspecific subordinate references; if it does, the function can fail with a DS_C_UPDATE_ERROR (DS_E_AFFECTS_MULTIPLE_DSAS). A nonspecific subordinate reference is an indication that another DSA holds some number of children, but does not indicate their RDNs. This means that it is not possible to check the uniqueness of the requested new RDN within a single DSA.

new_RDN

(Object(DS_C_RELATIVE_NAME)). The requested new RDN. If an attribute value in the new RDN does not already exist in the entry (either as part of the old RDN or as a nondistinguished value), the new value is added. If it cannot be added, an error is reported.

delete_old_RDN

(Boolean). If this value is OM_TRUE, all attribute values that are in the old RDN but not in the new RDN are deleted. If the value is OM_FALSE, the old values should remain in the entry (not as part of the RDN). The value must be OM_TRUE when a single value attribute in the RDN has its value changed by the operation. If this operation removes the last attribute value of an attribute, that attribute is deleted.

Output

invoke_id_return

(Integer). Not supported.

DESCRIPTION

The ds_modify_rdn() function is used to change the RDN of a leaf entry (either an object entry or an alias entry).

NOTES

CDS does not support ds_modify_rdn(), and returns with DS_C_SERVICE_ERROR (DS_E_UNWILLING_TO_PERFORM).

RETURN VALUES

DS_status

Indicates whether the name of the entry is changed (DS_SUCCESS is returned); otherwise, an error is returned.

ERRORS

This function can return a DS_C_SYSTEM_ERROR or one of the following DS_C_LIBRARY_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

DS_C_UPDATE_ERROR

The DS_C_UPDATE_ERROR (DS_E_AFFECTS_MULTIPLE_DSAS) error, referred to earlier in this reference page, need not be returned if there is local agreement between the DSAs to allow the entry to be modified.

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