NAME

intro - Introduction to X/OPEN Directory Services (XDS) functions

SYNOPSIS

#include <xom.h>
#include <xds.h>
#include <xdsext.h>

DESCRIPTION

This xds_intro reference page lists the XDS interface functions in the following table. XDS provides a C language binding.

____________________________________________________________________________________________
                       Service Interface Functions - xds_intro(3xds)
____________________________________________________________________________________________
 Function                    Description
____________________________________________________________________________________________
 dsX_extract_attr_values()   Extracts attribute values from an OM object.
 ds_abandon()                Function not supported. See below.
 ds_add_entry()              Adds a leaf entry to the Directory Information Tree (DIT).
 ds_bind()                   Opens a session with a Directory User Agent.
 ds_compare()
                             Compares a purported attribute value with the attribute  value
                             stored in the directory for a particular entry.
 ds_initialize()             Initializes the interface.
 ds_list()                   Enumerates the immediate subordinates of a particular
                             directory entry.
 ds_modify_entry()           Performs an atomic modification of a directory entry.
 ds_modify_rdn()             Changes the Relative Distinguished Name (RDN) of a leaf entry.
 ds_read()                   Queries information on a directory entry by name.
 ds_receive_result()         Function partially supported (see below).
 ds_remove_entry()           Removes a leaf entry from the DIT.
 ds_search()                 Finds entries of interest in a portion of the DIT.
 ds_shutdown()               Shuts down the interface.
 ds_unbind()                 Unbinds from a directory session.
 ds_version()                Negotiates features of the interface and service.
 gds_decode_alt_addr()       Used by DME applications for alternate address mapping.
 gds_encode_alt_addr()       Used by DME applications for alternate address mapping.
____________________________________________________________________________________________

The Distributed Computing Environment (DCE) XDS interface does not support asynchronous operations within the same thread. Thus, ds_abandon is redundant. A ds_abandon call returns with a DS_C_ABANDON_FAILED (DS_E_TOO_LATE) error. Refer to Chapter 10 of the OSF DCE Application Development Guide for information on how to abandon an operation. For ds_receive_result, if there are any outstanding operations (when multiple threads issue XDS calls in parallel), this function returns DS_SUCCESS with the completion_flag_return parameter set to DS_OUTSTANDING_OPERATIONS. If no XDS calls are outstanding, then ds_receive_result returns with DS_status set to DS_SUCCESS, and the completion_flag_return parameter set to DS_NO_OUTSTANDING_OPERATION.

The following differences exist between Global Directory Service (GDS) and Cell Directory Service (CDS):

All functions operate on the GDS namespace.

CDS does not support the ds_modify_rdn() or ds_search(). The error message DS_C_SERVICE_ERROR (DS_E_UNWILLING_TO_PERFORM) is returned if either of these two functions are attempted on CDS.

In CDS, no X.500 schema rules apply. There is
- No concept of an object class.
- No mandatory attributes for a given object.
- No set of attributes expressly permitted for a given object.
- No predefined definition of single and multivalued attributes.

The absence of these schema rules means that the usual errors, which are returned by GDS for breach of schema rules, are not returned by CDS.

The CDS naming DIT is modeled on a typical file system architecture, where directories are used for storing objects and directories can contain subdirectories. Leaf objects in the CDS DIT are similar to X.500 naming objects. However, subtree objects are called directories as in a file system directory. All new objects must be added to an existing directory. CDS directory objects cannot be added, removed, modified, or compared using the XDS programming interface.

In CDS, the naming attribute of an object is not stored in the object. Consequently, in CDS, ds_read() never returns this attribute, and ds_compare() applied to this attribute returns with DS_C_ATTRIBUTE_ERROR (DS_E_CONSTRAINT_VIOLATION).

NOTES

See the notes in the relevant reference page for function-specific differences.

XDS functions check for NULL pointers and will return an error. The pointers are only checked at the function interface. The check is only for NULL and not for validity. If NULL pointers are passed, this may result in an undetermined behavior.