LDAPS_SETOPTIONS

Sets options on an open LDAP server session.

Syntax

CALL LDAPS_SETOPTIONS(lHandle, timeLimit, sizeLimit, base, referral, restart, rc <,Property, propertyValue>);

lHandle

Numeric, input.
Specifies the connection handle 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

Numeric, input.

Specifies the maximum number of seconds that the client will wait for an answer to a search request. A value of 0 indicates that no limit will be imposed. The default value is 0 unless another value is specified. A value of -1 specifies that the server retain its current timeLimit value; the value will not be changed.

sizelimit

Numeric, input.
Specifies the maximum number of entries that the server is to return from the search. A value of 0 indicates that no limit should be imposed. The default value is 0 unless another value is specified. A value of -1 specifies that the server is to retain its current sizeLimit setting; the value will not be changed.

base

Character, input.
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

Character, input.
Indicates whether or not 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

Character, input.
Indicates whether or not to restart a query if 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

Numeric, output.
Receive a return code that indicates success or failure.

property

Character, input.
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 using the propertyValue parameter.

propertyValue

Character, input.
Specifies the value for the property parameter. Valid values for the SEARCH_SCOPE property are:

SUBTREE_SEARCH_SCOPE

Sets the scope of the search to include all subtrees. This is the default.

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 overrides the default value of SUBTREE_SEARCH_SCOPE.

Examples

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

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