DBMS_LDAP , 7 of 30

search_s Function

This function performs a synchronous search in the LDAP server. It returns control to the PL/SQL environment only after all of the search results have been sent by the server or if the search request is timed out by the server.

Syntax

FUNCTION search_s  (    

ld  IN SESSION,
base  IN VARCHAR2,
scope  IN PLS_INTEGER,
filter  IN VARCHAR2,
attrs  IN STRING_COLLECTION,
attronly  IN PLS_INTEGER,
res  OUT MESSAGE)

RETURN PLS_INTEGER;

Parameters
Table 20-19 search_s Function Parameters

Parameter Description

`ld (IN)`

A valid LDAP session handle.

`base (IN)`

The dn of the entry at which to start the search.

`scope (IN)`

One of `SCOPE_BASE` `(0x00), SCOPE_ONELEVEL (0x01),` or `SCOPE_SUBTREE (0x02),` indicating the scope of the search.

`filter (IN)`

A character string representing the search filter. The value `NULL` can be passed to indicate that the filter (objectclass=) which matches all entries is to be used.

`attrs (IN)`

A collection of strings indicating which attributes to return for each matching entry. Passing `NULL` for this parameter causes all available user attributes to be retrieved. The special constant string `NO_ATTRS (1.1)` can be used as the only string in the array to indicate that no attribute types are returned by the server. The special constant string `ALL_USER_ATTRS` (``) can be used in the attrs array along with the names of some operational attributes to indicate that all user attributes plus the listed operational attributes are returned.

`attrsonly (IN)`

A boolean value that must be zero if both attribute types and values are returned, and non-zero if only types are wanted.

`res (OUT)`

This is a result parameter which will contain the results of the search upon completion of the call. If no results are returned, *res is set to `NULL.`

Parameter	Description
`ld (IN)`	A valid LDAP session handle.
`base (IN)`	The dn of the entry at which to start the search.
`scope (IN)`	One of `SCOPE_BASE` `(0x00), SCOPE_ONELEVEL (0x01),` or `SCOPE_SUBTREE (0x02),` indicating the scope of the search.
`filter (IN)`	A character string representing the search filter. The value `NULL` can be passed to indicate that the filter (objectclass=*) which matches all entries is to be used.
`attrs (IN)`	A collection of strings indicating which attributes to return for each matching entry. Passing `NULL` for this parameter causes all available user attributes to be retrieved. The special constant string `NO_ATTRS (1.1)` can be used as the only string in the array to indicate that no attribute types are returned by the server. The special constant string `ALL_USER_ATTRS` (`*`) can be used in the attrs array along with the names of some operational attributes to indicate that all user attributes plus the listed operational attributes are returned.
`attrsonly (IN)`	A boolean value that must be zero if both attribute types and values are returned, and non-zero if only types are wanted.
`res (OUT)`	This is a result parameter which will contain the results of the search upon completion of the call. If no results are returned, *res is set to `NULL.`

Return Values
Table 20-20 search_s Function Return Value

Value Description

`PLS_INTEGER`

`DBMS_LDAP.SUCCESS` if the search operation succeeded. An exception is raised in all other cases.

`res (OUT parameter)`

If the search succeeded and there are entries, this parameter is set to a NON-NULL value that can be used to iterate through the result set.

Value	Description
`PLS_INTEGER`	`DBMS_LDAP.SUCCESS` if the search operation succeeded. An exception is raised in all other cases.
`res (OUT parameter)`	If the search succeeded and there are entries, this parameter is set to a NON-NULL value that can be used to iterate through the result set.

Exceptions
Table 20-21 search_s Function Exceptions

Exception Description

`invalid_session`

Raised if the session handle ld is invalid.

`invalid_search_scope`

Raised if the search scope is not one of `SCOPE_BASE, SCOPE_ONELEVEL,` or `SCOPE_SUBTREE.`

`general_error`

For all other errors. The error string associated with this exception explains the error in detail.

Exception	Description
`invalid_session`	Raised if the session handle ld is invalid.
`invalid_search_scope`	Raised if the search scope is not one of `SCOPE_BASE, SCOPE_ONELEVEL,` or `SCOPE_SUBTREE.`
`general_error`	For all other errors. The error string associated with this exception explains the error in detail.

Usage Notes

This function issues a search operation, and does not return control to the user environment until all of the results have been returned from the server. Entries returned from the search, if any, are contained in the res parameter. This parameter is opaque to the caller. Entries, attributes, values, and so on can be extracted by calling the parsing routines described below.

See Also: