An instance of OM class DSX_C_GDS_CONTEXT comprises per-operation arguments that are accepted by most of the interface functions. GDS 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 the following table.
OM Attributes of DSX_C_GDS_CONTEXT
OM Attribute |
Value Syntax |
Value Length | Value Number | Value 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 DSX_SIGN_ MECHANISM |
OM_S_ BOOLEAN Enum(DSX_Sign_ Mechanism) |
- - |
1 01 |
OM_FALSE - |
DSX_PROT_ REQUEST |
Enum(DSX_Prot_ Request) |
- | 01 | - |
· DSX_DUAFIRST
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
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 (default value), nothing is stored in the DUA cache.
When this service control is set to OM_FALSE, the information read is stored in the DUA cache. 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 cacheable attributes; these are all public attributes that do not exceed 4Kbytes in length.
This information is only cached when a list of requested attributes is supplied. If all attributes are requested, then nothing is stored in the cache.
The DUA cache categorizes the information stored into three different memory classes. The user specifies the category with the following service controls:
· 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. If the number of entries in this class exceeds a maximum value, the entry that is not 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. 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; instead, it can only be removed with ds_remove_entry( ). The number of entries is limited; if this limit is exceeded, ds_add_entry( ) reports an error.
Only the service control of one memory class can be set. The ds_add_entry( ) function also evaluates these service control bits if the function 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. Depending on the values of these attributes, the following situations can arise:
- DSX_DUA_CACHE and DSX_USEDSA, both OM_TRUE
The ds_add_entry( ) and ds_remove_entry( ) functions report an error.
The query functions evaluate the service controls DS_DONT_USE_COPY and DSX_DUAFIRST. When DS_DONT_USE_COPY is OM_FALSE, then DSX_DUAFIRST determines whether the DUA cache or the DSA is read first. When DS_DONT_USE_COPY is OM_TRUE, information from the DSA only is read.
- DSX_DUA_CACHE, OM_TRUE and DSX_USEDSA, OM_FALSE
The ds_add_entry( ) and ds_remove_entry( ) functions and the query functions
only go to the DUA cache.
- DSX_DUA_CACHE, OM_FALSE and DSX_USEDSA, OM_TRUE
The ds_add_entry( ) and ds_remove_entry( ) functions and the query functions
only go to the DSA.
- DSX_DUA_CACHE and DSX_USEDSA, both OM_FALSE
The ds_add_entry( ) and ds_remove_entry( ) functions and the query functions report an
error.
All other functions always operate on the DSA currently connected.
· DSX_PREFER_ADM_FUNCS
GDS uses the three following optional attributes:
- DSX_A_MASTER_KNOWLEDGE, which contains the DN of the DSA that holds the master copy of an entry.
- DSX_A_ACL, which is used for GDS access control.
- DS_A_USER_PASSWORD as an attribute of the DS_O_DSA object class, which is used by the GDS shadowing mechanism.
The DSX_A_MASTER_KNOWLEDGE and DSX_A_ACL attributes are present in every GDS entry.
When an application requests all attributes, it can prevent any of these three optional attributes from being returned by setting this service control 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 of all its OM attributes, works with all the interface functions. The constant DS_DEFAULT_CONTEXT can be used as an argument to functions instead of creating an OM object with default values.
The default DSX_C_GDS_CONTEXT is defined in the following table.
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 |