Properties for directory services

The following properties control an application’s use of directory services:

CS_DS_COPY determines whether the connection’s directory service provider is allowed to use cached information to satisfy requests for information in the directory. For directory drivers that support the property, the default is CS_TRUE, which allows the use of cached information.

Not all directory service providers support caching. An application calls ct_con_props(CS_SUPPORTED) to determine if the current directory driver supports caching.

Some directory service providers support a distributed model with directory server agents (DSAs) and directory user agents (DUAs). Directory server agents are programs that manage the directory and respond to requests from the directory user agents. The DUAs run on each machine and transmit application requests to directory server agents and forward the responses to the application.

Directory caching allows the directory user agent to provide a cached copy of recently read information rather than sending the request to the directory server agent. This can speed up directory request handling.

Using the local copy may be faster, but querying the actual directory ensures that the application receives the most recent changes to directory entries.

CS_DS_DITBASE specifies a directory node where directory searches start. This node is called the DIT base.

The default DIT base value is specified as follows:

• In the configuration of the directory driver, or

• By the driver-specific default, if the configuration specifies no default DIT base value.

Directory driver configuration is described in the Open Client and Open Server Configuration Guide for Microsoft Windows or Open Client and Open Server Configuration Guide for UNIX.

CS_DS_EXPANDALIAS determines whether the connection’s directory service provider expands alias entries when searching the directory. For directory drivers that support this property, the default is CS_TRUE, which means alias entries are expanded.

Not all directory service providers support aliases. An application calls ct_con_props(CS_SUPPORTED) to determine if the current directory driver supports this property.

Some directory service providers allow directory alias entries to be created. An alias entry contains a link to a primary entry. Aliases allow the primary entry to appear as one or more entries in different locations.

If CS_DS_EXPANDALIAS is CS_TRUE, the directory service provider is permitted to follow alias links when searching the directory. If the value is CS_FALSE, the links in alias entries are not followed.

CS_DS_FAILOVER determines whether Client-Library fails over to the next directory driver entry in libtcl.cfg file and eventually to the interfaces file when the current directory driver does not load or when the current directory server is not available. The default CS_DS_FAILOVER value is CS_TRUE, which means Client-Library silently fails over when the current directory driver cannot be loaded.

Client-Library requires a directory for (among other things) mapping logical server names to network addresses. The directory can either be the Sybase interfaces file or a network-based directory service such as DCE Cell Directory Services (CDS).

To use a directory source other than the interfaces file, Client-Library requires a directory driver.

Failover occurs when an application requests (or defaults) to use a network-based directory service rather than the interfaces file. If Client-Library cannot load the directory driver, by default, failover occurs to the next directory driver entry in the libtcl.cfg file and, eventually, to the interfaces file. An application may set CS_DS_FAILOVER to CS_FALSE to prevent failover.

If directory service failover is not permitted, and Client-Library loads a specified directory driver, then the connection’s directory source is undefined. In this case, any subsequent action that requires directory access will fail. These actions are:

• A call to ct_con_props to get, set, or clear any CS_DS_ property besides CS_DS_FAILOVER or CS_DS_PROVIDER

• A call to ct_con_props to get or clear the CS_DS_PROVIDER property

• A call to ct_connect or ct_ds_lookup

CS_DS_PASSWORD specifies a directory service password to go with the principal (user) name specified as CS_DS_PRINCIPAL. Some directory providers require an authenticated principal (user) name to control the application’s access to directory entries.

CS_DS_PRINCIPAL specifies a directory service principal (user) name to go with the password specified as CS_DS_PASSWORD. Some directory providers require an authenticated principal (user) ID to control the application’s access to directory entries. For drivers that support the property, the default is NULL.

By default, CS_DS_RAND_OFFSET is set to true to avoid disrupting current installations. When set to true, CS_DS_RAND_OFFSET starts from a random offset and scans the network address list until a successful connect occurs. The random offset is determined when the network address list is retrieved from the directory service.

If CS_DS_RAND_OFFSET is set to false, connection attempts start from the initial entry in the network address list.

CS_DS_RAND_OFFSET can be set via ct_con_props, ct_config or ocs.cfg.

CS_DS_PROVIDER contains the name of the current directory service provider as a null-terminated string.

Client-Library uses a driver configuration file to map directory service provider names to directory driver file names. On most platforms, this file is named libtcl.cfg. See the Open Client and Open Server Configuration Guide for Microsoft Windows or Open Client and Open Server Configuration Guide for UNIX to view a full description of this file.

The default provider name corresponds to the first entry in the [DIRECTORY] section of the libtcl.cfg driver configuration file. This section has entries of the form:

[DIRECTORY]
 provider_name = driver_file_name init_string
 provider_name = driver_file_name init_string

where:

• provider_name specifies a possible value for the CS_DS_PROVIDER property

• driver_name is a file name for the driver

• init_string specifies start-up settings for the driver.

If no driver configuration file is present on the system, or the file lacks a [DIRECTORY] section, then the default provider name is “InterfacesDriver” to indicate that Client-Library uses the interfaces file as the directory source.

See the Open Client and Open Server Configuration Guide for Microsoft Windows or Open Client and Open Server Configuration Guide for UNIX to view a detailed description of driver configuration on your platform.

For each connection structure, Client-Library loads the default directory driver in any of the following circumstances:

• A call to ct_con_props to get, set, or clear any CS_DS_ property besides CS_DS_FAILOVER or CS_DS_PROVIDER loads the default directory driver if a driver is not already loaded.

• A call to ct_con_props to get the CS_DS_PROVIDER property loads the default directory driver if a driver is not already loaded. A call to clear CS_DS_PROVIDER always unloads the existing driver and reloads the default driver.

• A call to ct_connect or ct_ds_lookup loads the default directory driver if a driver is not already loaded.

Applications change a connection’s directory service provider by calling ct_con_props(CS_SET, CS_DS_PROVIDER).

When setting CS_DS_PROVIDER, the new property value must be mapped to a valid directory driver. If this is the case, then Client-Library loads the new driver and initializes it.

If Client-Library cannot load the requested driver, then the connection’s state depends on the value of the CS_DS_FAILOVER property and whether a driver was loaded before.

When a directory driver is loaded, Client-Library assigns a default value for the DIT-base property based on the associated configuration file entry.

For driver configuration instructions, see the Open Client and Open Server Configuration Guide for Microsoft Windows or Open Client and Open Server Configuration Guide for UNIX.

CS_DS_SEARCH restricts the depth to which a directory search descends from the starting point.

The following values are legal for CS_DS_SEARCH:

Not all directory service providers support the search-depth property. An application calls ct_con_props(CS_SUPPORTED) to determine if the current directory driver supports this property.

CS_DS_SIZELIMIT limits the number of entries returned by a directory search started with ct_ds_lookup. The default is 0, which indicates there is no size limit.

Not all directory service providers support search-results size limits. An application calls ct_con_props(CS_SUPPORTED) to determine if the current directory driver supports this property.

CS_DS_TIMELIMIT specifies an absolute time limit for completion of a directory search, expressed in seconds. The default is 0, which indicates there is no time limit.

Not all directory service providers support search time limits. An application calls ct_con_props(CS_SUPPORTED) to determine if the current directory driver supports this property.