ORACLE - DBA Tips Corner

Oracle DBA Tips Corner

Return to the Oracle DBA Tips Corner.

Installing the Oracle Internet Directory PL/SQL API - (Version 9.2.0)

by Jeff Hunter, Sr. Database Administrator

Contents

About the OID PL/SQL API
Building Applications with the OID PL/SQL API
Summary of Subprograms
Exception Summary
Data-Type Summary

About the OID PL/SQL API

The PL/SQL API is packaged in the DBMS_LDAP package. It is based on the C API described in the previous section.
You can use the Oracle Internet Directory API release 3.0.1 in the following modes:

SSL-All communication secured using SSL
Non-SSL-Client-to-server communication not secure

The API uses TCP/IP to connect to an LDAP server. When it does this, it uses, by default, an unencrypted channel. To use the SSL mode, you must use the Oracle SSL call interface. You determine which mode you are using by the presence or absence of the SSL calls in the API usage. You can easily switch between SSL and non-SSL modes.
Using the PL/SQL API from a Database Trigger
The DBMS_LDAP API can be invoked from database triggers to synchronize any changes to a database table with an enterprise-wide LDAP server. The following example illustrates how changes to a table called 'EMP' are synchronized with the data in an LDAP server using triggers for insert, update, and delete.
Examples can be found in the plsql directory under $ORACLE_HOME/ldap/demo.

Building Applications with the OID PL/SQL API

To use the PL/SQL LDAP API, you must first load it into the database. You do this by using a script called catldap.sql that is located in the $ORACLE_HOME/rdbms/admin directory.
You must be connected as SYSDBA using the SQL*Plus command line tool.
The following is a sample command sequence that you can use to load the DBMS_LDAP package:
SQL> CONNECT / AS SYSDBA
SQL>  @?/rdbms/admin/catldap.sql
Dependencies and Limitations
The PL/SQL LDAP API for this release has the following limitations:

The LDAP session handles obtained from the API are valid only for the duration of the database session. The LDAP session handles cannot be written to a table and re-used in other database sessions.
Only synchronous versions of LDAP API functions are supported in this release.
The PL/SQL LDAP API requires a database connection to work. It cannot be used in client-side PL/SQL engines (like Oracle Forms) without a valid database connection.

PL/SQL Reference
The PL/SQL package DBMS_LDAP contains the functions and procedures which can be used by PL/SQL programmers to access data from LDAP servers. This section explains all of the API functions in detail.

Summary of 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/password based 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 given entry in the result set.

FUNCTION -- get_values The function get_values() can be used to retrieve all of the values associated for 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 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 happen after DBMS_LDAP.create_mod_array() is called.

FUNCTION -- modify_s Performs a synchronous modification of an existing LDAP directory entry. Before calling add_s, we have to call DBMS_LDAP.creat_mod_array () and DBMS_LDAP.populate_mod_array() first.

FUNCTION -- add_s 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.

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.

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

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 entries attributes and values.

MOD_ARRAY Used to hold a handle into the array of modifications being passed into 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 which 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 forpopulating a modification array.

All articles, scripts and material located at the Internet address of http://www.idevelopment.info is the copyright of Jeffrey M. Hunter and is protected under copyright laws of the United States. This document may not be hosted on any other site without my express, prior, written permission. Application to host any of the material elsewhere can be made by contacting me at jhunter@idevelopment.info.

I have made every effort and taken great care in making sure that the material included on my web site is technically accurate, but I disclaim any and all responsibility for any loss, damage or destruction of data or any other property which may arise from relying on it. I will in no case be liable for any monetary damages arising from such loss, damage or destruction.

Last modified on
Friday, 20-Jan-2006 15:37:37 EST
Page Count: 5479

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/password based 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 given entry in the result set.
FUNCTION -- get_values	The function get_values() can be used to retrieve all of the values associated for 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 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 happen after DBMS_LDAP.create_mod_array() is called.
FUNCTION -- modify_s	Performs a synchronous modification of an existing LDAP directory entry. Before calling add_s, we have to call DBMS_LDAP.creat_mod_array () and DBMS_LDAP.populate_mod_array() first.
FUNCTION -- add_s	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.
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.

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

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 entries attributes and values.
MOD_ARRAY	Used to hold a handle into the array of modifications being passed into 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 which 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 forpopulating a modification array.