Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Directory services

Directory organization

Directory organization

Since directory services are provided by different vendors, each directory may have a different way of organizing and storing entries.

A directory has either a flat structure or a hierarchical structure. A hierarchical structure allows related entries to be combined into distinct logical groupings that descend from a parent entry. In a flat structure, all entries in the directory are in one logical grouping.

A hierarchical structure can be thought of as an inverted tree. The "root" entry is at the top and is the "ancestor" of all other entries. "Parent" entries represent logical groupings of related entries. If an entry is the parent of no other entry, it is called a "leaf" entry.

In any directory structure, each entry has a fully qualified name that uniquely identifies the entry. Entries also have a common name that is unique only among entries that have the same parent node.

In a hierarchical directory structure, names must contain navigation information. Only at the root node are the common name and the fully qualified name the same. For any other entry, the fully qualified name is constructed by combining the entry's common name with the fully qualified name of the entry's parent node.

In a flat directory structure, there is no root node, and every entry's fully qualified name is the same as its common name.

The Sybase interfaces file is an example of a flat directory. Most network-based directory services provide a hierarchical directory.

Entry names must be recognized by the directory provider software. Each provider requires a different name syntax. Table 2-19 illustrates some examples of fully qualified names.

These examples are for discussion purposes only. For name syntax information on directories other than the interfaces file, please see the documentation for the network directory provider software used on your system. All example entry names in this book are fictional.

Table 2-19 does not provide an exhaustive list of supported directory service providers, and the providers listed may not be supported on all platforms. See the Open Client/Server Configuration Guide for information about the directory providers supported on your platform.

Sybase applications access a DCE directory by using DCE Cell Directory Services (CDS) as the directory provider.

In DCE CDS, the directory name space is divided into cells. Each cell acts as an administrative domain for managing network resources and their users. In CDS, a fully qualified name can be cell-relative or globally qualified:

• Cell-relative qualified names begin with the special token "/.:". The common name of descendant nodes are listed in order (from left to right) and each common name is separated from its parent with a forward slash (/). The following example illustrates a cell-relative qualified name:

  /.:/eng/license_data

• Globally qualified names begin with the special token "/...". Following "/..." is a Domain Name Services (DNS) name for the DCE cell. The rest of the name consists of the descendant nodes from the cell root, in left-to-right order and separated by slashes. The following example illustrates a globally qualified name. In this example, "sales.fictional.com" identifies the cell that contains the entry:

  /.../sales.fictional.com/dataservers/license_data

In a Banyan StreetTalk directory, fully qualified names use the three-part StreetTalk name syntax. This allows a three-tiered hierarchy of directory entries.

StreetTalk names have the form:

item@group@organization

The top level (organization) is the organization name. At the next level (group), group names descend from an organization, and at the bottom level (item), user and resource names descend from a group name.

In an NDS directory, fully qualified names use a typed format, with a value specified for each level in the hierarchy.

The type hierarchy, with example values, consists of the following:

• An organization (O). This is an example of an organization:

   O=Fictional Incorporated

• One or more organizational units (OU) descended from the organization node. The organizational unit can represent a department name within the organization. For example:

   OU=eng.OU=testing

  Organizational units can be nested. In the example above, "testing" is below "eng" in the hierarchy.

• The common name (CN), descended from the organizational unit. For example:

   CN=my_server

• Combining all the values yields a fully qualified NDS name:

  CN=my_server.OU=testing.OU=eng.O=Fictional Incorporated

The Windows Registry comprises a hierarchical structure in which nodes are called "keys." The common name of descendant nodes are listed in order (from left to right) and each common name is separated from its parent by a backslash ("\"). Registry storage is local to each machine, but entries may be read from another machine's Registry by including the machine name in the fully qualified name.

The following example shows a fully qualified name for an entry in the local Registry:

SOFTWARE\SYBASE\SERVER\the_server

The example below names an entry in the machine queenbee's Registry:

queenbee:SOFTWARE\SYBASE\SERVER\the_server

All entry names for Sybase directory entries are located relative to the key "\HKEY_LOCAL_MACHINE\".

Registry entries are not case sensitive.

The libtcl.cfg and the libtcl64.cfg files (collectively libtcl*.cfg files) determine whether the interfaces file or LDAP directory services should be used. If LDAP is specified in the libtcl*.cfg file, the interfaces file is ignored unless the application specifically overrides the libtcl*.cfg file by passing the -I parameter while connecting to a server.

You use the libtcl*.cfg to specify the LDAP server name, port number, DIT base, user name, and password to authenticate the connection to an LDAP server. In the libtcl*.cfg file, LDAP directory services are specified with a URL in the DIRECTORY section.

For example:

[DIRECTORY] 

ldap=libdldap.so ldap://huey:11389/dc=sybase,dc=com??
     one????bindname=cn=Manager,dc=sybase,dc=com secret

Table 2-20 defines the keywords for the ldapurl variables.

You can find a complete list of Sybase's LDAP directory schema in:

UNIX - $SYBASE/$SYBASE_OCS/config

NT - %SYBASE%\%SYBASE_OCS%\ini In the same directory, there is also a file called sybase-schema.conf, which contains the same schema, but in a Netscape-specific syntax.

The interfaces file is a flat directory. The fully qualified name for an interfaces file entry is the same as the common name. See "Interfaces file".

A Directory Information Tree base, or DIT base, is an intermediate node in a directory tree used to qualify partial entry names. An application's DIT base setting is similar in concept to an application's current working directory in a hierarchical file system.

For any directory source other than the interfaces file, an application can specify a DIT base by setting the CS_DS_DITBASE connection property (see "Base for directory searches").

ct_connect uses the DIT base to resolve partial server names. An application specifies a server name for ct_connect in one of two ways:

• By specifying the fully qualified name, or

• By setting the CS_DS_DITBASE connection property and specifying a name relative to the CS_DS_DITBASE node.

Some directory service providers provide a special name syntax to indicate that an entry is fully qualified. When using these directory providers, the application overrides the current DIT base.

The sections below give examples of how the DIT base is combined with partial names. The rules vary by directory service provider. If your directory service provider is not listed, see the Open Client/Server Configuration Guide for your platform.

DIT base for DCE CDS

With DCE CDS as the directory provider, the DIT base may be a cell-relative name or a global name. If a global name is used, it must contain enough information to completely identify a cell.

The following two examples illustrate DIT-base settings for DCE CDS. The first example identifies a DIT base within the current DCE cell:

/.:/dataservers

The second example identifies a DIT base in the cell

sales.fictional.com

/.../sales.fictional.com/dataservers

The following example shows a partial name that is passed to ct_connect (as the server_name parameter):

sybase/test_server

ct_connect combines the DIT base and the value of the server_name as follows:

dit_base_value/server_name

For example:

/.:/dataservers/sybase/test_server

or

/.../sales.fictional.com/dataservers/sybase/test_server

Client-Library appends a slash (

/

Client-Library ignores the DIT base when server_name contains special syntax that indicates a fully qualified name. This syntax is:

• A cell-relative qualified name (server_name begins with "/.:"), or

• A globally qualified name (server_name begins with "/...").

In either of these cases, server_name is considered to be a fully qualified name, and ct_connect ignores the DIT base.

The default DIT base for the DCE CDS directory driver is:

/.:/subsys/sybase/dataservers

This default may be overridden by the directory driver configuration. To override the configured default, call ct_con_props to set the CS_DS_DITBASE property.

DIT base for Banyan STDA

A DIT base for Banyan always contains the group and organization names. For example:

sales@FictionalCo

The following example illustrates a partial name that is given to ct_connect:

fin_data

If a name does not contain the

@

@

fin_data@sales@FictionalCo

ct_connect assumes any name that contains the

@

The default DIT base for the Banyan directory driver is "SERVER@SYBASE". This default may be overridden by the directory driver configuration. To override the configured default, call ct_con_props to set the CS_DS_DITBASE property.

DIT base for Novell NDS

When NDS is the connection's directory service provider, the NDS software combines partial names with the DIT base. The Sybase-supplied NDS directory driver passes entry names and DIT-base settings unchanged to NDS. See your NDS documentation for the rules used to combine partial names with the DIT base. In Novell documentation, the DIT base is called a name context.

This example shows a DIT base for Novell NDS:

OU=testing.OU=eng.O=Fictional Incorporated

This example demonstrates a partial name that is given to ct_connect:

my_server

The default DIT base for the NDS directory driver may be specified in the directory driver configuration. Otherwise, the default DIT base is the name context setting for the user's Novell login session. To override the default, call ct_con_props to set the CS_DS_DITBASE property.

DIT base for Windows NT Registry

With the NT Registry as the connection's directory service provider, ct_connect appends a backslash "\" and the server_name value to the DIT base value. The DIT base cannot end with a backslash, and a server_name value that represents a partial name cannot begin with a backslash.

This is an example of a DIT base for the NT Registry:

SOFTWARE\SYBASE\SERVER

This an example of a partial name that is given to ct_connect:

dataserver\fin_data

These are combined to yield:

SOFTWARE\SYBASE\SERVER\dataserver\fin_data

The default DIT base for the Registry directory driver is

SOFTWARE\SYBASE\SERVER

This default may be overridden by the directory driver configuration. To override the configured default, call ct_con_props to set the CS_DS_DITBASE property.

Names are considered fully qualified when they begin with the DIT base value. For example, if the DIT base is "SOFTWARE\SYBASE\SERVER", then the following is a fully qualified name:

SOFTWARE\SYBASE\SERVER\debug\fin_data

All DIT base nodes are located relative to the "\HKEY_LOCAL_MACHINE\" key.

To specify a DIT base node from another machine's Registry, include the machine name and a colon (:) in the DIT base value. For example, the following DIT base value refers to the machine queenbee's registry:

queenbee:SOFTWARE\SYBASE\SERVER

DIT base for the Interfaces file

The CS_DS_DITBASE property is not supported when the connection's directory source is the interfaces file.

Using Client-Library, you may view directory entries by coding an application that installs a directory callback routine, then calls ct_ds_lookup and ct_ds_objinfo. See Chapter 9, "Using Directory Services," in the Open Client Client-Library/C Programmer's Guide for details.

The attributes of a directory object are determined by what kind of directory object it is. Sybase directory object is Server and the OID is CS_OID_OBJSERVER. See "Server directory object".

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.

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.

Base for directory searches

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

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.

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:

• 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"

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.

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

CS_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/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/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".

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.

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

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

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:

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").

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.

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

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