20
DBMS_LDAP

DBMS_LDAP provides functions and procedures to access data from LDAP servers. To use DBMS_LDAP, you must first load it into the database. Use the catldap.sql script located in the $ORACLE_HOME/rdbms/admin directory.

See Also: Oracle Internet Directory Application Developer's Guide for more information on using DBMS_LDAP.

This chapter discusses the following topics:

• Exception Summary

• Summary of Data Types

• Summary of DBMS_LDAP Subprograms

Exception Summary

Table 20-1 lists the exceptions generated by DBMS_LDAP.

Table 20-1 DBMS_LDAP Exception Summary

Exception Name	Oracle Error	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 local language of the user.
init_failed	31203	Raised by DBMS_LDAP.init if there are some 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 of the search functions if the scope of the search is invalid.
invalid_search_time_val	31207	Raised by time based search function: DBMS_LDAP.search_st if it is given an invalid value for the 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 the functions that modify/add/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 if the value of the RDN is NULL.
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 one of 1, 2, or 3.
mts_mode_not_supported	31398	Raised by the functions init, bind_s or simple_bind_s if they are ever invoked in MTS mode.

Summary of Data Types

The DBMS_LDAP package uses the data types shown in Table 20-2.

Table 20-2 DBMS_LDAP Summary of Data Types

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

Summary of DBMS_LDAP Subprograms

Table 20-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"	Converta 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.