12 DBMS_LDAP PL/SQL Reference

DBMS_LDAP contains the functions and procedures that enable PL/SQL programmers to access data from LDAP servers. This chapter examines all of the API functions in detail.

The chapter contains these topics:

Summary of Subprograms
Exception Summary
Data Type Summary
Subprograms

Note:

Sample code for the DBMS_LDAP package is available at this URL:

http://www.oracle.com/technology/sample_code/

Look for the Oracle Identity Management link under Sample Applications–Oracle Application Server.

12.1 Summary of Subprograms

Table 12-1 DBMS_LDAP API Subprograms

Function or Procedure	Description
FUNCTION init	`init()` initializes a session with an LDAP server. This actually establishes a connection with the LDAP server.
FUNCTION simple_bind_s	The function `simple_bind_s()` can be used to perform simple user name and password authentication to the directory server.
FUNCTION bind_s	The function `bind_s()` can be used to perform complex authentication to the directory server.
FUNCTION unbind_s	The function `unbind_s()` is used for closing an active LDAP session.
FUNCTION compare_s	The function `compare_s()` can be used to test if a particular attribute in a particular entry has a particular value.
FUNCTION search_s	The function `search_s()` 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.
FUNCTION search_st	The function `search_st()` performs a synchronous search in the LDAP server with a client side time out. 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.
FUNCTION first_entry	The function first_entry is used to retrieve the first entry in the result set returned by either `search_s()` or search_st.
FUNCTION next_entry	The function `next_entry()` is used to iterate to the next entry in the result set of a search operation.
FUNCTION count_entries	This function is used to count 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`.
FUNCTION first_attribute	The function `first_attribute()` fetches the first attribute of a given entry in the result set.
FUNCTION next_attribute	The function `next_attribute()`fetches the next attribute of a given entry in the result set.
FUNCTION get_dn	The function `get_dn()` retrieves the X.500 distinguished name of a given entry in the result set.
FUNCTION get_values	The function `get_values()`can be used to retrieve all of the values associated with a given attribute in a given entry.
FUNCTION get_values_len	The function `get_values_len()` can be used to retrieve values of attributes that have a 'Binary' syntax.
FUNCTION delete_s	This function can be used to remove a leaf entry in the LDAP Directory Information Tree.
FUNCTION modrdn2_s	The function `modrdn2_s()` can be used to rename the relative distinguished name of an entry.
FUNCTION err2string	The function `err2string()` can be used to convert an LDAP error code to a string in the local language in which the API is operating.
FUNCTION create_mod_array	The function `create_mod_array()` allocates memory for array modification entries that will be applied to an entry using the `modify_s()` functions.
PROCEDURE populate_mod_array (String Version)	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.
PROCEDURE populate_mod_array (Binary Version)	Populates one set of attribute information for add or modify operations. This procedure call has to occur after `DBMS_LDAP.create_mod_array()` is called.
PROCEDURE populate_mod_array (Binary Version. Uses BLOB Data Type)	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.
FUNCTION get_values_blob	The function `get_values_blob()` can be used to retrieve larger values of attributes that have a binary syntax.
FUNCTION count_values_blob	Counts the number of values returned by `DBMS_LDAP.get_values_blob()`.
FUNCTION value_free_blob	Frees the memory associated with the `BLOB_COLLECTION` returned by `DBMS_LDAP.get_values_blob()`.
FUNCTION modify_s	Performs a synchronous modification of an existing LDAP directory entry. Before calling `add_s`, you must call `DBMS_LDAP.creat_mod_array()` and `DBMS_LDAP.populate_mod_array()`.
FUNCTION add_s	Adds a new entry to the LDAP directory synchronously. Before calling `add_s`, you must call `DBMS_LDAP.creat_mod_array()` and `DBMS_LDAP.populate_mod_array()`.
PROCEDURE free_mod_array	Frees the memory allocated by `DBMS_LDAP.create_mod_array()`.
FUNCTION count_values	Counts the number of values returned by `DBMS_LDAP.get_values()`.
FUNCTION count_values_len	Counts the number of values returned by `DBMS_LDAP.get_values_len ()`.
FUNCTION rename_s	Renames an LDAP entry synchronously.
FUNCTION explode_dn	Breaks a DN up into its components.
FUNCTION open_ssl	Establishes an SSL (Secure Sockets Layer) connection over an existing LDAP connection.
FUNCTION msgfree	This function frees the chain of messages associated with the message handle returned by synchronous search functions.
FUNCTION ber_free	This function frees the memory associated with a handle to `BER_ELEMENT`.
FUNCTION nls_convert_to_utf8	The `nls_convert_to_utf8` function converts the input string containing database character set data to UTF8 character set data and returns it.
FUNCTION nls_convert_from_utf8	The `nls_convert_from_utf8` function converts the input string containing UTF8 character set data to database character set data and returns it.
FUNCTION nls_get_dbcharset_name	The `nls_get_dbcharset_name` function returns a string containing the database character set name.

12.2 Exception Summary

DBMS_LDAP can generate the exceptions described in Table 12-2.

Table 12-2 DBMS_LDAP Exception Summary

Exception Name	Oracle Error Number	Cause of Exception
general_error	31202	Raised anytime an error is encountered that does not have a specific PL/SQL exception associated with it. The error string contains the description of the problem in the user's language.
init_failed	31203	Raised by `DBMS_LDAP.init()` if there are problems.
invalid_session	31204	Raised by all functions and procedures in the `DBMS_LDAP` package if they are passed an invalid session handle.
invalid_auth_method	31205	Raised by `DBMS_LDAP.bind_s()`if the authentication method requested is not supported.
invalid_search_scope	31206	Raised by all search functions if the scope of the search is invalid.
invalid_search_time_val	31207	Raised by `DBMS_LDAP.search_st()`if it is given an invalid value for a time limit.
invalid_message	31208	Raised by all functions that iterate through a result-set for getting entries from a search operation if the message handle given to them is invalid.
count_entry_error	31209	Raised by `DBMS_LDAP.count_entries` if it cannot count the entries in a given result set.
get_dn_error	31210	Raised by `DBMS_LDAP.get_dn` if the DN of the entry it is retrieving is `NULL`.
invalid_entry_dn	31211	Raised by all functions that modify, add, or rename an entry if they are presented with an invalid entry DN.
invalid_mod_array	31212	Raised by all functions that take a modification array as an argument if they are given an invalid modification array.
invalid_mod_option	31213	Raised by `DBMS_LDAP.populate_mod_array` if the modification option given is anything other than `MOD_ADD`, `MOD_DELETE` or `MOD_REPLACE`.
invalid_mod_type	31214	Raised by `DBMS_LDAP.populate_mod_array` if the attribute type that is being modified is `NULL`.
invalid_mod_value	31215	Raised by `DBMS_LDAP.populate_mod_array` if the modification value parameter for a given attribute is `NULL`.
invalid_rdn	31216	Raised by all functions and procedures that expect a valid RDN and are provided with an invalid one.
invalid_newparent	31217	Raised by `DBMS_LDAP.rename_s` if the new parent of an entry being renamed is `NULL`.
invalid_deleteoldrdn	31218	Raised by `DBMS_LDAP.rename_s` if the `deleteoldrdn` parameter is invalid.
invalid_notypes	31219	Raised by `DBMS_LDAP.explode_dn` if the `notypes` parameter is invalid.
invalid_ssl_wallet_loc	31220	Raised by `DBMS_LDAP.open_ssl` if the wallet location is `NULL` but the SSL authentication mode requires a valid wallet.
invalid_ssl_wallet_password	31221	Raised by `DBMS_LDAP.open_ssl` if the wallet password given is `NULL`.
invalid_ssl_auth_mode	31222	Raised by `DBMS_LDAP.open_ssl` if the SSL authentication mode is not `1`, `2` or `3`.

12.3 Data Type Summary

The DBMS_LDAP package uses the data types described in Table 12-3.

Table 12-3 DBMS_LDAP Data Type Summary

Data-Type	Purpose
SESSION	Used to hold the handle of the LDAP session. Nearly all of the functions in the API require a valid LDAP session to work.
MESSAGE	Used to hold a handle to the message retrieved from the result set. This is used by all functions that work with entry attributes and values.
MOD_ARRAY	Used to hold a handle to the array of modifications being passed to either `modify_s()` or `add_s()`.
TIMEVAL	Used to pass time limit information to the LDAP API functions that require a time limit.
BER_ELEMENT	Used to hold a handle to a `BER` structure used for decoding incoming messages.
STRING_COLLECTION	Used to hold a list of `VARCHAR2` strings that can be passed on to the LDAP server.
BINVAL_COLLECTION	Used to hold a list of `RAW` data, which represent binary data.
BERVAL_COLLECTION	Used to hold a list of `BERVAL` values that are used for populating a modification array.
BLOB_COLLECTION	Used to hold a list of `BLOB` data, which represent binary data.

12.4 Subprograms

This section takes a closer look at each of the DBMS_LDAP subprograms.

12.4.1 FUNCTION init

init() initializes a session with an LDAP server. This actually establishes a connection with the LDAP server.

Syntax

FUNCTION init      
(

hostname IN VARCHAR2,
portnum  IN PLS_INTEGER

RETURN SESSION;

Parameters

Table 12-4 INIT Function Parameters

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

Return Values

Table 12-5 INIT Function Return Values

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

Exceptions

Table 12-6 INIT Function Exceptions

Exception	Description
init_failed	Raised when there is a problem contacting the LDAP server.
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 because it establishes a session with the LDAP server. Function 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 will return NULL and raise the INIT_FAILED exception if the session cannot be initialized. After init() has been called, the connection has to be authenticated using DBMS_LDAP.bind_s or DBMS_LDAP.simple_bind_s().

See Also

DBMS_LDAP.simple_bind_s(), DBMS_LDAP.bind_s().

12.4.2 FUNCTION simple_bind_s

The function simple_bind_s can be used to perform simple user name and password authentication to the directory server.

Syntax

FUNCTION simple_bind_s 
(

ld     IN SESSION,
dn     IN VARCHAR2,
passwd IN VARCHAR2

RETURN PLS_INTEGER;

Parameters

Table 12-7 SIMPLE_BIND_S Function Parameters

Parameter	Description
ld	A valid LDAP session handle.
dn	The Distinguished Name of the User that we are trying to login as.
passwd	A text string containing the password.

Return Values

Table 12-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 following exceptions will be raised.

Exceptions

Table 12-9 SIMPLE_BIND_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 will explain 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().

12.4.3 FUNCTION bind_s

The function bind_s can be used to perform complex authentication to the directory server.

Syntax

FUNCTION  bind_s 
(

ld     IN SESSION,
dn     IN VARCHAR2,
cred IN VARCHAR2,
meth IN PLS_INTEGER

RETURN PLS_INTEGER;

Parameters

Table 12-10 BIND_S Function Parameters

Parameter	Description
ld	A valid LDAP session handle.
dn	The distinguished name of the user.
cred	A text string containing the credentials used for authentication.
meth	The authentication method.

Return Values

Table 12-11 BIND_S Function Return Values

Value	Description
PLS_INTEGER	`DBMS_LDAP.SUCCESS` upon successful completion. One of the following exceptions is raised if there is a problem.

Exceptions

Table 12-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.
general_error	For all other errors. The error string associated with this exception will explain 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().

See Also

DBMS_LDAP.init(), DBMS_LDAP.simple_bind_s().

12.4.4 FUNCTION unbind_s

The function unbind_s is used for closing an active LDAP session.

Syntax

FUNCTION unbind_s 
(

ld IN OUT SESSION

RETURN PLS_INTEGER;

Parameters

Table 12-13 UNBIND_S Function Parameters

Parameter	Description
ld	A valid LDAP session handle.

Return Values

Table 12-14 UNBIND_S Function Return Values

Value	Description
PLS_INTEGER	`DBMS_LDAP.SUCCESS` on proper completion. One of the following exceptions is raised otherwise.

Exceptions

Table 12-15 UNBIND_S Function Exceptions

Exception	Description
invalid_session	Raised if the sessions handle `ld` is invalid.
general_error	For all other errors. The error string associated with this exception will explain 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.

See Also

DBMS_LDAP.bind_s(), DBMS_LDAP.simple_bind_s().

12.4.5 FUNCTION compare_s

The function compare_s can be used to test if a particular attribute in a particular entry has a particular value.

Syntax

FUNCTION compare_s 
(

ld    IN SESSION,
dn    IN VARCHAR2,
attr  IN VARCHAR2,
value IN VARCHAR2

RETURN PLS_INTEGER;

Parameters

Table 12-16 COMPARE_S Function Parameters

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

Return Values

Table 12-17 COMPARE_S Function Return Values

Value Description

Value	Description
PLS_INTEGER	`COMPARE_TRUE` if the given attribute has a matching value. `COMPARE_FALSE` if the given attribute does not have a matching value.

PLS_INTEGER

COMPARE_TRUE if the given attribute has a matching value.

COMPARE_FALSE if the given attribute does not have a matching value.

Exceptions

Table 12-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 will explain the error in detail.

Usage Notes

The function compare_s can be used to assert that an attribute in the directory has a certain value. This operation can be performed only on attributes whose syntax enables them to be compared. The compare_s function can be called only after a valid LDAP session handle has been obtained from the init() function and authenticated by the bind_s() or simple_bind_s() functions.

See Also

DBMS_LDAP.bind_s()

12.4.6 FUNCTION search_s

The function search_s performs a synchronous search in the directory. 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 12-19 SEARCH_S Function Parameters

Parameter	Description
ld	A valid LDAP session handle.
base	The DN of the entry at which to start the search.
scope	One of `SCOPE_BASE (0x00)`, `SCOPE_ONELEVEL (0x01)`, or `SCOPE_SUBTREE (0x02)`, indicating the scope of the search.
filter	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	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")` may be used as the only string in the array to indicate that no attribute types are to be 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 to be returned.
attrsonly	A boolean value that must be zero if both attribute types and values are to be returned, and nonzero if only types are wanted.
res	This is a result parameter that contains the results of the search upon completion of the call. If no results are returned, `*res` is set to `NULL`.

Return Values

Table 12-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	If the search succeeded and there are entries, this parameter is set to a non-null value which can be used to iterate through the result set.

Exceptions

Table 12-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 will explain the error in detail.

Usage Notes

The function search_s() 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, and values can be extracted by calling the parsing routines described in this chapter.

See Also

DBMS_LDAP.search_st(), DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry.

12.4.7 FUNCTION search_st

The function search_st() performs a synchronous search in the LDAP server with a client-side time out. 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

FUNCTION 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 12-22 SEARCH_ST Function Parameters

Parameter	Description
ld	A valid LDAP session handle.
base	The DN of the entry at which to start the search.
scope	One of `SCOPE_BASE (0x00)`, `SCOPE_ONELEVEL (0x01)`, or `SCOPE_SUBTREE (0x02)`, indicating the scope of the search.
filter	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	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")` may be used as the only string in the array to indicate that no attribute types are to be 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 to be returned.
attrsonly	A boolean value that must be zero if both attribute types and values are to be returned, and nonzero if only types are wanted.
tv	The time out value, expressed in seconds and microseconds, that should be used for this search.
res	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 12-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	If the search succeeded and there are entries, this parameter is set to a non-null value which can be used to iterate through the result set.

Exceptions

Table 12-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 time out is invalid.
general_error	For all other errors. The error string associated with this exception will explain the error in detail.

Usage Notes

This function is very similar to DBMS_LDAP.search_s() except that it requires a time out value to be given.

See Also

DBMS_LDAP.search_s(), DBML_LDAP.first_entry(), DBMS_LDAP.next_entry.

12.4.8 FUNCTION first_entry

The function first_entry() is used to retrieve the first entry in the result set returned by either search_s() or search_st().

Syntax

FUNCTION first_entry 
(

ld  IN SESSION,
msg IN MESSAGE

RETURN MESSAGE;

Parameters

Table 12-25 FIRST_ENTRY Function Parameters

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

Return Values

Table 12-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 12-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.

See Also

DBMS_LDAP.next_entry(), DBMS_LDAP.search_s(), DBMS_LDAP.search_st()

12.4.9 FUNCTION next_entry

The function next_entry() is used to iterate to the next entry in the result set of a search operation.

Syntax

FUNCTION next_entry 
(

ld  IN SESSION,
msg IN MESSAGE

RETURN MESSAGE;

Parameters

Table 12-28 NEXT_ENTRY Function Parameters

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

Return Values

Table 12-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 12-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 the function 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 the function next_entry() to fetch the next entry in the list.

See Also

DBMS_LDAP.first_entry(), DBMS_LDAP.search_s(), DBMS_LDAP.search_st()

12.4.10 FUNCTION count_entries

This function is used to count 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().

Syntax

FUNCTION count_entries 
(

ld  IN SESSION,
msg IN MESSAGE

RETURN PLS_INTEGER;

Parameters

Table 12-31 COUNT_ENTRY Function Parameters

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

Return Values

Table 12-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 12-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

count_entries() 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(), next_reference().

See Also

DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry().

12.4.11 FUNCTION first_attribute

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

Syntax

FUNCTION first_attribute     
(

ld          IN  SESSION,
ldapentry   IN  MESSAGE,
ber_elem    OUT BER_ELEMENT

RETURN VARCHAR2;

Parameters

Table 12-34 FIRST_ATTRIBUTE Function Parameters

Parameter	Description
ld	A valid LDAP session handle.
ldapentry	The entry whose attributes are to be stepped through, as returned by `first_entry()` or `next_entry()`.
ber_elem	A handle to a `BER_ELEMENT` that is used to keep track of attributes in the entry that have already been read.

Return Values

Table 12-35 FIRST_ATTRIBUTE Function Return Values

Value Description

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

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 12-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.

See Also

DBMS_LDAP.next_attribute(), DBMS_LDAP.get_values(), DBMS_LDAP.get_values_len(), DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry().

12.4.12 FUNCTION next_attribute

The function next_attribute() retrieves the next attribute of a given entry in the result set.

Syntax

FUNCTION next_attribute 
(

ld       IN SESSION,
ldapentry      IN MESSAGE,
ber_elem IN BER_ELEMENT

RETURN VARCHAR2;

Parameters

Table 12-37 NEXT_ATTRIBUTE Function Parameters

Parameter	Description
ld	A valid LDAP session handle.
ldapentry	The entry whose attributes are to be stepped through, as returned by `first_entry()` or `next_entry()`.
ber_elem	A handle to a `BER_ELEMENT` that is used to keep track of attributes in the entry that have been read.

Return Values

Table 12-38 NEXT_ATTRIBUTE Function Return Values

Value	Description
VARCHAR2 (function return)	The name of the attribute if it exists.

Value

Description

VARCHAR2

(function return)

The name of the attribute if it exists.

Exceptions

Table 12-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 the functions get_values() or get_values_len() to get the values of that particular attribute.

See Also

DBMS_LDAP.first_attribute(), DBMS_LDAP.get_values(), DBMS_LDAP.get_values_len(), DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry().

12.4.13 FUNCTION get_dn

The function get_dn() retrieves the X.500 distinguished name of given entry in the result set.

Syntax

FUNCTION get_dn
(

ld  IN SESSION,
ldapentrymsg IN MESSAGE

RETURN VARCHAR2;

Parameters

Table 12-40 GET_DN Function Parameters

Parameter	Description
ld	A valid LDAP session handle.
ldapentry	The entry whose DN is to be returned.

Return Values

Table 12-41 GET_DN Function Return Values

Value Description

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

VARCHAR2

The X.500 Distinguished name of the entry as a PL/SQL string.

NULL if there was a problem.

Exceptions

Table 12-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 can in turn be used as an input to explode_dn() to retrieve the individual components of the DN.

See Also

DBMS_LDAP.explode_dn().

12.4.14 FUNCTION get_values

The function get_values() can be used to retrieve all of the values associated with a given attribute in a given entry.

Syntax

FUNCTION get_values
(

ld   IN SESSION,
ldapentry IN MESSAGE,
attr IN VARCHAR2

RETURN STRING_COLLECTION;

Parameters

Table 12-43 GET_VALUES Function Parameters

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

Return Values

Table 12-44 GET_VALUES Function Return Values

Value Description

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.

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 12-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 call to either first_entry() or next_entry(). The name of the attribute may be known beforehand or can be determined by a call to first_attribute() or next_attribute().The function get_values() always assumes that the data type of the attribute it is retrieving is a string. For retrieving binary data types, get_values_len() should be used.

See Also

DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry(), DBMS_LDAP.count_values(), DBMS_LDAP.get_values_len().

12.4.15 FUNCTION get_values_len

The function get_values_len() can be used to retrieve values of attributes that have a binary syntax.

Syntax

FUNCTION get_values_len
(

ld   IN SESSION,
ldapentry IN MESSAGE,
attr IN VARCHAR2

RETURN BINVAL_COLLECTION;

Parameters

Table 12-46 GET_VALUES_LEN Function Parameters

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

Return Values

Table 12-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 12-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 an entry has been retrieved by a call to either first_entry() or next_entry().The name of the attribute may be known beforehand or can also be determined by a call to first_attribute() or next_attribute().This function can be used to retrieve both binary and non-binary attribute values.

See Also

DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry(), DBMS_LDAP.count_values_len(), DBMS_LDAP.get_values().

12.4.16 FUNCTION delete_s

The function delete_s() can be used to remove a leaf entry in the DIT.

Syntax

FUNCTION delete_s
(

ld      IN SESSION,
entrydn IN VARCHAR2

RETURN PLS_INTEGER;

Parameters

Table 12-49 DELETE_S Function Parameters

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

Return Values

Table 12-50 DELETE_S Function Return Values

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

Exceptions

Table 12-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 will explain the error in detail.

Usage Notes

The function delete_s() can be used to remove only leaf entries in the DIT. A leaf entry is an entry that does not have any entries under it. This function cannot be used to delete non-leaf entries.

See Also

DBMS_LDAP.modrdn2_s().

12.4.17 FUNCTION modrdn2_s

The function modrdn2_s() can be used to rename the relative distinguished name of an entry.

Syntax

FUNCTION modrdn2_s 
(

ld IN SESSION,
entrydn in VARCHAR2
newrdn in VARCHAR2
deleteoldrdn IN PLS_INTEGER

RETURN PLS_INTEGER;

Parameters

Table 12-52 MODRDN2_S Function Parameters

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

Return Values

Table 12-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 12-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 will explain the error in detail.

Usage Notes

The function nodrdn2_s() 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 fulfills the same purpose.

See Also

DBMS_LDAP.rename_s().

12.4.18 FUNCTION err2string

The function err2string() can be used to convert an LDAP error code to a string in the local language in which the API is operating.

Syntax

FUNCTION err2string
(

ldap_err IN PLS_INTEGER

RETURN VARCHAR2;

Parameters

Table 12-55 ERR2STRING Function Parameters

Parameter	Description
ldap_err	An error number returned from one of the API calls.

Return Values

Table 12-56 ERR2STRING Function Return Values

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

Exceptions

err2string() raises no exceptions.

Usage Notes

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

12.4.19 FUNCTION create_mod_array

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

Syntax

FUNCTION create_mod_array 
(

num IN PLS_INTEGER

RETURN MOD_ARRAY;

Parameters

Table 12-57 CREATE_MOD_ARRAY Function Parameters

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

Return Values

Table 12-58 CREATE_MOD_ARRAY Function Return Values

Value Description

MOD_ARRAY

The data structure holds a pointer to an LDAP mod array.

Returns NULL if there was a problem.

Exceptions

create_mod_array() raises no exceptions.

Usage Notes

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

See Also

DBMS_LDAP.populate_mod_array(), DBMS_LDAP.modify_s(), DBMS_LDAP.add_s(), and DBMS_LDAP.free_mod_array().

12.4.20 PROCEDURE populate_mod_array (String Version)

Populates one set of attribute information for add or modify operations.

Syntax

PROCEDURE 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 12-59 POPULATE_MOD_ARRAY (String Version) Procedure Parameters

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

Exceptions

Table 12-60 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.

See Also

DBMS_LDAP.create_mod_array(), DBMS_LDAP.modify_s(), DBMS_LDAP.add_s(), and DBMS_LDAP.free_mod_array().

12.4.21 PROCEDURE populate_mod_array (Binary Version)

Populates one set of attribute information for add or modify operations. This procedure call occurs 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,
modbval  IN DBMS_LDAP.BERVAL_COLLECTION

);

Parameters

Table 12-61 POPULATE_MOD_ARRAY (Binary Version) Procedure Parameters

Parameter	Description
modptr	This data structure holds a pointer to an LDAP mod array.
mod_op	This field specifies the type of modification to perform.
mod_type	This field indicates the name of the attribute type to which the modification applies.
modbval	This field specifies the attribute values to add, delete, or replace. It is for the binary values.

Exceptions

Table 12-62 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 is invoked after DBMS_LDAP.create_mod_array is called.

See Also

DBMS_LDAP.create_mod_array(), DBMS_LDAP.modify_s(), DBMS_LDAP.add_s(), and DBMS_LDAP.free_mod_array().

12.4.22 PROCEDURE populate_mod_array (Binary Version. Uses BLOB Data Type)

Populates one set of attribute information for add or modify operations. This procedure call occurs 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,
modbval IN DBMS_LDAP.BLOB_COLLECTION
);

Parameters

Table 12-63 POPULATE_MOD_ARRAY (Binary) Parameters

Parameter	Description
modptr	This data structure holds a pointer to an LDAP mod array.
mod_op	This field specifies the type of modification to perform.
mod_type	This field indicates the name of the attribute type to which the modification applies.
modbval	This field specifies the binary attribute values to add, delete, or replace.

Exceptions

Table 12-64 POPULATE_MOD_ARRAY (Binary) 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 is invoked after DBMS_LDAP.create_mod_array is called.

See Also

DBMS_LDAP.create_mod_array(), DBMS_LDAP.modify_s(), DBMS_LDAP.add_s(), and DBMS_LDAP.free_mod_array().

12.4.23 FUNCTION get_values_blob

The function get_values_blob() can be used to retrieve larger values of attributes that have a binary syntax.

Syntax

Syntax
FUNCTION get_values_blob
(
ld IN SESSION,
ldapentry IN MESSAGE,
attr IN VARCHAR2
)
RETURN BLOB_COLLECTION;

Parameters

Table 12-65 GET_VALUES_BLOB Parameters

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

Return Values

Table 12-66 get_values_blob Return Values

Value	Description
BLOB_COLLECTION	A PL/SQL BLOB collection containing all the values of the given attribute.
NULL	No values are associated with the given attribute.

Exceptions

Table 12-67 get_values_blob 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_blob() can only be called after the handle to an entry has been retrieved by a call to either first_entry() or next_entry(). The name of the attribute may be known beforehand or 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.

See Also

DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry(), DBMS_LDAP.count_values_blob(), DBMS_LDAP.get_values().

12.4.24 FUNCTION count_values_blob

Counts the number of values returned by DBMS_LDAP.get_values_blob().

Syntax

FUNCTION count_values_blob
(
values IN DBMS_LDAP.BLOB_COLLECTION
)
RETURN PLS_INTEGER;

Parameters

Table 12-68 COUNT_VALUES_BLOB Parameters

Parameter	Description
values	The collection of large binary values.

Return Values

Table 12-69 COUNT_VALUES_BLOB Return Values

Values	Description
PLS_INTEGER	Indicates the success or failure of the operation.

Exceptions

The function count_values_blob() raises no exceptions.

See Also

DBMS_LDAP.count_values(), DBMS_LDAP.get_values_blob().

12.4.25 FUNCTION value_free_blob

Frees the memory associated with BLOB_COLLECTION returned by DBMS_LDAP.get_values_blob().

Syntax

PROCEDURE value_free_blob
(
vals IN OUT DBMS_LDAP.BLOB_COLLECTION
);

Parameters

Table 12-70 VALUE_FREE_BLOB Parameters

Parameter	Description
vals	The collection of large binary values returned by `DBMS_LDAP.get_values_blob()`.

Exceptions

value_free_blob() raises no exceptions.

See Also

DBMS_LDAP.get_values_blob().

12.4.26 FUNCTION modify_s

Performs a synchronous modification of an existing LDAP directory entry.

Syntax

FUNCTION modify_s
(

ld      IN DBMS_LDAP.SESSION,
entrydn IN VARCHAR2,
modptr  IN DBMS_LDAP.MOD_ARRAY

RETURN PLS_INTEGER;

Parameters

Table 12-71 MODIFY_S Function Parameters

Parameter	Description
ld	This parameter is a handle to an LDAP session returned by a successful call to `DBMS_LDAP.init()`.
entrydn	This parameter specifies the name of the directory entry whose contents are to be modified.
modptr	This parameter is the handle to an LDAP mod structure, as returned by successful call to `DBMS_LDAP.create_mod_array()`.

Return Values

Table 12-72 MODIFY_S Function Return Values

Value	Description
PLS_INTEGER	Indicates the success or failure of the modification operation.

Exceptions

Table 12-73 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().

See Also

DBMS_LDAP.create_mod_array(),DBMS_LDAP.populate_mod_array(), DBMS_LDAP.add_s(), and DBMS_LDAP.free_mod_array().

12.4.27 FUNCTION add_s

Adds a new entry to the LDAP directory synchronously. Before calling add_s, DBMS_LDAP.create_mod_array() and DBMS_LDAP.populate_mod_array() must be called.

Syntax

FUNCTION add_s
(

ld      IN DBMS_LDAP.SESSION,
entrydn IN VARCHAR2,
modptr  IN DBMS_LDAP.MOD_ARRAY

RETURN PLS_INTEGER;

Parameters

Table 12-74 ADD_S Function Parameters

Parameter	Description
ld	This parameter is a handle to an LDAP session, as returned by a successful call to `DBMS_LDAP.init()`.
entrydn	This parameter specifies the name of the directory entry to be created.
modptr	This parameter is the handle to an LDAP mod structure, as returned by successful call to `DBMS_LDAP.create_mod_array()`.

Return Values

Table 12-75 ADD_S Function Return Values

Value	Description
PLS_INTEGER	Indicates the success or failure of the modification operation.

Exceptions

Table 12-76 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 to DBMS_LDAP.create_mod_array() and DBMS_LDAP.populate_mod_array().

See Also

DBMS_LDAP.create_mod_array(), DBMS_LDAP.populate_mod_array(), DBMS_LDAP.modify_s(), and DBMS_LDAP.free_mod_array().

12.4.28 PROCEDURE free_mod_array

Frees the memory allocated by DBMS_LDAP.create_mod_array().

Syntax

PROCEDURE free_mod_array
(

modptr IN DBMS_LDAP.MOD_ARRAY

);

Parameters

Table 12-77 FREE_MOD_ARRAY Procedure Parameters

Parameter	Description
modptr	This parameter is the handle to an LDAP mod structure returned by a successful call to `DBMS_LDAP.create_mod_array()`.

Exceptions

free_mod_array raises no exceptions.

See Also

DBMS_LDAP.populate_mod_array(), DBMS_LDAP.modify_s(), DBMS_LDAP.add_s(), and DBMS_LDAP.create_mod_array().

12.4.29 FUNCTION count_values

Counts the number of values returned by DBMS_LDAP.get_values().

Syntax

FUNCTION count_values
(

values IN DBMS_LDAP.STRING_COLLECTION

RETURN PLS_INTEGER;

Parameters

Table 12-78 COUNT_VALUES Function Parameters

Parameter	Description
values	The collection of string values.

Return Values

Table 12-79 COUNT_VALUES Function Return Values

Value	Description
PLS_INTEGER	Indicates the success or failure of the operation.

Exceptions

count_values raises no exceptions.

See Also

DBMS_LDAP.count_values_len(), DBMS_LDAP.get_values().

12.4.30 FUNCTION count_values_len

Counts the number of values returned by DBMS_LDAP.get_values_len().

Syntax

FUNCTION count_values_len 
(

values IN DBMS_LDAP.BINVAL_COLLECTION

RETURN PLS_INTEGER;

Parameters

Table 12-80 COUNT_VALUES_LEN Function Parameters

Parameter	Description
values	The collection of binary values.

Return Values

Table 12-81 COUNT_VALUES_LEN Function Return Values

Value	Description
PLS_INTEGER	Indicates the success or failure of the operation.

Exceptions

count_values_len raises no exceptions.

See Also

DBMS_LDAP.count_values(), DBMS_LDAP.get_values_len().

12.4.31 FUNCTION rename_s

Renames an LDAP entry synchronously.

Syntax

FUNCTION 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 12-82 RENAME_S Function Parameters

Parameter	Description
ld	This parameter is a handle to an LDAP session returned by a successful call to `DBMS_LDAP.init()`.
dn	This parameter specifies the name of the directory entry to be renamed or moved.
newrdn	This parameter specifies the new RDN.
newparent	This parameter specifies the DN of the new parent.
deleteoldrdn	This parameter specifies whether the old RDN should be retained. If this value is `1`, the old RDN is removed.
serverctrls	Currently not supported.
clientctrls	Currently not supported.

Return Values

Table 12-83 RENAME_S Function Return Values

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

Exceptions

Table 12-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.

See Also

DBMS_LDAP.modrdn2_s().

12.4.32 FUNCTION explode_dn

Breaks a DN up into its components.

Syntax

FUNCTION explode_dn 
(

dn      IN VARCHAR2,
notypes IN PLS_INTEGER

RETURN STRING_COLLECTION;

Parameters

Table 12-85 EXPLODE_DN Function Parameters

Parameter	Description
dn	This parameter specifies the name of the directory entry to be broken up.
notypes	This parameter specifies whether the attribute tags will be returned. If this value is not `0`, no attribute tags are returned.

Return Values

Table 12-86 EXPLODE_DN Function Return Values

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

Exceptions

Table 12-87 EXPLODE_DN Function Exceptions

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

See Also

DBMS_LDAP.get_dn().

12.4.33 FUNCTION open_ssl

Establishes an SSL (Secure Sockets Layer) connection over an existing LDAP connection.

Syntax

FUNCTION open_ssl
(

ld              IN SESSION,
sslwrl          IN VARCHAR2,
sslwalletpasswd IN VARCHAR2,
sslauth         IN PLS_INTEGER

RETURN PLS_INTEGER;

Parameters

Table 12-88 OPEN_SSL Function Parameters

Parameter	Description
ld	This parameter is a handle to an LDAP session that is returned by a successful call to `DBMS_LDAP.init()`.
sslwrl	This parameter specifies the wallet location. Required for one-way or two-way SSL connections.
sslwalletpasswd	This parameter specifies the wallet password. Required for one-way or two-way SSL connections.
sslauth	This parameter specifies the SSL Authentication Mode. (`1` for no authentication, `2` for one-way authentication required, `3` for two-way authentication).

Return Values

Table 12-89 OPEN_SSL Function Return Values

Value	Description
PLS_INTEGER	Indicates the success or failure of the operation.

Exceptions

Table 12-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 password.
invalid_ssl_auth_mode	Invalid LDAP SSL authentication mode.

Usage Notes

Need to call DBMS_LDAP.init() first to acquire a valid ldap session.

See Also

DBMS_LDAP.init().

12.4.34 FUNCTION msgfree

This function frees the chain of messages associated with the message handle returned by synchronous search functions.

Syntax

FUNCTION msgfree
(

res             IN MESSAGE

RETURN PLS_INTEGER;

Parameters

Table 12-91 MSGFREE Function Parameters

Parameter	Description
res	The message handle obtained by a call to one of the synchronous search routines.

Return Values

Table 12-92 MSGFREE Return Values

Value Description

PLS_INTEGER

Indicates the type of the last message in the chain.

The function might return any of the following values:

DBMS_LDAP.LDAP_RES_BIND
DBMS_LDAP.LDAP_RES_SEARCH_ENTRY
DBMS_LDAP.LDAP_RES_SEARCH_REFERENCE
DBMS_LDAP.LDAP_RES_SEARCH_RESULT
DBMS_LDAP.LDAP_RES_MODIFY
DBMS_LDAP.LDAP_RES_ADD
DBMS_LDAP.LDAP_RES_DELETE
DBMS_LDAP.LDAP_RES_MODDN
DBMS_LDAP.LDAP_RES_COMPARE
DBMS_LDAP.LDAP_RES_EXTENDED

Exceptions

msgfree raises no exceptions.

See Also

DBMS_LDAP.search_s(), DBMS_LDAP.search_st().

12.4.35 FUNCTION ber_free

This function frees the memory associated with a handle to BER ELEMENT.

Syntax

FUNCTION ber_free 
(

ber_elem IN BER_ELEMENT,
freebuf  IN PLS_INTEGER

Parameters

Table 12-93 BER_FREE Function Parameters

Parameter Description

ber_elem

A handle to BER ELEMENT.

freebuf

The value of this flag should be 0 while the BER ELEMENT returned from DBMS_LDAP.first_attribute() is being freed. For any other case, the value of this flag should be 1.

The default value of this parameter is zero.

Return Values

ber_free returns no values.

Exceptions

ber_free raises no exceptions.

See Also

DBMS_LDAP.first_attribute(),DBMS_LDAP.next_attribute().

12.4.36 FUNCTION nls_convert_to_utf8

The nls_convert_to_utf8() function converts the input string containing database character set data to UTF8 character set data and returns it.

Syntax

Function nls_convert_to_utf8
(
	data_local IN VARCHAR2
)
	RETURN VARCHAR2;

Parameters

Table 12-94 Parameters for nls_convert_to_utf8

Parameter	Description
data_local	Contains the database character set data.

Return Values

Table 12-95 Return Values for nls_convert_to_utf8

Value	Description
VARCHAR2	UTF8 character set data string.

Usage Notes

The functions in DBMS_LDAP package expect the input data to be UTF8 character set data if the UTF8_CONVERSION package variable is set to FALSE. The nls_convert_to_utf8() function converts database character set data to UTF8 character set data.

If the UTF8_CONVERSION package variable of the DBMS_LDAP package is set to TRUE, functions in the DBMS_LDAP package expect input data to be database character set data.

See Also

DBMS_LDAP.nls_convert_from_utf8(), DBMS_LDAP.nls_get_dbcharset_name().

12.4.37 FUNCTION nls_convert_to_utf8

The nls_convert_to_utf8() function converts the input string collection containing database character set data to UTF8 character set data. It then returns the converted data.

Syntax

Function nls_convert_to_utf8
(
	data_local IN STRING_COLLECTION
)
	RETURN STRING_COLLECTION;

Parameters

Table 12-96 Parameters for nls_convert_to_utf8

Parameter	Description
data_local	Collection of strings containing database character set data.

Return Values

Table 12-97 Return Values for nls_convert_to_utf8

Value	Description
STRING_COLLECTION	Collection of strings containing UTF8 character set data.

Usage Notes

The functions in the DBMS_LDAP package expect the input data to be in the UTF8 character set if the UTF8_CONVERSION package variable is set to FALSE. The nls_convert_to_utf8() function converts the input data from the database character set to the UTF8 character set.

If the UTF8_CONVERSION package variable of the DBMS_LDAP package is set to TRUE, functions in the DBMS_LDAP package expect the input data to be in the database character set.

See Also

DBMS_LDAP.nls_convert_from_utf8(), DBMS_LDAP.nls_get_dbcharset_name().

12.4.38 FUNCTION nls_convert_from_utf8

The nls_convert_from_utf8() function converts the input string containing UTF8 character set to database character set data. It then returns this data.

Syntax

Function nls_convert_from_utf8
(
	data_utf8 IN VARCHAR2
)
	RETURN VARCHAR2;

Parameters

Table 12-98 Parameter for nls_convert_from_utf8

Parameter	Description
data_utf8	Contains UTF8 character set data.

Return Values

Table 12-99 Return Value for nls_convert_from_utf8

Value

Description

VARCHAR2

Data string in the database character set.

Usage Notes

The functions in the DBMS_LDAP package return UTF8 character set data if the UTF8_CONVERSION package variable is set to FALSE. The nls_convert_from_utf8() function converts the output data from the UTF8 character set to the database character set.

If the UTF8_CONVERSION package variable of the DBMS_LDAP package is set to TRUE, functions in the DBMS_LDAP package return database character set data.

See Also

DBMS_LDAP.nls_convert_to_utf8(), DBMS_LDAP.nls_get_dbcharset_name().

12.4.39 FUNCTION nls_convert_from_utf8

The nls_convert_from_utf8() function converts the input string collection containing UTF8 character set data to database character set data. It then returns this data.

Syntax

Function nls_convert_from_utf8
(
	data_utf8 IN STRING_COLLECTION
)
	RETURN STRING_COLLECTION;

Parameters

Table 12-100 Parameter for nls_convert_from_utf8

Parameter	Description
data_utf8	Collection of strings containing UTF8 character set data.

Return Values

Table 12-101 Return Value for nls_convert_from_utf8

Value

Description

VARCHAR2

Collection of strings containing database character set data.

Usage Notes

The functions in the DBMS_LDAP package return UTF8 character set data if the UTF8_CONVERSION package variable is set to FALSE. nls_convert_from_utf8() converts the output data from the UTF8 character set to the database character set. If the UTF8_CONVERSION package variable of the DBMS_LDAP package is set to TRUE, functions in the DBMS_LDAP package return database character set data.

See Also

DBMS_LDAP.nls_convert_to_utf8(), DBMS_LDAP.nls_get_dbcharset_name().

12.4.40 FUNCTION nls_get_dbcharset_name

The nls_get_dbcharset_name() function returns a string containing the database character set name.

Syntax

Function nls_get_dbcharset_name

	RETURN VARCHAR2;

Parameters

None.

Return Values

Table 12-102 Return Value for nls_get_dbcharset_name

Value

Description

VARCHAR2

String containing the database character set name.

See Also

DBMS_LDAP.nls_convert_to_utf8(), DBMS_LDAP.nls_convert_from_utf8().