DBA Tips Archive for Oracle

  


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

by Jeff Hunter, Sr. Database Administrator


Contents

  1. About the OID PL/SQL API
  2. Building Applications with the OID PL/SQL API
  3. Summary of Subprograms
  4. Exception Summary
  5. 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:

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:

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.


Copyright (c) 1998-2017 Jeffrey M. Hunter. All rights reserved.

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: 9526