|
Oracle® Identity Management Application Developer's Guide
10g Release 2 (10.1.2) Part No. B14087-01 |
|
 Previous |
 Next |
|
Oracle® Identity Management Application Developer's Guide
10g Release 2 (10.1.2) Part No. B14087-01 |
|
|
Previous |
Next |
This chapter contains reference material for the DBMS_LDAP_UTL package, which contains Oracle Extension utility functions. The chapter contains these topics:
|
Note: Sample code for theDBMS_LDAP_UTL package is available at this URL:
|
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. |
This section contains the following topics:
A user is represented by the DBMS_LDAP_UTL.HANDLE data type. You can create a user handle by using a DN, GUID, or simple name, along with the appropriate subscriber handle. When a simple name is used, additional information from the root Oracle Context and the subscriber Oracle Context is used to identify the user. This example shows a user handle being created:
retval := DBMS_LDAP_UTL.create_user_handle( user_handle, DBMS_LDAP_UTL.TYPE_DN, "cn=user1,cn=users,o=acme,dc=com" );
This user handle must be associated with an appropriate subscriber handle. If, for example, subscriber_handle is o=acme,dc=com, the subscriber handle can be associated in the following way:
retval := DBMS_LDAP_UTL.set_user_handle_properties( user_handle, DBMS_LDAP_UTL.SUBSCRIBER_HANDLE, subscriber_handle );
Common uses of user handles include setting and getting user properties and authenticating the user. Here is a handle that authenticates a user:
retval := DBMS_LDAP_UTL.authenticate_user( my_session user_handle DBMS_LDAP_UTL.AUTH_SIMPLE, "welcome" NULL );
In this example, the user is authenticated using a clear text password welcome.
Here is a handle that retrieves a user's telephone number:
--my_attrs is of type DBMS_LDAP.STRING_COLLECTION my_attrs(1) := 'telephonenumber'; retval := DBMS_LDAP_UTL.get_user_properties( my_session, my_attrs, DBMS_LDAP_UTL.ENTRY_PROPERTIES, my_pset_coll );
|
See Also: "DBMS_LDAP_UTL Sample Code" on page B-9 for more examples of user handles |
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().
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:
|
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().
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().
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:
|
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().
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:
|
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().
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().
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().
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:
|
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.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().
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().
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:
|
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().
A group is represented using by using the DBMS_LDAP_UTL.HANDLE data type. A group handle represents a valid group entry. You can create a group handle by using a DN, GUID or a simple name, along with the appropriate subscriber handle. When a simple name is used, additional information from the Root Oracle Context and the Subscriber Oracle Context is used to identify the group. Here is an example of a group handle creation:
retval := DBMS_LDAP_UTL.create_group_handle( group_handle, DBMS_LDAP_UTL.TYPE_DN, "cn=group1,cn=Groups,o=acme,dc=com" );
This group handle has to be associated with an appropriate subscriber handle. For example, given a subscriber handle: subscriber_handle representing o=acme,dc=com, the subscriber handle can be associated in the following way:
retval := DBMS_LDAP_UTL.set_group_handle_properties( group_handle, DBMS_LDAP_UTL.SUBSCRIBER_HANDLE, subscriber_handle );
A sample use of group handle is getting group properties. Here is an example:
my_attrs is of type DBMS_LDAP.STRING_COLLECTION my_attrs(1) := 'uniquemember'; retval := DBMS_LDAP_UTL.get_group_properties( my_session, my_attrs, DBMS_LDAP_UTL.ENTRY_PROPERTIES, my_pset_coll );
The group-related subprograms also support membership-related functionality. Given a user handle, you can find out if it is a direct or a nested member of a group by using the DBMS_LDAP_UTL.check_group_membership() function. Here is an example:
retval := DBMS_LDAP_UTL.check_group_membership( session, user_handle, group_handle, DBMS_LDAP_UTL.DIRECT_MEMBERSHIP
You can also obtain a list of groups that a particular group belongs to, using the DBMS_LDAP_UTL.get_group_membership() function. For example:
my_attrs is of type DBMS_LDAP.STRING_COLLECTION my_attrs(1) := 'cn'; retval := DBMS_LDAP_UTL.get_group_membership( my_session, user_handle, DBMS_LDAP_UTL.DIRECT_MEMBERSHIP, my_attrs my_pset_coll );
|
See Also: Example: User-Related Functions on page B-9 for more examples of group handles |
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:
|
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().
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().
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 doe not identify a NULL subscriber handle as a default subscriber. The default subscriber can be obtained fromDBMS_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().
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().
A subscriber is represented by using dbms_ldap_utl.handle data type. You can create a subscriber handle by using a DN, GUID or simple name. When a simple name is used, additional information from the root Oracle Context is used to identify the subscriber. This example shows a subscriber handle being created:
retval := DBMS_LDAP_UTL.create_subscriber_handle(
subscriber_handle, DBMS_LDAP_UTL.TYPE_DN, "o=acme,dc=com" );
subscriber_handle is created by it's DN: o=oracle,dc=com.
Getting subscriber properties is one common use of a subscriber handle. Here is an example:
my_attrs is of type DBMS_LDAP.STRING_COLLECTION
my_attrs(1) := 'orclguid';
retval := DBMS_LDAP_UTL.get_subscriber_properties(
my_session,
my_attrs,
DBMS_LDAP_UTL.ENTRY_PROPERTIES,
my_pset_coll
);
|
See Also: "DBMS_LDAP_UTL Sample Code" on page B-9 for examples of subscriber handles |
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:
|
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().
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:
|
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().
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().
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().
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.
|
See Also: Example: User-Related Functions on page B-9 for more usage samples of the Property-related subpropgrams |
The miscellaneous subprograms in the DBMS_LDAP_UTL package perform a variety of different functions.
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 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 lower case. 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.
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:
|
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().
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:
|
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().
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:
|
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().
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:
|
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().
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().
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:
|
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().
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().
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().
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
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:
|
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().
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().
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 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. |
