11 DBMS_LDAP_UTL PL/SQL Reference

The DBMS_LDAP_UTL package contains Oracle Extension utility functions for user, group and subscribers.

11.1 Subprograms at a Glance

Subprograms are used to retrieve information from users, groups and subscribers.

The following topics provide the summary of subprograms at various levels:

11.1.1 dbms_ldap_utl User-Related Subprograms

dbms_ldap_utl user-related subprograms are used to authenticate, retrieve and modify the user properties from an LDAP server.

Table 11-1 describes dbms_ldap_utl user-related subprograms.

Table 11-1 DBMS_LDAP_UTL User-Related Subprograms

Function or Procedure Purpose

Function authenticate_user

Authenticates a user against an LDAP server.

Function create_user_handle

Creates a user handle.

Function set_user_handle_properties

Associates the given properties to the user handle.

Function get_user_properties

Retrieves user properties from an LDAP server.

Function set_user_properties

Modifies the properties of a user.

Function get_user_extended_properties

Retrieves user extended properties.

Function get_user_dn

Retrieves a user DN.

Function check_group_membership

Checks whether a user is member of a given group.

Function locate_subscriber_for_user

Retrieves the subscriber for the given user.

Function get_group_membership

Retrieves a list of groups of which the user is a member.

11.1.2 dbms_ldap_utl Group-Related Subprograms

dbms_ldap_utl group-related subprograms are used to create and retrieve information from an LDAP server.

Table 11-2 describes dbms_ldap_utl group-related subprograms.

Table 11-2 DBMS_LDAP_UTL Group-Related Subprograms

Function or Procedure Purpose

Function create_group_handle

Creates a group handle.

Function set_group_handle_properties

Associates the given properties with the group handle.

Function get_group_properties

Retrieves group properties from an LDAP server.

Function get_group_dn

Retrieves a group DN.

11.1.3 dbms_ldap_utl Subscriber-Related Subprograms

dbms_ldap_utl subscriber-related subprograms are used to create and retrieve subscriber properties from an LDAP server.

Table 11-3 describes dbms_ldap_utl subscriber-related subprograms.

Table 11-3 DBMS_LDAP_UTL Subscriber-Related Subprograms

Function or Procedure Purpose

Function create_subscriber_handle

Creates a subscriber handle.

Function get_subscriber_properties

Retrieves subscriber properties from an LDAP server.

Function get_subscriber_dn

Retrieves a subscriber DN.

11.1.4 dbms_ldap_utl Miscellaneous Subprograms

dbms_ldap_utl miscellaneous subprograms are used to retrieve list of property names and binary values for a property etc.

Table 11-4 describes dbms_ldap_utl miscellaneous subprograms.

Table 11-4 DBMS_LDAP_UTL Miscellaneous Subprograms

Function or Procedure Purpose

Function normalize_dn_with_case

Normalizes the DN string.

Function get_property_names

Retrieves a list of property names in a PROPERTY_SET.

Function get_property_values

Retrieves a list of values for a property name.

Function get_property_values_blob

Retrieves a list of large binary values for a property name.

Procedure property_value_free_blob

Frees the memory associated with BLOB_COLLECTION returned by DBMS_LDAP_UTL.get_property_values_blob().

Function get_property_values_len

Retrieves a list of binary values for a property name.

Procedure free_propertyset_collection

Frees PROPERTY_SET_COLLECTION.

Function create_mod_propertyset

Creates a MOD_PROPERTY_SET.

Function populate_mod_propertyset

Populates a MOD_PROPERTY_SET structure.

Procedure free_mod_propertyset

Frees a MOD_PROPERTY_SET.

Procedure free_handle

Frees handles.

Function check_interface_version

Checks for support of the interface version.

11.2 Handling Subprograms

DBMS_LDAP_UTL package contains user, group, property and subscriber related subprograms.

The following topics describe the various subprograms available for the DBMS_LDAP_UTL package:

11.2.1 Using User-Related Subprograms

A user is represented by the DBMS_LDAP_UTL.HANDLE data type. You can create a user handle by using a DN, GUID, or simple name, along with the appropriate subscriber handle. When a simple name is used, additional information from the root Oracle Context and the subscriber Oracle Context is used to identify the user.

The following example shows a user handle being created:

retval := DBMS_LDAP_UTL.create_user_handle(
user_handle,
DBMS_LDAP_UTL.TYPE_DN,
"cn=user1,cn=users,o=example,dc=com"
);

This user handle must be associated with an appropriate subscriber handle. If, for example, subscriber_handle is o=example,dc=com, the subscriber handle can be associated in the following way:

retval := DBMS_LDAP_UTL.set_user_handle_properties(
user_handle,
DBMS_LDAP_UTL.SUBSCRIBER_HANDLE,
subscriber_handle
);

Common uses of user handles include setting and getting user properties and authenticating the user. Here is a handle that authenticates a user:

retval := DBMS_LDAP_UTL.authenticate_user(
my_session
user_handle
DBMS_LDAP_UTL.AUTH_SIMPLE,
"welcome"
NULL
);

In this example, the user is authenticated using a clear text password welcome.

Here is a handle that retrieves a user's telephone number:

--my_attrs is of type DBMS_LDAP.STRING_COLLECTION
my_attrs(1) :='telephonenumber';  
retval := DBMS_LDAP_UTL.get_user_properties(
my_session,
my_attrs,
DBMS_LDAP_UTL.ENTRY_PROPERTIES,
my_pset_coll
);

11.2.2 Using Group-Related Subprograms

A group is represented using by using the DBMS_LDAP_UTL.HANDLE data type. A group handle represents a valid group entry. You can create a group handle by using a DN, GUID or a simple name, along with the appropriate subscriber handle. When a simple name is used, additional information from the Root Oracle Context and the Subscriber Oracle Context is used to identify the group.

Here is an example of a group handle creation:

retval := DBMS_LDAP_UTL.create_group_handle(
group_handle,
DBMS_LDAP_UTL.TYPE_DN,
"cn=group1,cn=Groups,o=example,dc=com"
);

This group handle has to be associated with an appropriate subscriber handle. For example, given a subscriber handle: subscriber_handle representing o=example,dc=com, the subscriber handle can be associated in the following way:

retval := DBMS_LDAP_UTL.set_group_handle_properties(
group_handle,
DBMS_LDAP_UTL.SUBSCRIBER_HANDLE,
subscriber_handle
);

A sample use of group handle is getting group properties. Here is an example:

my_attrs is of type DBMS_LDAP.STRING_COLLECTION
my_attrs(1) :='uniquemember';
retval := DBMS_LDAP_UTL.get_group_properties(
my_session,
my_attrs,
DBMS_LDAP_UTL.ENTRY_PROPERTIES,
my_pset_coll
);

The group-related subprograms also support membership-related functionality. Given a user handle, you can find out if it is a direct or a nested member of a group by using the DBMS_LDAP_UTL.check_group_membership() function. Here is an example:

retval := DBMS_LDAP_UTL.check_group_membership(
session,
user_handle,
group_handle,
DBMS_LDAP_UTL.DIRECT_MEMBERSHIP

You can also obtain a list of groups that a particular group belongs to, using the DBMS_LDAP_UTL.get_group_membership() function. For example:

my_attrs is of type DBMS_LDAP.STRING_COLLECTION
my_attrs(1) :='cn';
retval := DBMS_LDAP_UTL.get_group_membership(
my_session,
user_handle,
DBMS_LDAP_UTL.DIRECT_MEMBERSHIP,
my_attrs
my_pset_coll
);

11.2.3 Using Subscriber-Related Subprograms

A subscriber is represented by using dbms_ldap_utl.handle data type. You can create a subscriber handle by using a DN, GUID or simple name. When a simple name is used, additional information from the root Oracle Context is used to identify the subscriber.

This example shows a subscriber handle being created:

retval := DBMS_LDAP_UTL.create_subscriber_handle(
subscriber_handle,
DBMS_LDAP_UTL.TYPE_DN,
"o=example,dc=com"
);

subscriber_handle is created by it's DN: o=oracle,dc=com.

Getting subscriber properties is one common use of a subscriber handle. Here is an example:

my_attrs is of type DBMS_LDAP.STRING_COLLECTION
       my_attrs(1) :='orclguid';  
       retval := DBMS_LDAP_UTL.get_subscriber_properties(
my_session,
my_attrs,
DBMS_LDAP_UTL.ENTRY_PROPERTIES,
my_pset_coll
);

11.2.4 Using Property-Related Subprograms

Many of the user-related, subscriber-related, and group-related subprograms return DBMS_LDAP_UTL.PROPERTY_SET_COLLECTION, which is a collection of one or more LDAP entries representing results. Each of these entries is represented by a DBMS_LDAP_UTL.PROPERTY_SET. A PROPERTY_SET may contain attributes—that is, properties—and its values.

Here is an example that illustrates the retrieval of properties from DBMS_LDAP_UTL.PROPERTY_SET_COLLECTION:

my_attrs is of type DBMS_LDAP.STRING_COLLECTION
my_attrs(1) :='cn';

retval := DBMS_LDAP_UTL.get_group_membership(
my_session,
user_handle,
DBMS_LDAP_UTL.DIRECT_MEMBERSHIP,
my_attrs,
my_pset_coll
);

IF my_pset_coll.count > 0 THEN
      FOR i in my_pset_coll.first .. my_pset_coll.last LOOP
--    my_property_names is of type DBMS_LDAP.STRING_COLLECTION
       retval := DBMS_LDAP_UTL.get_property_names(
pset_coll(i),
property_names
       IF my_property_names.count > 0 THEN
           FOR j in my_property_names.first .. my_property_names.last LOOP
             retval := DBMS_LDAP_UTL.get_property_values(
pset_coll(i),
property_names(j),
property_values
             if my_property_values.COUNT > 0 then
              FOR k in my_property_values.FIRST..my_property_values.LAST LOOP
                     DBMS_OUTPUT.PUT_LINE(my_property_names(j)  || ':'  
                        ||my_property_values(k));
                    END LOOP; -- For each value
             else
                DBMS_OUTPUT.PUT_LINE('NO VALUES FOR' || my_property_names(j));
             end if;
           END LOOP; -- For each property name
         END IF; -- IF my_property_names.count > 0
      END LOOP; -- For each propertyset
  END IF; -- If my_pset_coll.count > 0

use_handle is a user handle. my_pset_coll contains all the nested groups that user_handle belongs to. The code loops through the resulting entries and prints out the cn of each entry.

11.3 Function Return Code Summary

The DBMS_LDAP_UTL package includes functions which return error codes.

Table 11-5 Function Return Codes

Name Return Code Description
SUCCESS
0

Operation successful.

GENERAL_ERROR
-1

This error code is returned on failure conditions other than those conditions listed here.

PARAM_ERROR
-2

Returned by all functions when an invalid input parameter is encountered.

NO_GROUP_MEMBERSHIP
-3

Returned by user-related functions and group functions when the user is not a member of a group.

NO_SUCH_SUBSCRIBER
-4

Returned by subscriber-related functions when the subscriber does not exist in the directory.

NO_SUCH_USER
-5

Returned by user-related functions when the user does not exist in the directory.

NO_ROOT_ORCL_CTX
-6

Returned by most functions when the root oracle context does not exist in the directory.

MULTIPLE_SUBSCRIBER_ENTRIES
-7

Returned by subscriber-related functions when multiple subscriber entries are found for the given subscriber nickname.

INVALID_ROOT_ORCL_CTX
-8

Root Oracle Context does not contain all the required information needed by the function.

NO_SUBSCRIBER_ORCL_CTX
-9

Oracle Context does not exist for the subscriber.

INVALID_SUBSCRIBER_ORCL_CTX
-10

Oracle Context for the subscriber is invalid.

MULTIPLE_USER_ENTRIES
-11

Returned by user-related functions when multiple user entries exist for the given user nickname.

NO_SUCH_GROUP
-12

Returned by group related functions when a group does not exist in the directory.

MULTIPLE_GROUP_ENTRIES
-13

Multiple group entries exist for the given group nickname in the directory.

ACCT_TOTALLY_LOCKED_EXCEPTION
-14

Returned by DBMS_LDAP_UTL.authenticate_user() function when a user account is locked. This error is based on the password policy set in the subscriber oracle context.

AUTH_PASSWD_CHANGE_WARN
-15

This return code is deprecated.

AUTH_FAILURE_EXCEPTION
-16

Returned by DBMS_LDAP_UTL.authenticate_user() function when user authentication fails.

PWD_EXPIRED_EXCEPTION
-17

Returned by DBMS_LDAP_UTL.authenticate_user() function when the user password has expired. This is a password policy error.

RESET_HANDLE
-18

Returned when entity handle properties are being reset by the caller.

SUBSCRIBER_NOT_FOUND
-19

Returned by DBMS_LDAP-UTL.locate_subscriber_for_user() function when it is unable to locate the subscriber.

PWD_EXPIRE_WARN
-20

Returned by DBMS_LDAP_UTL.authenticate_user() function when the user password is about to expire. This is a password policy error.

PWD_MINLENGTH_ERROR
-21

Returned by DBMS_LDAP_UTL.set_user_properties() function while changing the user password and the new user password is less than the minimum required length. This is a password policy error.

PWD_NUMERIC_ERROR
-22

Returned by DBMS_LDAP_UTL.set_user_properties() function while changing the user password and the new user password does not contain at least one numeric character. This is a password policy error.

PWD_NULL_ERROR
-23

Returned by DBMS_LDAP_UTL.set_user_properties() function while changing the user password and the new user password is an empty password. This is a password policy error.

PWD_INHISTORY_ERROR
-24

Returned by DBMS_LDAP_UTL.set_user_properties() function while changing the user password and the new user password is the same as the previous password. This is a password policy error.

PWD_ILLEGALVALUE_ERROR
-25

Returned by DBMS_LDAP_UTL.set_user_properties() function while changing the user password and the new user password has an illegal character. This is a password policy error.

PWD_GRACELOGIN_WARN
-26

Returned by DBMS_LDAP_UTL.authenticate_user() function to indicate that the user password has expired and the user has been given a grace login. This is a password policy error.

PWD_MUSTCHANGE_ERROR
-27

Returned by DBMS_LDAP_UTL.authenticate_user() function when user password must be changed. This is a password policy error.

USER_ACCT_DISABLED_ERROR
-29

Returned by DBMS_LDAP_UTL.authenticate_user() function when user account has been disabled. This is a password policy error.

PROPERTY_NOT_FOUND
-30

Returned by user-related functions while searching for a user property in the directory.

11.4 Data Type Summary

The DBMS_LDAP_UTL package includes the data types to hold entity and properties of an entity.

The DBMS_LDAP_UTL package uses the data types in the following table:

Table 11-6 DBMS_LDAP_UTL Data Types

Data Type Purpose
HANDLE

Used to hold the entity.

PROPERTY_SET

Used to hold the properties of an entity.

PROPERTY_SET_COLLECTION

List of PROPERTY_SET structures.

MOD_PROPERTY_SET

Structure to hold modify operations on an entity.

11.5 User-Related Subprograms

A user is represented by the DBMS_LDAP_UTL.HANDLE data type. You can create a user handle by using a DN, GUID, or simple name, along with the appropriate subscriber handle.

When a simple name is used, additional information from the root Oracle Context and the subscriber Oracle Context is used to identify the user.

The following topics describe the user related subprograms:

11.5.1 Function authenticate_user

The function authenticate_user()authenticates the user against Oracle Internet Directory.

Syntax

FUNCTION authenticate_user 
( 
ld IN SESSION, 
user_handle IN HANDLE, 
auth_type IN PLS_INTEGER, 
credentials IN VARCHAR2, 
binary_credentials IN RAW 
) 
RETURN PLS_INTEGER;

Parameters

Following table lists authenticate_user function parameters:

Table 11-7 authenticate_user Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

user_handle
HANDLE

The user handle.

auth_type
PLS_INTEGER

Type of authentication. The only valid value is DBMS_LDAP_UTL.AUTH_SIMPLE

credentials
VARCHAR2

The user credentials.

binary_credentials
RAW

The binary credentials. This parameter is optional. It can be NULL by default.

Return Values

Following table lists authenticate_user function return values:

Table 11-8 authenticate_user Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.GENERAL_ERROR

Authentication failed.

DBMS_LDAP_UTL.NO_SUCH_USER

User does not exist.

DBMS_LDAP_UTL.MULTIPLE_USER_ENTRIES

The user has multiple DN entries.

DBMS_LDAP_UTL.INVALID_SUBSCRIBER_ORCL_CTX

Invalid Subscriber Oracle Context.

DBMS_LDAP_UTL.NO_SUCH_SUBSCRIBER

Subscriber doesn't exist.

DBMS_LDAP_UTL.MULTIPLE_SUBSCRIBER_ENTRIES

The subscriber has multiple DN entries.

DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX

Invalid Root Oracle Context.

DBMS_LDAP_UTL.ACCT_TOTALLY_LOCKED_EXCP

User account is locked.

DBMS_LDAP_UTL.AUTH_PASSWD_CHANGE_WARN

This return value is deprecated.

DBMS_LDAP_UTL.AUTH_FAILURE_EXCP

Authentication failed.

DBMS_LDAP_UTL.PWD_EXPIRED_EXCP

User password has expired.

DBMS_LDAP_UTL.PWD_GRACELOGIN_WARN

Grace login for user.

DBMS_LDAP error codes

Return proper DBMS_LDAP error codes for unconditional failures that occurred when LDAP operations were carried out.

Usage Notes

This function can be called only after a valid LDAP session is obtained from a call to DBMS_LDAP.init().

Related Functions

DBMS_LDAP.init(), DBMS_LDAP_UTL.create_user_handle().

11.5.2 Function create_user_handle

The function create_user_handle() creates a user handle.

Syntax

FUNCTION create_user_handle 
( 
user_hd OUT HANDLE, 
user_type IN PLS_INTEGER, 
user_id IN VARCHAR2, 
) 
RETURN PLS_INTEGER;

Parameters

Following table lists create_user_handle function parameters:

Table 11-9 CREATE_USER_HANDLE Function Parameters

Parameter Name Parameter Type Parameter Description
user_hd
HANDLE

A pointer to a handle to a user.

user_type
PLS_INTEGER

The type of user ID that is passed. Valid values for this argument are as follows:

  • DBMS_LDAP_UTL.TYPE_DN

  • DBMS_LDAP_UTL.TYPE_GUID

  • DBMS_LDAP_UTL.TYPE_NICKNAME

user_id
VARCHAR2

The user ID representing the user entry.

Return Values

Following table lists create_user_handle function parameters:

Table 11-10 CREATE_USER_HANDLE Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.get_user_properties(), DBMS_LDAP_UTL.set_user_handle_properties().

11.5.3 Function set_user_handle_properties

The function set_user_handle_properties() configures the user handle properties.

Syntax

FUNCTION set_user_handle_properties 
( 
user_hd IN HANDLE, 
property_type IN PLS_INTEGER, 
property IN HANDLE 
) 
RETURN PLS_INTEGER;

Parameters

Following table lists the parameters:

Table 11-11 SET_USER_HANDLE_PROPERTIES Function Parameters

Parameter Name Parameter Type Parameter Description
user_hd
HANDLE

A pointer to a handle to a user.

property_type
PLS_INTEGER

The type of property that is passed. Valid values for this argument are as follows: - DBMS_LDAP_UTL.SUBSCRIBER_HANDLE.

property
HANDLE

The property describing the user entry.

Return Values

Following table lists the set_user_handle_properties function return values:

Table 11-12 SET_USER_HANDLE_PROPERTIES Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.RESET_HANDLE

When a caller tries to reset the existing handle properties.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

Usage Notes

The subscriber handle does not have to be set in User Handle Properties if the user handle is created with TYPE_DN or TYPE_GUID as the user type.

Related Functions

DBMS_LDAP_UTL.get_user_properties().

11.5.4 Function get_user_properties

The function get_user_properties() retrieves the user properties.

Syntax

FUNCTION get_user_properties 
( 
ld IN SESSION, 
user_handle IN HANDLE, 
attrs IN STRING_COLLECTION, 
ptype IN PLS_INTEGER, 
ret_pset_coll OUT PROPERTY_SET_COLLECTION 
) 
RETURN PLS_INTEGER;

Parameters

Following table lists get_user_properties function parameters:

Table 11-13 GET_USER_PROPERTIES Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

user_handle
HANDLE

The user handle.

attrs
STRING_COLLECTION

The list of user attributes to retrieve.

ptype
PLS_INTEGER

Type of properties to return. These are valid values:

  • DBMS_LDAP_UTL.ENTRY_PROPERTIES

  • DBMS_LDAP_UTL.NICKNAME_PROPERTY

ret-pset_collection
PROPERTY_SET_COLLECTION

User details contained in attributes requested by the caller.

Return Values

Following table lists get_user_properties function return values:

Table 11-14 GET_USER_PROPERTIES Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.NO_SUCH_USER

User does not exist.

DBMS_LDAP_UTL.MULTIPLE_USER_ENTRIES

The user has multiple DN entries.

DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX

Invalid root Oracle Context.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

DBMS_LDAP error codes

Return proper DBMS_LDAP error codes for unconditional failures that occur when LDAP operations are carried out.

Usage Notes

This function requires the following:

  • A valid LDAP session handle, which must be obtained from the DBMS_LDAP.init() function.

  • A valid subscriber handle to be set in the group handle properties if the user type is of DBMS_LDAP_UTL.TYPE_NICKNAME.

This function does not identify a NULL subscriber handle as a default subscriber. The default subscriber can be obtained from DBMS_LDAP_UTL.create_subscriber_handle(), where a NULL subscriber_id is passed as an argument.

If the group type is either DBMS_LDAP_UTL.TYPE_GUID or DBMS_LDAP_UTL.TYPE_DN, the subscriber handle need not be set in the user handle properties. If the subscriber handle is set, it is ignored.

Related Functions

DBMS_LDAP.init(), DBMS_LDAP_UTL.create_user_handle().

11.5.5 Function set_user_properties

The function set_user_properties() modifies the properties of a user.

Syntax

FUNCTION set_user_properties 
( 
ld IN SESSION, 
user_handle IN HANDLE, 
pset_type IN PLS_INTEGER, 
mod_pset IN PROPERTY_SET, 
mod_op IN PLS_INTEGER 
) 
RETURN PLS_INTEGER;

Parameters

Following table lists the set_user_properties function parameters:

Table 11-15 SET_USER_PROPERTIES Function Parameters

Parameter Name Parameter Type Description
ld
SESSION

A valid LDAP session handle.

user_handle
HANDLE

The user handle.

pset_type
PLS_INTEGER

The type of property set being modified. A valid value is ENTRY_PROPERTIES.

mod_pset
PROPERTY_SET

Data structure containing modify operations to perform on the property set.

mod_op
PLS_INTEGER

The type of modify operation to be performed on the property set. Here are valid values:

  • ADD_PROPERTYSET

  • MODIFY_PROPERTYSET

  • DELETE_PROPERTYSET

Return Values

Following table lists set_user_properties return values:

Table 11-16 SET_USER_PROPERTIES Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.NO_SUCH_USER

User does not exist.

DBMS_LDAP_UTL.MULTIPLE_USER_ENTRIES

The user has multiple DN entries.

DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX

Invalid root Oracle Context.

DBMS_LDAP_UTL.PWD_MIN_LENGTH_ERROR

Password length is less than the minimum required length.

DBMS_LDAP_UTL.PWD_NUMERIC_ERROR

Password must contain numeric characters.

DBMS_LDAP_UTL.PWD_NULL_ERROR

Password cannot be NULL.

DBMS_LDAP_UTL.PWD_INHISTORY_ERROR

Password cannot be the same as the one that is being replaced.

DBMS_LDAP_UTL.PWD_ILLEGALVALUE_ERROR

Password contains illegal characters.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

DBMS_LDAP error codes

Return proper DBMS_LDAP error codes for unconditional failures while carrying out LDAP operations by the LDAP server.

Usage Notes

This function can only be called after a valid LDAP session is obtained from a call to DBMS_LDAP.init().

Related Functions

DBMS_LDAP.init(), DBMS_LDAP_UTL.get_user_properties().

11.5.6 Function get_user_extended_properties

The function get_user_extended_properties() retrieves user extended properties.

Syntax

FUNCTION get_user_extended_properties 
( 
ld IN SESSION, 
user_handle IN HANDLE, 
attrs IN STRING_COLLECTION 
ptype IN PLS_INTEGER, 
filter IN VARCHAR2, 
rep_pset_coll OUT PROPERTY_SET_COLLECTION 
) 
RETURN PLS_INTEGER;

Parameters

Following table lists the get_user_extended_properties function parameters:

Table 11-17 GET_USER_EXTENDED_PROPERTIES Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

user_handle
HANDLE

The user handle.

attrs
STRING_COLLECTION

A list of attributes to fetch for the user.

ptype
PLS_INTEGER

The type of properties to return. Here is a valid value: - DBMS_LDAP_UTL.EXTPROPTYPE_RAD

filter
VARCHAR2

An LDAP filter to further refine the user properties returned by the function.

ret_pset_collection
PROPERTY_SET_COLLECTION

The user details containing the attributes requested by the caller.

Return Values

Following table lists get_user_extended_properties function return values:

Table 11-18 GET_USER_EXTENDED_PROPERTIES Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.NO_SUCH_USER

User does not exist.

DBMS_LDAP_UTL.MULTIPLE_USER_ENTRIES

The user has multiple DN entries.

USER_PROPERTY_NOT_FOUND

User extended property does not exist.

DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX

Invalid root Oracle Context.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

DBMS_LDAP error codes

Return proper DBMS_LDAP error codes for unconditional failures that occur when LDAP operations are carried out.

Usage Notes

This function can be called only after a valid LDAP session is obtained from a call to DBMS_LDAP.init().

Related Functions

DBMS_LDAP.init(), DBMS_LDAP_UTL.get_user_properties().

11.5.7 Function get_user_dn

The function get_user_dn() returns the user DN.

Syntax

FUNCTION get_user_dn 
( 
ld IN SESSION, 
user_handle IN HANDLE, 
dn OUT VARCHAR2
) 
RETURN PLS_INTEGER;

Parameters

Following table lists get_user_dn parameters:

Table 11-19 GET_USER_DN Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

user_handle
HANDLE

The user handle.

dn
VARCHAR2

The user DN.

Return Values

Following table lists get_user_dn function return values:

Table 11-20 GET_USER_DN Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.GENERAL_ERROR

Authentication failed.

DBMS_LDAP_UTL.NO_SUCH_USER 

User does not exist.

DBMS_LDAP_UTL.MULTIPLE_USER_ENTRIES

The user has multiple DN entries.

DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX

Invalid root Oracle Context.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

DBMS_LDAP error codes

Return proper DBMS_LDAP error codes for unconditional failures that occur when LDAP operations are carried out.

Usage Notes

This function can be called only after a valid LDAP session is obtained from a call to DBMS_LDAP.init().

Related Functions

DBMS_LDAP.init().

11.5.8 Function check_group_membership

The function check_group_membership() checks whether the user belongs to a group.

Syntax

FUNCTION check_group_membership 
( 
ld IN SESSION, 
user_handle IN HANDLE, 
group_handle IN HANDLE, 
nested IN PLS_INTEGER 
) 
RETURN PLS_INTEGER;

Parameters

The following table lists check_group_membership function parameters:

Table 11-21 CHECK_GROUP_MEMBERSHIP Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

user_handle
HANDLE

The user handle.

group_handle
HANDLE

The group handle.

nested
PLS_INTEGER

The type of membership the user holds in groups. Here are valid values:

  • DBMS_LDAP_UTL.NESTED_MEMBERSHIP

  • DBMS_LDAP_UTL.DIRECT_MEMBERSHIP

Return Values

The following table lists check_group_membership function return values:

Table 11-22 CHECK_GROUP_MEMBERSHIP Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

If user is a member.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.NO_GROUP_MEMBERSHIP

If user is not a member.

Usage Notes

This function can be called only after a valid LDAP session is obtained from a call to DBMS_LDAP.init().

Related Functions

DBMS_LDAP.get_group_membership().

11.5.9 Function locate_subscriber_for_user

The function locate_subscriber_for_user() retrieves the subscriber for the given user and returns a handle to it.

Syntax

FUNCTION locate_subscriber_for_user 
( 
ld IN SESSION, 
user_handle IN HANDLE, 
subscriber_handle OUT HANDLE 
) 
RETURN PLS_INTEGER;

Parameters

Following table lists locate_subscriber_for_user function parameters:

Table 11-23 LOCATE_SUBSCRIBER_FOR_USER Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

user_handle
HANDLE

The user handle.

subscriber_handle
HANDLE

The subscriber handle.

Return Values

Following table lists locate subscriber for user function return values:

Table 11-24 LOCATE SUBSCRIBER FOR USER Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS 

On a successful completion.

DBMS_LDAP_UTL.NO_SUCH_SUBSCRIBER

Subscriber doesn't exist.

DBMS_LDAP_UTL.MULTIPLE_SUBSCRIBER_ENTRIES

Multiple number of subscriber DN entries exist in the directory for the given subscriber.

DBMS_LDAP_UTL.NO_SUCH_USER

User doesn't exist.

DBMS_LDAP_UTL.MULTIPLE_USER_ENTRIES

Multiple number of user DN entries exist in the directory for the given user.

DBMS_LDAP_UTL.SUBSCRIBER_NOT_FOUND

Unable to locate subscriber for the given user.

DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX

Invalid Root Oracle Context.

DBMS_LDAP_UTL.ACCT_TOTALLY_LOCKED_EXCP

User account is locked.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

DBMS_LDAP error codes

Return proper DBMS_LDAP error codes for unconditional failures while carrying out LDAP operations by the LDAP server.

Usage Notes

This function can be called only after a valid LDAP session is obtained from a call to DBMS_LDAP.init().

Related Functions

DBMS_LDAP.init(), DBMS_LDAP_UTL.create_user_handle().

11.5.10 Function get_group_membership

The function get_group_membership() returns the list of groups to which the user is a member.

Syntax

FUNCTION get_group_membership 
( 
user_handle IN HANDLE, 
nested IN PLS_INTEGER, 
attr_list IN STRING_COLLECTION, 
ret_groups OUT PROPERTY_SET_COLLECTION
) 
RETURN PLS_INTEGER;

Parameters

Following table lists get_group_membership function parameters:

Table 11-25 GET_GROUP_MEMBERSHIP Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

user_handle
HANDLE

The user handle.

nested
PLS_INTEGER

The type of membership the user holds in groups. Here are valid values:

  • DBMS_LDAP_UTL.NESTED_MEMBERSHIP

  • DBMS_LDAP_UTL.DIRECT_MEMBERSHIP

attr_list
STRING_COLLECTION

A list of attributes to be returned.

ret_groups
PROPERTY_SET_COLLECTION

A pointer to a pointer to an array of group entries.

Return Values

The following table lists get_group_membership function return values:

Table 11-26 GET_GROUP_MEMBERSHIP Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

Usage Notes

This function can be called only after a valid LDAP session is obtained from a call to DBMS_LDAP.init().

Related Functions

DBMS_LDAP.init().

11.6 Group-Related Subprograms

A group is represented using by using the DBMS_LDAP_UTL.HANDLE data type. A group handle represents a valid group entry. You can create a group handle by using a DN, GUID or a simple name, along with the appropriate subscriber handle.

When a simple name is used, additional information from the Root Oracle Context and the Subscriber Oracle Context is used to identify the group.

The following topics describe group_related subprograms:

11.6.1 Function create_group_handle

The function create_group_handle() creates a group handle.

Syntax

FUNCTION create_group_handle 
( 
group_hd OUT HANDLE, 
group_type IN PLS_INTEGER, 
group_id IN VARCHAR2  
) 
RETURN PLS_INTEGER;

Parameters

The following table create_group_handle function parameters:

Table 11-27 CREATE_GROUP_HANDLE Function Parameters

Parameter Name Parameter Type Parameter Description
group_hd
HANDLE

A pointer to a handle to a group.

group_type
PLS_INTEGER

The type of group ID that is passed. Valid values for this argument are as follows:

  • DBMS_LDAP_UTL.TYPE_DN

  • DBMS_LDAP_UTL.TYPE_GUID

  • DBMS_LDAP_UTL.TYPE_NICKNAME

group_id
VARCHAR2

The group ID representing the group entry.

Return Values

Following table lists create_group_handle function return values:

Table 11-28 CREATE_GROUP_HANDLE Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.get_group_properties(), DBMS_LDAP_UTL.set_group_handle_properties().

11.6.2 Function set_group_handle_properties

The function set_group_handle_properties() configures the group handle properties.

Syntax

FUNCTION set_group_handle_properties 
( 
group_hd IN HANDLE, 
property_type IN PLS_INTEGER, 
property IN HANDLE 
) 
RETURN PLS_INTEGER;

Parameters

Following table lists set_group_handle_properties function parameters:

Table 11-29 SET_GROUP_HANDLE_PROPERTIES Function Parameters

Parameter Name Parameter Type Parameter Description
group_hd
HANDLE

A pointer to the handle to the group.

property_type
PLS_INTEGER

The type of property that is passed. Valid values for this argument are as follows: DBMS_LDAP_UTL.GROUP_HANDLE

property
HANDLE

The property describing the group entry.

Return Values

Following table lists set_group_handle_properties function return values:

Table 11-30 SET_GROUP_HANDLE_PROPERTIES Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.RESET_HANDLE

When a caller tries to reset the existing handle properties.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

Usage Notes

The subscriber handle doesn't need to be set in Group Handle Properties if the group handle is created with TYPE_DN or TYPE_GUID as the group type.

Related Functions

DBMS_LDAP_UTL.get_group_properties().

11.6.3 Function get_group_properties

The function get_group_properties() retrieves the group properties.

Syntax

FUNCTION get_group_properties 
( 
ld IN SESSION, 
group_handle IN HANDLE, 
attrs IN STRING_COLLECTION, 
ptype IN PLS_INTEGER, 
ret_pset_coll OUT PROPERTY_SET_COLLECTION
) 
RETURN PLS_INTEGER;

Parameters

The following table lists get_group_properties function parameters:

Table 11-31 GET_GROUP_PROPERTIES Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

group_handle
HANDLE

The group handle.

attrs
STRING_COLLECTION

A list of attributes that must be fetched for the group.

ptype
PLS_INTEGER

The type of properties to be returned. The valid value is DBMS_LDAP_UTL.ENTRY_PROPERTIES

ret_pset_coll
PROPERTY_SET_COLLECTION

The group details containing the attributes requested by the caller.

Return Values

The following table lists get_group_properties function return values:

Table 11-32 GET_GROUP_PROPERTIES Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS 

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR 

Invalid input parameters.

DBMS_LDAP_UTL.NO_SUCH_GROUP

Group doesn't exist.

DBMS_LDAP_UTL.MULTIPLE_GROUP_ENTRIES

Multiple number of group DN entries exist in the directory for the given group.

DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX

Invalid Root Oracle Context.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

DBMS_LDAP error codes

Return proper DBMS_LDAP error codes for unconditional failures while carrying out LDAP operations by the LDAP server.

Usage Notes

This function requires the following:

  • A valid LDAP session handle which must be obtained from the DBMS_LDAP.init() function.

  • A valid subscriber handle to be set in the group handle properties if the group type is of: DBMS_LDAP_UTL.TYPE_NICKNAME.

This function does not identify a NULL subscriber handle as a default subscriber. The default subscriber can be obtained from DBMS_LDAP_UTL.create_subscriber_handle(), where a NULL subscriber_id is passed as an argument.

If the group type is either DBMS_LDAP_UTL.TYPE_GUID or DBMS_LDAP_UTL.TYPE_DN, the subscriber handle does not have to be set in the group handle properties. If the subscriber handle is set, it is ignored.

Related Functions

DBMS_LDAP.init(), DBMS_LDAP_UTL.create_group_handle().

11.6.4 Function get_group_dn

The function get_group_dn()returns the group DN.

Syntax

FUNCTION get_group_dn
( 
ld IN SESSION,
group_handle IN HANDLE
dn OUT VARCHAR2
) 
RETURN PLS_INTEGER;

Parameters

The following table lists get_group_dn function parameters:

Table 11-33 GET_GROUP_DN Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

group_handle
HANDLE

The group handle.

dn
VARCHAR2

The group DN.

Return Values

The following table lists get_group_dn function return values:

Table 11-34 GET_GROUP_DN Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.NO_SUCH_GROUP

Group doesn't exist.

DBMS_LDAP_UTL.MULTIPLE_GROUP_ENTRIES

Multiple number of group DN entries exist in the directory for the given group.

DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX

Invalid Root Oracle Context.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

DBMS_LDAP error codes

Return proper DBMS_LDAP error codes for unconditional failures that are encountered when LDAP operations are carried out.

Usage Notes

This function can only be called after a valid LDAP session is obtained from a call to DBMS_LDAP.init().

Related Functions

DBMS_LDAP.init().

11.7 Subscriber-Related Subprograms

A subscriber is represented by using dbms_ldap_utl.handle data type. You can create a subscriber handle by using a DN, GUID or simple name.

When a simple name is used, additional information from the root Oracle Context is used to identify the subscriber.

The Subscriber related subprograms are described below:

11.7.1 Function create_subscriber_handle

The function create_subscriber_handle() creates a subscriber handle.

Syntax

FUNCTION create_subscriber_handle 
( 
subscriber_hd OUT HANDLE, 
subscriber_type IN PLS_INTEGER, 
subscriber_id IN VARCHAR2 
) 
RETURN PLS_INTEGER;

Parameters

The following table lists create_subscriber_handle function parameters:

Table 11-35 CREATE_SUBSCRIBER_HANDLE Function Parameters

Parameter Name Parameter Type Parameter Description
subscriber_hd
HANDLE

A pointer to a handle to a subscriber.

subscriber_type
PLS_INTEGER

The type of subscriber ID that is passed. Valid values for this argument are:

  • DBMS_LDAP_UTL.TYPE_DN

  • DBMS_LDAP_UTL.TYPE_GUID

  • DBMS_LDAP_UTL.TYPE_NICKNAME

  • DBMS_LDAP_UTL.TYPE_DEFAULT

subscriber_id
VARCHAR2

The subscriber ID representing the subscriber entry. This can be NULL if subscriber_type is DBMS_LDAP_UTL.TYPE_DEFAULT. In this case, the default subscriber is retrieved from the root Oracle Context.

Return Values

The following table lists create_subscriber_handle function return values:

Table 11-36 CREATE_SUBSCRIBER_HANDLE Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.get_subscriber_properties().

11.7.2 Function get_subscriber_properties

The function get_subscriber_properties()retrieves the subscriber properties for the given subscriber handle.

Syntax

FUNCTION get_subscriber_properties 
( 
ld IN SESSION, 
subscriber_handle IN HANDLE, 
attrs IN STRING_COLLECTION, 
ptype IN PLS_INTEGER, 
ret_pset_coll OUT PROPERTY_SET_COLLECTION
) 
RETURN PLS_INTEGER;

Parameters

The following table get_subscriber_properties function parameters:

Table 11-37 GET_SUBSCRIBER_PROPERTIES Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

subscriber_handle
HANDLE

The subscriber handle.

attrs
STRING_COLLECTION

A list of attributes that must be retrieved for the subscriber.

ptype
PLS_INTEGER

Properties of the subscriber's Oracle Context to return. These are valid values:

  • DBMS_LDAP_UTL.ENTRY_PROPERTIES

  • DBMS_LDAP_UTL.COMMON_PROPERTIES

ret_pset_coll
PROPERTY_SET_COLLECTION

The subscriber details containing the attributes requested by the caller.

Return Values

The following table lists get_subscriber_properties function return values:

Table 11-38 GET_SUBSCRIBER_PROPERTIES Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.NO_SUCH_SUBSCRIBER

Subscriber doesn't exist.

DBMS_LDAP_UTL.MULTIPLE_SUBSCRIBER_ENTRIES

Subscriber has a multiple number of DN entries.

DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX

Invalid root Oracle Context.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

DBMS_LDAP error codes

Return proper DBMS_LDAP error codes for unconditional failures encountered while LDAP operations are carried out.

Usage Notes

This function can only be called after a valid LDAP session is obtained from a call to DBMS_LDAP.init().

Related Functions

DBMS_LDAP.init(), DBMS_LDAP_UTL.create_subscriber_handle().

11.7.3 Function get_subscriber_dn

The function get_subscriber_dn() returns the subscriber DN.

Syntax

FUNCTION get_subscriber_dn 
( 
ld IN SESSION, 
subscriber_handle IN HANDLE, 
dn OUT VARCHAR2
) 
RETURN PLS_INTEGER;

Parameters

The following table lists get_subscriber_dn function parameters:

Table 11-39 GET_SUBSCRIBER_DN Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

subscriber_handle
HANDLE

The subscriber handle.

dn
VARCHAR2

The subscriber DN.

Return Values

The following table lists get_subscriber_dn function return values:

Table 11-40 GET_SUBSCRIBER_DN Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.NO_SUCH_SUBSCRIBER

Subscriber doesn't exist.

DBMS_LDAP_UTL.MULTIPLE_SUBSCRIBER_ENTRIES

Multiple number of subscriber DN entries exist in the directory for the given subscriber.

DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX

Invalid root Oracle Context.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

DBMS_LDAP error codes

Return proper DBMS_LDAP error codes for unconditional failures encountered when LDAP operations are carried out.

Usage Notes

This function can only be called after a valid LDAP session is obtained from a call to DBMS_LDAP.init().

Related Functions

DBMS_LDAP.init().

11.7.4 Function get_subscriber_ext_properties

The function get_subscriber_ext_properties() retrieves the subscriber extended properties. Currently this can be used to retrieve the subscriber-wide default Resource Access Descriptors.

Syntax

FUNCTION get_subscriber_ext_properties
(
ld IN SESSION,
subscriber_handle IN HANDLE,
attrs IN STRING_COLLECTION,
ptype IN PLS_INTEGER,
filter IN VARCHAR2,
rep_pset_coll OUT PROPERTY_SET_COLLECTION
)
RETURN PLS_INTEGER;

Parameters

The following table lists get_subscriber_ext_properties function parameters:

Table 11-41 GET_SUBSCRIBER_EXT_PROPERTIES Function Parameters

Parameter Name Parameter Type Parameter Description
ld
SESSION

A valid LDAP session handle.

subscriber_handle
HANDLE

The subscriber handle.

attrs
STRING_COLLECTION

A list of subscriber attributes to retrieve.

ptype
PLS_INTEGER

The type of properties to return. A valid value is DBMS_LDAP_UTL.DEFAULT_RAD_PROPERTIES

filter
VARCHAR2

An LDAP filter to further refine the subscriber properties returned by the function.

ret_pset_collection
PROPERTY_SET_COLLECTION

The subscriber details containing the attributes requested by the caller.

Return Values

The following table lists get_user_extended_properties function return values:

Table 11-42 GET_USER_EXTENDED_PROPERTIES Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS 

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR 

Invalid input parameters.

DBMS_LDAP_UTL.NO_SUCH_USER

User does not exist.

DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX

Invalid root Oracle Context.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

DBMS_LDAP error codes

Return proper DBMS_LDAP error codes for unconditional failures encountered when LDAP operations are carried out.

Usage Notes

This function can be called only after a valid LDAP session is obtained from a call to DBMS_LDAP.init().

Related Functions

DBMS_LDAP.init(), DBMS_LDAP_UTL.get_subscriber_properties().

11.8 Property-Related Subprograms

Many of the user-related, subscriber-related, and group-related subprograms return DBMS_LDAP_UTL.PROPERTY_SET_COLLECTION, which is a collection of one or more LDAP entries representing results.

Each of these entries is represented by a DBMS_LDAP_UTL.PROPERTY_SET. A PROPERTY_SET may contain attributes—that is, properties—and its values.

11.9 Miscellaneous Subprograms

The miscellaneous subprograms in the DBMS_LDAP_UTL package perform a variety of different functions.

11.9.1 Function normalize_dn_with_case

The function normalize_dn_with_case() removes unnecessary white space characters from a DN and converts all characters to lowercase based on a flag.

Syntax

FUNCTION normalize_dn_with_case 
( 
dn IN VARCHAR2, 
lower_case IN PLS_INTEGER, 
norm_dn OUT VARCHAR2 
) 
RETURN PLS_INTEGER;

Parameters

The following table lists normalize_dn_with_case function parameters:

Table 11-43 NORMALIZE_DN_WITH_CASE Function Parameters

Parameter Name Parameter Type Parameter Description
dn
VARCHAR2

The DN.

lower_case
PLS_INTEGER

If set to 1: The normalized DN returns in lowercase. If set to 0: The case is preserved in the normalized DN string.

norm_dn
VARCHAR2

The normalized DN.

Return Values

The following table lists normalize_dn_with_case function return values

Table 11-44 NORMALIZE_DN_WITH_CASE Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.GENERAL_ERROR

On failure.

Usage Notes

This function can be used while comparing two DNs.

Related Functions

None

11.9.2 Function get_property_names

The function get_property_names() retrieves the list of property names in the property set.

Syntax

FUNCTION get_property_names 
( 
pset IN PROPERTY_SET, 
property_names OUT STRING_COLLECTION 
) 
RETURN PLS_INTEGER;

Parameters

The following table lists get_property_names function parameters:

Table 11-45 GET_PROPERTY_NAMES Function Parameters

Parameter Name Parameter Type Parameter Description
pset
PROPERTY_SET

The property set in the property set collection returned from any of the following functions:

  • DBMS_LDAP_UTL.get_group_membership()

  • DBMS_LDAP_UTL.get_subscriber_properties()

  • DBMS_LDAP_UTL.get_user_properties()

  • DBMS_LDAP_UTL.get_group_properties()

property_names
STRING_COLLECTION

A list of property names associated with the property set.

Return Values

The following table lists get_property_names function return values:

Table 11-46 GET_PROPERTY_NAMES Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS 

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.GENERAL_ERROR

On error.

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.get_property values().

11.9.3 Function get_property_values

The function get_property_values() retrieves the property values (the strings) for a given property name and property.

Syntax

FUNCTION get_property_values 
( 
pset IN PROPERTY_SET, 
property_name IN VARCHAR2, 
property_values OUT STRING_COLLECTION 
) 
RETURN PLS_INTEGER;

Parameters

The following table lists get_property_values function parameters:

Table 11-47 GET_PROPERTY_VALUES Function Parameters

Parameter Name Parameter Type Parameter Description
property_name
VARCHAR2

The property name.

pset
PROPERTY_SET

The property set in the property set collection obtained from any of the following function returns:

  • DBMS_LDAP_UTL.get_group_membership()

  • DBMS_LDAP_UTL.get_subscriber_properties()

  • DBMS_LDAP_UTL.get_user_properties()

  • DBMS_LDAP_UTL.get_group_properties()

property_values
STRING_COLLECTION

A list of property values (strings).

Return Values

The following table lists get_property_values function return values:

Table 11-48 GET_PROPERTY_VALUES Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS 

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.GENERAL_ERROR

On failure.

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.get_property_values_len().

11.9.4 Function get_property_values_len

The function get_property_values_len() retrieves the binary property values for a given property name and property.

Syntax

Parameters

Return Values

See Also

Syntax

FUNCTION get_property_values_len 
( 
pset IN PROPERTY_SET, 
property_name IN VARCHAR2, 
auth_type IN PLS_INTEGER, 
property_values OUT BINVAL_COLLECTION 
) 
RETURN PLS_INTEGER;

Parameters

The following table lists get_property_values_len function parameters:

Table 11-49 GET_PROPERTY_VALUES_LEN Function Parameters

Parameter Name Parameter Type Parameter Description
property_name
VARCHAR2

A property name.

pset
PROPERTY_SET

The property set in the property set collection obtained from any of the following function returns:

  • DBMS_LDAP_UTL.get_group_membership()

  • DBMS_LDAP_UTL.get_subscriber_properties()

  • DBMS_LDAP_UTL.get_user_properties()

  • DBMS_LDAP_UTL.get_group_properties()

property_values
BINVAL_COLLECTION

A list of binary property values.

Return Values

The following table lists get_property_values_len function return values:

Table 11-50 GET_PROPERTY_VALUES_LEN Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR 

Invalid input parameters.

DBMS_LDAP_UTL.GENERAL_ERROR

On failure.

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.get_property_values().

11.9.5 Procedure free_propertyset_collection

The procedure free_propertyset_collection() frees the memory associated with property set collection.

Syntax

PROCEDURE free_propertyset_collection 
( 
pset_collection IN OUT PROPERTY_SET_COLLECTION
); 

Parameters

The following table lists free_propertyset_collection procedure parameters:

Table 11-51 FREE_PROPERTYSET_COLLECTION Procedure Parameters

Parameter Name Parameter Type Parameter Description
pset_collection
PROPERTY_SET_COLLECTION

The property set collection returned from one of the following functions:

  • DBMS_LDAP_UTL.get_group_membership()

  • DBMS_LDAP_UTL.get_subscriber_properties()

  • DBMS_LDAP_UTL.get_user_properties()

  • DBMS_LDAP_UTL.get_group_properties()

Return Values

None

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.get_group_membership(), DBMS_LDAP_UTL.get_subscriber_properties(), DBMS_LDAP_UTL.get_user_properties(), DBMS_LDAP_UTL.get_group_properties().

11.9.6 Function create_mod_propertyset

The function create_mod_propertyset() creates a MOD_PROPERTY_SET data structure.

Syntax

FUNCTION create_mod_propertyset 
( 
pset_type IN PLS_INTEGER, 
pset_name IN VARCHAR2, 
mod_pset OUT MOD_PROPERTY_SET 
) 
RETURN PLS_INTEGER;

Parameters

The following table lists create_mod_propertyset function parameters:

Table 11-52 CREATE_MOD_PROPERTYSET Function Parameters

Parameter Name Parameter Type Parameter Description
pset_type
PLS_INTEGER

The type of property set being modified. Here is a valid value: ENTRY_PROPERTIES

pset_name
VARCHAR2

The name of the property set. This can be NULL if ENTRY_PROPERTIES are being modified.

mod_pset
MOD_PROPERTY_SET

The data structure to contain modify operations to be performed on the property set.

Return Values

The following table lists create_mod_propertyset function return values:

Table 11-53 CREATE_MOD_PROPERTYSET Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.populate_mod_propertyset().

11.9.7 Function populate_mod_propertyset

The function populate_mod_propertyset() populates the MOD_PROPERTY_SET data structure.

Syntax

FUNCTION populate_mod_propertyset 
( 
mod_pset IN MOD_PROPERTY_SET,
property_mod_op IN PLS_INTEGER,
property_name IN VARCHAR2,
property_values IN STRING_COLLECTION
) 
RETURN PLS_INTEGER;

Parameters

The following table lists populate_mod_propertyset function parameters:

Table 11-54 POPULATE_MOD_PROPERTYSET Function Parameters

Parameter Name Parameter Type Parameter Description
mod_pset
MOD_PROPERTY_SET

Mod-PropertySet data structure.

property_mod_op
PLS_INTEGER

The type of modify operation to perform on a property. These are valid values:

  • ADD_PROPERTY

  • REPLACE_PROPERTY

  • DELETE_PROPERTY

property_name
VARCHAR2

The name of the property

property_values
STRING_COLLECTION

Values associated with the property.

Return Values

The following table lists populate_mod_propertyset function return values:

Table 11-55 POPULATE_MOD_PROPERTYSET Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.GENERAL_ERROR

Authentication failed.

DBMS_LDAP_UTL.PWD_GRACELOGIN_WARN

Grace login for user.

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.create_mod_propertyset().

11.9.8 Procedure free_mod_propertyset

The procedure free_mod_propertyset() frees the MOD_PROPERTY_SET data structure.

Syntax

PROCEDURE free_mod_propertyset 
( 
mod_pset IN MOD_PROPERTY_SET
); 

Parameters

The following table lists free_mod_propertyset procedure parameters:

Table 11-56 FREE_MOD_PROPERTYSET Procedure Parameters

Parameter Name Parameter Type Parameter Description
mod_pset
PROPERTY_SET

Mod_PropertySet data structure.

Return Values

None

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.create_mod_propertyset().

11.9.9 Procedure free_handle

The procedure free_handle() frees the memory associated with the handle.

Syntax

PROCEDURE free_handle 
( 
handle IN OUT HANDLE 
); 

Parameters

The following table lists free_handle procedure parameters:

Table 11-57 FREE_HANDLE Procedure Parameters

Parameter Name Parameter Type Parameter Description
handle
HANDLE

A pointer to a handle.

Return Values

None

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.create_user_handle(), DBMS_LDAP_UTL.create_subscriber_handle(), DBMS_LDAP_UTL.create_group_handle().

11.9.10 Function check_interface_version

The function check_interface_version() checks the interface version.

Syntax

FUNCTION check_interface_version 
( 
interface_version IN VARCHAR2 
)
RETURN PLS_INTEGER; 

Parameters

The following table lists check_interface_version function parameters:

Table 11-58 CHECK_INTERFACE_VERSION Function Parameters

Parameter Name Parameter Type Parameter Description
interface_version
VARCHAR2

Version of the interface.

Return Values

The following table lists check_interface_version return values:

Table 11-59 CHECK_VERSION_INTERFACE Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

Interface version is supported.

DBMS_LDAP_UTL.GENERAL_ERROR

Interface version is not supported.

Usage Notes

None

Related Functions

None

11.9.11 Function get_property_values_blob

The function get_property_values_blob() retrieves large binary property values for a given property name and property.

Syntax

FUNCTION get_property_values_blob
(
pset IN PROPERTY_SET,
property_name IN VARCHAR2,
auth_type IN PLS_INTEGER,
property_values OUT BLOB_COLLECTION
)
RETURN PLS_INTEGER;

Parameters

The following table lists get_property_values_blob function parameters:

Table 11-60 GET_PROPERTY_VALUES_BLOB Function Parameters

Parameters Parameter Type Description
property_name
VARCHAR2

A property name.

pset
PROPERTY_SET

The property set in the property set collection obtained from any of the following function returns:

  • DBMS_LDAP_UTL.get_group_membership()

  • DBMS_LDAP_UTL.get_subscriber_properties()

  • DBMS_LDAP_UTL.get_user_properties()

  • DBMS_LDAP_UTL.get_group_properties()

property_values
BLOB_COLLECTION

A list of binary property values.

Return Values

The following table lists get_property_values_blob function return values:

Table 11-61 GET_PROPERTY_VALUES_BLOB Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.PARAM_ERROR

Invalid input parameters.

DBMS_LDAP_UTL.GENERAL_ERROR

On failure.

Usage Notes

None

Related Functions

DBMS_LDAP_UTL.get_property_values().

11.9.12 Procedure property_value_free_blob

Frees the memory associated with BLOB_COLLECTION returned by DBMS_LDAP.get_property_values_blob().

Syntax

Syntax
PROCEDURE property_value_free_blob
(
vals IN OUT DBMS_LDAP.BLOB_COLLECTION
);

Parameters

The following table lists property_value_free_blob function parameters:

Table 11-62 PROPERTY_VALUE_FREE_BLOB Function Parameters

Parameter Description
vals

The collection of large binary values returned by DBMS_LDAP.get_property_values_blob().

Return Values

None

Usage Notes

None

Related Functions

DBMS_LDAP.get_property_values_blob().