Skip Headers
Oracle® Fusion Middleware Application Developer's Guide for Oracle Identity Management
11g Release 1 (11.1.1)

Part Number E10186-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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

11.1 Summary of 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.


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.


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.


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 Subprograms

This section contains the following topics:

11.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=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.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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.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().

See Also

DBMS_LDAP.get_group_membership().

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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=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.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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=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.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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().

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

11.2.5 Miscellaneous Subprograms

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

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

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

norm_dn
VARCHAR2

The normalized DN.


Return Values

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

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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().

11.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 11-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 11-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().

11.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 11-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 11-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().

11.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 11-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().

11.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 11-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().

11.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 11-56 CHECK_INTERFACE_VERSION Function Parameters

Parameter Name Parameter Type Parameter Description
interface_version
VARCHAR2

Version of the interface.


Return Values

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


11.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 11-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 11-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().

11.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 11-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().

11.3 Function Return Code Summary

The DBMS_LDAP_UTL functions can return the values in the following table

Table 11-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 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 uses the data types in the following table

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