Properties for directory services

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


Directory service cache use

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.

NoteCS_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.


Base for directory searches

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

NoteCS_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:

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.


Directory service expansion of aliases

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.

NoteCS_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.


Directory service failover

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:

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”


Directory service password

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.

NoteCS_DS_PASSWORD cannot be set, cleared, or retrieved unless Client-Library is using a directory service provider that supports the property.


Directory service principal name

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.

NoteCS_DS_PRINCIPAL cannot be set, cleared, or retrieved unless Client-Library is using a directory service provider that supports the property.


Directory service provider

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.

Loading the default directory driver

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:

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”.

Changing to a different directory service provider

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.

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

Directory driver initialization

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.


Directory service search depth

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

NoteCS_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.

NoteThe 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”).


Directory search size limit

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.

NoteCS_DS_SIZELIMIT cannot be set, cleared, or retrieved unless Client-Library is using a directory driver that supports the property.


Directory search time limit

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.

NoteCS_DS_TIMELIMIT cannot be set, cleared, or retrieved unless Client-Library is using a directory driver that supports the property.