When referring to classes and attributes in the Directory Service, the chapters in Parts 3 and 4 make a clear distinction between OM classes and directory classes, and between OM attributes and directory attributes. In both cases, the former is a construct of the closely associated Object Management interface, while the latter is a construct of the Directory Service to which XDS provides access. The terms object class and attribute indicate the directory constructs, while the phrases OM class and OM attribute indicate the Object Management constructs.
\\x2B\\xC\\x2\\x87\\x73\\x1C\\x0This object identifier is represented by the constant DS_SERVICE_PKG.
The Object Management notation is briefly described in the following text. See Chapters 17 through 19 for more information on Object Management.
Each OM class is described in a separate section, which identifies the OM attributes specific to that OM class. The OM classes and OM attributes for each OM class are listed in alphabetical order. The OM attributes that can be found in an instance of an OM class are those OM attributes specific to that OM class, as well as those inherited from each of its superclasses. The OM class-specific OM attributes are defined in a table. The table indicates the name of each OM attribute, the syntax of each of its values, any restrictions upon the length (in bits, octets (bytes), or characters) of each value, any restrictions upon the number of values, and the value, if any, om_create() supplies.
The constants that represent the OM classes and OM attributes in the C binding are defined in the xds.h(4xds) header file.
Errors are reported to the application program by means of DS_status, which is a result of every function (it is the function result in the C language binding for most functions). A function that completes successfully returns the value DS_SUCCESS, whereas one that is not successful returns an error. The error is a private object containing details of the problem that occurred. The error constant DS_NO_WORKSPACE can be returned by all Directory Service functions, except ds_initialize(). DS_NO_WORKSPACE is returned if ds_initialize() is not invoked before calling any other Directory Service function.
Errors are classified into ten OM classes. The standards (see The Directory: Abstract Service Definition , ISO 9594-3, CCITT X.511) classify errors into eight different groups, as follows:
The Directory Service interface never returns an Abandoned error. The interface also defines three more kinds of errors: DS_C_LIBRARY_ERROR, DS_C_COMMUNICATIONS_ERROR, and DS_C_SYSTEM_ERROR. Each of these kinds of errors is represented by an OM class. These OM classes are detailed in subsequent sections of this chapter. All of them inherit the OM attribute DS_PROBLEM from their superclass DS_C_ERROR, which is described in this Chapter. The values DS_PROBLEM can take are listed in the relevent subsections of this Chapter. For a description of these errors please refer to the OSF DCE Problem Determination Guide. The error OM classes defined in this chapter are part of the Directory Service Package.
The ds_bind() operation returns a Security Error or a Service Error. All other operations can also return the same errors as ds_bind(). Such errors can arise in the course of following an automatic referral list.
DS_C_REFERRAL is not a real error, and it is not a subclass of DS_C_ERROR, although it is reported in the same way as a DS_status result. A DS_C_ATTRIBUTE_ERROR, also not a subclass of DS_C_ERROR, is special because it can report several problems at once. Each one is reported in DS_C_ATTRIBUTE_PROBLEM, which is a subclass of DS_C_ERROR.
OM_C_OBJECT
None of the classes in the preceding list are encodable using om_encode and om_decode. The application is not permitted to create or modify instances of some OM classes because these OM classes are only returned by the interface and never supplied to it. These OM classes are as follows:
DS_C_ACCESS POINT DS_C_ATTRIBUTE_ERROR DS_C_COMPARE_RESULT DS_C_CONTINUATION_REF All subclasses of DS_C_ERROR DS_C_LIST_INFO DS_C_LIST_INFO_ITEM DS_C_LIST_RESULT DS_C_OPERATION_PROGRESS DS_C_PARTIAL_OUTCOME_QUAL DS_C_READ_RESULT DS_C_REFERRAL DS_C_SEARCH_INFO DS_C_SEARCH_RESULT
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ERROR, and no additional OM attributes.
The OM attribute DS_PROBLEM, which is inherited from the superclass DS_C_ERROR, identifies the problem. Its value is one of the following:
A ds_abandon XDS call always returns a DS_E_TOO_LATE error for the DS_C_ABANDON_FAILED OM class. Refer to Chapter 10 for information on abandoning directory operations.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-1.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_ADDRESS | Object(DS_C_ADDRESS | -- | 1 | -- |
| DS_AE_TITLE | Object(DS_C_NAME | -- | 1 | -- |
This attribute indicates the address of the DSA to be used when communicating with it.
This attribute indicates the name of the DSA.
It is an abstract class that has the OM attributes of its superclass, OM_C_OBJECT, and no other OM attributes.
An address is an unambiguous name, label, or number that identifies the location of the entity or service. All addresses are represented as instances of some subclass of this OM class.
The only subclass defined by the DCE XDS API is DS_C_PRESENTATION_ADDRESS, which is the presentation address of an OSI application entity used for OSI communications with this subclass.
An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-2.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_ATTRIBUTE_TYPE | String(OM_S_OBJECT_IDENTIFIER_STRING) | -- | 1 | -- |
| DS_ATTRIBUTE_VALUES | Any | -- | 0 or more | -- |
The attribute type that indicates the class of information given by this attribute.
The attribute values. The OM value syntax and the number of values allowed for this OM attribute are determined by the value of the DS_ATTRIBUTE_TYPE OM attribute in accordance with the rules given in Section 10.6.1.
If the values of this OM attribute have the syntax String(*), the strings can be long and segmented. For this reason, om_read() and om_write() need to be used to access all String(*) values.
Note: A directory attribute must always have at least one value, although it is acceptable for instances of this OM class not to have any values.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-3.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_OBJECT_NAME | Object(DS_C_NAME) | -- | 1 | -- |
| DS_PROBLEMS | Object(DS_C_ATTRIBUTE_PROBLEM | -- | 1 or more | -- |
This attribute contains the name of the directory entry to which the operation is applied when the failure occurs.
This attribute documents the attribute-related problems encountered. Uniquely, a DS_C_ATTRIBUTE_ERROR can report several problems at once. All problems are related to the preceding object.
An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attribute listed in Table 11-4.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially | Object(DS_C_ATTRIBUTE) | -- | 0 or more | -- |
|---|
The attributes that constitute a new object's directory entry, or those selected from an existing entry.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ERROR, in addition to the OM attributes listed in Table 11-5.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_ATTRIBUTE_TYPE | String(OM_S_OBJECT_IDENTIFIER_STRING | -- | 1 | -- |
| DS_ATTRIBUTE_VALUE | Any | -- | 0 or 1 | -- |
This attribute identifies the type of attribute with which the problem is associated.
This attribute specifies the attribute value with which the problem is associated. Its syntax is determined by the value of DS_ATTRIBUTE_TYPE. This OM attribute is present if it is necessary to avoid ambiguity.
The OM attribute DS_PROBLEM, which is inherited from the superclass DS_C_ERROR, identifies the problem. Its value is one of the following:
An instance of this OM class has the OM attributes of its superclasses,
OM_C_OBJECT and DS_C ATTRIBUTE,
and no other OM attributes.
An additional restriction on this OM class is
that there must be exactly one value of the OM attribute
DS_ATTRIBUTE_VALUES.
The
DS_ATTRIBUTE_TYPE
remains single valued.
The OM value syntax of
DS_ATTRIBUTE_VALUES
must conform to the rules outlined in Section 10.6.1.
11.12. DS_C_COMMON_RESULTS
It is an abstract OM class, which has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-6.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_ALIAS_DEREFERENCED | OM_S_BOOLEAN | -- | 1 | -- | Object(DS_C_NAME) | -- | 0 or 1 | -- |
This attribute indicates whether the name of the target object that is passed as a function argument includes an alias that is dereferenced to determine the DN.
When present, this attribute gives the DN of the performer of a particular operation. It can be present when the result is signed, and it holds the name of the DSA that signed the result. The DCE Directory Service does not support the optional feature of signed results; therefore, this OM attribute is never present.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ERROR, and no additional OM attributes.
Communications errors include those arising in remote operation, association control, presentation, session, and transport.
The OM attribute DS_PROBLEM, which is inherited from the superclass DS_C_ERROR, identifies the problem. Its value is DS_E_COMMUNICATIONS_PROBLEM.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_COMMON_RESULTS, in addition to the OM attributes listed in Table 11-7.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_FROM_ENTRY | OM_S_BOOLEAN | -- | 1 | -- |
| DS_MATCHED | OM_S_BOOLEAN | -- | 1 | -- |
| DS_OBJECT_NAME | Object(DS_C_NAME) | -- | 0 or 1 | -- |
This attribute indicates whether the assertion is tested against the specified object's entry, rather than a copy of the entry.
This attribute indicates whether the assertion specified as an argument returns the value OM_TRUE. It takes the value OM_TRUE if the values are compared and matched; otherwise, it takes the value OM_FALSE.
This attribute contains the DN of the target object of the operation. It is present if the OM attribute DS_ALIAS_DEREFERENCED, inherited from the superclass DS_C_COMMON_RESULTS, is OM_TRUE.
An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-8.
| 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 Section 10.9. 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:
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.
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 .na DS_OPERATION_NOT_STARTED described in the DS_C_OPERATION_PROGRESS OM class definition. .ad
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.
This attribute indicates that chaining and other methods of distributing the request around the Directory Service are prohibited.
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).
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.
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.
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.
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:
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_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.
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.
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.
The interface currently only operates synchronously (within the same thread) as detailed in Section 10.8. There is only one possible value:
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:
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.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-9.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_ACCESS_POINTS | Object(DS_C_ACCESS_POINT) | -- | 1 or more | -- |
| DS_ALIASED_RDNS | OM_S_INTEGER | -- | 1 | -- |
| DS_OPERATION_PROGRESS | Object(DS_C_OPERATION_PROGRESS) | -- | 1 | -- |
| DS_RDNS_RESOLVED | OM_S_INTEGER | -- | 0 or 1 | -- |
| DS_TARGET_OBJECT | Object(DS_C_NAME) | -- | 1 | -- |
This attribute indicates the names and presentation addresses of the DSAs from where the directory request is continued.
This attribute indicates how many (if any) of the RDNs in the target name are produced by dereferencing an alias. Its value is 0 (zero) if no aliases are dereferenced. This value needs to be used in the DS_C_CONTEXT of any continued operation.
This attribute indicates the state at which the directory request must be continued. This value needs to be used in the DS_C_CONTEXT of any continued operation.
This attribute indicates the number of RDNs in the supplied object name that are resolved (using internal references), and not just assumed to be correct (using cross-references).
This attribute indicates the name of the object upon which the continuation must focus.
An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_NAME, in addition to the OM attribute listed in Table 11-10.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_RDNS | Object(DS_C_DS_RDN) | -- | 0 or more | -- |
This attribute indicates the sequence of RDNs that define the path through the DIT from its root to the object that the DS_C_DS_DN indicates. The DS_C_DS_DN of the root of the directory is the null name (no DS_RDNS values). The order of the values is significant; the first value is closest to the root, and the last value is the RDN of the object.
An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_RELATIVE_NAME, in addition to the OM attribute listed in Table 11-11.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_AVAS | Object(DS_C_AVA) | -- | 1 or more | -- |
This attribute indicates the DS_AVAS that are marked by the DIB as components of the object's RDN. The assertion is TRUE of the object but not of any of its siblings, and the attribute type and value are displayed in the object's directory entry. The order of the DS_AVAS is not significant.
An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ATTRIBUTE_LIST, in addition to the OM attributes listed in Table 11-12.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_FROM_ENTRY | OM_S_BOOLEAN | -- | 1 | -- |
| DS_OBJECT_NAME | Object(DS_C_NAME) | -- | 1 | -- |
The OM attribute DS_ATTRIBUTES is inherited from the superclass DS_C_ATTRIBUTE_LIST. It contains the information extracted from the directory entry of the target object. The type of each attribute requested and located is indicated in the list as are its values, if types and values are requested.
The OM class-specific OM attributes are as follows:
This attribute indicates whether the information is extracted from the specified object's entry, rather than from a copy of the entry.
This attribute contains the object's DN.
An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-13.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_ALL_ATTRIBUTES | OM_S_BOOLEAN | -- | 1 | OM_TRUE |
| DS_ATTRIBUTES_SELECTED | String(OM_S_OBJECT_IDENTIFIER_STRING) | -- | 0 or more | -- |
| DS_INFO_TYPE | Enum(DS_Information_Type | -- | 1 | DS_TYPES_AND_VALUES |
This attribute indicates which attributes are relevant. It can take one of the following values:
This attribute lists the types of attributes in the entry from which information will be extracted. The value of this OM attribute is used only if the value of DS_ALL_ATTRIBUTES is OM_FALSE. If an empty list is supplied, no attribute data is returned that could be used to verify the existence of an entry for a DN.
This attribute identifies what information will be extracted from each attribute identified. It must take one of the following values:
An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ATTRIBUTE, in addition to the OM attribute listed in Table 11-14.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_MOD_TYPE | Enum(DS_Modification_Type) | -- | 1 | DS_ADD_ATTRIBUTE |
The attribute type to be modified, and the associated values, are specified in the OM attributes DS_ATTRIBUTE_TYPE and DS_ATTRIBUTE_VALUES that are inherited from the DS_C_ATTRIBUTE superclass.
This attribute identifies the type of modification. It must have one of the following values:
An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attribute listed in Table 11-15.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_CHANGES | Object(DS_C_ENTRY_MOD) | -- | 1 or more | -- |
This attribute identifies the modifications to be made (in the order specified) to the directory entry of the specified object.
It is an abstract OM class with the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attribute listed in Table 11-16.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_PROBLEM | Enum(DS_Problem) | -- | 1 | -- |
Details of errors are returned in an instance of a subclass of this OM class. Each such subclass represents a particular kind of error, and is one of the following:
A number of possible values are defined for these subclasses. DCE XDS does not return other values for error conditions described in this chapter. Information on system errors can be found in Section 11.44. The following is a list of the error values. Each error OM class section defines the possible error values associated with that class. For a description of the errors please refer to the OSF DCE Problem Determination Guide.
An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-17.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_CRIT | OM_S_BOOLEAN | -- | 1 | OM_FALSE |
| DS_IDENT | OM_S_INTEGER | -- | 1 | -- |
| DS_ITEM_PARAMETERS | Any | -- | 1 | -- |
This attribute must have one of the following values:
This attribute identifies the service extension.
This OM attribute supplies the parameters of the extension. Its syntax is determined by the value of DS_IDENT.
An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-18.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_FILTER_ITEMS | Object(DS_C_FILTER_ITEM) | -- | 0 or more | -- |
| DS_FILTERS | Object(DS_C_FILTER)T} | -- | 0 or more | -- |
| DS_FILTER_TYPE | Enum(DS_Filter_Type) | -- | 1 | DS_AND |
A filter is a collection of less elaborate filters and elementary DS_FILTER_ITEMS, together with a Boolean operation. The filter value is undefined if, and only if, all the component DS_FILTERS and DS_FILTER_ITEMS are undefined. Otherwise, the filter has a Boolean value with respect to any directory entry, which can be determined by evaluating each of the nested components and combining their values using the Boolean operation. The components whose values are undefined are ignored.
This attribute is a collection of assertions, each relating to just one attribute of a directory entry.
This attribute is a collection of simpler filters.
This attribute is the filter's type. It can have any of the following values:
An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ATTRIBUTE, in addition to the OM attributes listed in Table 11-19.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_FILTER_ITEM_TYPE | Enum(DS_Filter_Item_Type) | -- | 1 | -- |
| DS_FINAL_SUBSTRING | String(*) | 1 or more | 0 or 1 | -- |
| DS_INITIAL_SUBSTRING | String(*) | 1 or more | 0 or 1 | -- |
Note: OM attributes DS_ATTRIBUTE_TYPE and DS_ATTRIBUTE_VALUES are inherited from the superclass DS_C_ATTRIBUTE.
The value of the filter item is undefined in the following cases:
Access control restrictions can also cause the value to be undefined.
This attribute identifies the type of filter item and, thus, the nature of the filter. The filter item can adopt any of the following values:
Rules for approximate matching are defined locally. For example, an approximate match may take into account spelling variations or employ phonetic comparison rules. In the absence of any such capabilities, a DSA needs to treat an approximate match as a test for equality. DCE GDS supports phonetic comparisons. There must be exactly one value of the OM attribute DS_ATTRIBUTE_VALUES.
Any values of the OM attribute DS_ATTRIBUTE_VALUES are ignored.
Any number of substrings can be given as values of the OM attribute DS_ATTRIBUTE_VALUES. Similarly, no substrings can be specified. There can also be a substring in DS_INITIAL_SUBSTRING or DS_FINAL_SUBSTRING, or both. The substrings do not overlap, but they can be separated from each other or from the ends of the attribute value by zero or more string elements. However, at least one attribute of type DS_ATTRIBUTE_VALUES, DS_INITIAL_SUBSTRING, or DS_FINAL_SUBSTRING must exist.
If present, this attribute is the substring that will match the final part of an attribute value in the entry. This attribute can only exist if the DS_FILTER_ITEM_TYPE is equal to DS_SUBSTRINGS.
If present, this attribute is the substring that will match the initial part of an attribute value in the entry.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ERROR, and no additional OM attributes.
Each function has several possible errors that can be detected by the library itself and that are returned directly by the subroutine. These errors occur when the library itself is incapable of performing an action, submitting a service request, or deciphering a response from the Directory Service.
The OM attribute DS_PROBLEM, which is inherited from the superclass DS_C_ERROR, identifies the particular library error that occurred. (In reference pages, the ERRORS section of each function description lists the errors that the respective function can return.) Its value is one of the following:
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_COMMON_RESULTS, in addition to the OM attributes listed in Table 11-20.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_OBJECT_NAME | Object(DS_C_NAME) | -- | 0 or 1 | -- |
| DS_PARTIAL_OUTCOME_QUAL | Object(DS_C_PARTIAL_OUTCOME_QUAL) | -- | 0 or 1 | -- |
| DS_SUBORDINATES | Object(DS_C_LIST_INFO_ITEM) | -- | 0 or more | -- |
This attribute is the DN of the target object of the operation. It is present if the OM attribute DS_ALIAS_DEREFERENCED, inherited from the superclass DS_C_COMMON_RESULTS, is OM_TRUE.
This OM attribute value is present if the list of subordinates is incomplete. The DSA or DSAs that provided this list did not complete the search for some reason. The partial outcome qualifier contains details of why the search is not completed, and which areas of the directory have not been searched.
This attribute contains information about zero or more subordinate objects identified by ds_list().
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-21.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_ALIAS_ENTRY | OM_S_BOOLEAN | -- | 1 | -- |
| DS_FROM_ENTRY | OM_S_BOOLEAN | -- | 1 | -- |
| DS_RDN | Object(DS_C_RELATIVE_NAME) | -- | 1 | -- |
This attribute indicates whether the object is an alias.
This attribute indicates whether information about the object was obtained directly from its directory entry, rather than from a copy of the entry.
This attribute contains the RDN of the object. If this is the name of an alias entry, as indicated by DS_ALIAS_ENTRY, it is not dereferenced.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-22.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_LIST_INFO | Object(DS_C_LIST_INFO) | -- | 0 or 1 | -- |
| DS_UNCORRELATED_LIST_INFO | Object(DS_C_LIST_RESULT) | -- | 0 or more | -- |
Note: No instance contains values of both OM attributes.
This attribute contains the full results of ds_list(), or just part of them.
When the DUA requests a protection request of ``signed,'' the information returned can comprise a number of sets of results originating from, and signed by, different components of the directory. Implementations can reflect this structure by nesting DS_LIST_RESULT OM objects as values of this OM attribute. Alternatively, they can collapse all results into a single value of the OM attribute DS_LIST_INFO. The DCE Directory Service does not support the optional feature of signed results; therefore, this OM attribute is never present.
It is an abstract class, which has the attributes of its superclass, OM_C_OBJECT, and no other OM attributes.
A name uniquely distinguishes the object from all other objects whose entries are displayed in the DIT. However, an object can have more than one name; that is, a name need not be unique. A DN is unique; there are no other DNs that identify the same object. An RDN is part of a name and only distinguishes the object from others that are its siblings.
Most of the interface functions take a name parameter, the value of which must be an instance of one of the subclasses of this OM class. Thus, this OM class is useful for amalgamating all possible representations of names.
The DCE XDS implementation defines one subclass of this OM class and, thus, a single representation for names; that is, DS_C_DS_DN, which provides a representation for names, including DNs.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ERROR, in addition to the OM attribute listed in Table 11-23.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_MATCHED | Object(DS_C_NAME) | -- | 1 | -- |
This attribute identifies the initial part (up to, but excluding, the first RDN that is unrecognized) of the name that is supplied, or of the name resulting from dereferencing an alias. It names the lowest entry (object or alias) in the DIT that is matched.
The OM attribute DS_PROBLEM, which is inherited from the superclass DS_C_ERROR, identifies the cause of the failure. Its value is one of the following:
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-24.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_NAME_RESOLUTION_PHASE | Enum(DS_Name_Resolution_Phase) | -- | 1 | -- |
| DS_NEXT_RDN_TO_BE_RESOLVED | OM_S_INTEGER | -- | 0 or 1 | -- |
The target name mentioned as follows is the name upon which processing of the directory request is currently focused.
This attribute indicates what phase is reached in handling the target name. It must have one of the following values:
This attribute indicates to the DSA which of the RDNs in the target name is next to be resolved. It takes the form of an integer in the range from 1 to the number of RDNs in the name. This OM attribute only has a value if the value of DS_NAME_RESOLUTION_PHASE is DS_PROCEEDING.
The constant DS_OPERATION_NOT_STARTED can be used in the DS_C_CONTEXT of an operation instead of an instance of this OM class.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-25.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_LIMIT_PROBLEM | Enum(DS_Limit_Problem) | -- | 1 | -- |
| DS_UNAVAILABLE_CRIT_EXT | OM_S_BOOLEAN | -- | 1 | -- |
| DS_UNEXPLORED | Object(DS_C_CONTINUATION_REF) | -- | 0 or more | -- |
This attribute explains fully or partly why the results are incomplete. It can have one of the following values:
If OM_TRUE, this attribute indicates that some part of the Directory Service cannot provide a requested critical service extension. The user requested one or more standard service extensions by including values of the OM attribute DS_EXT in the DS_C_CONTEXT supplied for the operation. Furthermore, the user indicated that some of these extensions are essential by setting the OM attribute DS_CRIT in the extension to OM_TRUE. Some of the critical extensions cannot be performed by one particular DSA or by a number of DSAs. In general, it is not possible to determine which DSA could not perform which particular extension.
This attribute identifies any regions of the directory that are left unexplored in such a way that the directory request can be continued. Only continuation references within the scope specified by the DS_SCOPE_OF_REFERRAL service control are included.
An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ADDRESS, in addition to the OM attributes listed in Table 11-26.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_N_ADDRESSES | String(OM_S_OCTET_STRING) | -- | 1 or more | -- |
| DS_P_SELECTOR | String(OM_S_OCTET_STRING | -- | 0 or 1 | -- |
| DS_S_SELECTOR | String(OM_S_OCTET_STRING) | -- | 0 or 1 | -- |
| DS_T_SELECTOR | String(OM_S_OCTET_STRING) | -- | 0 or 1 | -- |
This attribute is the network addresses of the application entity.
This attribute is the presentation selector.
This attribute is the session selector.
This attribute is the transport selector.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_ENTRY | Object(DS_C_ENTRY_INFO) | -- | 1 | -- |
This attribute contains the information extracted from the directory entry of the target object.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_CONTINUATION_REF, and no additional OM attributes.
The referral is a continuation reference by means of which the operation can progress.
An RDN is part of a name, and only distinguishes the object from others that are its siblings. This OM class is used to accumulate all possible representations of RDNs. An argument of interface functions that is an RDN, or an OM attribute value that is an RDN is an instance of one of the subclasses of this OM class.
The DCE XDS API defines one subclass of this OM class, and, thus, a single representation for RDNs; that is, DS_C_DS_RDN, which provides a representation for RDNs.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_COMMON_RESULTS, in addition to the OM attributes listed in Table 11-28.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_ENTRIES | Object(DS_C_ENTRY_INFO) | -- | 0 or more | -- |
| DS_OBJECT_NAME | Object(DS_C_NAME) | -- | 0 or 1 | -- |
| DS_PARTIAL_OUTCOME_QUAL | Object(DS_C_PARTIAL_OUTCOME_QUAL) | -- | 0 or 1 | -- |
This attribute contains information about zero or more objects found by ds_search() that matched the given selection criteria.
This attribute contains the DN of the target object of the operation. It is present if the OM attribute DS_ALIAS_DEREFERENCED, inherited from the superclass DS_C_COMMON_RESULTS, is OM_TRUE.
This OM attribute value is only present if the list of entries is incomplete. The DSA or DSAs that provided this list did not complete the search for some reason. The partial outcome qualifier contains details of why the search was not completed and which areas of the directory were not searched.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-29.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_SEARCH_INFO | Object(DS_C_SEARCH_INFO) | -- | 0 or 1 | -- |
| DS_UNCORRELATED_SEARCH_INFO | Object(DS_C_SEARCH_RESULT) | -- | 0 or more | -- |
Note: No instance contains values of both OM attributes.
This attribute contains the full result of ds_search(), or part of the result.
When the DUA requests a protection request of ``signed,'' the information returned can comprise a number of sets of results originating from and signed by different components of the Directory Service. Implementations can reflect this structure by nesting DS_C_SEARCH_RESULT OM objects as values of this OM attribute. Alternatively, they can collapse all results into a single value of the OM attribute DS_SEARCH_INFO. The DCE Directory Service does not support the optional feature of signed results; therefore, this OM attribute is never present.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ERROR, and no additional OM attributes.
The OM attribute DS_PROBLEM, which is inherited from the superclass DS_C_ERROR, identifies the cause of this failure. Its value is one of the following:
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ERROR, and no additional OM attributes.
The OM attribute DS_PROBLEM, which is inherited from the superclass DS_C_ERROR, identifies the cause of the failure. Its value is one of the following:
An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 11-30.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_DSA_ADDRESS | Object(DS_C_ADDRESS) | -- | 0 or 1 | local1 |
| DS_DSA_NAME | Object(DS_C_NAME) | -- | 0 or 1 | local1 |
| DS_FILE_ DESCRIPTOR | OM_S_INTEGER | -- | 1 | See the text |
| DS_REQUESTOR | Object(DS_C_NAME) | -- | 0 or 1 | -- |
- 1
- set to the address and name of the default DSA entry in the local cache. If this cache entry is not present, then these OM attributes are absent.
The DS_C_SESSION gathers all the information that describes a particular directory interaction. The parameters that will control such a session are set up in an instance of this OM class, which is then passed as an argument to ds_bind(). This sets the OM attributes that describe the actual characteristics of this session, and then starts the session. A session started in this way must pass as the first argument to each interface function. The result of modifying an initiated session is unspecified. Finally, ds_unbind() is used to terminate the session, after which the parameters can be modified and a new session started using the same instance, if required. Multiple concurrent sessions can run using multiple instances of this OM class.
The OM attributes of a session are as follows:
This attribute indicates the address of the default DSA named by DS_DSA_NAME.
This attribute indicates the DN of the DSA that is used by default to service directory requests.
This OM attribute is not used by DCE XDS and is always set to DS_NO_VALID_FILE_DESCRIPTOR.
This attribute is the DN of the user of this Directory Service session.
Applications can assume that an object of OM class DS_C_SESSION, created with default values of all its OM attributes, works with all the interface functions. Local administrators need to ensure that this is the case. Such a session can be created by passing the constant DS_DEFAULT_SESSION as an argument to ds_bind().
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ERROR, and no additional OM attributes, although there can be additional implementation-defined OM attributes.
The OM attribute DS_PROBLEM, which is inherited from the superclass DS_C_ERROR, identifies the cause of the failure. Its value is the same as that of errno defined in the C language.
The standard names of system errors are defined in Volume 2 of the X/Open Portability Guide.
If such an error persists, a DS_C_LIBRARY_ERROR (DS_E_MISCELLANEOUS) is reported.
An application is not permitted to create or modify instances of this OM class. An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_ERROR, and no additional OM attributes.
The OM attribute DS_PROBLEM, which is inherited from the superclass DS_C_ERROR, identifies the cause of the failure. Its value is one of the following: