Summary of DBMS_LDAP Subprograms

Table 21-3 DBMS_LDAP Subprograms  

Function or Procedure	Description
init Function	Initializes a session with an LDAP server. This actually establishes a connection with the LDAP server.
simple_bind_s Function	Performs simple username/password based authentication to the directory server.
bind_s Function	Performs complex authentication to the directory server.
unbind_s Function	Closes an active LDAP session.
compare_s Function	Tests if a particular attribute in a particular entry has a particular value.
search_s Function	Performs a synchronous search in the LDAP server. It returns control to the PL/SQL environment only after all of the search results have been sent by the server or if the search request is timed out by the server.
search_st Function	Performs a synchonous search in the LDAP server with a client side timeout. It returns control to the PL/SQL environment only after all of the search results have been sent by the server or if the search request is timed out by the client or the server.
first_entry Function	Retrieves the first entry in the result set returned by either search_s or search_st.
next_entry Function	Iterates to the next entry in the result set of a search operation.
count_entries Function	Counts the number of entries in the result set. It can also be used to count the number of entries remaining during a traversal of the result set using a combination of the functions first_entry and next_entry.
first_attribute Function	Fetches the first attribute of a given entry in the result set.
next_attribute Function	Fetches the next attribute of a given entry in the result set.
get_dn Function	Retrieves the X.500 distinguished name of given entry in the result set.
get_values Function	Retrieves all of the values associated for a given attribute in a given entry.
get_values_len Function	Retrieves values of attributes that have a Binary syntax.
delete_s Function	Removes a leaf entry in the LDAP Directory Information Tree.
modrdn2_s Function	Renames the relative distinguished name of an entry.
err2string Function	Converts an LDAP error code to string in the local language in which the API is operating.
create_mod_array Function	Allocates memory for array modification entries that are applied to an entry using the modify_s functions.
populate_mod_array (String Version) Procedure	Populates one set of attribute information for add or modify operations.
populate_mod_array (Binary Version) Procedure	Populates one set of attribute information for add or modify operations. This procedure call has to happen after DBMS_LDAP.create_mod_array is called.
modify_s Function	Performs a sychronous modification of an existing LDAP directory entry.
add_s Function	Adds a new entry to the LDAP directory synchronously. Before calling add_s, we have to call DBMS_LDAP.creat_mod_array and DBMS_LDAP.populate_mod_array first.
free_mod_array Procedure	Frees the memory allocated by DBMS_LDAP.create_mod_array.
count_values Function	Counts the number of values returned by DBMS_LDAP.get_values.
count_values_len Function	Counts the number of values returned by DBMS_LDAP.get_values_len.
rename_s Function	Renames an LDAP entry synchronously.
explode_dn Function	Breaks a DN up into its components.
open_ssl Function	Establishes an SSL (Secure Sockets Layer) connection over an existing LDAP connection.

init Function

This function initializes a session with an LDAP server. This actually establishes a connection with the LDAP server.

Syntax

DBMS_LDAP.init (
   hostname  IN VARCHAR2,
   portnum   IN PLS_INTEGER )
RETURN SESSION;

Parameters

Table 21-4 init Function Parameters

Parameter	Description
hostname (IN)	Contains a space-separated list of host names or dotted strings representing the IP address of hosts running an LDAP server. Each host name in the list may include a port number, which is separated from the host with a colon (:). The hosts are tried in the order listed, stopping with the first one to which a successful connection is made.
portnum (IN)	Contains the TCP port number to connect to. If a host includes a port number, this parameter is ignored. If this parameter is not specified and the host name does not contain the port number, the default port number 389 is assumed.

Return Values

Table 21-5 init Function Return Values

Value	Description
SESSION	A handle to an LDAP session that can be used for further calls into the API.

Exceptions

Table 21-6 init Function Exceptions

Exception	Description
init_failed	Raised when there is a problem contacting the LDAP server.
ts_mode_not_supported	Raised if DBMS_LDAP.init is invoked from a user session that is logged onto the database using an MTS service.
general_error	For all other errors. The error string associated with the exception describes the error in detail.

Usage Notes

DBMS_LDAP.init is the first function that should be called in order to establish a session to the LDAP server. DBMS_LDAP.init returns a session handle, a pointer to an opaque structure that must be passed to subsequent calls pertaining to the session. This routine returns NULL and raises the INIT_FAILED exception if the session cannot be initialized. Subsequent to the call to init, the connection must be authenticated using DBMS_LDAP.bind_s or DBMS_LDAP.simple_bind_s.

simple_bind_s Function

This function can be used to perform simple username/password based authentication to the directory server.

Syntax

DBMS_LDAP.simple_bind_s (    
   ld      IN SESSION,
   dn      IN VARCHAR2,
   passwd  IN VARCHAR2)
RETURN PLS_INTEGER;

Parameters

Table 21-7 simple_bind_s Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle.
dn (IN)	The distinguished name of the user under which you are trying to login.
passwd (IN)	A text string containing the password.

Return Values

Table 21-8 simple_bind_s Function Return Values

Value	Description
PLS_INTEGER	DBMS_LDAP SUCCESS on a successful completion. If there was a problem, one of the exceptions in Table 21-9 is raised.

Exceptions

Table 21-9 simple_bind_s Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
mts_mode_not_supported	Raised if DBMS_LDAP.init is invoked from a user session that is logged onto as an MTS service.
general_error	For all other errors. The error string associated with this exception explains the error in detail.

Usage Notes

DBMS_LDAP.simple_bind_s can be used to authenticate a user whose directory distinguished name and directory password are known. It can be called only after a valid LDAP session handle is obtained from a call to DBMS_LDAP.init.

bind_s Function

This function performs complex authentication to the directory server.

Syntax

DBMS_LDAP.bind_s (    
   ld    IN SESSION,
   dn    IN VARCHAR2,
   cred  IN VARCHAR2,
   meth  IN PLS_INTEGER )
RETURN PLS_INTEGER;

Parameters

Table 21-10 bind_s Function Parameters

Parameter	Description
ld	A valid LDAP session handle.
dn	The distinguished name of the user under which you are trying to login.
cred	A text string containing the credentials used for authentication.
meth	The authentication method.

Return Values

Table 21-11 bind_s Function Return Values

Value	Description
PLS_INTEGER	DBMS_LDAP.SUCCESS on a successful completion. One of the exceptions in Table 21-12 is raised if there is a problem.

Exceptions

Table 21-12 bind_s Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
invalid_auth_method	Raised if the authentication method requested is not supported.
mts_mode_not_supported	Raised if invoked from a user session that is logged onto an MTS service.
general_error	For all other errors. The error string associated with this exception explains the error in detail.

Usage Notes

DBMS_LDAP.bind_s can be used to authenticate a user. It can be called only after a valid LDAP session handle is obtained from a call to DBMS_LDAP.init.

unbind_s Function

This function closes an active LDAP session.

Syntax

DBMS_LDAP.unbind_s (
   ld  IN SESSION )  
RETURN PLS_INTEGER;

Parameters

Table 21-13 unbind_s Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle.

Return Values

Table 21-14 unbind_s Function Return Values

Value	Description
PLS_INTEGER	SUCCESS on proper completion. One of the exceptions listed in Table 21-15 is raised otherwise.

Exceptions

Table 21-15 unbind_s Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
general error	For all other errors. The error string associated with this exception explains the error in detail.

Usage Notes

The unbind_s function sends an unbind request to the server, closes all open connections associated with the LDAP session, and disposes of all resources associated with the session handle before returning. After a call to this function, the session handle ld is invalid and it is illegal to make any further LDAP API calls using ld.

compare_s Function

This function tests whether a particular attribute in a particular entry has a particular value.

Syntax

DBMS_LDAP.compare_s (
   ld     IN SESSION,
   dn     IN VARCHAR2,
   attr   IN VARCHAR2,
   value  IN VARCHAR2)
RETURN PLS_INTEGER;

Parameters

Table 21-16 compare_s Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle
dn (IN)	The name of the entry to compare against
attr (IN)	The attribute to compare against.
value (IN)	A string attribute value to compare against

Return Values

Table 21-17 compare_s Function Return Values

Value	Description
PLS_INTEGER	COMPARE_TRUE is the given attribute that has a matching value. COMPARE_FALSE if the value of the attribute does not match the value given.

Exceptions

Table 21-18 compare_s Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
general_error	For all other errors. The error string associated with this exception explains the error in detail.

Usage Notes

The function compare_s can be used to assert if the value of a given attribute stored in the directory server matches a certain value.This operation can only be performed on attributes whose syntax definition allows them to be compared. The compare_s function can only be called after a valid LDAP session handle has been obtained from the init function and authenticated using the bind_s or simple_bind_s functions.

search_s Function

This function performs a synchronous search in the LDAP server. It returns control to the PL/SQL environment only after all of the search results have been sent by the server or if the search request is timed out by the server.

Syntax

FUNCTION search_s  (    
   ld        IN SESSION,
   base      IN VARCHAR2,
   scope     IN PLS_INTEGER,
   filter    IN VARCHAR2,
   attrs     IN STRING_COLLECTION,
   attronly  IN PLS_INTEGER,
   res       OUT MESSAGE)
RETURN PLS_INTEGER;

Parameters

Table 21-19 search_s Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle.
base (IN)	The dn of the entry at which to start the search.
scope (IN)	One of SCOPE_BASE (0x00), SCOPE_ONELEVEL (0x01), or SCOPE_SUBTREE (0x02), indicating the scope of the search.
filter (IN)	A character string representing the search filter. The value NULL can be passed to indicate that the filter (objectclass=*) which matches all entries is to be used.
attrs (IN)	A collection of strings indicating which attributes to return for each matching entry. Passing NULL for this parameter causes all available user attributes to be retrieved. The special constant string NO_ATTRS (1.1) can be used as the only string in the array to indicate that no attribute types are returned by the server. The special constant string ALL_USER_ATTRS (*) can be used in the attrs array along with the names of some operational attributes to indicate that all user attributes plus the listed operational attributes are returned.
attrsonly (IN)	A boolean value that must be zero if both attribute types and values are returned, and nonzero if only types are wanted.
res (OUT)	This is a result parameter which will contain the results of the search upon completion of the call. If no results are returned, *res is set to NULL.

Return Values

Table 21-20 search_s Function Return Value

Value	Description
PLS_INTEGER	DBMS_LDAP.SUCCESS if the search operation succeeded. An exception is raised in all other cases.
res (OUT parameter)	If the search succeeded and there are entries, this parameter is set to a nonnull value that can be used to iterate through the result set.

Exceptions

Table 21-21 search_s Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
invalid_search_scope	Raised if the search scope is not one of SCOPE_BASE, SCOPE_ONELEVEL, or SCOPE_SUBTREE.
general_error	For all other errors. The error string associated with this exception explains the error in detail.

Usage Notes

This function issues a search operation, and does not return control to the user environment until all of the results have been returned from the server. Entries returned from the search, if any, are contained in the res parameter. This parameter is opaque to the caller. Entries, attributes, values, and so on can be extracted by calling the parsing routines described in the following sections.

search_st Function

This function performs a synchronous search in the LDAP server with a client-side timeout. It returns control to the PL/SQL environment only after all of the search results have been sent by the server or if the search request is timed out by the client or the server.

Syntax

DBMS_LDAP.search_st ( 
   ld        IN  SESSION,
   base      IN  VARCHAR2,
   scope     IN  PLS_INTEGER,
   filter    IN  VARCHAR2,
   attrs     IN  STRING_COLLECTION,
   attronly  IN  PLS_INTEGER,
   tv        IN  TIMEVAL,
   res       OUT MESSAGE)
RETURN PLS_INTEGER;

Parameters

Table 21-22 search_st Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle.
base (IN)	The dn of the entry at which to start the search.
scope (IN)	One of SCOPE_BASE (0x00), SCOPE_ONELEVEL (0x01), or SCOPE_SUBTREE (0x02), indicating the scope of the search.
filter (IN)	A character string representing the search filter. The value NULL can be passed to indicate that the filter (objectclass=*) which matches all entries is to be used.
attrs (IN)	A collection of strings indicating which attributes to return for each matching entry. Passing NULL for this parameter causes all available user attributes to be retrieved. The special constant string NO_ATTRS (1.1) can be used as the only string in the array to indicate that no attribute types are returned by the server. The special constant string ALL_USER_ATTRS (*) can be used in the attrs array along with the names of some operational attributes to indicate that all user attributes plus the listed operational attributes are returned.
attrsonly (IN)	A boolean value that must be zero if both attribute types and values are returned, and nonzero if only types are wanted.
tv (IN)	The timeout value expressed in seconds and microseconds that should be used for this search.
res (OUT)	This is a result parameter that will contain the results of the search upon completion of the call. If no results are returned, *res is set to NULL.

Return Values

Table 21-23 search_st Function Return Values

Value	Description
PLS_INTEGER	DBMS_LDAP.SUCCESS if the search operation succeeded. An exception is raised in all other cases.
res (OUT parameter)	If the search succeeded and there are entries, this parameter is set to a NON_NULL value that can be used to iterate through the result set.

Exceptions

Table 21-24 search_st Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
invalid_search_scope	Raised if the search scope is not one of SCOPE_BASE, SCOPE_ONELEVEL or SCOPE_SUBTREE.
invalid_search_time_value	Raised if the time value specified for the timeout is invalid.
general_error	For all other errors. The error string associated with this exception explains the error in detail.

Usage Notes

This function is very similar to DBMS_LDAP.search_s, except that it requires a timeout value.

first_entry Function

This function retrieves the first entry in the result set returned by either search_s or search_st

Syntax

DBMS_LDAP.first_entry (
   ld   IN SESSION,
   msg  IN MESSAGE )
RETURN MESSAGE;

Parameters

Table 21-25 first_entry Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle.
msg (IN)	The search result obtained by a call to one of the synchronous search routines.

Return Values

Table 21-26 first_entry Return Values

Value	Description
MESSAGE	A handle to the first entry in the list of entries returned from the LDAP server. It is set to NULL if there was an error and an exception is raised.

Exceptions

Table 21-27 first_entry Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
invalid_message	Raised if the incoming msg handle is invalid.

Usage Notes

The function first_entry should always be the first function used to retrieve the results from a search operation.

next_entry Function

This function iterates to the next entry in the result set of a search operation.

Syntax

DBMS_LDAP.next_entry (
   ld   IN SESSION,
   msg  IN MESSAGE )
RETURN MESSAGE;

Parameters

Table 21-28 next_entry Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle.
msg (IN)	The search result, as obtained by a call to one of the synchronous search routines.

Return Values

Table 21-29 next_entry Function Return Values

Value	Description
MESSAGE	A handle to the next entry in the list of entries returned from the LDAP server. It is set to NULL if there was an error and an exception is raised.

Exceptions

Table 21-30 next_entry Function Exceptions

Exception	Description
invalid_session	Raised if the session handle, ld is invalid.
invalid_message	Raised if the incoming msg handle is invalid.

Usage Notes

The function next_entry should always be called after a call to first_entry. Also, the return value of a successful call to next_entry should be used as msg argument used in a subsequent call to next_entry to fetch the next entry in the list.

count_entries Function

This function counts the number of entries in the result set. It can also count the number of entries remaining during a traversal of the result set using a combination of the functions first_entry and next_entry.

Syntax

DBMS_LDAP.count_entries (
   ld   IN SESSION,
   msg  IN MESSAGE )
RETURN PLS_INTEGER;

Parameters

Table 21-31 count_entry Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle
msg (IN)	The search result, as obtained by a call to one of the synchronous search routines

Return Values

Table 21-32 count_entry Function Return Values

Value	Description
PLS INTEGER	Nonzero if there are entries in the result set -1 if there was a problem.

Exceptions

Table 21-33 count_entry Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
invalid_message	Raised if the incoming msg handle is invalid.
count_entry_error	Raised if there was a problem in counting the entries.

Usage Notes

The count_entries function returns the number of entries contained in a chain of entries. If an error occurs, such as the res parameter being invalid, -1 is returned. The count_entries call can also be used to count the number of entries that remain in a chain if called with a message, entry, or reference returned by first_message, next_message, first_entry, next_entry, first_reference, and next_reference.

first_attribute Function

This function fetches the first attribute of a given entry in the result set.

Syntax

DBMS_LDAP.first_attribute (
   ld        IN  SESSION,
   msg       IN  MESSAGE,
   ber_elem  OUT BER_ELEMENT)
RETURN VARCHAR2;

Parameters

Table 21-34 first_attribute Function Parameter

Parameter	Description
ld (IN)	A valid LDAP session handle
msg (IN)	The entry whose attributes are to be stepped through, as returned by first_entry or next_entry
ber_elem (OUT)	A handle to a BER ELEMENT that is used to keep track of which attribute in the entry has been read

Return Values

Table 21-35 first_attribute Function Return Values

Value	Description
VARCHAR2	The name of the attribute if it exists. NULL if no attribute exists or if an error occurred.
ber_elem	A handle used by DBMS_LDAP.next_attribute to iterate over all of the attributes

Exceptions

Table 21-36 first_attribute Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
invalid_message	Raised if the incoming msg handle is invalid.

Usage Notes

The handle to the BER_ELEMENT returned as a function parameter to first_attribute should be used in the next call to next_attribute to iterate through the various attributes of an entry. The name of the attribute returned from a call to first_attribute can in turn be used in calls to the functions get_values or get_values_len to get the values of that particular attribute.

next_attribute Function

This function fetches the next attribute of a given entry in the result set.

Syntax

DBMS_LDAP.next_attribute (
   ld        IN SESSION,
   msg       IN MESSAGE,
   ber_elem  IN BER_ELEMENT)
RETURN VARCHAR2;

Parameters

Table 21-37 next_attribute Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle.
msg (IN)	The entry whose attributes are to be stepped through, as returned by first_entry or next_entry.
ber_elem (IN)	A handle to a BER ELEMENT that is used to keep track of which attribute in the entry has been read.

Return Values

Table 21-38 next_attribute Function Return Values

Value	Description
VARCHAR2	The name of the attribute, if it exists.

Exceptions

Table 21-39 next_attribute Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
invalid_message	Raised if the incoming msg handle is invalid.

Usage Notes

The handle to the BER_ELEMENT returned as a function parameter to first_attribute should be used in the next call to next_attribute to iterate through the various attributes of an entry. The name of the attribute returned from a call to next_attribute can in turn be used in calls to get_values or get_values_len to get the values of that particular attribute.

get_dn Function

This function retrieves the X.500 distinguished name of a given entry in the result set.

The function first_attribute fetches the first attribute of a given entry in the result set

Syntax

DBMS_LDAP.get_dn (
   ld   IN SESSION,
   msg  IN MESSAGE)
RETURN VARCHAR2;

Parameters

Table 21-40 get_dn Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle.
msg (IN)	The entry whose DN is to be returned.

Return Values

Table 21-41 get_dn Function Return Values

Value	Description
VARCHAR2	The X.500 distinguished name of the entry as a PL/SQL string. NULL if there was a problem.

Exceptions

Table 21-42 get_dn Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
invalid_message	Raised if the incoming msg handle is invalid.
get_dn_error	Raised if there was a problem in determining the DN.

Usage Notes

The function get_dn can be used to retrieve the DN of an entry as the program logic is iterating through the result set. This be used as an input to explode_dn to retrieve the individual components of the DN.

get_values Function

This function retrieves all of the values associated for a given attribute in a given entry.

Syntax

DBMS_LDAP.get_values (
   ld       IN SESSION,
   ldapentry  IN MESSAGE,
   attr       IN VARCHAR2)
RETURN STRING_COLLECTION;

Parameters

Table 21-43 get_values Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle.
ldapentry (IN)	A valid handle to an entry returned from a search result.
attr (IN)	The name of the attribute for which values are being sought.

Return Values

Table 21-44 get_values Function Return Values

Value	Description
STRING_COLLECTION	A PL/SQL string collection containing all of the values of the given attribute. NULL if there are no values associated with the given attribute.

Exceptions

Table 21-45 get_values Function Exceptions

Exception	Description
invalid session	Raised if the session handle ld is invalid.
invalid message	Raised if the incoming entry handle is invalid.

Usage Notes

The function get_values can only be called after the handle to entry has been first retrieved by a call to either first_entry or next_entry. The name of the attribute can be known beforehand, and it can also be determined by a call to first_attribute or next_attribute. The function get_values always assumes that the datatype of the attribute it is retrieving is String. For retrieving binary datatypes, use get_values_len.

.

get_values_len Function

This function retrieves values of attributes that have a Binary syntax.

Syntax

DBMS_LDAP.get_values_len (    
   ld         IN SESSION,
   ldapentry  IN MESSAGE,
   attr       IN VARCHAR2)
RETURN BINVAL_COLLECTION;

Parameters

Table 21-46 get_values_len Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle.
ldapentrymsg (IN)	A valid handle to an entry returned from a search result.
attr (IN)	The string name of the attribute for which values are being sought.

Return Values

Table 21-47 get_values_len Function Return Values

Value	Description
BINVAL_COLLECTION	A PL/SQL Raw collection containing all the values of the given attribute. NULL if there are no values associated with the given attribute.

Exceptions

Table 21-48 get_values_len Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
invalid_message	Raised if the incoming entry handle is invalid

Usage Notes

The function get_values_len can only be called after the handle to entry has been retrieved by a call to either first_entry or next_entry. The name of the attribute can be known beforehand, and it can also be determined by a call to first_attribute or next_attribute. This function can be used to retrieve both binary and nonbinary attribute values.

delete_s Function

This function removes a leaf entry in the LDAP Directory Information Tree.

Syntax

DBMS_LDAP.delete_s (
   ld       IN SESSION,
   entrydn  IN VARCHAR2)
RETURN PLS_INTEGER;

Parameters

Table 21-49 delete_s Function Parameters

Parameter Name	Description
ld (IN)	A valid LDAP session
entrydn (IN)	The X.500 distinguished name of the entry to delete.

Return Values

Table 21-50 delete_s Function Return Values

Value	Description
PLS_INTEGER	DBMS_LDAP.SUCCESS if the delete operation wa successful. An exception is raised otherwise.

Exceptions

Table 21-51 delete_s Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
invalid_entry_dn	Raised if the distinguished name of the entry is invalid
general_error	For all other errors. The error string associated with this exception explains the error in detail.

Usage Notes

The function delete_s can be used to remove only leaf level entries in the LDAP DIT. A leaf level entry is an entry that does not have any children/LDAP entries under it. It cannot be used to delete nonleaf entries.

modrdn2_s Function

This function modrdn2_s can be used to rename the relative distinguished name of an entry.

Syntax

DBMS_LDAP.modrdn2_s (
   ld            IN SESSION,
   entrydn       IN VARCHAR2
   newrdn        IN VARCHAR2
   deleteoldrdn  IN PLS_INTEGER)
RETURN PLS_INTEGER;

Parameters

Table 21-52 modrdn2_s Function Parameters

Parameter	Description
ld (IN)	A valid LDAP session handle.
entrydn (IN)	The distinguished name of the entry. (This entry must be a leaf node in the DIT.).
newrdn (IN)	The new relative distinguished name of the entry.
deleteoldrdn (IN)	A boolean value that if nonzero, indicates that the attribute values from the old name should be removed from the entry.

Return Values

Table 21-53 modrdn2_s Function Return Values

Value	Description
PLS_INTEGER	DBMS_LDAP.SUCCESS if the operation was successful. An exception is raised otherwise.

Exceptions

Table 21-54 modrdn2_s Function Exceptions

Exception	Description
invalid_session	Raised if the session handle ld is invalid.
invalid_entry_dn	Raised if the distinguished name of the entry is invalid.
invalid_rdn	Invalid LDAP RDN.
invalid_deleteoldrdn	Invalid LDAP deleteoldrdn.
general error	For all other errors. The error string associated with this exception explains the error in detail.

Usage Notes

This function can be used to rename the leaf nodes of a DIT. It simply changes the relative distinguished name by which they are known. The use of this function is being deprecated in the LDAP v3 standard. Please use rename_s, which can achieve the same foundation.

err2string Function

This function converts an LDAP error code to string in the local language in which the API is operating

Syntax

DBMS_LDAP.err2string ( 
   ldap_err  IN PLS_INTEGER )
RETURN VARCHAR2;

Parameters

Table 21-55 err2string Function Parameters

Parameter	Description
ldap_err (IN)	An error number returned from one the API calls.

Return Values

Table 21-56 err2string Function Return Values

Value	Description
VARCHAR2	A character string appropriately translated to the local language which describes the error in detail.

Exceptions

Table 21-57 err2string Function Exceptions

Exception	Description
N/A	None.

Usage Notes

In this release, the exception handling mechanism automatically invokes this if any of the API calls encounter an error.

create_mod_array Function

This function allocates memory for array modification entries that are applied to an entry using the modify_s or add_s functions.

Syntax

DBMS_LDAP.create_mod_array (
   num  IN PLS_INTEGER)
RETURN MOD_ARRAY;

Parameters

Table 21-58 create_mod_array Function Parameters

Parameter	Description
num (IN)	The number of the attributes that you want to add or modify.

Return Values

Table 21-59 create_mod_array Function Return Values

Value	Description
MOD_ARRAY	The data structure holds a pointer to an LDAP mod array. NULL if there was a problem.

Exceptions

Table 21-60 create_mod_array Function Exceptions

Exception	Description
N/A	No LDAP specific exception is raised

Usage Notes

This function is one of the preparation steps for DBMS_LDAP.add_s and DBMS_LDAP.modify_s. It is required to call DBMS_LDAP.free_mod_array to free memory after the calls to add_s or modify_s have completed.

populate_mod_array (String Version) Procedure

This procedure populates one set of attribute information for add or modify operations.

Syntax

DBMS_LDAP.populate_mod_array (
   modptr    IN DBMS_LDAP.MOD_ARRAY,
   mod_op    IN PLS_INTEGER,
   mod_type  IN VARCHAR2,
   modval    IN DBMS_LDAP.STRING_COLLECTION);

Parameters

Table 21-61 populate_mod_array (String Version) Procedure Parameters

Parameter	Description
modptr (IN)	The data structure holds a pointer to an LDAP mod array.
Mod_op (IN)	This field specifies the type of modification to perform.
Mod_type (IN)	This field indicates the name of the attribute type to which the modification applies.
Modval (IN)	This field specifies the attribute values to add, delete, or replace. It is for the string values only.

Return Values

Table 21-62 populate_mod_array (String Version) Procedure Return Values

Value	Description
N/A	-

Exceptions

Table 21-63 populate_mod_array (String Version) Procedure Exceptions

Exception	Description
invalid_mod_array	Invalid LDAP mod array.
invalid_mod_option	Invalid LDAP mod option.
invalid_mod_type	Invalid LDAP mod type.
invalid_mod_value	Invalid LDAP mod value.

Usage Notes

This function is one of the preparation steps for DBMS_LDAP.add_s and DBMS_LDAP.modify_s. It has to happen after DBMS_LDAP.create_mod_array is called.

populate_mod_array (Binary Version) Procedure

This procedure populates one set of attribute information for add or modify operations. This procedure call has to happen after DBMS_LDAP.create_mod_array is called.

Syntax

PROCEDURE populate_mod_array
    (modptr   IN DBMS_LDAP.MOD_ARRAY,
     mod_op   IN PLS_INTEGER,
     mod_type IN VARCHAR2,
     modval   IN DBMS_LDAP.BERVAL_COLLECTION);

Parameters

Table 21-64 populate_mod_array (Binary Version) Procedure Parameters

Parameter	Description
modptr (IN)	The data structure holds a pointer to an LDAP mod array.
Mod_op (IN)	This field specifies the type of modification to perform.
Mod_typ (IN)	This field indicates the name of the attribute type to which the modification applies.
Modval (IN)	This field specifies the attribute values to add, delete, or replace. It is for the binary values.

Return Values

Table 21-65 populate_mod_array (Binary Version) Procedure Return Values

Value	Description
N/A	-

Exceptions

Table 21-66 populate_mod_array (Binary Version) Procedure Exceptions

Exception	Description
invalid_mod_array	Invalid LDAP mod array.
invalid_mod_option	Invalid LDAP mod option.
invalid_mod_type	Invalid LDAP mod type.
invalid_mod_value	Invalid LDAP mod value.

Usage Notes

This function is one of the preparation steps for DBMS_LDAP.add_s and DBMS_LDAP.modify_s. It has to happen after DBMS_LDAP.create_mod_array is called.

modify_s Function

This function performs a synchronous modification of an existing LDAP directory entry.

Syntax

DBMS_LDAP.modify_s (
   ld       IN DBMS_LDAP.SESSION,
   entrydn  IN VARCHAR2,
   modptr   IN DBMS_LDAP.MOD_ARRAY)
RETURN PLS_INTEGER;

Parameters

Table 21-67 modify_s Function Parameters

Parameter	Description
ld (IN)	A handle to an LDAP session, as returned by a successful call to DBMS_LDAP.init.
entrydn (IN)	Specifies the name of the directory entry whose contents are to be modified.
modptr (IN)	The handle to an LDAP mod structure, as returned by a successful call to DBMS_LDAP.create_mod_array.

Return Values

Table 21-68 modify_s Function Return Values

Value	Description
PLS_INTEGER	The indication of the success or failure of the modification operation

Exceptions

Table 21-69 modify_s Function Exceptions

Exception	Description
invalid_session	Invalid LDAP session.
invalid_entry_dn	Invalid LDAP entry dn.
invalid_mod_array	Invalid LDAP mod array.

Usage Notes

This function call has to follow successful calls of DBMS_LDAP.create_mod_array and DBMS_LDAP.populate_mod_array.

add_s Function

This function adds a new entry to the LDAP directory sychronously. Before calling add_s, you must call DBMS_LDAP.create_mod_array and DBMS_LDAP.populate_mod_array.

Syntax

DBMS_LDAP.add_s (
   ld       IN DBMS_LDAP.SESSION,
   entrydn  IN VARCHAR2,
   modptr   IN DBMS_LDAP.MOD_ARRAY)
RETURN PLS_INTEGER;

Parameters

Table 21-70 add_s Function Parameters

Parameter	Description
ld (IN)	A handle to an LDAP session, as returned by a successful call to DBMS_LDAP.init.
Entrydn (IN)	Specifies the name of the directory entry to be created.
Modptr (IN)	The handle to an LDAP mod structure, as returned by successful call to DBMS_LDAP.create_mod_array.

Return Values

Table 21-71 add_s Function Return Values

Value	Description
PLS_INTEGER	The indication of the success or failure of the modification operation.

Exceptions

Table 21-72 add_s Function Exceptions

Exception	Description
invalid_session	Invalid LDAP session.
invalid_entry_dn	Invalid LDAP entry dn.
invalid_mod_array	Invalid LDAP mod array.

Usage Notes

The parent entry of the entry to be added must already exist in the directory. This function call has to follow successful calls of DBMS_LDAP.create_mod_array and DBMS_LDAP.populate_mod_array.

free_mod_array Procedure

This procedure frees the memory allocated by DBMS_LDAP.create_mod_array.

Syntax

DBMS_LDAP.free_mod_array (
   modptr  IN DBMS_LDAP.MOD_ARRAY);

Parameters

Table 21-73 free_mod_array Procedure Parameters

Parameter	Description
modptr (in)	The handle to an LDAP mod structure, as returned by successful call to DBMS_LDAP.create_mod_array.

Return Values

Table 21-74 free_mod_array Procedure Return Value

Value	Description
N/A	-

Exceptions

Table 21-75 free_mod_array Procedure Exceptions

Exception	Description
N/A	No LDAP specific exception is raised.

count_values Function

This function counts the number of values returned by DBMS_LDAP.get_values.

Syntax

DBMS_LDAP.count_values (
   values  IN DBMS_LDAP.STRING_COLLECTION)
RETURN PLS_INTEGER;

Parameters

Table 21-76 count_values Function Parameters

Parameter	Description
values (IN)	The collection of string values.

Return Values

Table 21-77 count_values Function Return Values

Value	Description
PLS_INTEGER	The indication of the success or failure of the operation.

Exceptions

Table 21-78 count_values Function Exceptions

Exception	Description
N/A	No LDAP specific exception is raised.

count_values_len Function

This function counts the number of values returned by DBMS_LDAP.get_values_len.

Syntax

DBMS_LDAP.count_values_len (
   values  IN DBMS_LDAP.BINVAL_COLLECTION)
RETURN PLS_INTEGER;

Parameters

Table 21-79 count_values_len Function Parameters

Parameter	Description
values (IN)	The collection of binary values.

Return Values

Table 21-80 count_values_len Function Return Values

Value	Description
PLS_INTEGER	The indication of the success or failure of the operation.

Exceptions

Table 21-81 count_values_len Function Exceptions

Exception	Description
N/A	No LDAP specific exception is raised.

.

rename_s Function

This function renames an LDAP entry synchronously.

Syntax

DBMS_LDAP.rename_s (
   ld            IN SESSION,
   dn            IN VARCHAR2,
   newrdn        IN VARCHAR2,
   newparent     IN VARCHAR2,
   deleteoldrdn  IN PLS_INTEGER,
   serverctrls   IN LDAPCONTROL,
   clientctrls   IN LDAPCONTROL)
RETURN PLS_INTEGER;

Parameters

Table 21-82 rename_s Function Parameters

Parameter	Description
ld (IN)	A handle to an LDAP session, as returned by a successful call to DBMS_LDAP.init.
Dn (IN)	Specifies the name of the directory entry to be renamed or moved.
newrdn (IN)	Specifies the new RDN.
Newparent (IN)	Specifies the DN of the new parent.
Deleteoldrdn (IN)	Specifies if the old RDN should be retained. If this value is 1, then the old RDN is removed.
Serverctrls (IN)	Currently not supported.
Clientctrls (IN)	Currently not supported.

Return Values

Table 21-83 rename_s Function Return Values

Value	Description
PLS_INTEGER	The indication of the success or failure of the operation.

Exceptions

Table 21-84 rename_s Function Exceptions

Exception	Description
invalid_session	Invalid LDAP Session.
invalid_entry_dn	Invalid LDAP DN.
invalid_rdn	Invalid LDAP RDN.
invalid_newparent	Invalid LDAP newparent.
invalid_deleteoldrdn	Invalid LDAP deleteoldrdn.

explode_dn Function

This function breaks a DN up into its components.

Syntax

DBMS_LDAP.explode_dn (
   dn       IN VARCHAR2,
   notypes  IN PLS_INTEGER)
RETURN STRING_COLLECTION;

Parameters

Table 21-85 explode_dn Function Parameters

Parameter	Description
dn (IN)	Specifies the name of the directory entry to be broken up.
Notypes (IN)	Specifies if the attribute tags will be returned. If this value is not 0, no attribute tags are returned.

Return Values

Table 21-86 explode_dn Function Return Values

Value	Description
STRING_COLLECTION	An array of strings. If the DN cannot be broken up, NULL is returned.

Exceptions

Table 21-87 explode_dn Function Exceptions

Exception	Description
invalid_entry_dn	Invalid LDAP DN.
invalid_notypes	Invalid LDAP notypes value.

open_ssl Function

This function establishes an SSL (Secure Sockets Layer) connection over an existing LDAP connection.

Syntax

DBMS_LDAP.open_ssl (
   ld               IN SESSION,
   sslwrl           IN VARCHAR2,
   sslwalletpasswd  IN VARCHAR2,
   sslauth          IN PLS_INTEGER)
RETURN PLS_INTEGER;

Parameters

Table 21-88 open_ssl Function Parameters

Parameter	Description
ld (IN)	A handle to an LDAP session, as returned by a successful call to DBMS_LDAP.init.
Sslwrl (IN)	Specifies the wallet location (Required for one-way or two-way SSL connection.)
sslwalletpasswd (IN)	Specifies the wallet password (Required for one-way or two-way SSL connection.)
sslauth (IN)	Specifies the SSL Authentication Mode (1 for no authentication required, 2 for one way authentication required, 3 for two way authentication required.

Return Values

Table 21-89 open_ssl Function Return Values

Value	Description
PLS_INTEGER	The indication of the success or failure of the operation.

Exceptions

Table 21-90 open_ssl Function Exceptions

Exception	Description
invalid_session	Invalid LDAP Session.
invalid_ssl_wallet_loc	Invalid LDAP SSL wallet location.
invalid_ssl_wallet_passwd	Invalid LDAP SSL wallet passwd.
invalid_ssl_auth_mode	Invalid LDAP SSL authentication mode.

Usage Notes

Call DBMS_LDAP.init first to acquire a valid LDAP session.