7
The DBMS_LDAP_UTL PL/SQL Package

This chapter introduces the DBMS_LDAP_UTL Package, which contains Oracle Extension utility functions. This chapter contains these topics:

Introduction

This section contains details about the DBMS_LDAP_UTL subprograms. The entries for each subprogram contain the following information:

Table 7-1 Function Entry Information

Term	Description
Syntax	A code snippet showing the syntax for calling the function, including the ordering and types of the parameters.
Description	A brief statement of the purpose of the function.
Comments	Detailed information about the function, if available. This can include restrictions on use of the function, or other information that may be useful when using the function in an application.
Parameters	A description of each of the function's parameters. This includes the parameter's mode. The mode of a parameter has the following possible values: IN - A parameter that passes data to Oracle. OUT - A parameter that receives data from Oracle on this or a subsequent call. IN/OUT - A parameter that passes data on the call and receives data on the return from this or a subsequent call.
Return Values	Values returned by the function.
Usage Notes	Notes about using the specific function.
Related Functions	Related functions listed under the heading of See Also.

DBMS_LDAP_UTL Reference

This section contains information about the DBMS_LDAP_UTL functions. This section contains these topics:

Summary of Subprograms

Table 7-2 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 the 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 7-3 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 7-4 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 7-5 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_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.

User-Related Subprograms

A user is represented using DBMS_LDAP_UTL.HANDLE data type. You can create a user 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 user. Here is an example of a user handle creation:

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 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_user_handle_properties(


user_handle,
DBMS_LDAP_UTL.SUBSCRIBER_HANDLE,
subscriber_handle
);

Some common usage of User handles include setting and getting user properties, and authentication of the user. Here is an example of authenticating 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 an example of getting the telephone number of the user:

--    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
                  );

See Also:

"DBMS_LDAP_UTL Sample Code" for samples of user handle

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 7-6 AUTHENTICATE_USER Function Parameters

Parameter Name	Parameter Type	Parameter Description
ld	SESSION	A valid LDAP session handle.
user	HANDLE	The user handle.
auth_type	PLS_INTEGER	Type of authentication. Valid values are as follows: - DBMS_LDAP_UTL.AUTH_SIMPLE
credentials	VARCHAR2	The user credentials. Valid values are as follows: for DBMS_LDAP_UTL.AUTH_SIMPLE - password
binary_credentials	RAW	The binary credentials. Valid values are as follows: for DBMS_LDAP_UTL.AUTH_SIMPLE - NULL

Return Values

Table 7-7 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 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.INVALID_SUBSCRIBER_ORCL_CTX	Invalid Subscriber Oracle Context.
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.ACCT_TOTALLY_LOCKED_EXCP	User account is locked.
DBMS_LDAP_UTL.AUTH_PASSWD_CHANGE_WARN	Password should be changed.
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	Returns 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().

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

Table 7-9

Return Values

Table 7-10 CREATE_USER_HANDLE Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.

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 7-11 SET_USER_HANDLE_PROPERTIES Function Parameters

Parameter Name	Parameter Type	Parameter Description
user_hd	HANDLE	A pointer to a handle to a user.
property_type	PLS_INTEGER	The type of property that is passed. Valid values for this argument are as follows: DBMS_LDAP_UTL.SUBSCRIBER_HANDLE
property	HANDLE	The property describing the user entry.

Return Values

Table 7-12 SET_USER_HANDLE_PROPERTIES Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.RESET_HANDLE	When a caller tries to reset the existing handle properties.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.

Usage Notes

The subscriber handle doesn't need to be set in User Handle Properties if the user handle is created with TYPE_DN or TYPE_GUID as the user_type.

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 7-13 GET_USER_PROPERTIES Function Parameters

Parameter Name	Parameter Type	Parameter Description
ld	SESSION	A valid LDAP session handle.
user_handle	HANDLE	The user handle.
attrs	STRING_COLLECTION	The list of attributes to fetch for the user.
ptype	PLS_INTEGER	Type of properties to return. Valid values are as follows: - DBMS_LDAP_UTL.ENTRY_PROPERTIES, - DBMS_LDAP_UTL.NICKNAME_PROPERTY
ret-pset_collection	PROPERTY_SET_COLLECTION	The user details containing the attributes requested by the caller.

Return Values

Table 7-14 GET_USER_PROPERTIES Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.NO_SUCH_USER	User 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.INVALID_ROOT_ORCL_CTX	Invalid Root Oracle Context.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.
DBMS_LDAP error codes	Returns 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 user type is of: - DBMS_LDAP_UTL.TYPE_NICKNAME.

This function doesn't 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 any of the following, then the subscriber handle doesn't need to be set in the user handle properties:

- DBMS_LDAP_UTL.TYPE_GUID

- DBMS_LDAP_UTL.TYPE_DN .

If the subscriber handle is set, then it would be ignored.

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 7-15 SET_USER_PROPERTIES Function Parameters

Parameter Name	Parameter Type	Parameter 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. Valid values are as follows: 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. Valid values are as follows: ADD_PROPERTYSET, MODIFY_PROPERTYSET, DELETE_PROPERTYSET

Return Values

Table 7-16 SET_USER_PROPERTIES Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
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.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	Returns 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().

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, 
ptype IN PLS_INTEGER, 
filter IN VARCHAR2, 
rep_pset_coll OUT PROPERTY_SET_COLLECTION 
) 
RETURN PLS_INTEGER;

Parameters

Table 7-17 GET_USER_EXTENDED_PROPERTIES Function Parameters

Parameter Name	Parameter Type	Parameter Description
ld	SESSION	A valid LDAP session handle.
user_handle	HANDLE	The user handle.
attrs	STRING_COLLECTION	A list of attributes to fetch for the user.
ptype	PLS_INTEGER	The type of properties to return. Valid values are as follows: DBMS_LDAP_UTL.EXTPROPTYPE_RESOURCE_ACCESS_DES
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 7-18 GET_USER_EXTENDED_PROPERTIES Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.NO_SUCH_USER	User doesn't exist.
DBMS_LDAP_UTL.MULTIPLE_USER_ENTRIES	Multiple number of user DN entries exist in the directory for the given user.
USER_PROPERTY_NOT_FOUND	User extended property doesn't exist.
DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX	Invalid Root Oracle Context.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.
DBMS_LDAP error codes	Returns 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().

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 7-19 GET_USER_DN Function Parameters

Parameter Name	Parameter Type	Parameter Description
ld	SESSION	A valid LDAP session handle.
user_handle	HANDLE	The user handle.
dn	VARCHAR2	The user DN.

Return Values

Table 7-20 GET_USER_DN Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.GENERAL_ERROR	Authentication failed.
DBMS_LDAP_UTL.NO_SUCH_USER	User 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.INVALID_ROOT_ORCL_CTX	Invalid Root Oracle Context.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.
DBMS_LDAP error codes	Returns 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().

Function check_group_membership

The function check_group_membership() checks the membership of the user 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 7-21 CHECK_GROUP_MEMBERSHIP Function Parameters

Parameter Name	Parameter Type	Parameter Description
ld	SESSION	A valid LDAP session handle.
user_handle	HANDLE	The user handle.
group_handle	HANDLE	The group handle.
nested	PLS_INTEGER	The type of membership the user holds in groups. Valid values are as follows: DBMS_LDAP_UTL.NESTED_MEMBERSHIP, DBMS_LDAP_UTL.DIRECT_MEMBERSHIP

Return Values

Table 7-22 CHECK_GROUP_MEMBERSHIP Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	If user is a member.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.GROUP_MEMBERSHIP	If user is not a member.

Usage Notes

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

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 7-23 LOCATE_SUBSCRIBER_FOR_USER Function Parameters

Parameter Name	Parameter Type	Parameter Description
ld	SESSION	A valid LDAP session handle.
user_handle	HANDLE	The user handle.
subscriber_handle	HANDLE	The subscriber handle.

Return Values

Table 7-24 LOCATE SUBSCRIBER FOR USER Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.NO_SUCH_SUBSCRIBER	Subscriber doesn't exist.
DBMS_LDAP_UTL.MULTIPLE_SUBSCRIBER_ENTRIES	Multiple number of subscriber DN entries exist in the directory for the given subscriber.
DBMS_LDAP_UTL.NO_SUCH_USER	User doesn't exist.
DBMS_LDAP_UTL.MULTIPLE_USER_ENTRIES	Multiple number of user DN entries exist in the directory for the given user.
DBMS_LDAP_UTL.SUBSCRIBER_NOT_FOUND	Unable to locate subscriber for the given user.
DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX	Invalid Root Oracle Context.
DBMS_LDAP_UTL.ACCT_TOTALLY_LOCKED_EXCP	User account is locked.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.
DBMS_LDAP error codes	Returns 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().

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 7-25 GET_GROUP_MEMBERSHIP Function Parameters

Parameter Name	Parameter Type	Parameter Description
ld	SESSION	A valid LDAP session handle.
user_handle	HANDLE	The user handle.
nested	PLS_INTEGER	The type of membership the user holds in groups. Valid values are as follows: 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 7-26 GET_GROUP_MEMBERSHIP Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.

Usage Notes

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

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 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 usage 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 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
);

See Also:

Example: Group-Related Functions for more usage samples of group handle

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 7-27 CREATE_GROUP_HANDLE Function Parameters

Parameter Name	Parameter Type	Parameter Description
group_hd	HANDLE	A pointer to a handle to a group.
group_type	PLS_INTEGER	The type of group ID that is passed. Valid values for this argument are as follows: - DBMS_LDAP_UTL.TYPE_DN, DBMS_LDAP_UTL.TYPE_GUID, DBMS_LDAP_UTL.TYPE_NICKNAME
group_id	VARCHAR2	The group ID representing the group entry.

Return Values

Table 7-28 CREATE_GROUP_HANDLE Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.

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 7-29 SET_GROUP_HANDLE_PROPERTIES Function Parameters

Parameter Name	Parameter Type	Parameter Description
group_hd	HANDLE	A pointer to the handle to the group.
property_type	PLS_INTEGER	The type of property that is passed. Valid values for this argument are as follows: DBMS_LDAP_UTL.GROUP_HANDLE
property	HANDLE	The property describing the group entry.

Return Values

Table 7-30 SET_GROUP_HANDLE_PROPERTIES Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.RESET_HANDLE	When a caller tries to reset the existing handle properties.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.

Usage Notes

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

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 7-31 GET_GROUP_PROPERTIES Function Parameters

Parameter Name	Parameter Type	Parameter Description
ld	SESSION	A valid LDAP session handle.
group_handle	HANDLE	The group handle.
attrs	STRING_COLLECTION	A list of attributes that must be fetched for the group.
ptype	PLS_INTEGER	The type of properties to be returned. Valid values are as follows: DBMS_LDAP_UTL.ENTRY_PROPERTIES
ret_pset_coll	PROPERTY_SET_COLLECTION	The group details containing the attributes requested by the caller.

Return Values

Table 7-32 GET_GROUP_PROPERTIES Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.NO_SUCH_GROUP	Group doesn't exist.
DBMS_LDAP_UTL.MULTIPLE_GROUP_ENTRIES	Multiple number of group DN entries exist in the directory for the given group.
DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX	Invalid Root Oracle Context.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.
DBMS_LDAP error codes	Returns 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.

If the group type is any of the following, then the subscriber handle doesn't need to be set in the group handle properties:

DBMS_LDAP_UTL.TYPE_GUID
DBMS_LDAP_UTL.TYPE_DN .

If the subscriber handle is set, then it would be ignored.

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 7-33 GET_GROUP_DN Function Parameters

Parameter Name	Parameter Type	Parameter Description
ld	SESSION	A valid LDAP session handle.
group_handle	HANDLE	The group handle.
dn	VARCHAR2	The group DN.

Return Values

Table 7-34 GET_GROUP_DN Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.NO_SUCH_GROUP	Group doesn't exist.
DBMS_LDAP_UTL.MULTIPLE_GROUP_ENTRIES	Multiple number of group DN entries exist in the directory for the given group.
DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX	Invalid Root Oracle Context.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.
DBMS_LDAP error codes	Returns 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().

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 a simple name. When a simple name is used, additional information from the root Oracle Context is used to identify the subscriber. Here is an example of a subscriber handle creation:

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.

A common usage of subscriber handle is getting subscriber properties. 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
);

See Also:

"DBMS_LDAP_UTL Sample Code" for samples of subscriber handle

Function create_subscriber_handle

The function create_subscriber_handle() creates a subscriber handle.

Syntax

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

Parameters

Table 7-35 CREATE_SUBSCRIBER_HANDLE Function Parameters

Parameter Name	Parameter Type	Parameter Description
subscriber_hd	HANDLE	A pointer to a handle to a subscriber.
subscriber_type	PLS_INTEGER	The type of subscriber ID that is passed. Valid values for this argument are: DBMS_LDAP_UTL.TYPE_DN, DBMS_LDAP_UTL.TYPE_GUID, DBMS_LDAP_UTL.TYPE_NICKNAME, DBMS_LDAP_UTL.TYPE_DEFAULT
subscriber_id	VARCHAR2	The subscriber ID representing the subscriber entry. This can be NULL if subscriber_type is as follows: DBMS_LDAP_UTL.TYPE_DEFAULT Then the default subscriber is fetched from Root Oracle Context.

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 as follows: DBMS_LDAP_UTL.TYPE_DEFAULT

Then the default subscriber is fetched from Root Oracle Context.

Return Values

Table 7-36 CREATE_SUBSCRIBER_HANDLE Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.

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 7-37 GET_SUBSCRIBER_PROPERTIES Function Parameters

Parameter Name	Parameter Type	Parameter Description
ld	SESSION	A valid LDAP session handle.
subscriber_handle	HANDLE	The subscriber handle.
attrs	STRING_COLLECTION	A list of attributes that must be fetched for the subscriber.
ptype	PLS_INTEGER	The type of properties to return. Valid values are as follows: DBMS_LDAP_UTL.ENTRY_PROPERTIES, DBMS_LDAP_UTL.COMMON_PROPERTIES, to retrieve the subscriber's Oracle Context Properties.
ret_pset_coll	PROPERTY_SET_COLLECITON	The subscriber details containing the attributes requested by the caller.

Return Values

Table 7-38 GET_SUBSCRIBER_PROPERTIES Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.NO_SUCH_SUBSCRIBER	Subscriber doesn't exist.
DBMS_LDAP_UTL.MULTIPLE_SUBSCRIBER_ENTRIES	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	Returns 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().

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 7-39 GET_SUBSCRIBER_DN Function Parameters

Parameter Name	Parameter Type	Parameter Description
ld	SESSION	A valid LDAP session handle.
subscriber_handle	HANDLE	The subscriber handle.
dn	VARCHAR2	The subscriber DN.

Return Values

Table 7-40 GET_SUBSCRIBER_DN Function Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.PARAM_ERROR	Invalid input parameters.
DBMS_LDAP_UTL.NO_SUCH_SUBSCRIBER	Subscriber doesn't exist.
DBMS_LDAP_UTL.MULTIPLE_SUBSCRIBER_ENTRIES	Multiple number of subscriber DN entries exist in the directory for the given subscriber.
DBMS_LDAP_UTL.INVALID_ROOT_ORCL_CTX	Invalid Root Oracle Context.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.
DBMS_LDAP error codes	Returns 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().

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 sample usage illustrating 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 userhandle. 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.

See Also:

Example: Property-Related Subprograms for more usage samples of the Property-related subpropgrams

Miscellaneous Subprograms

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

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

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

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

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

Return Values

N/A

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, 
) 
RETURN PLS_INTEGER;

Parameters

Table 7-50 CREATE_MOD_PROPERTYSET Function Parameters

Parameter Name	Parameter Type	Parameter Description
pset_type	PLS_INTEGER	The type of property set being modified. Valid values are as follows: 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 7-51 CREATE_MOD_PROPERTYSETFunction Return Values

Value	Description
DBMS_LDAP_UTL.SUCCESS	On a successful completion.
DBMS_LDAP_UTL.GENERAL_ERROR	Other error.

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 7-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. Valid values are as follows: 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 7-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.

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 7-54 FREE_MOD_PROPERTYSET Procedure Parameters

Parameter Name	Parameter Type	Parameter Description
mod_pset	PROPERTY_SET	Mod_PropertySet data structure.

Return Values

N/A

Procedure free_handle

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

Syntax

PROCEDURE free_handle 
( 
handle IN OUT HANDLE 
);

Parameters

Table 7-55 FREE_HANDLE Procedure Parameters

Parameter Name	Parameter Type	Parameter Description
handle	HANDLE	A pointer to a handle.

Return Values

N/A

Function check_interface_version

The function check_interface_version() checks for support of the interface version.

Syntax

FUNCTION check_interface_version 
( 
interface_version IN VARCHAR2 
)
RETURN PLS_INTEGER;

Parameters

Table 7-56 CHECK_INTERFACE_VERSION Function Parameters

Parameter Name	Parameter Type	Parameter Description
interface_version	VARCHAR2	Version of the interface.

Return Values

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

Function Return Code Summary

The DBMS_LDAP_UTL functions can return the values in the following table

Table 7-58 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 given user doesn't have any group membership.
NO_SUCH_SUBSCRIBER	-4	Returned by subscriber-related functions when the subscriber doesn't exist in the directory.
NO_SUCH_USER	-5	Returned by user-related functions when the user doesn't exist in the directory.
NO_ROOT_ORCL_CTX	-6	Returned by most functions when the root oracle context doesn't 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 doesn't contain all the required information needed by the function.
NO_SUBSCRIBER_ORCL_CTX	-9	Oracle context doesn't 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 doesn't 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	Returned by DBMS_LDAP_UTL.authenticate_user() function when the user password needs to be changed. This is a password policy error.
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 doesn't 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_userr() 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.

Data-Type Summary

The DBMS_LDAP_UTL package uses the data types in the following table

Table 7-59 DBMS_LDAP_UTL Data Types

Data Type	Purpose
HANDLE	Used to hold entity related.
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.

7 The DBMS_LDAP_UTL PL/SQL Package

Introduction

Table 7-1 Function Entry Information

DBMS_LDAP_UTL Reference

Summary of Subprograms

Table 7-2 DBMS_LDAP_UTL User-Related Subprograms

Table 7-3 DBMS_LDAP_UTL Group-Related Subprograms

Table 7-4 DBMS_LDAP_UTL Subscriber-Related Subprograms

Table 7-5 DBMS_LDAP_UTL Miscellaneous Subprograms

User-Related Subprograms

Function authenticate_user

Syntax

Parameters

Table 7-6 AUTHENTICATE_USER Function Parameters

Return Values

Table 7-7 AUTHENTICATE_USER Function Return Values

Usage Notes

See Also

Function create_user_handle

Syntax

Parameters

Table 7-8 CREATE_USER_HANDLE Function Parameters

Return Values

Table 7-10 CREATE_USER_HANDLE Function Return Values

See Also

Function set_user_handle_properties

Syntax

Parameters

Table 7-11 SET_USER_HANDLE_PROPERTIES Function Parameters

Return Values

Table 7-12 SET_USER_HANDLE_PROPERTIES Function Return Values

Usage Notes

See Also

Function get_user_properties

Syntax

Parameters

Table 7-13 GET_USER_PROPERTIES Function Parameters

Return Values

Table 7-14 GET_USER_PROPERTIES Function Return Values

Usage Notes

See Also

Function set_user_properties

Syntax

Parameters

Table 7-15 SET_USER_PROPERTIES Function Parameters

Return Values

Table 7-16 SET_USER_PROPERTIES Function Return Values

Usage Notes

See Also

Function get_user_extended_properties

Syntax

Parameters

Table 7-17 GET_USER_EXTENDED_PROPERTIES Function Parameters

Return Values

Table 7-18 GET_USER_EXTENDED_PROPERTIES Function Return Values

Usage Notes

See Also

Function get_user_dn

Syntax

Parameters

Table 7-19 GET_USER_DN Function Parameters

Return Values

Table 7-20 GET_USER_DN Function Return Values

Usage Notes

See Also

Function check_group_membership

Syntax

Parameters

Table 7-21 CHECK_GROUP_MEMBERSHIP Function Parameters

Return Values

Table 7-22 CHECK_GROUP_MEMBERSHIP Function Return Values

Usage Notes

See Also

Function locate_subscriber_for_user

Syntax

Parameters

Table 7-23 LOCATE_SUBSCRIBER_FOR_USER Function Parameters

Return Values

Table 7-24 LOCATE SUBSCRIBER FOR USER Function Return Values

Usage Notes

7
The DBMS_LDAP_UTL PL/SQL Package