PreviousNext

Guidelines for Constructing Names of Directory Service Entries

A global name includes both a cell name and a cell-relative name composed of a directory path name and a leaf name. The cell name is assigned to a cell root at its creation. When you specify only a cell-relative name to an NSI operation, NSI automatically expands the name into a global name by inserting the local cell name. When returning the name of a directory service entry, a group member, or a member in a profile element, NSI operations return global names.

The directory path name and leaf name uniquely identify a directory service entry. The leaf name should somehow describe the entry; for example, by identifying its owner or its contents. The remainder of this topic contains guidelines for choosing leaf names.

Note: Directory path names and leaf names are case sensitive.

Use the following guidelines for constructing names:

· Naming a server entry

For a server entry that advertises an RPC interface or service offered by a server, the leaf name must distinguish the entry from the equivalent entries of other servers. When a single server instance runs on a host, you can ensure a unique name by combining the name of the service, interface (from the interface definition), or the system name for the server's host system.

For example, consider two servers, one offering a calendar service on host JULES, and one on host VERNE.

The server on JULES uses the following leaf name:

calendar_JULES

The server on VERNE uses the following leaf name:

calendar_VERNE

For servers that perform tasks on or for a specific system, an alternative approach is to create server entries in a system-specific host directory within the namespace. Each host directory takes the name of the host to which it corresponds. Because the directory name identifies the system, the leaf name of the server entry name does not need to include the host name, for example:

/.:/LandS/host_1/Process_control

To construct names for the server entries used by distinctive server instances on a single host, you can construct unique server entry names by combining the following information: the name of the server's service, interface, or object; the system name of the server's host system; and a reusable instance identifier such as an integer.

For example, the following leaf names distinguish two instances of a calendar service on the JULES system:

calendar_JULES_01

calendar_JULES_02

Avoid automatically generating entry names for the server entries of server instances; for example, by using unique data such as a timestamp (calendar_verne_15OCT91_21:25:32) or a process identifier (calendar_jules_208004D6). When a server incorporates such unique data into its server entry names, each server instance creates a separate server entry, causing many server entries. When a server instance stops running, it leaves an obsolete server entry that is not reused. The creation of a new entry whenever a server instance starts may impair performance.

A server can use multiple server entries to advertise different combinations of interfaces and objects. For example, a server can create a separate server entry for a specific object, and the associated interfaces. The name of such a server entry should correspond to a well-known name for the object. For example, consider a server that offers a horticulture bulletin board known to users as horticulture_bb. The server exports the horticulture_bb object, binding information, and the associated bulletin-board interface to a server entry whose leaf name identifies the object, as follows:

horticulture_bb

Note: An RPC server that uses RPC authentication can choose identical names for its principal name and its server entry. Use of identical names permits a client that calls the rpc_binding_set_auth_info( ) routine to automatically determine a server's principal name. (The client will assume the principal name to be the same as the server's entry name.) If a server uses different principal and server entry names, users must explicitly supply the principal name. For an explanation of principal names, see Part 5 of this guide.

· Naming a group

The leaf name of a group should indicate the interface, service, or object that determines membership in the group. For example, for a group whose members are selected because they advertise an interface named Statistics, the following is an effective leaf name:

Statistics

For a group whose members advertise laser printer print queues as objects, the following is an effective leaf name:

laser-printer

· Naming a profile

The leaf name of a profile should indicate the profile users; for example, for a profile that serves the members of an accounting department, the following is an effective leaf name:

accounting_profile

The following text describes the NSI begin, next, and done operations. NSI accesses a variety of search and inquire operations that read NSI attributes in directory service entries. An NSI attribute is an RPC-defined attribute of a directory service entry used by the DCE RPC directory service interface. An NSI attribute stores one of the following: binding information, object UUIDs, a group, or a profile. Reading information from any attribute involves an equivalent set of search or inquire operations; that is, an integral set of begin, next, and done operations. An RPC application uses these operations as follows:

1. The application creates a directory service handle (a reference to the context of the ensuing series of next operations) by calling an NSI begin operation.

2. The application calls the NSI next operation corresponding to the begin operation one or more times. Each next operation returns another value or list of values from the target RPC directory service attribute. For example, an import_next operation returns binding information from a binding attribute and an object from an object attribute.

3. The application deletes the directory service handle by calling the corresponding NSI done operation.

Note: Search and inquire operations are also accessible interactively from within the RPC control program.

The following table lists the NSI next operations used by RPC applications.


NSI next Operations

Search Operation Attributes Traversed
rpc_ns_binding_import_next( ) Searches for binding and object attributes of a compatible server; reads any NSI attribute in a search path. Returns a binding handle that refers to a potential binding for a compatible server, and also to a single object UUID.
rpc_ns_binding_lookup_next( ) Searches for binding and object attributes of a compatible server; reads any NSI attribute in a search path. Returns a list of binding handles, each of which refers to a potential binding for a compatible server, and also to a single object UUID. The same object UUID is associated with each potential binding.
Note that, after calling the lookup_next operation, the client must select one binding handle from the list. To select a binding handle at random, the client can call the NSI binding select routine rpc_ns_binding_select( ). For an alternative selection algorithm, the client can define and call its own application-specific select algorithm.
Inquire Operation Attributes Traversed
rpc_ns_group_mbr_inq_next( ) Reads a group attribute and returns a member name.
rpc_ns_profile_elt_inq_next( ) Reads a profile attribute and returns the fields of a profile element.