LDAPS_SETOPTIONS
Sets options on an open LDAP server session
Syntax
CALL LDAPS_SETOPTIONS(
lHandle,
timeLimit,
sizeLimit,
base,
referral,
restart,
rc<, Property, propertyValue> );
Required Arguments
- lHandle
-
specifies the connection
handle that is returned by the LDAPS_OPEN CALL routine. The connection
handle identifies the open connection to use when specifying options
on the LDAP server session.
- timeLimit
-
specifies the maximum
number of seconds that the client waits for an answer to a search
request. The value 0 indicates that
no limit is imposed. The default value is 0 unless another value is specified. The value -1 specifies that the server retain its current timeLimit value; the value is not changed.
- sizelimit
-
specifies the maximum
number of entries that the server is to return from the search. The
value 0 indicates that no limit should
be imposed. The default value is 0 unless
another value is specified. The value -1 specifies that the server is to retain its current sizeLimit setting; the value is not changed.
- base
-
specifies the base
object (distinguished name) for the search operation. An initial base
object was specified when the connection to the LDAP server was established
with the LDAPS_OPEN CALL routine. Specifying a non-blank value for
the base parameter overrides
the existing base object definition. To retain the existing base object
definition, specify a blank value for the base parameter.
- referral
-
indicates whether to
chase referrals, by setting either the OPT_REFERRALS_ON option or
the OPT_REFERRALS_OFF option. One or the other of these options was
specified when the connection to the LDAP server was established with
the LDAPS_OPEN CALL routine. Specifying either option as the value
of the referral parameter overrides
the existing value. Specifying a blank value retains the existing
value.
- restart
-
indicates whether to
restart a query if error condition EINTR occurs. At ldaps_open time,
the default session settings are determined. ldaps_setOptions can
be used to change these defaults. Valid values for restart are OPT_RESTART_ON
or OPT_RESTART_OFF. A blank value can be passed in to indicate that
the default value of OPT_RESTART_OFF should be used.
- rc
-
receives a return code
that indicates success or failure.
Optional Arguments
- property
-
specifies the name
of an optional property that is being set. Currently, the only property
that is supported is the SEARCH_SCOPE property, which specifies the
scope of searches in the LDAP directory. Specify the value of the
property by using the propertyValue parameter.
- propertyValue
-
specifies the value
for the property parameter. The following values for the SEARCH_SCOPE
property are valid:
| SUBTREE_SEARCH_SCOPE |
sets the scope of the search to include all subtrees.
This is the default value.
|
| BASE_SEARCH_SCOPE |
sets the scope of the search to include only the
base. This value overrides the default value of SUBTREE_SEARCH_SCOPE.
|
| ONELEVEL_SEARCH_SCOPE |
sets the scope of the search to include the base
and one additional level. This value overrides the default value of
SUBTREE_SEARCH_SCOPE.
|
Examples
Example 1
The following example
specifies maximum limits on search time and number of entries returned.
This example also specifies that the server is to refrain from chasing
referrals. The existing base object definition is to remain unchanged.
timeLimit=120;
sizeLimit=100;
base=; /* use default set at _open time */
referral = OPT_REFERRALS_OFF;
restart = ;
call ldaps_setOptions(lHandle, timeLimit, sizeLimit, base,
referral, restart, rc);
Example 2
The following example
uses the optional properties parameter to set the scope of LDAP searches.
timelimit = -1; /* use current setting */
sizelimit = -1; /* use current setting */
base=; /* use default set at _open time */
referral = ; /* use default set at _open time */
restart = ; /* use default */
prop = SEARCH_SCOPE;
propValue = BASE_SEARCH_SCOPE; /* only search the base */
call ldaps_setOptions(lHandle, timelimit, sizelimit, base, referral, restart,
prop, propValue);