DS_C_CONTEXT

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

OM Attributes of DS_C_CONTEXT

OM Attribute

Value Syntax

Value Length

Value Number

Value Initially

Common Arguments

DS_EXT	Object(DS_C_ EXT	-	0 or more	-
DS_OPERATION_ PROGRESS	Object(DS_C_ OPERATION_ PROGRESS	-	1	DS_ OPERATION_ NOT_STARTED
DS_ALIASED_ RDNS	OM_S_ INTEGER	-	0 or 1	0

Service Controls

DS_CHAINING_ PROHIB	OM_S_ BOOLEAN	-	1	OM_TRUE
DS_DONT_ DEREFERENCE_ ALIASES	OM_S_ BOOLEAN	-	1	OM_FALSE
DS_DONT_ USE_COPY	OM_S_ BOOLEAN	-	1	OM_TRUE
DS_LOCAL_ SCOPE	OM_S_ BOOLEAN	-	1	OM_FALSE
DS_PREFER_ CHAINING	OM_S_ BOOLEAN	-	1	OM_FALSE
DS_PRIORITY	Enum(DS_ Priority)	-	1	DS_MEDIUM
DS_SCOPE_ OF_REFERRAL	Enum(DS_ Scope_ of_Referral)	-	0 or 1	-
DS_SIZE_ LIMIT	OM_S_ INTEGER	-	0 or 1	-
DS_TIME_ LIMIT	OM_S_ INTEGER	-	0 or 1	-

Local Controls

DS_ ASYNCHRONOUS	OM_S_ BOOLEAN	-	1	OM_FALSE
DS_AUTOMATIC_ CONTINUATION	OM_S_ BOOLEAN	-	1	OM_TRUE

The context gathers several arguments passed to interface functions, which are presumed to be relatively static for a given directory user during a particular directory interaction. The context is passed as an argument to each function that interrogates or updates the directory. Although it is generally assumed that the context is changed infrequently, the value of each argument can be changed between every operation if required. The DS_ASYNCHRONOUS argument must not be changed. Each argument is represented by one of the OM attributes of the DS_C_CONTEXT OM class.

The context contains the common arguments defined in the standards (see The Directory: Abstract Service Definition, ISO 9594-3, CCITT X.511), except that all security information is omitted for reasons discussed in XDS Interface Description. These are made up of a number of service controls explained in the following text, possible extensions in the DS_EXT OM attribute, and operation progress and alias dereferencing information in the DS_OPERATION_PROGRESS OM attribute. It also contains a number of arguments that provide local control over the interface.

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

· Common Arguments

- DS_EXT

This attribute represents any future standardized extensions that need to be applied to the directory service operation. The DCE XDS implementation does not evaluate this optional OM attribute.

- DS_OPERATION_PROGRESS

This attribute represents the state that the directory service assumes at the start of the operation. This OM attribute normally takes its default value, which is the value DS_OPERATION_NOT_STARTED described in the DS_C_OPERATION_PROGRESS OM class definition.

- DS_ALIASED_RDNS

This attribute indicates to the directory service that the object component of the operation parameter is created by dereferencing of an alias on an earlier operation attempt. This value is set in the referral response of the previous operation.

· Service Controls

- DS_CHAINING_PROHIB

This attribute indicates that chaining and other methods of distributing the request around the directory service are prohibited.

- DS_DONT_DEREFERENCE_ALIASES

This attribute indicates that any alias used to identify the target entry of an operation is not dereferenced. This allows interrogation of alias entries (aliases are never dereferenced during updates).

- DS_DONT_USE_COPY

This attribute indicates that the request can only be satisfied by accessing directory entries, and not by using copies of entries. This includes both copies maintained in other DSAs by bilateral agreement, and, copies cached locally.

- DS_LOCAL_SCOPE

This attribute indicates that the directory request will be satisfied locally. The meaning of this option is configured by an administrator. This option typically restricts the request to a single DSA or DMD.

- DS_PREFER_CHAINING

This attribute indicates that chaining is preferred to referrals when necessary. The directory service is not obliged to follow this preference, and can return a referral even if it is set.

- DS_PRIORITY

This attribute indicates the priority, relative to other directory requests, according to which the directory service attempts to satisfy the request. This is not a guaranteed service since there is no queuing throughout the directory. Its value must be one of the following:

- DS_LOW

- DS_MEDIUM

- DS_HIGH

- DS_SCOPE_OF_REFERRAL

This attribute indicates the part of the directory to which referrals are limited. This includes referral errors and partial outcome qualifiers. Its value must be one of the following:

- DS_COUNTRY, meaning DSAs within the country in which the request originates.

- DS_DMD, meaning DSAs within the DMD in which the request originates.

DS_SCOPE_OF_REFERRAL is an optional attribute. The lack of this attribute in a DS_C_CONTEXT object indicates that the scope is not limited.

- DS_SIZE_LIMIT

If present, this attribute indicates the maximum number of objects about which ds_list( ) or ds_search( ) needs to return information. If this limit is exceeded, information is returned about exactly this number of objects. The objects that are chosen are not specified because this can depend on the timing of interactions between DSAs, among other reasons.

- DS_TIME_LIMIT

If present, this attribute indicates the maximum elapsed time, in seconds, within which the service needs to be provided (not the processing time devoted to the request). If this limit is reached, a service error (DS_E_TIME_LIMIT_EXCEEDED) is returned, except for the ds_list( ) or ds_search( ) operations, which return an arbitrary selection of the accumulated results.

· Local Controls

- DS_ASYNCHRONOUS (Optional Functionality)
The interface currently operates synchronously (within the same thread) only, as detailed in XDS Interface Description . There is only one possible value, as follows:

- OM_FALSE, meaning that the operation is performed sequentially (synchronously) with the application being blocked until a result or error is returned.

- DS_AUTOMATIC_CONTINUATION

This attribute indicates the requestor's requirement for continuation reference handling, including referrals and those in partial outcome qualifiers. The value is one of the following:

- OM_FALSE, meaning that the interface returns all continuation references to the application program.

- OM_TRUE, meaning that continuation references are automatically processed, and the subsequent results are returned to the application instead of the continuation references, whenever practical. This is a much simpler option than OM_FALSE unless the application has special requirements.

Note: Continuation references can still be returned to the application if, for example, the relevant DSA cannot be contacted.

Applications can assume that an object of OM class DS_C_CONTEXT, created with default values of all its OM attributes, works with all the interface functions. The DS_DEFAULT_CONTEXT constant can be used as an argument to interface functions instead of creating an OM object with default values.