Previous section.

DCE 1.1: Directory Services
Copyright © 1997 The Open Group

CDS Protocol Definition

This chapter contains the abstract definition of the CDS transaction protocol and solicitation protocol whose encodings are specified in CDS Protocol Encodings ; it is a specification of the protocol machines employed by CDS clerks and CDS servers.

Conforming implementations shall comply with the behaviour defined in this chapter.

Clerk Operation

The CDS clerk communicates with one or more CDS servers (including the Global Directory Agent) for the processing of client requests.

A clerk performs the following functions:

Solicitation and Clearinghouse Selection

When requested by a client to perform some CDS operation, the clerk must first select a clearinghouse that is likely to be able to process the request. It then has to bind to the appropriate CDS server controlling that clearinghouse.

Since the cell's name space database is partitioned and distributed among a number of clearinghouses, the clerk must first decide which clearinghouses are good candidates for being able to process a client request, and then select one of them. The algorithm for choosing a clearinghouse is internal to the implementation of a clerk and how it caches previously received information; only the solicitation protocol for learning about available clearinghouses is specified in this document.

The following assumptions can be made about the location of clearinghouses:

Regardless of the details of its particular implementation, a clerk has some or all of the following information at its disposal to use in choosing a clearinghouse:

The algorithm for selecting among multiple possible clearinghouses and CDS servers is not specified. Implementations may follow some rules of probability that reduce the average transactions necessary, balance the load among servers, and account for network topology.

The process of binding and establishing communication with the CDS server that supports a particular clearinghouse is subject to the underlying RPC protocol. This process includes mutual authentication. The clerk generally has several ways of obtaining the appropriate protocol tower for the server. These include:

These methods are usually tried in the order listed above, in the interest of securing the best performance.

Referral Handling (Progress Record)

When a clearinghouse is requested (in the person of a CDS server) to perform a CDS operation via the transaction protocol, it attempts to get the clerk as close to the desired result as possible, either by performing the operation itself, or by directing the clerk to other clearinghouses (that is, CDS servers) that can provide further guidance. A progress record returned to the clerk indicates the status of the requested operation and contains whatever information the server was able to resolve. The clerk is responsible for repeating the request (this time to the new clearinghouse that it was referred to) for as many times as is necessary to complete the information provided in the progress record.

The progress record contains the following flags and other fields:

This flag is initially set to FALSE by the clerk and subsequently set to TRUE by the server if the operation was completed successfully. Otherwise, if the returned flag is FALSE, the fully-qualified global name of the request could only partially be resolved; the resolved and residual (unresolved) parts of the fully-qualified global name are returned in the appropriate fields of the progress record.

This flag is initially set by the clerk to TRUE, and is never reset by the clerk. As soon as a clearinghouse for an ancestor directory is found, the server sets this flag FALSE to prevent oscillation in the search later on.

The server leaves this flag TRUE if the name points to another cell. The GDA then clears this flag if the foreign cell name is successfully looked up.

This flag is initially set to FALSE by the clerk and then set to TRUE whenever a soft link is followed by the clerk or server in resolving the name.

This flag is initially set to FALSE by the clerk and then set to TRUE by a server when it detects a soft link and returns control to the clerk to check for loops in the soft link graph. The clerk resets this flag to FALSE before each new call to a server.

This flag is set to TRUE by the clerk if it wishes the server to ignore the state of a directory/replica and return information regardless.

This flag is set to TRUE by the server whenever the partial or full resolved name is found to be a directory; otherwise (including the case where the full resolved name is NULL) it is set to FALSE.

This flag is required for cache handling when the entry type ET_dirOrObj is requested, because otherwise the clerk does not know which entity (directory or object) was matched if a match is reported.

This field is used by servers to compute the minimum timeout for all soft links followed in resolving a name. This information can then be used by the clerk to determine its policy for storing in cache, and may also be returned to the client as an indication of how long the supplied name is valid.

Unresolved Name
This field contains the portion of the original fully-qualified global name that has not yet been located by the servers. The servers are responsible for maintaining this field, and clerks use the value (if any) returned in it as input for subsequent requests for the given operation. The clerk initially sets this field to the requested fully-qualified global name argument of the operation. Generally the field contains one of the following values:

Resolved Name
This field contains the portion of the current name which has been successfully processed (resolved) by the servers. The name in this field may be different from the original name supplied by the client if a soft link was traversed. The clerk is not required to do anything with the information in this field, but it may use it for either of the following purposes:

Replica Pointer
This field contains a set of clearinghouses which are believed to have a good probability either of being able to perform the desired operation or of having information about other clearinghouses closer to ones that can actually perform the operation. The clerk initially sets this field to NULL.

Tree Walk Algorithm

Every client call to the clerk results in the clerk's interactively walking the tree of interest and causing the operation to be performed at an appropriate clearinghouse for the directory.

The abstract semantic of the tree walk algorithm is as follows:

  1. Initialise the progress record and the soft link loop detector.

  2. Select the initial clearinghouse.

  3. Send request to clearinghouse.

    If the selected clearinghouse is unavailable and the request fails, the clerk selects another clearinghouse that is at its disposal (iterate through previous step). See also Solicitation and Clearinghouse Selection .

  4. Loop while PR_done flag of result is FALSE:

  5. If PR_done flag is TRUE, return the operation result to the client.

Loop Detection

The clerk is responsible for detecting loops in soft links while walking the name space tree. Any time a soft link is detected by the server, the transaction agent returns a progress record to the clerk with the PR_hitLink flag set to TRUE. When this occurs, the clerk has to determine whether a loop in the graph of soft links has been detected (see Tree Walk Algorithm ); if so, the clerk returns the failure status [CDS_POSSIBLECYCLE] to the calling client.

The algorithm for loop detection and determining the depth of cycles is implementation-specific.

Server Operation

The CDS server contains two basic functional modules: the clearinghouse and the transaction agent.


Clearinghouses are databases in which the contents of the cell name space controlled by a CDS are stored. Clearinghouses accommodate partitioning and (possibly) replication.

The naming of clearinghouses follows a set of rigid rules which ensure that name lookup cannot fail because the clearinghouse in which the directory is storing the object entry cannot be found. In particular, CDS ensures that the following clearinghouse invariant is never violated during normal operation:

Clearinghouses are either up or down. When a clearinghouse is up at a given node, that node is acting as a CDS server for that clearinghouse, and may advertise its availability. A server may be controlling more than one clearinghouse simultaneously.

A clearinghouse contains the following types of information:

Information that controls the operation of the clearinghouse as a whole is stored in a pseudo-directory entry in the clearinghouse. The unique identifier (UUID) of this pseudo-directory has the same value as the UUID of the clearinghouse object itself. Thus, clearinghouses can be named and accessed the same way as regular directory entries by clients. The specific attributes applied to these clearinghouse pseudo-directories are defined in Architected Default Attributes .

Every clearinghouse is catalogued in an object entry within the cell root directory. When a server is walking the tree looking for a clearinghouse, it may encounter a clearinghouse object whose information it needs to use for building a referral to the actual clearinghouse. Clearinghouses are accessed by the transaction agents of CDS servers. A set of operational attributes (as determined in Architected Default Attributes ) are exclusively maintained by CDS servers. Any other entries and attributes can be accessed by clerks by means of requests to CDS servers.

Clients can access the clearinghouse operational information by specifying the clearinghouse name with the entry type ET_clearinghouse.

Transaction Agent

The transaction agent is responsible for processing clerk transactions, reading and writing clearinghouses, and communicating with transaction agents at other servers.

The transaction agent processes the following two sets of the transaction protocol:

Logically, there is a single transaction agent for each clearinghouse, which processes transactions destined for it. However, the transaction agent has to multiplex the transactions of many clerks simultaneously, and it must thus be able to manage multiple simultaneous execution contexts. Whether this is accomplished by multi-threaded code, multiple processes or other mechanisms is implementation-dependent.

CDS servers export the transaction agent interface with the object UUID of clearinghouses. Clerks bind to clearinghouses using these object UUIDs.

The common operations needed for accessing clearinghouses and processing transactions are described below, in Common Operations of the Transaction Agent . This is followed by a specification of the protocol state model for operations on directory entries. Common Operations of the Transaction Agent , in conjunction with Abstract Definitions of CDS Service Primitives , fully defines the abstract algorithm applied to any other operations.

Common Operations of the Transaction Agent

Each transaction initiated by a clerk consists of a single request. The transaction agent is responsible for processing the request and generating an appropriate response. However, before any request can be processed, the transaction agent must perform the following functions:

  1. Determine whether the clearinghouse requested by the clerk is available.

    If the clearinghouse is available, the transaction agent proceeds as described in the following steps. Otherwise, one of the following failure statuses is returned to the clerk:


    If the clearinghouse is known currently to reside at this transaction agent's server.


    If the clearinghouse is not known to this transaction agent's server.

  2. Find the requested entry in the clearinghouse; if this cannot be done, return the partial result, together with any possible location hints, in an updated progress record to the clerk.

    Since a clearinghouse may contain any part of a path through the name space to the directory which contains the entry of interest, the transaction agent implements a local version of the tree walk algorithm used by clerks. In particular, the transaction agent must perform the following activities:

    1. Determine whether the clearinghouse contains some portion of the path provided by the clerk.

      If it does not, the clearinghouse must either return success with no additional information, or, if the PR_up flag is set to TRUE by the clerk, return a CDS_GDAPointer. If the CDS_GDAPointer does not exist, a [CDS_ROOTLOST] status is returned.

    2. The transaction agent then walks the tree down from the point specified by the clerk in the progress record supplied, until one of the following happens:

      • The entry requested by the clerk is reached.

      • A child pointer entry pointing to a different set of clearinghouses is encountered.

      • A soft link is encountered.

      • An access failure occurs, or a portion of the path is determined not to exist. In this case, the appropriate failure status is returned.

  3. Ensure that the client has sufficient permission to access the entry.

    The transaction agent calls the ACL Manager (see Access Control and Protection Model ) to perform the access control verification. If access is denied, the transaction agent returns the appropriate failure status to the clerk and rejects this operation request.

  4. After successful verification of access permission on the encountered entry, the transaction agent proceeds as follows, depending on the result in step ii above:

After obtaining the handle for the target entry of the requested operation, the transaction agent processes the request according to its service definition as follows:

Transactions for Manipulating Directory Entries
The operations which modify directory entries may require the coordination of multiple clearinghouses to maintain consistency in the name space structure. In general, the clerk issues the client's request to one clearinghouse (that is, CDS server), and the transaction agent for that clearinghouse calls its clerk to perform special internal server transactions to manipulate state at the other clearinghouse.

The clerk operations that may cause operations of the transaction protocol, which are originated by the initially targeted server and the activities of the transaction agent, are as follows:

This operation causes a new directory to be created. It is issued by the clerk to the transaction agent controlling the clearinghouse that is to contain the master replica of the new directory. This may not be the same clearinghouse which holds the master replica for the new directory's parent; hence synchronisation is needed.

The algorithm for creating a new directory is as follows (note that this is an asynchronous series of actions):

  1. A new directory is created at the local clearinghouse, and its CDS_ParentPointer attribute is set to point to its (purported) parent directory. Note that it may be true that some directory on the specified path to the new directory may not exist, or that the new directory has a name which conflicts with an already existing child directory. These problems are detected when the attempt is made to create the child pointer entry at the parent's master replica (see the next step).

  2. The transaction agent attempts to create the child pointer entry in the parent directory by performing the cds_CreateChild operation. If this fails, the new directory entry is destroyed and the appropriate failure status is returned to the clerk.

  3. If the child pointer entry is successfully created, the CDS_ParentPointer attribute is set to the actual name of the parent directory (resolving a possibly linked name).

  4. The Access Control List for the directory is appropriately initialised.

This operation removes an existing directory. The directory must be completely empty (that is, no object, soft link or child pointer entries can exist in the directory), or the deletion fails, and the failure status [CDS_NOTEMPTY] is returned to the calling clerk. The operation is issued by the clerk to the transaction agent controlling the master replica of the directory.

The algorithm for deleting a directory proceeds as follows (note that this is an asynchronous series of actions):

  1. The transaction agent attempts to delete the child pointer entry in the parent directory by performing the cds_DeleteChild operation. If this fails, the appropriate failure status is returned to the calling clerk.
    This operation is performed asynchronously in the background. The directory is marked as dying, and a success status is returned to the clerk. Some time may have elapsed before the child pointer entry is actually deleted and the directory is marked dead.

  2. If the child pointer entry is successfully deleted, the local replica of the directory is placed in the dead state for processing the clean-up.

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.

Contents Next section Index