ds_modify_entry(3xds) — Subroutines
(c) Digital Equipment Corporation. 1994. All rights reserved.
Name
ds_modify_entry − Performs an modification on an entry.
Syntax
Status = ds_modify_entry(Session, Context, Name, Changes, Invoke-ID)
Argument@Data Type@Access
Session@OM_private_object@T{ read T} Context@OM_private_object@T{ read T} Name@OM_object@T{ read T} Changes@OM_object@T{ read T} Invoke-ID@Integer@T{ write T} Status@T{ DS_status T}
C Binding
DS_status ds_modify_entry(session, context, name, changes, invoke_id_return)
OM_private_object@T{ session T} OM_private_object@T{ context T} OM_object@T{ name T} OM_object@T{ changes T} OM_sint@T{ ∗invoke_id_return T}
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 Digital 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 Value
All the modifications were made to the entry, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously. T} DS_NO_WORKSPACE@T{ A workspace has not been set up by a call to the Initialize function. T}
If neither of these constants is returned, then the function returns a pointer to an error object of one of the classes listed below.
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 non-existent attribute type
•To use Remove-Attribute to remove a non-existent attribute or non-existent 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.
Exhibit 0-0.
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 successful0);
}
else
{
printf("MODIFY ENTRY failed0);
}
/∗ 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;
}
}
} }
Example 1 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.
Exhibit 0-0.
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 successful0);
}
else
{
printf("MODIFY_ENTRY failed0);
} }
Example 2 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.