Oracle Internet Directory Application Developer's Guide Release 2.1.1 Part Number A86082-01 |
|
This chapter introduces the Oracle Internet Directory PL/SQL API and provides examples of how to use it. It contains these topics:
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.
This section contains these topics
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 personorganizationalperson inetOrgPerson topMODIFIED (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 DECLAREretval 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);BEGINretval := -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 settingsDBMS_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 THENemp_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 EXCEPTIONWHEN 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---------------------------
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. FILEsearch.sqlDESCRIPTIONThis 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/welcomeNOTE 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 DECLAREretval 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);BEGINretval := -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 settingsDBMS_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 loopmy_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 ExceptionsEXCEPTIONWHEN OTHERS THENDBMS_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---------------------------
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
The PL/SQL LDAP API for this release has the following limitations:
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:
The DBMS_LDAP package shipped with RDBMS 8.1.7 can generate the following exceptions
The DBMS_LDAP package uses the following data-types.
init() initializes a session with an LDAP server. This actually establishes a connection with the LDAP server.
FUNCTION init (hostname IN VARCHAR2, portnum IN PLS_INTEGER)RETURN SESSION;
Value | Description |
---|---|
SESSION (function return) |
A handle to an LDAP session which can be used for further calls into the API. |
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().
DBMS_LDAP.simple_bind_s(), DBMS_LDAP.bind_s().
The function simple_bind_s can be used to perform simple username/password based authentication to the directory server.
FUNCTION simple_bind_s (ld IN SESSION, dn IN VARCHAR2, passwd IN VARCHAR2)RETURN PLS_INTEGER;
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. |
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. |
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().
The function bind_s can be used to perform complex authentication to the directory server.
FUNCTION bind_s (ld IN SESSION, dn IN VARCHAR2, cred IN VARCHAR2, meth IN PLS_INTEGER)RETURN PLS_INTEGER;
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. |
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().
DBMS_LDAP.init(), DBMS_LDAP.simple_bind_s().
The function unbind_s is used for closing an active LDAP session.
FUNCTION unbind_s (ld IN SESSION)RETURN PLS_INTEGER;
Parameter | Description |
---|---|
ld |
A valid LDAP session handle. |
Value | Description |
---|---|
PLS_INTEGER (function return) |
SUCCESS on proper completion. One of the following exceptions is raised otherwise. |
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.
DBMS_LDAP.bind_s(), DBMS_LDAP.simple_bind_s().
The function compare_s can be used to test if a particular attribute in a particular entry has a particular value.
FUNCTION compare_s (ld IN SESSION, dn IN VARCHAR2, attr IN VARCHAR2, value IN VARCHAR2)RETURN PLS_INTEGER;
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 |
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. |
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.
DBMS_LDAP.bind_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_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;
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.
DBMS_LDAP.search_st(), DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry.
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 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;
This function is very similar to DBMS_LDAP.search_s() except that it requires a time-out value to be given.
DBMS_LDAP.search_s(), DBML_LDAP.first_entry(), DBMS_LDAP.next_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 first_entry (ld IN SESSION, msg IN MESSAGE)RETURN MESSAGE;
Parameter | Description |
---|---|
ld |
A valid LDAP session handle. |
msg |
The search result, as obtained by a call to one of the synchronous search routines. |
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. |
Exception | Description |
---|---|
invalid_session |
Raised if the session handle 'ld' is invalid. |
invalid_message |
Raised if the incoming "msg" handle is invalid. |
The function first_entry() should always be the first function used to retrieve the results from a search operation.
DBMS_LDAP.next_entry(), DBMS_LDAP.search_s(), DBMS_LDAP.search_st()
The function next_entry() is used to iterate to the next entry in the result set of a search operation.
FUNCTION next_entry (ld IN SESSION, msg IN MESSAGE)RETURN MESSAGE;
Parameter | Description |
---|---|
ld |
A valid LDAP session handle. |
msg |
The search result, as obtained by a call to one of the synchronous search routines. |
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. |
Exception | Description |
---|---|
invalid_session |
Raised if the session handle, 'ld' is invalid. |
invalid_message |
Raised if the incoming 'msg' handle is invalid. |
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.
DBMS_LDAP.first_entry(), DBMS_LDAP.search_s(), DBMS_LDAP.search_st()
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 count_entries (ld IN SESSION, msg IN MESSAGE)RETURN PLS_INTEGER;
Parameter | Description |
---|---|
ld |
A valid LDAP session handle |
msg |
The search result, as obtained by a call to one of the synchronous search routines |
Value | Description |
---|---|
PLS INTEGER (function return) |
Non-zero if there are entries in the result set -1 if there was a problem. |
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().
DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry().
The function first_attribute() fetches the first attribute of a given entry in the result set.
FUNCTION first_attribute (ld IN SESSION, msg IN MESSAGE, ber_elem OUT BER_ELEMENT)RETURN VARCHAR2;
Exception | Description |
---|---|
invalid_session |
Raised if the session handle 'ld' is invalid. |
invalid_message |
Raised if the incoming 'msg' handle is invalid |
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.
DBMS_LDAP.next_attribute(), DBMS_LDAP.get_values(), DBMS_LDAP.get_values_len(), DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry().
The function next_attribute() fetches the next attribute of a given entry in the result set.
FUNCTION next_attribute (ld IN SESSION, msg IN MESSAGE, ber_elem IN BER_ELEMENT)RETURN VARCHAR2;
Value | Description |
---|---|
VARCHAR2 (function return) |
The name of the attribute if it exists. |
Exception | Description |
---|---|
invalid_session |
Raised if the session handle 'ld' is invalid. |
invalid_message |
Raised if the incoming 'msg' handle is invalid. |
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.
DBMS_LDAP.first_attribute(), DBMS_LDAP.get_values(), DBMS_LDAP.get_values_len(), DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry().
The function get_dn() retrieves the X.500 distinguished name of given entry in the result set.
FUNCTION get_dn (ld IN SESSION, msg IN MESSAGE)RETURN VARCHAR2;
Parameter | Description |
---|---|
ld |
A valid LDAP session handle. |
msg |
The entry whose DN is to be returned. |
Value | Description |
---|---|
VARCHAR2 (function return) |
The X.500 Distinguished name of the entry as a PL/SQL string. NULL if there was a problem. |
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.
DBMS_LDAP.explode_dn().
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 (ld IN SESSION, ldapentry IN MESSAGE, attr IN VARCHAR2)RETURN STRING_COLLECTION;
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 |
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 |
Exception | Description |
---|---|
invalid session |
Raised if the session handle 'ld' is invalid. |
invalid message |
Raised if the incoming "entry handle' is invalid. |
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.
DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry(), DBMS_LDAP.count_values(), DBMS_LDAP.get_values_len().
The function get_values_len() can be used to retrieve values of attributes that have a 'Binary' syntax.
FUNCTION get_values_len (ld IN SESSION, ldapentry IN MESSAGE, attr IN VARCHAR2)RETURN BINVAL_COLLECTION;
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. |
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. |
Exception | Description |
---|---|
invalid_session |
Raised if the session handle 'ld' is invalid. |
invalid_message |
Raised if the incoming 'entry handle' is invalid |
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.
DBMS_LDAP.first_entry(), DBMS_LDAP.next_entry(), DBMS_LDAP.count_values_len(), DBMS_LDAP.get_values().
The function delete_s() can be used to remove a leaf entry in the LDAP Directory Information Tree.
FUNCTION delete_s (ld IN SESSION, entrydn IN VARCHAR2)RETURN PLS_INTEGER;
Parameter Name | Description |
---|---|
ld |
A valid LDAP session |
entrydn |
The X.500 distinguished name of the entry to delete |
Value | Description |
---|---|
PLS_INTEGER (function return) |
DBMS_LDAP.SUCCESS if the delete operation wa successful. And exception is raised otherwise. |
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.
DBMS_LDAP.modrdn2_s()
The function modrdn2_s() can be used to rename the relative distinguished name of an entry.
FUNCTION modrdn2_s (ld IN SESSION, entrydn in VARCHAR2 newrdn in VARCHAR2 deleteoldrdn IN PLS_INTEGER)RETURN PLS_INTEGER;
Value | Description |
---|---|
PLS_INTEGER (function return) |
DBMS_LDAP.SUCCESS if the operation was successful. An exception is raised otherwise. |
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.
DBMS_LDAP.rename_s().
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 err2string (ldap_err IN PLS_INTEGER)RETURN VARCHAR2;
Parameter | Description |
---|---|
ldap_err |
An error number returned from one the API calls. |
Value | Description |
---|---|
VARCHAR2 (function return) |
A character string appropriately translated to the local language which describes the error in detail. |
Exception | Description |
---|---|
N/A |
None. |
In this release, the exception handling mechanism automatically invokes this if any of the API calls encounter an error.
N/A
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.
FUNCTION create_mod_array (num IN PLS_INTEGER)RETURN MOD_ARRAY;
Parameter | Description |
---|---|
num |
The number of the attributes that you want to add/modify. |
Value | Description |
---|---|
MOD_ARRAY (function return) |
The data structure holds a pointer to an LDAP mod array. NULL if there was a problem. |
Exception | Description |
---|---|
N/A |
No LDAP specific exception will be raised |
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.
DBMS_LDAP.populate_mod_array(), DBMS_LDAP.modify_s(), DBMS_LDAP.add_s(), and DBMS_LDAP.free_mod_array().
Populates one set of attribute information for add or modify operations.
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);
Value | Description |
---|---|
N/A |
|
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 |
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.
DBMS_LDAP.create_mod_array(), DBMS_LDAP.modify_s(), DBMS_LDAP.add_s(), and DBMS_LDAP.free_mod_array().
Populates one set of attribute information for add or modify operations. This procedure call has to happen after DBMS_LDAP.create_mod_array() called.
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);
Value | Description |
---|---|
N/A |
|
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 |
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.
DBMS_LDAP.create_mod_array(), DBMS_LDAP.modify_s(), DBMS_LDAP.add_s(), and DBMS_LDAP.free_mod_array().
Performs a synchronous modification of an existing LDAP directory entry.
FUNCTION modify_s (ld IN DBMS_LDAP.SESSION, entrydn IN VARCHAR2, modptr IN DBMS_LDAP.MOD_ARRAY)RETURN PLS_INTEGER;
Value | Description |
---|---|
PLS_INTEGER |
The indication of the success or failure of the modification operation |
Exception | Description |
---|---|
invalid_session |
Invalid LDAP session |
invalid_entry_dn |
Invalid LDAP entry dn |
invalid_mod_array |
Invalid LDAP mod array |
This function call has to follow successful calls of DBMS_LDAP.create_mod_array() and DBMS_LDAP.populate_mod_array().
DBMS_LDAP.create_mod_array(),DBMS_LDAP.populate_mod_array(), DBMS_LDAP.add_s(), and DBMS_LDAP.free_mod_array().
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().
FUNCTION add_s (ld IN DBMS_LDAP.SESSION, entrydn IN VARCHAR2, modptr IN DBMS_LDAP.MOD_ARRAY)RETURN PLS_INTEGER;
Value | Description |
---|---|
PLS_INTEGER |
The indication of the success or failure of the modification operation. |
Exception | Description |
---|---|
invalid_session |
Invalid LDAP session. |
invalid_entry_dn |
Invalid LDAP entry dn. |
invalid_mod_array |
Invalid LDAP mod array. |
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().
DBMS_LDAP.create_mod_array(),DBMS_LDAP.populate_mod_array(), DBMS_LDAP.modify_s(), and DBMS_LDAP.free_mod_array().
Frees the memory allocated by DBMS_LDAP.create_mod_array().
PROCEDURE free_mod_array (modptr IN DBMS_LDAP.MOD_ARRAY);
Parameter | Description |
---|---|
modptr |
This parameter is the handle to an LDAP mod structure, as returned by successful call to DBMS_LDAP.create_mod_array(). |
Value | Description |
---|---|
N/A |
|
Exception | Description |
---|---|
N/A |
No LDAP specific exception will be raised. |
N/A
DBMS_LDAP.populate_mod_array(), DBMS_LDAP.modify_s(), DBMS_LDAP.add_s(), and DBMS_LDAP.create_mod_array().
Counts the number of values returned by DBMS_LDAP.get_values().
FUNCTION count_values (values IN DBMS_LDAP.STRING_COLLECTION)RETURN PLS_INTEGER;
Parameter | Description |
---|---|
values |
The collection of string values. |
Value | Description |
---|---|
PLS_INTEGER |
The indication of the success or failure of the operation. |
Exception | Description |
---|---|
N/A |
No LDAP specific exception will be raised. |
N/A
DBMS_LDAP.count_values_len(), DBMS_LDAP.get_values().
Counts the number of values returned by DBMS_LDAP.get_values_len().
FUNCTION count_values_len (values IN DBMS_LDAP.BINVAL_COLLECTION)RETURN PLS_INTEGER;
Parameter | Description |
---|---|
values |
The collection of binary values. |
Value | Description |
---|---|
PLS_INTEGER |
The indication of the success or failure of the operation. |
Exception | Description |
---|---|
N/A |
No LDAP specific exception will be raised. |
N/A
DBMS_LDAP.count_values(), DBMS_LDAP.get_values_len().
Renames an LDAP entry synchronously.
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;
Value | Description |
---|---|
PLS_INTEGER |
The indication of the success or failure of the operation. |
N/A
DBMS_LDAP.modrdn2_s().
Breaks a DN up into its components.
FUNCTION explode_dn (dn IN VARCHAR2, notypes IN PLS_INTEGER)RETURN STRING_COLLECTION;
Value | Description |
---|---|
STRING_COLLECTION |
An array of strings. If the DN can not be broken up, NULL will be returned. |
Exception | Description |
---|---|
invalid_entry_dn |
Invalid LDAP DN. |
invalid_notypes |
Invalid LDAP notypes value. |
N/A
DBMS_LDAP.get_dn().
Establishes an SSL (Secure Sockets Layer) connection over an existing LDAP connection.
FUNCTION open_ssl (ld IN SESSION, sslwrl IN VARCHAR2, sslwalletpasswd IN VARCHAR2, sslauth IN PLS_INTEGER)RETURN PLS_INTEGER;
Value | Description |
---|---|
PLS_INTEGER |
The indication of the success or failure of the operation. |
Need to call DBMS_LDAP.init() first to acquire a valid ldap session.
DBMS_LDAP.init().
|
Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|