Previous section.

DCE 1.1: Directory Services
Copyright © 1997 The Open Group

The Open Group Directory Service API (XDS)

This chapter identifies the conformance requirements of The Open Group Directory Services (XDS) API implementations for the DCE. For the full Open Group XDS API, see the referenced XDS specification.

The XDS interface comprises a number of functions, together with OM classes of OM objects, which are used as the arguments and results of the functions. Both the functions and the OM objects are based on the Abstract Service specified in the ISO 9594-3 standard.

The interface models the directory interactions as service requests made through a number of interface functions, which take a number of input arguments. Each valid request causes an operation to be performed by the directory service, which eventually returns a status and any result of the operation.

All interactions between the user and the directory service belong to a session, which is represented by an OM object passed as the first argument to most interface functions.

The other arguments to the functions include a context and various service-specific arguments.

XDS Conformance

The XDS interface defines an API that application programs can use to access the functionality of the underlying directory service. The DCE XDS API conforms to the XDS specification. Both GDS and CDS are supported by the DCE XDS API.

DCE XDS is characterised by the following:

DCE XDS supports five packages, one of which is mandatory and the other four of which are optional. Use of the optional packages is negotiated through the ds_version () routine. The packages are as follows:

None of the OM classes defined in these packages are encodable. As a result, DCE XDS application programmers do not require the use of the XOM functions om_encode () and om_decode (), which are not supported by the DCE XOM API.

XDS Functions

The OSI Directory Service standards define Abstract Services that requestors use to interact with the directory. Each of these Abstract Services maps to a single function call, and the detailed specifications of the calls are given in the XDS reference pages in the XDS specification. The services, and the function calls to which they map, are as follows:

DirectoryBind

Maps to ds_bind ().

DirectoryUnbind

Maps to ds_unbind ().

Read

Maps to ds_read ().

Compare

Maps to ds_compare ().

Abandon

Maps to ds_abandon ().

List

Maps to ds_list ().

Search

Maps to ds_search ().

AddEntry

Maps to ds_add_entry ().

RemoveEntry

Maps to ds_remove_entry ().

ModifyEntry

Maps to ds_modify_entry ().

ModifyRDN

Maps to ds_modify_rdn ().

The XDS function ds_receive_result (), which is used with asynchronous operations, has no counterpart in the Abstract Service.

The ds_initialize (), ds_shutdown () and ds_version () functions are used to control the XDS API, and do not initiate any directory operations.

The interface functions are summarised in XDS Interface Functions .

Function Description
ds_abandon () Abandons the result of a pending asynchronous operation. This function is not supported.
ds_add_entry () Adds a leaf entry to the DIT (Directory Information Tree).
ds_bind () Opens a session with a Directory User Agent (DUA), which in turn connects to a Directory Service Agent (DSA).
ds_compare () Compares a purported attribute value with the attribute value stored in the Directory Information Base (DIB) for a particular entry.
ds_initialize () Initialises the XDS interface.
ds_list () Enumerates the names of the immediate subordinates of a particular directory entry.
ds_modify_entry () Atomically performs modification of a directory entry.
ds_modify_rdn () Changes the Relative Distinguished Name (RDN) of a leaf entry.
ds_read () Queries information on a particular directory entry by name.
ds_receive_result () Retrieves the result of an asynchronously executed function. This function is not supported.
ds_remove_entry () Removes a leaf entry from the DIT.
ds_search () Finds entries of interest in a portion of the directory information tree.
ds_shutdown () Discards a workspace.
ds_unbind () Unbinds from a directory session.
ds_version () Negotiates features of the interface and service.

Table: XDS Interface Functions

The XDS interface functions are fully specified in the XDS specification. The following sections specify the extensions made for the DCE XDS API for each of the interface functions.

ds_abandon()

The DCE XDS interface does not support asynchronous operations. Thus, ds_abandon () and ds_receive_result () are redundant. A ds_abandon () call always returns a [DS_C_ABANDON_FAILED] ([DS_E_TOO_LATE]) error.

ds_add_entry()

Note the following in regard to the ds_add_entry () operation:

Since CDS does not support the X.500 schema rules, some CDS objects may not contain GDS-mandatory attributes, such as object class and so on.

ds_bind()

In order to use CDS when GDS is not active, ds_bind () must be called with the value of the session argument set to DS_DEFAULT_SESSION.

ds_compare()

Note the following in regard to the ds_compare () operation:

ds_initialize()

No modifications apply.

ds_list()

For CDS, enumeration can be performed only on directories (that is, entries that are not leaf objects); if enumeration of a leaf object is attempted, the call returns a [DS_C_NAME_ERROR] ([DS_E_NO_SUCH_OBJECT]) error.

ds_modify_entry()

Note the following in regard to the ds_modify_entry () operation:

ds_modify_rdn()

CDS does not support the ds_modify_rdn () operation. Attempting this operation on a CDS object results in an error return of [DS_C_SERVICE_ERROR] ([DS_E_UNWILLING_TO_PERFORM]).

ds_read()

Note the following in regard to the ds_read() operation:

ds_receive_result()

The DCE XDS interface does not support asynchronous operations. Thus, ds_abandon () and ds_receive_result () are redundant. A ds_receive_result () function call always returns with DS_status set to [DS_SUCCESS], and the completion_flag_return argument set to DS_NO_OUTSTANDING_OPERATION.

ds_remove_entry()

No modifications apply.

ds_search()

CDS does not support the ds_search () operation. An attempt to perform a ds_search () in CDS results in an error of [DS_C_SERVICE_ERROR] ([DS_E_UNWILLING_TO PERFORM]) being returned.

ds_shutdown()

No modifications apply.

ds_unbind()

No modifications apply.

ds_version()

No modifications apply.

XDS Function Call Results

All XDS functions, with the exception of ds_initialize(), return a value of type DS_status, which is the C function result of the call. If the function is successful, then DS_status returns with a value of [DS_SUCCESS]. If the function does not complete successfully, then DS_status takes either the error [DS_NO_WORKSPACE] or a private error object.

Most XDS functions also return data in an invoke_id_return argument, which identifies the particular invocation; and each of the interrogation operations returns data in a result_return argument. The invoke_id_return and result_return values are returned using pointers that are supplied as arguments of the C function.

These three types of function results are described in the XDS specification.

invoke_id_return Parameter

All interface functions that invoke a directory service operation return an invoke_id_return argument, which is an integer that identifies the particular invocation of an operation. This information is meaningful only if asynchronous operations are supported. Since DCE XDS does not support asynchronous operations, the invoke_id_return value is meaningless in DCE XDS.

The affected interface functions are:

DCE application programmers must still supply this argument, as described in the XDS reference pages (see the XDS specification), but the value returned therein should be ignored.

Synchronous Operations

Since asynchronous use of the interface within the same thread is not supported, the value of the DS_ASYNCHRONOUS OM attribute in DS_C_CONTEXT is always OM_FALSE, causing all operations within the same thread to be synchronous.

In synchronous mode, all functions wait until the operation is complete before returning. The thread of control is blocked within the interface during the time which elapses between the calling of a function and its return, and the function result can be used immediately after the function returns.

Implementations may define a limit on the number of asynchronous operations that can be outstanding at any one time in any one session. The limit is defined by the implementation-defined constant DS_MAX_OUTSTANDING_OPERATIONS. In DCE XDS this constant always has the value 0 (zero), because asynchronous operations are not supported.

All errors occurring during a synchronous request are reported when the function returns.

The DS_FILE_DESCRIPTOR OM attribute of DS_C_SESSION is not used by the DCE XDS API. It is always set to DS_NO_VALID_FILE_DESCRIPTOR.

Security and XDS

The XDS specification does not define a security interface in order to avoid possibly constraining the security features of existing directory implementations.

DCE GDS proves an extension to the XDS API for security support. This is achieved at the XDS API level through a new DSX_C_GDS_SESSION session object which contains information on the security mechanism that should be used. Simple authentication through the use of name and password, and external authentication based on DCE security are supported. (See Global Directory Service Package for additional information.)

Automatic Connection Management

A directory service implementation can provide automatic management of the association or connection between the user and the directory service, making and releasing connections at its discretion.

DCE XDS does not support automatic connection management. A DSA connection is established when ds_bind () is successfully called, and released when ds_unbind () is successfully called.

Global Directory Service Package

The Global Directory Service Package (GDSP) is an OSF extension to the XDS interface. Applications must negotiate use of this package, by calling ds_version (), before using any of the package's features. If an application attempts to use features specific to this package without first negotiating its use, an error (for example, [OM_NO_SUCH_CLASS]) is returned by the DCE XOM function it attempted to execute.

The object identifier associated with the GDSP is:

{iso(1) identified-organisation(3) icd-ecma(0012) member-company(2)\ siemens-units(1107) sni(1) directory(3) xds-api(100) gdsp(0)}

It has the following encoding:

\x2B\xC\x2\x88\x53\x1\x3\x64\x0

The GDSP object identifier is represented by the constant DSX_GDS_PKG. This constant, together with the other C constants associated with the package, are contained in the <xdsgds.h> header file (see XDS/XOM Header Files ).

In the following sections, the GDSP's attribute types are introduced first; descriptions of its object classes follow. Finally, the OM class hierarchy and OM class definitions required to support the new attribute types are described.

GDSP Attribute Types

Additional directory attribute types are used with the GDS package. Each attribute type has its own object identifier, held as the value of the OM attribute DS_ATTRIBUTE_TYPE. These object identifiers are represented in the interface by constants with the same name as the directory attribute they identify, prefixed by DSX_A_.

Object Identifiers for GDSP Attribute Types shows the names of the GDSP attribute types, together with the BER encoding of the object identifiers associated with each of them. The third column of the table shows the hexadecimal values of the octets of the BER encoding of the object identifier in hexadecimal representation. All these object identifiers are derived from the root:

{iso(1) identified-organisation(3) icd-ecma(0012) member-company(2) siemens-units(1107) sni(1) directory(3) attribute-type(4)}

    Object Identifier BER
Package Attribute Type (Hexadecimal Value)
GDSP DSX_A_ACL \x2B\x0C\x02\x88\x53\x01\x03\x04\x01
GDSP DSX_A_AT \x2B\x0C\x02\x88\x53\x01\x03\x04\x06
GDSP DSX_A_CDS_CELL \x2B\x0C\x02\x88\x53\x01\x03\x04\x0D
GDSP DSX_A_CDS_REPLICA \x2B\x0C\x02\x88\x53\x01\x03\x04\x0E
GDSP DSX_A_CLIENT \x2B\x0C\x02\x88\x53\x01\x03\x04\x0A
GDSP DSX_A_DEFAULT_DSA \x2B\x0C\x02\x88\x53\x01\x03\x04\x08
GDSP DSX_A_DNLIST \x2B\x0C\x02\x88\x53\x01\x03\x04\x0B
GDSP DSX_A_LOCAL_DSA \x2B\x0C\x02\x88\x53\x01\x03\x04\x09
GDSP DSX_A_MASTER_KNOWLEDGE \x2B\x0C\x02\x88\x53\x01\x03\x04\x00
GDSP DSX_A_OCT \x2B\x0C\x02\x88\x53\x01\x03\x04\x05
GDSP DSX_A_SHADOWED_BY \x2B\x0C\x02\x88\x53\x01\x03\x04\x03
GDSP DSX_A_SHADOWING_JOB \x2B\x0C\x02\x88\x53\x01\x03\x04\x0C
GDSP DSX_A_SRT \x2B\x0C\x02\x88\x53\x01\x03\x04\x04
GDSP DSX_A_TIME_STAMP \x2B\x0C\x02\x88\x53\x01\x03\x04\x02

Table: Object Identifiers for GDSP Attribute Types

Values for GDSP Attribute Types shows the names of the attribute types, together with the OM value syntax used in the interface to represent each attribute's values. The table also indicates: the range of lengths in octets permitted for the string types; whether the attribute can be multi-valued; and which matching rules are provided for the syntax.

    Value Multi- Matching
Attribute Type OM Value Syntax Length Valued Rules
DSX_A_ACL Object (DSX_C_GDS_ACL) - no E
DSX_A_AT String (OM_S_PRINTABLE_STRING) 1-101 yes E,S
DSX_A_CDS_CELL String (OM_S_OCTET_STRING) 1-284 no E
DSX_A_CDS_REPLICA String (OM_S_OCTET_STRING) 1-905 yes E
DSX_A_CLIENT Only a cache attribute - - -
DSX_A_DEFAULT_DSA Only a cache attribute - - -
DSX_A_DNLIST Object (DS_C_DS_DN) - yes E,S
DSX_A_LOCAL_DSA Only a cache attribute - - -
DSX_A_MASTER_KNOWLEDGE Object (DS_C_DS_DN) - no E,S
DSX_A_OCT String (OM_S_PRINTABLE_STRING) 1-397 yes E,S
DSX_A_SHADOWED_BY Not used yet - - -
DSX_A_SHADOWING_JOB Not used yet - - -
DSX_A_SRT String (OM_S_PRINTABLE_STRING) 1-29 yes E,S
DSX_A_TIME_STAMP String (OM_S_UTC_TIME_STRING) 11-17 no E,O

Table: Values for GDSP Attribute Types

In the Matching Rules column, the abbreviations have the following meanings:

E
The matching rule determines whether two values are equal.

S
The matching rule identifies one value as a substring of the other.

O
The matching rule determines the ordering of two values.

Descriptions of GDSP Attribute Types
See the XDS specification for information on general matching rules.

DSX_A_ACL

The contents of this attribute describe the access rights for one or more directory service users.

DSX_A_AT

The contents of this attribute describe the attribute types permitted in GDS.

DSX_A_CDS_CELL and DSX_A_CDS_REPLICA

The contents of these attributes consist of the information necessary for contacting a remote DCE cell. These two attributes always exist together in the same object. See Cell Registration in Global Name Space for its representation.

DSX_A_CLIENT

This attribute applies only to the cache. It identifies the entry which holds the DUA's Presentation Address. Its OM syntax is OM_S_PRINTABLE_STRING and its value is CLIENT.

DSX_A_DEFAULT_DSA

This attribute applies only to the cache. It identifies an entry which holds the Distinguished Name (DN) of the DUA's default DSA. Its OM syntax is OM_S_PRINTABLE_STRING and its value is DEFAULT-DSA.

DSX_A_DNLIST

The contents of this attribute are used internally by the GDS DSA.

DSX_A_LOCAL_DSA

This attribute applies only to the cache. It identifies an entry which holds the Distinguished Name (DN) of the DUA's local DSA. Its OM syntax is OM_S_PRINTABLE_STRING and its value is LOCAL-DSA.

DSX_A_MASTER_KNOWLEDGE

The contents of this attribute consist of the Distinguished Name (DN) of the DSA that holds the master copy of this entry.

DSX_A_OCT

The contents of this attribute consist of a description of the object classes supported by the DSA.

DSX_A_SHADOWED_BY and DSX_A_SHADOWING_JOB

These two GDSP attributes are intended for future use.

DSX_A_SRT

The contents of this attribute consist of a description of the structure of the DNs (Distinguished Names) permitted in GDS.

DSX_A_TIME_STAMP

This attribute is part of the DSX_O_SCHEMA object. It contains the creation time of the DSX_O_SCHEMA object.

GDSP Object Classes

The only object class specific to the GDSP is DSX_O_SCHEMA (see Object Identifier for GDSP Object Classes ). It is stored in GDS as an object directly under the directory root. The most important attributes of the DSX_O_SCHEMA object are the three recurring ones DSX_A_OCT, DSX_A_AT and DSX_A_SRT, which describe the GDS directory information tree (DIT) structure.

The third column of the table shows the hexadecimal values of the octets of the BER encoding of the object identifier in hexadecimal representation. This object identifier is derived from the root:

{iso(1) identified-organisation(3) icd-ecma(0012) member-company(2) siemens-units(1107) sni(1) directory(3) object-class(6)}

    Object Identifier BER
Package Attribute Type (Hexadecimal Value)
GDSP DSX_O_SCHEMA \x2B\x0C\x02\x88\x53\x01\x03\x06\x00

Table: Object Identifier for GDSP Object Classes

GDS OM Class Hierarchy

The additional OM classes used by the GDS package are organised hierarchically. In the following list, subclassification is indicated by indentation; it shows which classes inherit additional OM attributes from their OM superclasses.
OM_C_OBJECT (defined in the OM package)
	DS_C_SESSION (defined in the Directory Service Package)
		DSX_C_GDS_SESSION
	DS_C_CONTEXT (defined in the Directory Service Package)
		DSX_C_GDS_CONTEXT
	DSX_C_GDS_ACL
	DSX_C_GDS_ACL_ITEM

None of the OM classes in the preceding list are encodable using om_encode () and om_decode ().

DSX_C_GDS_ACL

An instance of OM class DSX_C_GDS_ACL describes up to five categories of rights for one or more directory users.

An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in OM Attributes of DSX_C_GDS_ACL .

    Value Value Value
OM Attribute Value Syntax Length Number Initially
DSX_MODIFY_PUBLIC Object (DSX_C_GDS_ACL_ITEM) - 0-4 -
DSX_READ_STANDARD Object (DSX_C_GDS_ACL_ITEM) - 0-4 -
DSX_MODIFY_STANDARD Object (DSX_C_GDS_ACL_ITEM) - 0-4 -
DSX_READ_SENSITIVE Object (DSX_C_GDS_ACL_ITEM) - 0-4 -
DSX_MODIFY_SENSITIVE Object (DSX_C_GDS_ACL_ITEM) - 0-4 -

Table: OM Attributes of DSX_C_GDS_ACL

The OM attributes of DSX_C_GDS_ACL are as follows:

DSX_MODIFY_PUBLIC

This attribute specifies the user, or subtree of users, that can modify attributes classified as public attributes.

DSX_READ_STANDARD

This attribute specifies the user, or subtree of users, that can read attributes classified as standard attributes.

DSX_MODIFY_STANDARD

This attribute specifies the user, or subtree of users, that can modify attributes classified as standard attributes.

DSX_READ_SENSITIVE

This attribute specifies the user, or subtree of users, that can read attributes classified as sensitive attributes.

DSX_MODIFY_SENSITIVE

This attribute specifies the user, or subtree of users, that can modify attributes classified as sensitive attributes.

DSX_C_GDS_ACL_ITEM

An instance of OM class DSX_C_GDS_ACL_ITEM is a component of an instance of OM class DSX_C_GDS_ACL. It specifies the user, or subtree of users, to whom an access right applies.

An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in OM Attributes of DSX_C_GDS_ACL_ITEM .

    Value Value Value
OM Attribute Value Syntax Length Number Initially
DSX_INTERPRETATION Enum (DSX_Interpretation) - 1 -
DSX_USER Object(DS_C_DS_DN) - 1 -

Table: OM Attributes of DSX_C_GDS_ACL_ITEM

The OM attributes of a DSX_C_GDS_ACL_ITEM are as follows:

DSX_INTERPRETATION

This attribute specifies the scope of the access right. It can have one of the following values:

DSX_USER

This attribute contains the Distinguished Name of the user, or subtree of users, to whom an access right applies.

DSX_C_GDS_CONTEXT
An instance of OM class DSX_C_GDS_CONTEXT comprises per-operation arguments that are accepted by most of the interface functions. The GDS package supports additional service controls that are defined by the DSX_C_GDS_CONTEXT OM class.

An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_CONTEXT, in addition to the OM attributes listed in OM Attributes of DSX_C_GDS_CONTEXT .

    Value Value Value
OM Attribute Value Syntax Length Number Initially
Service Controls        
DSX_DUAFIRST OM_S_BOOLEAN - 1 OM_FALSE
DSX_DONT_STORE OM_S_BOOLEAN - 1 OM_TRUE
DSX_NORMAL_CLASS OM_S_BOOLEAN - 1 OM_FALSE
DSX_PRIV_CLASS OM_S_BOOLEAN - 1 OM_FALSE
DSX_RESIDENT_CLASS OM_S_BOOLEAN - 1 OM_FALSE
DSX_USEDSA OM_S_BOOLEAN - 1 OM_TRUE
DSX_DUA_CACHE OM_S_BOOLEAN - 1 OM_FALSE
DSX_PREFER_ADM_FUNCS OM_S_BOOLEAN - 1 OM_FALSE
DSX_SIGN_MECHANISM Enum(DSX_Sign_Mechanism) - 0-1     -
DSX_PROT_REQUEST Enum(DSX_Prot_Request) - 0-1     -

Table: OM Attributes of DSX_C_GDS_CONTEXT

The OM attributes of the DSX_C_GDS_CONTEXT OM class are as follows:

DSX_DUAFIRST

The value of this attribute defines whether the DUA cache or the DSA needs to be read first for query operations. The default value is OM_FALSE; that is, search the DSA first, if not found then search the DUA cache.

DSX_DONT_STORE

The value of this attribute specifies whether the information read from the DSAs by the query functions also needs to be stored in the DUA cache. When this service control is set to OM_TRUE (the default value), nothing is stored in the DUA cache.

When the value of this attribute is set to OM_FALSE, the information read is stored in the DUA cache, and the objects returned by ds_list () and ds_compare () are stored in the cache without their associated attribute information. The objects returned by ds_read () and ds_search () are stored in the cache with all their attributes that are capable of being stored in the cache; these are public attributes, except for the ACL attribute. This information is stored in the cache only when a list of requested attributes is supplied. If all attributes are requested, then nothing is stored in the cache.

The DUA cache categorises the information stored into three different memory classes. The user specifies the category with the following service control attributes:

DSX_NORMAL_CLASS

If this attribute is set to OM_TRUE, the entry in the DUA cache is assigned to the class of normal objects. When the number of entries in this class exceeds a maximum value, the entry that has not been addressed for the longest period of time is removed from the DUA cache.

DSX_PRIV_CLASS

If this attribute is set to OM_TRUE, the entry in the DUA cache is assigned to the class of privileged objects. Such entries can be removed from the class in the same way as normal objects. By using this memory sparingly, the user can protect entries from deletion.

DSX_RESIDENT_CLASS

If this attribute is set to OM_TRUE, the entry in the DUA cache is assigned to the class of resident objects. An entry in this memory class is never removed automatically; it can only be removed by a call to ds_remove_entry (). The number of entries is limited; if this limit is exceeded, ds_add_entry () reports an error.
Note:
Only one of the above service control attributes can be OM_TRUE at one time. Also, the ds_add_entry () function also evaluates these service control bits if it is used on the DUA cache.

DSX_DUA_CACHE and DSX_USEDSA

These attributes define whether the entries in the DUA cache or in the DSA, or both, need to be used when providing the service specified in the operation. Depending on the values of these attributes, the following situations can arise:

All other functions always operate on the currently connected DSA.

DSX_PREFER_ADM_FUNCS

The value of this attribute specifies whether the three following optional attributes are returned in an operation:

The DSX_A_MASTER_KNOWLEDGE and DSX_A_ACL attributes are present in every GDS entry.

When an application requests that all attributes be returned in an operation, it can prevent any of the above three optional attributes from being returned by setting the value of DSX_PREFER_ADM_FUNCS to OM_FALSE.

If GDS applications (for example, GDS administration) require these attributes, they are obtained by setting this service control to OM_TRUE.

DSX_SIGN_MECHANISM

This attribute is reserved for future use.

DSX_PROT_REQUEST

This attribute is reserved for future use.

Applications can assume that an object of OM class DSX_C_GDS_CONTEXT, created with default values for all its OM attributes, works with all interface functions. Note that an application can supply the constant DS_DEFAULT_CONTEXT as the context argument to GDS functions instead of creating a DSX_C_GDS_CONTEXT OM object with all default values.

The default form of DSX_C_GDS_CONTEXT is described in Default DSX_C_GDS_CONTEXT .

OM Attribute Default Value
Common Arguments
DS_OPERATION_PROGRESS DS_OPERATION_NOT_STARTED
DS_ALIASED_RDNS 0
Service Controls
DS_CHAINING_PROHIB OM_TRUE
DS_DONT_DEREFERENCE_ALIASES OM_FALSE
DS_DONT_USE_COPY OM_TRUE
DS_LOCAL_SCOPE OM_FALSE
DS_PREFER_CHAINING OM_FALSE
DS_PRIORITY DS_MEDIUM
Local Controls
DS_ASYNCHRONOUS OM_FALSE
DS_AUTOMATIC_CONTINUATION OM_TRUE
Private Extensions
DSX_DUAFIRST OM_FALSE
DSX_DONT_STORE OM_TRUE
DSX_NORMAL_CLASS OM_FALSE
DSX_PRIV_CLASS OM_FALSE
DSX_RESIDENT_CLASS OM_FALSE
DSX_USEDSA OM_TRUE
DSX_DUA_CACHE OM_FALSE
DSX_PREFER_ADM_FUNCS OM_FALSE
DSX_SIGN_MECHANISM Absent
DSX_PROT_REQUEST Absent

Table: Default DSX_C_GDS_CONTEXT

DSX_C_GDS_SESSION
An instance of OM class DSX_C_GDS_SESSION identifies and describes a particular link from an application program to a GDS DSA. This additional OM class is necessary if the user or application wants to do either or both of the following:

DSX_C_GDS_SESSION can be passed as an argument to ds_bind ().

An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_SESSION, in addition to the OM attributes listed in OM Attributes of DSX_C_GDS_SESSION .

    Value Value Value
OM Attribute Value Syntax Length Number Initially
DSX_PASSWORD String(OM_S_OCTET_STRING) - 0 or 1 -
DSX_DIR_ID OM_S_INTEGER - 1 1
DSX_AUTH_MECHANISM Enum(DSX_Auth_Mechanism) - 0-1 -
DSX_AUTH_INFO String(OM_S_OCTET_STRING) - 0-1 -

Table: OM Attributes of DSX_C_GDS_SESSION

The OM attributes of DSX_C_GDS_SESSION are as follows:

DSX_PASSWORD

The contents of this attribute consist of the password for the user credentials.

DSX_DIR_ID

The contents of this attribute are an identifier for distinguishing between several configurations of the directory service within a GDS installation. The valid range for this value is from 1 to 20.

DSX_AUTH_MECHANISM

This attribute, if present, identifies the authentication mechanism that the application requests. If it is absent or has the value DSX_NONE_AT_ALL, then a ds_bind() without credentials (anonymous bind) is requested. This attribute can take the following values:

If an authentication mechanism is selected that is not currently supported, ds_bind() returns a [DS_E_NOT_SUPPORTED] error. If the selected authentication mechanism requires the user's credentials that cannot be assembled, then a [DS_E_NO_INFO] error is returned.

DSX_AUTH_INFO

This attribute is reserved for future use.

Applications can assume that an object of OM class DSX_C_GDS_SESSION, created with default values for all its OM attributes, works with all interface functions. Note that an application can supply the constant DS_DEFAULT_SESSION as the session argument to ds_bind () to create a default session (instead of creating a DSX_C_GDS_SESSION OM object with all the default values), having already negotiated the GDS package.

Default DSX_C_GDS_SESSION describes DS_DEFAULT_SESSION.

OM Attribute Default Value
DS_DSA_ADDRESS Value obtained from the cache or absent
DS_DSA_NAME Value obtained from the cache or absent
DS_FILE_DESCRIPTOR DS_NO_VALID_FILE_DESCRIPTOR
DSX_DIR_ID 1
DSX_AUTH_MECHANISM Absent
DSX_AUTH_INFO Absent

Table: Default DSX_C_GDS_SESSION

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