Skip Headers
Oracle® Identity Management Application Developer's Guide
10g Release 2 (10.1.2)
B14087-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

14 DBMS_LDAP_UTL PL/SQL Reference

This chapter contains reference material for the DBMS_LDAP_UTL package, which contains Oracle Extension utility functions. The chapter contains these topics:


Note:

Sample code for the DBMS_LDAP_UTL package is available at this URL:
http://www.oracle.com/technology/sample_code/

Look for the Oracle Identity Management link under Sample Applications–Oracle Application Server.


14.1 Summary of Subprograms

Table 14-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.


Table 14-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.


Table 14-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.


Table 14-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.


14.2 Subprograms

This section contains the following topics:

14.2.1 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. This 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=acme,dc=com"
);

This user handle must be associated with an appropriate subscriber handle. If, for example, subscriber_handle is o=acme,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
);

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

Table 14-5 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

Table 14-6 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().

See Also

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

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

Table 14-7 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

Table 14-8 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.


See Also

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

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

Table 14-9 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

Table 14-10 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.

See Also

DBMS_LDAP_UTL.get_user_properties().

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

Table 14-11 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

Table 14-12 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.

See Also

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

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

Table 14-13 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

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

See Also

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

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

Table 14-15 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

Table 14-16 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().

See Also

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

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

Table 14-17 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

Table 14-18 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().

See Also

DBMS_LDAP.init().

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

Table 14-19 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

Table 14-20 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.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().

See Also

DBMS_LDAP.get_group_membership().

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

Table 14-21 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

Table 14-22 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().

See Also

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

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

Table 14-23 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

Table 14-24 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().

See Also

DBMS_LDAP.init().

14.2.2 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=acme,dc=com"
);

This group handle has to be associated with an appropriate subscriber handle. For example, given a subscriber handle: subscriber_handle representing o=acme,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
);

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

Table 14-25 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

Table 14-26 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.


See Also

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

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

Table 14-27 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

Table 14-28 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.

See Also

DBMS_LDAP_UTL.get_group_properties().

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

Table 14-29 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

Table 14-30 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.

See Also

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

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

Table 14-31 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

Table 14-32 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().

See Also

DBMS_LDAP.init().

14.2.3 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=acme,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
);

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

Table 14-33 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

Table 14-34 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.


See Also

DBMS_LDAP_UTL.get_subscriber_properties().

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

Table 14-35 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

Table 14-36 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().

See Also

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

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

Table 14-37 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

Table 14-38 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().

See Also

DBMS_LDAP.init().

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

Table 14-39 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

Table 14-40 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().

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

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

14.2.5 Miscellaneous Subprograms

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

14.2.5.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 lower case 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

Table 14-41 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 lower case. If set to 0: The case is preserved in the normalized DN string.

norm_dn
VARCHAR2

The normalized DN.


Return Values

Table 14-42 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.

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

Table 14-43 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

Table 14-44 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.


See Also

DBMS_LDAP_UTL.get_property values().

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

Table 14-45 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

Table 14-46 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.


See Also

DBMS_LDAP_UTL.get_property_values_len().

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

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

Table 14-47 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

Table 14-48 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.


See Also

DBMS_LDAP_UTL.get_property_values().

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

Table 14-49 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()


See Also

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

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

Table 14-50 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

Table 14-51 CREATE_MOD_PROPERTYSET Function Return Values

Value Description
DBMS_LDAP_UTL.SUCCESS

On a successful completion.

DBMS_LDAP_UTL.GENERAL_ERROR

Other error.


See Also

DBMS_LDAP_UTL.populate_mod_propertyset().

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

Table 14-52 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

Table 14-53 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.


See Also

DBMS_LDAP_UTL.create_mod_propertyset().

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

Table 14-54 FREE_MOD_PROPERTYSET Procedure Parameters

Parameter Name Parameter Type Parameter Description
mod_pset
PROPERTY_SET

Mod_PropertySet data structure.


See Also

DBMS_LDAP_UTL.create_mod_propertyset().

14.2.5.9 Procedure free_handle

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

Syntax

PROCEDURE free_handle 
( 
handle IN OUT HANDLE 
); 

Parameters

Table 14-55 FREE_HANDLE Procedure Parameters

Parameter Name Parameter Type Parameter Description
handle
HANDLE

A pointer to a handle.


See Also

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

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

Table 14-56 CHECK_INTERFACE_VERSION Function Parameters

Parameter Name Parameter Type Parameter Description
interface_version
VARCHAR2

Version of the interface.


Return Values

Table 14-57 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.


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

Table 14-58 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

Table 14-59 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.


See Also

DBMS_LDAP_UTL.get_property_values().

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

Table 14-60 PROPERTY_VALUE_FREE_BLOB Function Parameters

Parameter Description
vals

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


See Also

DBMS_LDAP.get_property_values_blob().

14.3 Function Return Code Summary

The DBMS_LDAP_UTL functions can return the values in the following table

Table 14-61 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 needs to 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.


14.4 Data Type Summary

The DBMS_LDAP_UTL package uses the data types in the following table

Table 14-62 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.