Digital DCE for OpenVMS VAX and OpenVMS Alpha
Reference Guide

This example shows:

A call to the List function.
How to use the Receive Result function to obtain the result of the List function.

How to use the OM Get function to copy the attributes of the List-Result OM private object into the equivalent List-Result OM public object (Spub_Result) for examination.
The OM Get function is assumed to succeed.

OM_private_object bound_session, context, name; { DS_status status; OM_private_object list_result; OM_public_object spub_result; OM_value_position desc_count; status = ds_list(bound_session, DS_DEFAULT_CONTEXT, name, &list_result, NULL); if (status == DS_SUCCESS) { /* LIST was successful */ /* now see what we have got back ... */ om_status = om_get(list_result, OM_NO_EXCLUSIONS, 0, 0, 0, OM_ALL_VALUES, &spub_result, &desc_count); if (om_status == OM_SUCCESS) { /* if desc_count!=0, results now available as a public */ /* object */ } else { /* error getting results */ } } else {...} }

This example shows how to perform a synchronous List operation. Note that the Invoke-ID argument is not needed and is therefore set to NULL. This example assumes that all other arguments have been defined as shown in Example 1.

ds_modify_entry(3xds)

Performs a modification on an entry.

Syntax

Status = ds_modify_entry(Session, Context, Name, Changes, Invoke-ID)

Argument	Data Type	Access
Session	OM_private_object	read
Context	OM_private_object	read
Name	OM_object	read
Changes	OM_object	read
Invoke-ID	Integer	write
Status	DS_status

C Binding

DS_status ds_modify_entry(session, context, name, changes, invoke_id_return)

DS_status ds_modify_entry (
OM_private_object session
OM_private_object context
OM_object name
OM_object changes
OM_sint invoke_id_return)

Arguments

Session
The Session OM private object that was returned by the Bind function, identifying the directory session to be used.
Context
The Context parameters to be used for this operation. This argument must be a Context OM private object or the constant Default-Context.
Name
A Name OM object containing the name of the target entry. Any aliases in the name will be dereferenced if the DSA attribute Dereference Alias on Modify is set and the Dont Deference Aliases service control is not set.
Changes
An Entry-Modification-List OM object specifying a sequence of modifications to the named entry.
Invoke-ID
The Invoke-ID of an asynchronous directory operation.

Description

This function is used to make a series of one or more of the following changes to a single entry:

Add a new attribute (add-attribute)
Remove an attribute (remove-attribute)
Add attribute values (add-values)
Remove attribute values (remove-values)

You can replace values by a combination of adding values and removing values in a single operation. You can only change the RDN of an entry by using the Modify-RDN function.
The result of the operation is as if each modification is made in the order specified in the Changes argument. If any of the individual modifications fail, then an Attribute-Error is reported and the entry is left as it was before the whole operation. The operation is atomic, either all the changes are made or none are. The Directory Service checks that the resulting entry conforms to the schema.

DCE Notes

Ideally, the user does not know whether X.500 or CDS is actually handling the DCE naming operations. There are, however, some situations where naming results will differ depending on which service is handling the operation. (The intro reference page for XDS functions describes the general differences between operations on X.500 and CDS.)
Note the following issues for the Modify Entry function:

All CDS operations are synchronous. If a CDS operation is attempted and the Context parameter Asynchronous has been set true, a Library-Error, not-supported, is returned.
When a CDS name is passed to XDS and DCE is not installed, a Library-Error, not-supported, is returned. This error is also returned when an X.500 name is passed to XDS and X.500 is not installed.
Naming schema rules do not apply in CDS. At the XDS API, all CDS attributes are treated as multivalued. Adding an attribute that already exists on the CDS entry causes an additional value to be added to that attribute's set of values. Thus, the following Attribute-Errors are never returned by CDS:

no-such-attribute-or-value
attribute-or-value-already-exists

Naming operations that would normally return these errors succeed in CDS. In particular, the addition of an attribute that already exists does not return with an error. Instead, the values of the attribute to be added are combined with the values of the existing attribute.
CDS supports only the following X.500 attribute syntaxes:

OM_S_TELETEX_STRING
OM_S_OBJECT_IDENTIFIER_STRING
OM_S_OCTET_STRING
OM_S_PRINTABLE_STRING
OM_S_NUMERIC_STRING
OM_S_BOOLEAN
OM_S_INTEGER
OM_S_UTC_TIME_STRING
OM_S_ENCODING_STRING

If attributes of any other syntax are supplied to a Modify Entry operation that references CDS, then it returns the Attribute-Error constraint-violation.
In CDS, the name parameter supplied to the Modify Entry function must ultimately resolve to the name of a leaf (that is, a CDS Object) entry; otherwise, the Name-Error no-such-object is returned. The function never interprets the name parameter as the name of a CDS Directory entry.

Return Values

Possible return values are as follows:

Return Description

DS_SUCCESS All the modifications were made to the entry, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously.

DS_NO_WORKSPACE A workspace has not been set up by a call to the Initialize function.

If neither of these constants is returned, then the function returns a pointer to an error object of one of the classes listed below.

Return	Description
DS_SUCCESS	All the modifications were made to the entry, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously.
DS_NO_WORKSPACE	A workspace has not been set up by a call to the Initialize function.

Errors

This function can return pointers to the following error objects:

Library-Error, with Problem attribute values of bad-argument, bad-context, bad-name, bad-session, miscellaneous, missing-type, not-supported, or too-many-operations
Attribute-Error, constraint-violation
Name-Error, no-such-object
Referral
Security-Error
Service-Error
Update-Error
Communications-Error
An Attribute-Error is returned if you attempt any of the following:

To use Add-Attribute to add an existing attribute
To add a value to a nonexistent attribute type
To use Remove-Attribute to remove a nonexistent attribute or nonexistent attribute value
An attempt to remove an attribute or attribute value which is part of the object's RDN or to modify the object class attribute results in an Update-Error.

Examples

The following code extracts show an example call to the Modify Entry function. Note that the standard schema does not contain an object class with the attributes used in the example. The Modify Entry function is used to modify the directory entry, identified in the Name argument, as follows:

Add a new X.500 attribute Title with the value "Sales & Marketing Director"
Add the value "Abacus Trading Corporation" to the X.500 attribute Organization Name
Remove the X.500 attribute Organizational Unit Name
Remove the value "US" from the Country Name X.500 attribute

There are two examples. The first example shows how to perform an asynchronous Modify Entry operation. The second example shows how to perform a synchronous Modify Entry operation.

The Bound_Session argument contains the identity of a session, established using the Bind function, through which the request should be issued. Two arguments are assumed to have been previously defined. These are the Name argument and the Context argument. Examples of how to define a Name argument, including an example of a CDS Name argument, are shown in the Read function. An example of how to define a Context argument is shown in the Add Entry function.

OM_private_object bound_session, context, name; /* define some public objects to contain the changes to be made to */ /* the directory entry */ /* declare the descriptor lists (public objects) */ OM_descriptor cpub_mod_list[6]; OM_descriptor cpub_mod1[5]; OM_descriptor cpub_mod2[6]; OM_descriptor cpub_mod3[4]; OM_descriptor cpub_mod4[5]; /* define the first descriptor list */ OMX_CLASS_DESC( cpub_mod1[0], DS_C_ENTRY_MOD); OMX_ENUM_DESC( cpub_mod1[1], DS_MOD_TYPE, DS_ADD_ATTRIBUTE); OMX_ATTR_TYPE_DESC( cpub_mod1[2], DS_ATTRIBUTE_TYPE, DS_A_TITLE); OMX_ZSTRING_DESC( cpub_mod1[3], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "Sales & Marketing Director"); OMX_OM_NULL_DESC( cpub_mod1[4]); /* define the second descriptor list */ OMX_CLASS_DESC( cpub_mod2[0], DS_C_ENTRY_MOD); OMX_ENUM_DESC( cpub_mod2[1], DS_MOD_TYPE, DS_ADD_VALUES); OMX_ATTR_TYPE_DESC( cpub_mod2[2], DS_ATTRIBUTE_TYPE, DS_A_ORG_NAME); OMX_ZSTRING_DESC( cpub_mod2[3], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "Abacus Trading Corporation"); OMX_ZSTRING_DESC( cpub_mod2[4], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "Abacus"); OMX_OM_NULL_DESC( cpub_mod2[5]); /* define the third descriptor list */ OMX_CLASS_DESC( cpub_mod3[0], DS_C_ENTRY_MOD); OMX_ENUM_DESC( cpub_mod3[1], DS_MOD_TYPE, DS_REMOVE_ATTRIBUTE); OMX_ATTR_TYPE_DESC( cpub_mod3[2], DS_ATTRIBUTE_TYPE, DS_A_ORG_UNIT_NAME); OMX_OM_NULL_DESC( cpub_mod3[3]); /* define the fourth descriptor list */ OMX_CLASS_DESC( cpub_mod4[0], DS_C_ENTRY_MOD); OMX_ENUM_DESC( cpub_mod4[1], DS_MOD_TYPE, DS_REMOVE_VALUES); OMX_ATTR_TYPE_DESC( cpub_mod4[2], DS_ATTRIBUTE_TYPE, DS_A_COUNTRY_NAME); OMX_ZSTRING_DESC( cpub_mod4[3], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "US"); OMX_OM_NULL_DESC( cpub_mod4[4]); /* define the fifth descriptor list */ OMX_CLASS_DESC( cpub_mod_list[0], DS_C_ENTRY_MOD_LIST); OMX_OBJECT_DESC( cpub_mod_list[1], DS_CHANGES, cpub_mod1); OMX_OBJECT_DESC( cpub_mod_list[2], DS_CHANGES, cpub_mod2); OMX_OBJECT_DESC( cpub_mod_list[3], DS_CHANGES, cpub_mod3); OMX_OBJECT_DESC( cpub_mod_list[4], DS_CHANGES, cpub_mod4); OMX_OM_NULL_DESC( cpub_mod_list[5]); { DS_status status; OM_sint invoke_id; OM_uint completion_flag; DS_status operation_status; OM_return_code om_status; OM_private_object changes, modify_entry_result; /* create an OM Private object called changes*/ om_status = om_create(DS_C_ENTRY_MOD_LIST, OM_FALSE, workspace, &changes); /* now put the contents of the public object, cpub_mod_list, */ /* in to the changes private object */ om_status = om_put(changes, OM_REPLACE_ALL, cpub_mod_list, 0, 0, 0); /* Call the Modify Entry function using the changes object as */ /* a parameter */ status = ds_modify_entry(bound_session, context, name, changes, &invoke_id); if (status == DS_SUCCESS) { printf("MODIFY ENTRY was successful\n"); } else { printf("MODIFY ENTRY failed\n"); } /* now wait for the response... */ completion_flag = DS_OUTSTANDING_OPERATIONS; /* loop around calls to receive_result() until we get one back */ while ((status == DS_SUCCESS) && (completion_flag == DS_OUTSTANDING_OPERATIONS)) { status = ds_receive_result(bound_session, &completion_flag, &operation_status, &modify_entry_result, &invoke_id); if (status == DS_SUCCESS) { switch (completion_flag) { case DS_COMPLETED_OPERATION: /* we have a completed operation */ /* check operation_status */ break; case DS_OUTSTANDING_OPERATIONS: ... break; case DS_NO_OUTSTANDING_OPERATION: ... break; } } } }

The above example shows the following:

How to define an Entry-Modification-List OM public object (cpub_mod_list) containing the modifications to be made.
How to use the OM Create function to create an Entry-Modification-List OM private object (changes) and how to use the OM Put function to copy the modifications from the public object (cpub_mod_list) into the newly created private object (changes).
Both the OM Create and the OM Put functions are assumed to succeed.

How to obtain the result of the Modify Entry function using the Receive Result function.

OM_private_object bound_session, context, name; { DS_status status; OM_private_object changes; status = ds_modify_entry(bound_session, DS_DEFAULT_CONTEXT, name, changes, NULL); if (status == DS_SUCCESS) { printf("MODIFY_ENTRY was successful\n"); } else { printf("MODIFY_ENTRY failed\n"); } }

The above example shows how to perform a synchronous Modify Entry operation. Note that the Invoke-ID argument is not needed, so NULL is used. This example assumes that the Changes argument has been defined as shown in Example 1.

ds_modify_rdn(3xds)

Changes the Relative Distinguished Name (RDN) of an entry.

Syntax

Status = ds_modify_rdn(Session, Context, Name, New-RDN, Delete-Old-RDN, Invoke-ID)

Argument	Data Type	Access
Session	OM_private_object	read
Context	OM_private_object	read
Name	OM_object	read
New-RDN	OM_object	read
Delete-Old-RDN	OM_boolean	read
Invoke-ID	Integer	write
Status	DS_status

C Binding

DS_status ds_modify_rdn(session, context, name, new_rdn, delete_old_rdn, invoke_id_return)

DS_status ds_modify_rdn (
OM_private_object session
OM_private_object context
OM_object name
OM_object new_rdn
OM_boolean delete_old_rdn
OM_sint invoke_id_return)

Arguments

Session
The Session OM private object that was returned by the Bind function, identifying the directory session to be used.
Context
The directory context to be used for this operation. This argument must be a Context OM private object or the constant Default-Context.
Name
A Name OM object containing the current name of the target entry. Any aliases in the name will be dereferenced if the DSA attribute Dereference Alias on Modify is set and the Dont Deference Aliases service control is not set.
New-RDN
A Relative-Name OM object specifying the new RDN. If an attribute value in the new RDN does not already exist in the entry, either as part of the old RDN or as a nondistinguished value, then the new value is added.
Delete-Old-RDN
When this takes the value false the old values will remain, but not as part of the RDN. When this takes the value true, all attribute values in the old RDN that are not also in the new RDN are deleted. If the operation removes the last value of an attribute, the attribute is deleted. This argument must be true when the value of a single-valued attribute is changed.
Invoke-ID
The Invoke-ID of an asynchronous directory operation.

Description

This function is used to change the RDN of a leaf entry. This can be either an object entry or an alias entry.

Note
CDS does not support the Modify RDN function; it returns with the Service-Error unwilling-to-perform.

Return Values

Possible return values are as follows:

Return Description

DS_SUCCESS The RDN of the entry was changed, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously.

DS_NO_WORKSPACE A workspace has not been set up by a call to the Initialize function.

If neither of these constants is returned, then the function returns a pointer to an error object of one of the classes listed below.

Return	Description
DS_SUCCESS	The RDN of the entry was changed, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously.
DS_NO_WORKSPACE	A workspace has not been set up by a call to the Initialize function.

Errors

This function can return pointers to the following error objects:

Library-Error, with Problem attribute values of bad-argument, bad-context, bad-name, bad-session, miscellaneous, missing-type, not-supported, or too-many-operations
Attribute-Error
Communications-Error
Name-Error
Referral
Security-Error
Service-Error
Update-Error
The Update-Error \fIaffects-multiple-DSAs\fP that is referred to in the argument descriptions need not be returned if there is local agreement between the DSAs to allow the entry to be modified.
Communications-Error

Examples

The following code extract shows an example call to the Modify RDN function.

OM_private_object bound_session, context, name, new_rdn; OM_sint invoke_id; OM_boolean delete_old_rdn; { DS_status status; status = ds_modify_rdn(bound_session, DS_DEFAULT_CONTEXT, name, new_rdn, delete_old_rdn, NULL); if (status == DS_SUCCESS) { printf("MODIFY RDN was successful\n"); } else { printf("MODIFY RDN failed\n"); } return status;}

ds_read(3xds)

Queries information in a particular entry.

Syntax

Status = ds_read(Session, Context, Name, Selection, Result, Invoke-ID)

Argument	Data Type	Access
Session	OM_private_object	read
Context	OM_private_object	read
Name	OM_object	read
Selection	OM_object	read
Result	OM_object	write
Invoke-ID	Integer	write
Status	DS_status

C Binding

DS_status ds_read(session, context, name, selection, result_return, invoke_id_return)

DS_status ds_add_read (
OM_private_object session
OM_private_object context
OM_object name
OM_object selection
OM_private_object result_return
OM_sint invoke_id_return)

Arguments

Session
The Session OM private object that was returned by the Bind function, identifying the directory session to be used.
Context
The directory context to be used for this operation. The Size-Limit Context parameter does not apply to this operation. This argument must be a Context OM private object or the constant Default-Context.
Name
A Name OM object containing the name of the target entry. Any aliases in the name will be dereferenced unless prohibited by the Context parameter Dont-Dereference-Aliases.
Selection
An Entry-Information-Selection OM object or a constant specifying what information from the named entry is requested. Information about no attributes, all attributes, or just a named set can be chosen. Attribute types are always returned, but the attribute values need not be. The following constants can be used:

Select-No-Attributes, to verify the existence of an entry
Select_All-Types, to return just the types of all attributes
Select-All-Types-And-Values, to return the types and values of all attributes

Result
A Read-Result OM object, passed by reference, containing the distinguished name of the target object and a flag indicating whether the result came from the original entry or a copy. It also contains any requested attribute types and values. Attribute information is only returned if access rights are sufficient. No object is returned if the call does not complete successfully.
Invoke-ID
The Invoke-ID of an asynchronous directory operation.

Description

This function is used to extract information from an explicitly named entry. It can also be used to verify a distinguished name.
If this function is called asynchronously, then the result can be abandoned by calling the Abandon function.

DCE Notes

Ideally, the user does not know whether X.500 or CDS is actually handling the DCE naming operations. There are, however, some situations where naming results will differ depending on which service is handling the operation. (The intro reference page for XDS functions describes the general differences between operations on X.500 and CDS.)
Note the following issues for the Read function:

All CDS operations are synchronous. If a CDS operation is attempted and the Context parameter Asynchronous has been set true, a Library-Error, not-supported, is returned.
When a CDS name is passed to XDS and DCE is not installed, a Library-Error, not-supported, is returned. This error is also returned when an X.500 name is passed to XDS, and X.500 is not installed.
Because CDS does not implement the X.500 schema rules, some CDS objects may not contain mandatory attributes such as object class and so on. In CDS, a read of an alias object fails if the DS_A_ALIASED_OBJECT_NAME does not exist. Instead, CDS returns with the Name-Error no-such-object.
In CDS, the naming attribute of an object is not stored in the attribute list for the object. Thus in CDS, the Read function does not return this attribute in the attribute list for an object.

Return Values

Possible return values are as follows:

Return Description

DS_SUCCESS The read was completed, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously.

DS_NO_WORKSPACE A workspace has not been set up by a call to the Initialize function.

If neither of these constants is returned, then the function returns a pointer to an error object of one of the classes listed below.

Return	Description
DS_SUCCESS	The read was completed, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously.
DS_NO_WORKSPACE	A workspace has not been set up by a call to the Initialize function.

Errors

This function can return pointers to the following error objects:

Library-Error, with Problem attribute values of bad-argument, bad-context, bad-name, bad-session, miscellaneous, missing-type, not-supported, or too-many-operations
Attribute-Error
Name-Error, no-such-object
Referral
Security-Error
Service-Error
Communications-Error

An Attribute-Error, no-such-attribute, is reported if an explicit list of attributes is specified by the selection argument but none of them are present in the entry. This error is not reported if any of the selected attributes are present.

A Security-Error, insufficient-access-rights, is reported where access rights prohibit the reading of all requested attribute values.

Examples

The following code extracts show an example call to the Read function. The Read function is used to read all the types and values from all attributes of the directory entry identified in the Name argument.
There are three examples. The first example shows how to perform an asynchronous Read operation. The second example shows how to perform a synchronous Read operation. The third example shows how to perform a synchronous Read operation with a CDS name.

Previous Next Contents Index

Digital DCE for OpenVMS VAX and OpenVMS AlphaReference Guide

ds_modify_entry(3xds)

Syntax

Status = ds_modify_entry(Session, Context, Name, Changes, Invoke-ID)

C Binding

Arguments

Session

Context

Name

Changes

Invoke-ID

Description

DCE Notes

Return Values

Errors

Examples

ds_modify_rdn(3xds)

Syntax

Status = ds_modify_rdn(Session, Context, Name, New-RDN, Delete-Old-RDN, Invoke-ID)

C Binding

Arguments

Session

Context

Name

New-RDN

Delete-Old-RDN

Invoke-ID

Description

Return Values

Errors

Examples

ds_read(3xds)

Syntax

Status = ds_read(Session, Context, Name, Selection, Result, Invoke-ID)

C Binding

Arguments

Session

Context

Name

Selection

Result

Invoke-ID

Description

DCE Notes

Return Values

Errors

Examples

Digital DCE for OpenVMS VAX and OpenVMS Alpha
Reference Guide