xds_intro(3xds) — Subroutines
Name
xds_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. |
| 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. |
| 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. 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, ds_receive_result() returns with DS_status set to DS_SUCCESS, and with 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(). If either of these two functions are attempted on CDS, the error message DS_C_SERVICE_ERROR is returned (DS_E_UNWILLING_TO_PERFORM).
•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. Note that the ds_compare() routine 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.