ldap_rename()--Asynchronously Rename an Entry

Syntax

 #include <ldap.h>
 
 int ldap_rename(
       LDAP            *ld,
       const char      *dn,
       const char      *newrdn,
       const char      *newparent,
       int             deleteoldrdn,
       LDAPControl     **serverctrls,
       LDAPControl     **clientctrls,
       int             *msgidp)

  Default Public Authority: *USE

  Library Name/Service Program: QSYS/QGLDCLNT

  Threadsafe: Yes

The ldap_rename() routine initiates an asynchronous modify DN operation

In LDAP version 2, the ldap_modrdn() API was used to change the name of an LDAP entry. It could only be used to change the least significant component of a name (the RDN or relative distinguished name). The LDAP version 3 protocol provides the Modify DN protocol operation that allows more general name change access. The ldap_rename() routine is used to change the name of an entry. The ldap_modrdn() routine is deprecated.

Authorities and Locks

No IBM^® i authority is required. All authority checking is done by the LDAP server.

Parameters

ld: (Input) Specifies the LDAP pointer returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().
dn: (Input) Specifies the DN of the entry whose DN is to be changed.
newrdn: (Input) Specifies the new RDN to be given to the entry.
newparent: (Input) Specifies the new parent, or superior entry. If this parameter is NULL, only the RDN of the entry is changed. The root DN may be specified by passing a zero length string, "". The newparent parameter should always be NULL when using version 2 of the LDAP protocol; otherwise the server's behavior is undefined.
deleteoldrdn: (Input) Specifies a boolean value. When set to 1, the old RDN value is to be deleted from the entry. When set to 0, the old RDN value should be retained as a non-distinguished value. This parameter only has meaning if newrdn is different from the old RDN.
serverctrls: (Input) Specifies a list of LDAP server controls. This parameter may be set to null. See Controls for LDAP APIs for more information about server controls.
clientctrls: (Input) Specifies a list of LDAP client controls. This parameter may be set to null. See Controls for LDAP APIs for more information about client controls.
msgidp: (Output) This result parameter is set to the message id of the request if the ldap_rename() call succeeds.

Return Value

LDAP_SUCCESS: if the request was successfully sent. ldap_rename() places the message id of the request in *msgidp. A subsequent call to ldap_result() can be used to obtain the result of the operation. Once the operation has completed, ldap_result() returns a result that contains the status of the operation (in the form of an error code). The error code indicates if the operation completed successfully. The ldap_parse_result() API is used to check the error code in the result.
another LDAP error code: in case of an error.

Error Conditions

If ldap_rename() is not successful, an error code will be returned. See LDAP Client API Error Conditions for possible LDAP error code values.

Error Messages

The following message may be sent from this function.

Message ID	Error Message Text
CPF3CF2 E	Error(s) occurred during running of ldap_rename API.

Related Information

ldap_rename_s() -- Synchronously rename an entry.
ldap_result() -- Retrieve result of an asynchronous LDAP operation.
ldap_modrdn() -- Asynchronously modify the RDN of an entry (deprecated).
ldap_modrdn_s() -- Synchronously modify the RDN of an entry (deprecated).

The ldap_rename() API supports LDAP V3 server controls and client controls.

API introduced: V4R5

[ Back to top | LDAP APIs | APIs by category ]