Oracle Internet Directory Application Developer's Guide Release 2.1.1 Part Number A86082-01 |
Library | Service | Contents | Index

# 3
PL/SQL API

This chapter introduces the Oracle Internet Directory PL/SQL API and provides examples of how to use it. It contains these topics:

- About the Oracle Internet Directory PL/SQL API

- Sample PL/SQL Usage

- Building Applications with PL/SQL LDAP API

- Dependencies and Limitations

- PL/SQL Reference

## About the Oracle Internet Directory PL/SQL API

The Oracle Internet Directory PL/SQL API is contained in a PL/SQL package called DBMS_LDAP. This package enables PL/SQL applications to access data located in enterprise-wide LDAP servers. The naming and syntax of the function calls are similar to those of the Oracle Internet Directory C API functions. However, the PL/SQL API contains only a subset of the functions available in the C API. In particular, only synchronous calls to the LDAP server are available in the PL/SQL API.

## Sample PL/SQL Usage

This section contains these topics

- Using the PL/SQL API from a Database Trigger

- Using the PL/SQL API for a Search

### 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. There are two files associated with this sample: `trigger.sql` and `empdata.sql`.

The file `trigger.sql` creates the table as well as the triggers associated with it.

The file `empdata.sql` inserts some sample data into the table EMP, which automatically gets updated to the LDAP server through the insert trigger.

These files can be found in the `plsql` directory under `$`ORACLE_HOME`/ldap/demo`

    $Header: $
    Copyright (c) Oracle Corporation 2000. All Rights Reserved.
    FILE
    trigger.sql
    DESCRIPTION
    This SQL file creates a database table called 'EMP' and creates a trigger on it
    called LDAP_EMP which will synchronize all changes happening to the table with
    an LDAP server. The changes to the database table are reflected/replicated to
    the LDAP directory using the DBMS_LDAP package.
    This script assumes the following:
    LDAP server hostname: NULL (local host)
    LDAP server portnumber: 389
    Directory container for employee records: o=acme, dc=com
    Username/Password for Directory Updates: cn=orcladmin/welcome
    The aforementioned variables could be customized for different environments by
    changing the appropriate variables in the code below.
    Table Definition:
    Employee Details(Columns) in Database Table(EMP):
    EMP_ID 	Number
    FIRST_NAME 	Varchar2
    LAST_NAME 	Varchar2
    MANAGER_ID	Number
    PHONE_NUMBER 	Varchar2
    MOBILE 	Varchar2
    ROOM_NUMBER 	Varchar2
    TITLE	Varchar2

    LDAP Schema Definition & mapping to relational schema EMP:
    Corresponding Data representation in LDAP directory:

    DN	cn=FIRST_NAME LAST_NAME, o=acme, dc=com]
    cn	FIRST_NAME LAST_NAME
    sn	LAST_NAME
    givenname	FIRST_NAME
    manager	DN
    telephonenumber	PHONE_NUMBER
    mobile	MOBILE
    employeeNumber	EMP_ID
    userpassword	FIRST_NAME
    objectclass	person

    	organizationalperson
    	inetOrgPerson
    	top

    MODIFIED   (MM/DD/YY)
    rbollu 07/21/00 - created

    --Creating EMP table

    PROMPT Dropping Table EMP ..
    drop table EMP;

    PROMPT Creating Table EMP ..
    CREATE TABLE EMP (

    EMP_ID    NUMBER,	Employee Number
    FIRST_NAME  VARCHAR2(256),	First Name
    LAST_NAME  VARCHAR2(256),	Last Name
    MANAGER_ID  NUMBER,	Manager Number
    PHONE_NUMBER VARCHAR2(256),	Telephone Number
    MOBILE   VARCHAR2(256),	Mobile Number
    ROOM_NUMBER  VARCHAR2(256),	Room Number
    TITLE   VARCHAR2(256)	Title in the company

    );

    --Creating Trigger LDAP_EMP

    PROMPT Creating Trigger LDAP_EMP ..

    CREATE OR REPLACE TRIGGER LDAP_EMP
    AFTER INSERT OR DELETE OR UPDATE ON EMP
    FOR EACH ROW

    DECLARE

    retval   PLS_INTEGER;
    emp_session  DBMS_LDAP.session;
    emp_dn   VARCHAR2(256);
    emp_rdn   VARCHAR2(256);
    emp_array  DBMS_LDAP.MOD_ARRAY;
    emp_vals  DBMS_LDAP.STRING_COLLECTION ;
    ldap_host  VARCHAR2(256);
    ldap_port  VARCHAR2(256);
    ldap_user  VARCHAR2(256);
    ldap_passwd  VARCHAR2(256);
    ldap_base  VARCHAR2(256);

    BEGIN

    retval       := -1;
    -- Customize the following variables as needed
    ldap_host  := NULL;
    ldap_port  := '389';
    ldap_user  := 'cn=orcladmin';
    ldap_passwd:= 'welcome';
    ldap_base  := 'o=acme,dc=com';
    -- end of customizable settings

    DBMS_OUTPUT.PUT('Trigger [LDAP_EMP]: Replicating changes ');
    DBMS_OUTPUT.PUT_LINE('to directory .. ');
    DBMS_OUTPUT.PUT_LINE(RPAD('LDAP Host ',25,' ') || ': ' || ldap_host);
    DBMS_OUTPUT.PUT_LINE(RPAD('LDAP Port ',25,' ') || ': ' || ldap_port);

    -- Choosing exceptions to be raised by DBMS_LDAP library.
    DBMS_LDAP.USE_EXCEPTION := TRUE;

    -- Initialize ldap library and get session handle.
    emp_session := DBMS_LDAP.init(ldap_host,ldap_port);

    DBMS_OUTPUT.PUT_LINE (RPAD('Ldap session ',25,' ')  || ': ' ||

    RAWTOHEX(SUBSTR(emp_session,1,8)) ||
    '(returned from init)');

    -- Bind to the directory
    retval := DBMS_LDAP.simple_bind_s(emp_session,

    ldap_user,ldap_passwd);

    DBMS_OUTPUT.PUT_LINE(RPAD('simple_bind_s Returns ',25,' ') || ': '

              || TO_CHAR(retval));

    -- Process New Entry in the database

    IF INSERTING THEN

    -- Create and setup attribute array for the New entry
    emp_array := DBMS_LDAP.create_mod_array(14);

    -- RDN to be - cn="FIRST_NAME LAST_NAME"

    emp_vals(1) := :new.FIRST_NAME || ' ' || :new.LAST_NAME;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_ADD,
    'cn',emp_vals);

    emp_vals(1) := :new.LAST_NAME;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_ADD,
                'sn',emp_vals);

    emp_vals(1) := :new.FIRST_NAME;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_ADD,
                'givenname',emp_vals);

    emp_vals(1) := 'top';
    emp_vals(2) := 'person';
    emp_vals(3) := 'organizationalPerson';
    emp_vals(4) := 'inetOrgPerson';

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_ADD,
                'objectclass',emp_vals);

    emp_vals.DELETE;
    emp_vals(1) := :new.PHONE_NUMBER;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_ADD,
                'telephonenumber',emp_vals);

    emp_vals(1) := :new.MOBILE;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_ADD,
                'mobile',emp_vals);

    emp_vals(1) := :new.ROOM_NUMBER;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_ADD,
                'roomNumber',emp_vals);

    emp_vals(1) := :new.TITLE;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_ADD,
                'title',emp_vals);

    emp_vals(1) := :new.EMP_ID;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_ADD,
                'employeeNumber',emp_vals);

    emp_vals(1) := :new.FIRST_NAME;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_ADD,
                'userpassword',emp_vals);

    -- DN for Entry to be Added under 'ldap_base' [o=acme, dc=com]

    emp_dn := 'cn=' || :new.FIRST_NAME || ' ' ||
    :new.LAST_NAME || ', ' || ldap_base ;
    DBMS_OUTPUT.PUT_LINE(RPAD('Adding Entry for DN ',25,' ') || ': ['
               || emp_dn || ']');

    -- Add new Entry to ldap directory
    retval := DBMS_LDAP.add_s(emp_session,emp_dn,emp_array);
    DBMS_OUTPUT.PUT_LINE(RPAD('add_s Returns ',25,' ')  || ': '
               || TO_CHAR(retval));

    -- Free attribute array (emp_array)
    DBMS_LDAP.free_mod_array(emp_array);

    END IF; -- INSERTING

    -- Process Entry deletion in database

    IF DELETING THEN

    -- DN for Entry to be deleted under 'ldap_base' [o=acme, dc=com]

    emp_dn := 'cn=' || :old.FIRST_NAME || ' ' ||
    :old.LAST_NAME || ', ' || ldap_base ;
    DBMS_OUTPUT.PUT_LINE(RPAD('Deleting Entry for DN ',25,' ') ||
             ': [' || emp_dn || ']');

    -- Delete entry in ldap directory
    retval := DBMS_LDAP.delete_s(emp_session,emp_dn);
         DBMS_OUTPUT.PUT_LINE(RPAD('delete_s Returns ',25,' ') || ': ' ||
               TO_CHAR(retval));

    END IF; -- DELETING

    -- Process updated Entry in database

    IF UPDATING THEN

    -- Since two Table columns(in this case) constitue a RDN
    -- check for any changes and update RDN in ldap directory
    -- before updating any other attributes of the Entry.

    IF :old.FIRST_NAME <> :new.FIRST_NAME OR
         :old.LAST_NAME  <> :new.LAST_NAME THEN

    emp_dn := 'cn=' || :old.FIRST_NAME || ' ' ||
        :old.LAST_NAME || ', ' || ldap_base;

    emp_rdn := 'cn=' || :new.FIRST_NAME || ' ' || :new.LAST_NAME;

    DBMS_OUTPUT.PUT_LINE(RPAD('Renaming OLD DN ',25,' ') ||
               ': [' || emp_dn || ']');
    DBMS_OUTPUT.PUT_LINE(RPAD(' => NEW RDN ',25,' ') ||
               ': [' || emp_rdn || ']' );
    retval := DBMS_LDAP.modrdn2_s(emp_session,emp_dn,emp_rdn,
                 DBMS_LDAP.MOD_DELETE);
    DBMS_OUTPUT.PUT_LINE(RPAD('modrdn2_s Returns ',25,' ') || ': ' ||
                 TO_CHAR(retval));

    END IF;

    -- DN for Entry to be updated under 'ldap_base' [o=acme, dc=com]

    emp_dn := 'cn=' || :new.FIRST_NAME || ' ' ||
       :new.LAST_NAME || ', ' || ldap_base;

    DBMS_OUTPUT.PUT_LINE(RPAD('Updating Entry for DN ',25,' ') ||
                ': [' || emp_dn || ']');

    -- Create and setup attribute array(emp_array) for updated entry
    emp_array := DBMS_LDAP.create_mod_array(7);

    emp_vals(1) := :new.LAST_NAME;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_REPLACE,
                'sn',emp_vals);

    emp_vals(1) := :new.FIRST_NAME;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_REPLACE,
                'givenname',emp_vals);

    emp_vals(1) := :new.PHONE_NUMBER;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_REPLACE,
                'telephonenumber',emp_vals);

    emp_vals(1) := :new.MOBILE;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_REPLACE,
                'mobile',emp_vals);

    emp_vals(1) := :new.ROOM_NUMBER;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_REPLACE,
                'roomNumber',emp_vals);

    emp_vals(1) := :new.TITLE;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_REPLACE,
                'title',emp_vals);

    emp_vals(1) := :new.EMP_ID;

    DBMS_LDAP.populate_mod_array(emp_array,DBMS_LDAP.MOD_REPLACE,
                'employeeNumber',emp_vals);

    -- Modify entry in ldap directory
      retval := DBMS_LDAP.modify_s(emp_session,emp_dn,emp_array);

    DBMS_OUTPUT.PUT_LINE(RPAD('modify_s Returns ',25,' ') || ': ' ||
                TO_CHAR(retval));

    -- Free attribute array (emp_array)
    DBMS_LDAP.free_mod_array(emp_array);

    END IF; -- UPDATING

    -- Unbind from ldap directory
    retval := DBMS_LDAP.unbind_s(emp_session);

    DBMS_OUTPUT.PUT_LINE(RPAD('unbind_res Returns ',25,' ') ||  ': ' ||
               TO_CHAR(retval));

    DBMS_OUTPUT.PUT_LINE('Directory operation Successful .. exiting');

    -- Handle Exceptions
    EXCEPTION

    WHEN OTHERS THEN
    -- TODO : should the trigger call unbind at this point ??
    --   what if the exception was raised from unbind itself ??

    DBMS_OUTPUT.PUT_LINE(' Error code    : ' || TO_CHAR(SQLCODE));
    DBMS_OUTPUT.PUT_LINE(' Error Message : ' || SQLERRM);
    DBMS_OUTPUT.PUT_LINE(' Exception encountered .. exiting');

    END;
    /
    -------------------------------END OF trigger.sql---------------------------

### Using the PL/SQL API for a Search

The following example illustrates using the DBMS_LDAP API to perform an LDAP search in a PL/SQL program. This example searches for the entries created using the trigger example described previously. It assumes a base of `o=acme,dc=com` and performs a subtree search to retrieve all entries that are subordinates of the base entry. The code shown below is contained in a file called `search.sql` which can be found in the `$`ORACLE_HOME`/ldap/demo/plsql` directory.

    $Header: $

    Copyright (c) Oracle Corporation 2000. All Rights Reserved.

    FILE

    search.sql

    DESCRIPTION

    This SQL file contains the PL/SQL code required to perform
    a typical search against an LDAP server.

    This script assumes the following:

    LDAP server hostname: NULL (local host)
    LDAP server portnumber: 389
    Directory container for employee records: o=acme, dc=com
    Username/Password for Directory Updates: cn=orcladmin/welcome

    NOTE
    Run this file after you have run the 'trigger.sql' and 'empdata.sql'
    scripts to see what entries were added by the database triggers.

    MODIFIED    (MM/DD/YY)
    akolli		07/21/00 - created

    set serveroutput on size 30000

    DECLARE

    retval       PLS_INTEGER;
    my_session   DBMS_LDAP.session;
    my_attrs     DBMS_LDAP.string_collection;
    my_message   DBMS_LDAP.message;
    my_entry     DBMS_LDAP.message;
    entry_index  PLS_INTEGER;
    my_dn        VARCHAR2(256);
    my_attr_name VARCHAR2(256);
    my_ber_elmt  DBMS_LDAP.ber_element;
    attr_index   PLS_INTEGER;
    i          PLS_INTEGER;
    my_vals DBMS_LDAP.STRING_COLLECTION ;
    ldap_host  VARCHAR2(256);
    ldap_port  VARCHAR2(256);
    ldap_user  VARCHAR2(256);
    ldap_passwd  VARCHAR2(256);
    ldap_base  VARCHAR2(256);

    BEGIN

    retval         := -1;

    -- Please customize the following variables as needed
    ldap_host  := NULL ;
    ldap_port  := '389';
    ldap_user  := 'cn=orcladmin';
    ldap_passwd:= 'welcome';
    ldap_base  := 'o=acme,dc=com';
    -- end of customizable settings

     DBMS_OUTPUT.PUT('DBMS_LDAP Search Example ');
     DBMS_OUTPUT.PUT_LINE('to directory .. ');
     DBMS_OUTPUT.PUT_LINE(RPAD('LDAP Host ',25,' ') || ': ' || ldap_host);
     DBMS_OUTPUT.PUT_LINE(RPAD('LDAP Port ',25,' ') || ': ' || ldap_port);

     -- Choosing exceptions to be raised by DBMS_LDAP library.
     DBMS_LDAP.USE_EXCEPTION := TRUE;

     my_session := DBMS_LDAP.init(ldap_host,ldap_port);

     DBMS_OUTPUT.PUT_LINE (RPAD('Ldap session ',25,' ')  || ': ' ||
         RAWTOHEX(SUBSTR(my_session,1,8)) ||
         '(returned from init)');

     -- bind to the directory
     retval := DBMS_LDAP.simple_bind_s(my_session,
                ldap_user, ldap_passwd);

     DBMS_OUTPUT.PUT_LINE(RPAD('simple_bind_s Returns ',25,' ') || ': '
              || TO_CHAR(retval));

     -- issue the search
     my_attrs(1) := '*'; -- retrieve all attributes
     retval := DBMS_LDAP.search_s(my_session, ldap_base,
                                  DBMS_LDAP.SCOPE_SUBTREE,
                                  'objectclass=*',
                                  my_attrs,
                                  0,
                                  my_message);

     DBMS_OUTPUT.PUT_LINE(RPAD('search_s Returns ',25,' ') || ': '
              || TO_CHAR(retval));
     DBMS_OUTPUT.PUT_LINE (RPAD('LDAP message  ',25,' ')  || ': ' ||
         RAWTOHEX(SUBSTR(my_message,1,8)) ||
         '(returned from search_s)');

     -- count the number of entries returned
     retval := DBMS_LDAP.count_entries(my_session, my_message);
     DBMS_OUTPUT.PUT_LINE(RPAD('Number of Entries ',25,' ') || ': '
              || TO_CHAR(retval));
     DBMS_OUTPUT.PUT_
    LINE('---------------------------------------------------');

     -- get the first entry
     my_entry := DBMS_LDAP.first_entry(my_session, my_message);
     entry_index := 1;

     -- Loop through each of the entries one by one
     while my_entry IS NOT NULL loop

       -- print the current entry
       my_dn := DBMS_LDAP.get_dn(my_session, my_entry);
       -- DBMS_OUTPUT.PUT_LINE ('        entry #' || TO_CHAR(entry_index) ||
        -- ' entry ptr: ' || RAWTOHEX(SUBSTR(my_entry,1,8)));
       DBMS_OUTPUT.PUT_LINE ('        dn: ' || my_dn);
       my_attr_name := DBMS_LDAP.first_attribute(my_session,my_entry,
       my_ber_elmt);
       attr_index := 1;
       while my_attr_name IS NOT NULL loop

         my_vals := DBMS_LDAP.get_values (my_session, my_entry,
         my_attr_name);
         if my_vals.COUNT > 0 then
           FOR i in my_vals.FIRST..my_vals.LAST loop
             DBMS_OUTPUT.PUT_LINE('           ' || my_attr_name || ' : '
    ||
             SUBSTR(my_vals(i),1,200));
           end loop;

         end if;
         my_attr_name := DBMS_LDAP.next_attribute(my_session,my_entry,
         my_ber_elmt);
         attr_index := attr_index+1;

       end loop;
       my_entry := DBMS_LDAP.next_entry(my_session, my_entry);
       DBMS_OUTPUT.PUT_
    LINE('===================================================');
       entry_index := entry_index+1;

     end loop;

     -- unbind from the directory
     retval := DBMS_LDAP.unbind_s(my_session);
     DBMS_OUTPUT.PUT_LINE(RPAD('unbind_res Returns ',25,' ') ||  ': ' ||
               TO_CHAR(retval));

     DBMS_OUTPUT.PUT_LINE('Directory operation Successful .. exiting');

    -- Handle Exceptions

    EXCEPTION

    WHEN OTHERS THEN

       DBMS_OUTPUT.PUT_LINE(' Error code    : ' || TO_CHAR(SQLCODE));
       DBMS_OUTPUT.PUT_LINE(' Error Message : ' || SQLERRM);
       DBMS_OUTPUT.PUT_LINE(' Exception encountered .. exiting');

    END;
    /
    -------------------------------END OF trigger.sql---------------------------

## Building Applications with PL/SQL LDAP 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:

- It cannot be used in the multi-threaded server (MTS) mode of the database.

- 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. Be sure that you have read the previous sections before using this section.``

This section contains these topics:

- Summary of Subprograms

- Exception Summary

- Data-Type Summary

- Subprograms

### Summary of Subprograms

##### Table 3-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/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.

### Exception Summary

The DBMS_LDAP package shipped with RDBMS 8.1.7 can generate the following exceptions

##### Table 3-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 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.

### Data-Type Summary

The DBMS_LDAP package uses the following data-types.

##### Table 3-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 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 for populating a modification array.

### Subprograms

#### 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 3-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 hostname in the list MAY include a port number which is separated from the host itself with a colon (:) character. The hosts will be 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 a host includes a port number then this parameter is ignored. If this parameter is not specified and the hostname also does not contain the port number, a default port number of 389 is assumed.

##### Return Values

##### Table 3-5 INIT Function Return Values

Value | Description
--- | ---
SESSION (function return) | A handle to an LDAP session which can be used for further calls into the API.

##### Exceptions

##### Table 3-6 INIT Function Exceptions

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

##### Usage Notes

DBMS_LDAP.init() is the first function that should be called in order to establish a session to the LDAP server. 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.Subsequent to the call to init(), 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().

#### FUNCTION simple_bind_s

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

##### Syntax

    FUNCTION simple_bind_s
    (

    ld     IN SESSION,
    dn     IN VARCHAR2,
    passwd IN VARCHAR2

    )

    RETURN PLS_INTEGER;

##### Parameters

##### Table 3-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 3-8 SIMPLE_BIND_S Function Return Values

Value | Description
--- | ---
PLS_INTEGER (function return) | DBMS_LDAP SUCCESS on a successful completion. If there was a problem, one of the following exceptions will be raised.

##### Exceptions

##### Table 3-9 SIMPLE_BIND_S Function Exceptions

Exception | Description
--- | ---
invalid_session | Raised if the session handle 'ld' is invalid.
mts_mode_not_supported | Raised if DBMS_LDAP.init() is invoked from a user session that is logged onto as an MTS service.
general_error | For all other errors. The error string associated with this exception 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().

#### 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 3-10 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.
cred | A text string containing the credentials used for authentication.
meth | The authentication method.

##### Return Values

##### Table 3-11 BIND_S Function Return Values

Value | Description
--- | ---
PLS_INTEGER (function return) | DBMS_LDAP.SUCCESS on a successful completion. One of the following exceptions is raised if there was a problem.

##### Exceptions

##### Table 3-12 BIND_S Function Exceptions

Exception | Description
--- | ---
invalid_session | Raised if the session handle 'ld' is invalid.
invalid_auth_method | Raised if the authentication method requested is not supported.
mts_mode_not_supported | Raised if invoked from a user session that is logged onto an MTS service.
general_error | For all other errors. The error string associated with this exception 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().

#### FUNCTION unbind_s

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

##### Syntax

    FUNCTION unbind_s
    (

    ld IN SESSION

    )

    RETURN PLS_INTEGER;

##### Parameters

##### Table 3-13 UNBIND_S Function Parameters

Parameter | Description
--- | ---
ld | A valid LDAP session handle.

##### Return Values

##### Table 3-14 UNBIND_S Function Return Values

Value | Description
--- | ---
PLS_INTEGER (function return) | SUCCESS on proper completion. One of the following exceptions is raised otherwise.

##### Exceptions

##### Table 3-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, will send an unbind request to the server, close all open connections associated with the LDAP session and dispose of all resources associated with the session handle before returning. After a call to this function, the session handle ld is invalid and it is illegal to make any further LDAP API calls using ld.

##### See Also

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

#### 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 3-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 3-17 COMPARE_S Function Return Values

Value | Description
--- | ---
PLS_INTEGER (function return) | COMPARE_TRUE is the given attribute has a matching value. COMPARE_FALSE if the value of the attribute does not match the value given.

##### Exceptions

##### Table 3-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 if the value of a given attribute stored in the directory server matches a certain value.This operation can only be performed on attributes whose syntax definition allows them to be compared. The compare_s function can only be called after a valid LDAP session handle has been obtained from the init() function and authenticated using the bind_s() or simple_bind_s() functions.

##### See Also

DBMS_LDAP.bind_s()

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

##### 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 3-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 non-zero if only types are wanted.
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 3-20 SEARCH_S Function Return Value

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

##### Exceptions

##### Table 3-21 SEARCH_S Function Exceptions

Exception | Description
--- | ---
invalid_session | Raised if the session handle 'ld' is invalid.
invalid_search_scope | Raised i 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, values, etc., can be extracted by calling the parsing routines described below.

##### See Also

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

#### 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 3-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 non-zero 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 3-23 SEARCH_ST Function Return Values

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

##### Exceptions

##### Table 3-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.

#### 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 3-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 3-26 FIRST_ENTRY Return Values

Value | Description
--- | ---
MESSAGE (function return) | 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 3-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()

#### 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 3-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 3-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 3-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()

#### 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 3-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 3-32 COUNT_ENTRY Function Return Values

Value | Description
--- | ---
PLS INTEGER (function return) | Non-zero if there are entries in the result set -1 if there was a problem.

##### Exceptions

##### Table 3-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().

#### 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,
    msg      IN  MESSAGE,
    ber_elem OUT BER_ELEMENT

    )

    RETURN VARCHAR2;

##### Parameters

##### Table 3-34 FIRST_ATTRIBUTE Function Parameter

Parameter | Description
--- | ---
ld | A valid LDAP session handle
msg | 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 which attribute in the entry has been read

##### Return Values

##### Table 3-35 FIRST_ATTRIBUTE Function Return Values

Value | Description
--- | ---
VARCHAR2 (function return) | 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 3-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().

#### FUNCTION next_attribute

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

##### Syntax

    FUNCTION next_attribute
    (

    ld       IN SESSION,
    msg      IN MESSAGE,
    ber_elem IN BER_ELEMENT

    )

    RETURN VARCHAR2;

##### Parameters

##### Table 3-37 NEXT_ATTRIBUTE Function Parameters

Parameter | Description
--- | ---
ld | A valid LDAP session handle.
msg | 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 which attribute in the entry has been read.

##### Return Values

##### Table 3-38 NEXT_ATTRIBUTE Function Return Values

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

##### Exceptions

##### Table 3-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().

#### 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,
    msg IN MESSAGE

    )

    RETURN VARCHAR2;

##### Parameters

##### Table 3-40 GET_DN Function Parameters

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

##### Return Values

##### Table 3-41 GET_DN Function Return Values

Value | Description
--- | ---
VARCHAR2 (function return) | The X.500 Distinguished name of the entry as a PL/SQL string. NULL if there was a problem.

##### Exceptions

##### Table 3-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().

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

##### Syntax

    FUNCTION get_values
    (

    ld   IN SESSION,
    ldapentry IN MESSAGE,
    attr IN VARCHAR2

    )

    RETURN STRING_COLLECTION;

##### Parameters

##### Table 3-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 3-44 GET_VALUES Function Return Values

Value | Description
--- | ---
STRING_COLLECTION (function return) | 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 3-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 also 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 '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().

#### 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 3-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 3-47 GET_VALUES_LEN Function Return Values

Value | Description
--- | ---
BINVAL_COLLECTION (function return | 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 3-48 GET_VALUES_LEN Function Exceptions

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

##### Usage Notes

The function get_values_len() can only be called after the handle to entry has been first retrieved by 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().

#### FUNCTION delete_s

The function delete_s() can be used to remove a leaf entry in the LDAP Directory Information Tree.

##### Syntax

    FUNCTION delete_s
    (

    ld      IN SESSION,
    entrydn IN VARCHAR2

    )

    RETURN PLS_INTEGER;

##### Parameters

##### Table 3-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 3-50 DELETE_S Function Return Values

Value | Description
--- | ---
PLS_INTEGER (function return) | DBMS_LDAP.SUCCESS if the delete operation wa successful. And exception is raised otherwise.

##### Exceptions

##### Table 3-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 level entries in the LDAP DIT. A leaf level entry is an entry that does not have any children/ldap entries under it. It cannot be used to delete non-leaf entries.

##### See Also

DBMS_LDAP.modrdn2_s()

#### 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 3-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 non-zero indicates that the attribute values from the old name should be removed from the entry.

##### Return Values

##### Table 3-53 MODRDN2_S Function Return Values

Value | Description
--- | ---
PLS_INTEGER (function return) | DBMS_LDAP.SUCCESS if the operation was successful. An exception is raised otherwise.

##### Exceptions

##### Table 3-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 can achieve the same foundation.

##### See Also

DBMS_LDAP.rename_s().

#### 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

##### Syntax

    FUNCTION err2string
    (

    ldap_err IN PLS_INTEGER

    )

    RETURN VARCHAR2;

##### Parameters

##### Table 3-55 ERR2STRING Function Parameters

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

##### Return Values

##### Table 3-56 ERR2STRING Function Return Values

Value | Description
--- | ---
VARCHAR2 (function return) | A character string appropriately translated to the local language which describes the error in detail.

##### Exceptions

##### Table 3-57 ERR2STRING Function Exceptions

Exception | Description
--- | ---
N/A | None.

##### Usage Notes

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

##### See Also

N/A

#### 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() or add_s() functions.

##### Syntax

    FUNCTION create_mod_array
    (

    num IN PLS_INTEGER

    )

    RETURN MOD_ARRAY;

##### Parameters

##### Table 3-58 CREATE_MOD_ARRAY Function Parameters

Parameter | Description
--- | ---
num | The number of the attributes that you want to add/modify.

##### Return Values

##### Table 3-59 CREATE_MOD_ARRAY Function Return Values

Value | Description
--- | ---
MOD_ARRAY (function return) | The data structure holds a pointer to an LDAP mod array. NULL if there was a problem.

##### Exceptions

##### Table 3-60 CREATE_MOD_ARRAY Function Exceptions

Exception | Description
--- | ---
N/A | No LDAP specific exception will be raised

##### Usage Notes

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

##### See Also

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

#### 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 3-61 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 the string values only.

##### Return Values

##### Table 3-62 POPULATE_MOD_ARRAY (String Version) Procedure Return Values

Value | Description
--- | ---
N/A |

##### Exceptions

##### Table 3-63 POPULATE_MOD_ARRAY (String Version) Procedure Exceptions

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

##### Usage Notes

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

##### See Also

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

#### 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() called.

##### Syntax

    PROCEDURE populate_mod_array
    (

    modptr   IN DBMS_LDAP.MOD_ARRAY,
    mod_op   IN PLS_INTEGER,
    mod_type IN VARCHAR2,
    modval   IN DBMS_LDAP.BERVAL_COLLECTION

    );

##### Parameters

##### Table 3-64 POPULATE_MOD_ARRAY (Binary 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 the binary values

##### Return Values

##### Table 3-65 POPULATE_MOD_ARRAY (Binary Version) Procedure Return Values

Value | Description
--- | ---
N/A |

##### Exceptions

##### Table 3-66 POPULATE_MOD_ARRAY (Binary Version) Procedure Exceptions

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

##### Usage Notes

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

##### See Also

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

#### 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 3-67 MODIFY_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 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 3-68 MODIFY_S Function Return Values

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

##### Exceptions

##### Table 3-69 MODIFY_S Function Exceptions

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

##### Usage Notes

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

##### See Also

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

#### FUNCTION add_s

Adds a new entry to the LDAP directory synchronously. Before calling add_s, we have to call DBMS_LDAP.create_mod_array() and DBMS_LDAP.populate_mod_array().

##### Syntax

    FUNCTION add_s
    (

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

    )

    RETURN PLS_INTEGER;

##### Parameters

##### Table 3-70 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 3-71 ADD_S Function Return Values

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

##### Exceptions

##### Table 3-72 ADD_S Function Exceptions

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

##### Usage Notes

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

##### See Also

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

#### 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 3-73 FREE_MOD_ARRAY Procedure Parameters

Parameter | Description
--- | ---
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 3-74 FREE_MOD_ARRAY Procedure Return Value

Value | Description
--- | ---
N/A |

##### Exceptions

##### Table 3-75 FREE_MOD_ARRAY Procedure Exceptions

Exception | Description
--- | ---
N/A | No LDAP specific exception will be raised.

##### Usage Notes

N/A

##### See Also

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

#### 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 3-76 COUNT_VALUES Function Parameters

Parameter | Description
--- | ---
values | The collection of string values.

##### Return Values

##### Table 3-77 COUNT_VALUES Function Return Values

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

##### Exceptions

##### Table 3-78 COUNT_VALUES Function Exceptions

Exception | Description
--- | ---
N/A | No LDAP specific exception will be raised.

##### Usage Notes

N/A

##### See Also

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

#### 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 3-79 COUNT_VALUES_LEN Function Parameters

Parameter | Description
--- | ---
values | The collection of binary values.

##### Return Values

##### Table 3-80 COUNT_VALUES_LEN Function Return Values

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

##### Exceptions

##### Table 3-81 COUNT_VALUES_LEN Function Exceptions

Exception | Description
--- | ---
N/A | No LDAP specific exception will be raised.

##### Usage Notes

N/A

##### See Also

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

#### FUNCTION rename_s

Renames an LDAP entry synchronously.

##### Syntax

    FUNCTION rename_s
    (

    ld           IN SESSION,
    dn           IN VARCHAR2,
    newrdn       IN VARCHAR2,
    ewparent    IN VARCHAR2,
    deleteoldrdn IN PLS_INTEGER,
    serverctrls  IN LDAPCONTROL,
    clientctrls  IN LDAPCONTROL

    )

    RETURN PLS_INTEGER;

##### Parameters

##### Table 3-82 RENAME_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().
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 if the old RDN should be retained. If this value is 1, then the old RDN will be removed.
serverctrls | Currently not supported.
clientctrls | Currently not supported.

##### Return Values

##### Table 3-83 RENAME_S Function Return Values

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

##### Exceptions

##### Table 3-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.

##### Usage Notes

N/A

##### See Also

DBMS_LDAP.modrdn2_s().

#### 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 3-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 if the attribute tags will be returned. If this value is not 0, then there will be no attribute tags will be returned.

##### Return Values

##### Table 3-86 EXPLODE_DN Function Return Values

Value | Description
--- | ---
STRING_COLLECTION | An array of strings. If the DN can not be broken up, NULL will be returned.

##### Exceptions

##### Table 3-87 EXPLODE_DN Function Exceptions

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

##### Usage Notes

N/A

##### See Also

DBMS_LDAP.get_dn().

#### 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 3-88 OPEN_SSL Function Parameters

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

##### Return Values

##### Table 3-89 OPEN_SSL Function Return Values

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

##### Exceptions

##### Table 3-90 OPEN_SSL Function Exceptions

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

##### Usage Notes

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

##### See Also

DBMS_LDAP.init().

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index