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.
CS_DS_COPY cannot be set, cleared,
or retrieved unless Client-Library is using a directory service
provider that 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.
CS_DS_DITBASE cannot be set, cleared,
or retrieved unless Client-Library is using a network-based directory
service rather than the interfaces file.
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 an Open Server Configuration Guide.
DIT base values must be fully qualified names in the name syntax of the directory service that Client-Library is using. In addition, each driver/provider combination has different rules for combining fully and partially qualified names. See “Directory entry name formats” for details.
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.
CS_DS_EXPANDALIAS cannot be set, cleared,
or retrieved unless Client-Library is using a directory driver that
supports alias entries.
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.
WARNING! Directories that contain alias entries may contain cyclic search paths as a result of the alias links. If CS_DS_EXPANDALIAS is enabled, it is possible for searches begun by ct_ds_lookup to go on indefinitely if the directory tree contains a cyclic search path.
CS_DS_FAILOVER determines whether Client-Library uses the interfaces file when a directory driver cannot be loaded. The default is CS_TRUE, which means Client-Library silently fails over when a 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) or Novell Directory Services (NDS).
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, then by default, failover occurs and subsequent directory requests use the interfaces file as the directory source. 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
For a description of when Client-Library loads a directory driver, see “Directory service provider”.
For information about Sybase failover options see “High-availability failover”
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.
Applications that use Novell’s NetWare Directory Services (NDS) and run on the Novell console must set the CS_DS_PRINCIPAL and CS_DS_PASSWORD to a valid network user name and password, respectively. The default for drivers that support the property is NULL. For details on CS_DS_PRINCIPAL, see “Directory service principal name”.
Not all directory service providers support passwords. An application calls ct_con_props(CS_SUPPORTED) to determine if the current directory driver supports this property.
CS_DS_PASSWORD cannot be set, cleared,
or retrieved unless Client-Library is using a directory service
provider that supports the property.
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.
For details on CS_DS_PASSWORD, see “Directory service password”.
Not all directory service providers support CS_DS_PRINCIPAL. An application calls ct_con_props(CS_SUPPORTED) to determine if the current directory driver supports this property.
CS_DS_PRINCIPAL cannot be set, cleared,
or retrieved unless Client-Library is using a directory service
provider that supports the property.
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 your Open Client and Open Server Configuration Guide for 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, and 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 a detailed description of driver configuration for your system.
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.
When Client-Library cannot load a directory driver, Client-Library silently fails over to the interfaces file by default. An application may change this behavior by setting the CS_DS_FAILOVER property before performing any of the actions listed above. For details, see “Directory service failover”.
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.
CS_DS_FAILOVER determines whether Client-Library uses the interfaces file as a directory source when a driver cannot be loaded. For details, see “Directory service failover”.
A connection will have a previously loaded driver if the application previously set the CS_DS_PROVIDER property or if the application previously issued one of the calls that requires a driver. See “Loading the default directory driver” for a list of calls that load the default directory driver.
The following table describes the directory source after a call to ct_con_props(CS_SET, CS_DS_PROVIDER) fails.
Driver previously loaded |
Value of CS_DS_FAILOVER |
New directory provider |
|---|---|---|
Yes |
CS_TRUE |
Interfaces file. |
Yes |
CS_FALSE |
Revert to previous driver |
No |
CS_TRUE |
Interfaces file |
No |
CS_FALSE |
Undefined |
When a directory driver is loaded, Client-Library assigns a default value for the DIT-base property based on the associated configuration file entry.
See the Open Client and Open Server Configuration Guide for driver configuration instructions.
CS_DS_SEARCH restricts the depth to which a directory search descends from the starting point.
CS_DS_SEARCH cannot be set, cleared,
or retrieved unless Client-Library is using a directory driver that
supports the property.
The following values are legal for CS_DS_SEARCH:
Value |
Meaning |
|---|---|
CS_SEARCH_ONE_LEVEL (default) |
Search includes only the leaf entries that are immediately descendants of the node specified by CS_DS_DITBASE. |
CS_SEARCH_SUBTREE |
Search the entire subtree whose root is specified by CS_DS_DITBASE. |
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.
The DCE directory driver does not allow CS_DS_SEARCH
to be set to a value other than the default, CS_SEARCH_ONE_LEVEL.
Searches start at the directory node indicated by the value of the CS_DS_DITBASE property (see “Base for directory searches”).
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_SIZELIMIT cannot be set, cleared,
or retrieved unless Client-Library is using a directory driver that
supports the 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.
CS_DS_TIMELIMIT cannot be set, cleared,
or retrieved unless Client-Library is using a directory driver that
supports the property.
