ds_modify_rdn(3xds) — Subroutines

Name

ds_modify_rdn − Changes the Relative Distinguished Name (RDN) of an entry.

Syntax

Status = ds_modify_rdn(Session, Context, Name, New-RDN, Delete-Old-RDN, 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} New-RDN@OM_object@T{ read T} Delete-Old-RDN@OM_boolean@T{ read T} Invoke-ID@Integer@T{ write T} Status@T{ DS_status T}

C Binding

DS_status ds_modify_rdn(session, context, name, new_rdn, delete_old_rdn, invoke_id_return)

OM_private_object@T{ session T} OM_private_object@T{ context T} OM_object@T{ name T} OM_object@T{ new_rdn T} OM_boolean@T{ delete_old_rdn 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. This argument must be a Context OM private object or the constant Default-Context.

Name

A Name OM object containing the current name of the target entry. Any aliases in the name will be dereferenced if the Digital DSA attribute Dereference Alias on Modify is set and the Dont Deference Aliases service control is not set.

New-RDN

A Relative-Name OM object specifying the 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 non-distinguished value, then the new value is added.

Delete-Old-RDN

When this takes the value false the old values will remain, but not as part of the RDN. When this takes the value true, all attribute values in the old RDN that are not also in the new RDN are deleted. If the operation removes the last value of an attribute, the attribute is deleted. This argument must be true when the value of a single-valued attribute is changed.

Invoke-ID

The Invoke-ID of an asynchronous directory operation.

Description

This function is used to change the RDN of a leaf entry. This can be either an object entry or an alias entry.

DCE Notes

CDS does not support the Modify RDN function; it returns with the Service-Error unwilling-to-perform.

Return Value

The RDN of the entry was changed, 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

Update-Error

Communications-Error

The Update-Error affects-multiple-DSAs that is referred to in the argument descriptions need not be returned if there is local agreement between the DSAs to allow the entry to be modified.

Example

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

Exhibit 0-0.

OM_private_object bound_session, context, name, new_rdn;

OM_sint            invoke_id;

OM_boolean         delete_old_rdn;

{

    DS_status          status;

    status = ds_modify_rdn(bound_session, DS_DEFAULT_CONTEXT, name,
                           new_rdn, delete_old_rdn, NULL);

    if (status == DS_SUCCESS)
    {
      printf("MODIFY RDN was successful0);
    }
    else
    {
      printf("MODIFY RDN failed0);
    }

    return status;

}

Museum