DBMS_LDAP , 8 of 30

search_st Function

This function performs a synchronous search in the LDAP server with a client-side timeout. 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 client or the server.

Syntax

DBMS_LDAP.search_st ( 

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

RETURN PLS_INTEGER;

Parameters
Table 20-22 search_st 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.

`tv (IN)`

The timeout value expressed in seconds and microseconds that should be used for this search.

`res (OUT)`

This is a result parameter that 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.
`tv (IN)`	The timeout value expressed in seconds and microseconds that should be used for this search.
`res (OUT)`	This is a result parameter that 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-23 search_st Function Return Values

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-24 search_st 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.`

`invalid_search_time_value`

Raised if the time value specified for the timeout is invalid.

`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.`
`invalid_search_time_value`	Raised if the time value specified for the timeout is invalid.
`general_error`	For all other errors. The error string associated with this exception explains the error in detail.

Usage Notes

This function is very similar to DBMS_LDAP.search_s, except that it requires a timeout value.

See Also: