NAME

SYNOPSIS

#include <xom.h>
#include <xds.h>

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

PARAMETERS

Input

session

(Object(DS_C_SESSION)). The directory session against which this operation is performed. This must be a private object.

context

(Object(DS_C_CONTEXT)). The directory context to be used for this operation. Note that DS_SIZE_LIMIT and DS_DONT_DEREFERENCE_ALIASES do not apply to this operation. This parameter must be a private object or the DS_DEFAULT_CONTEXT constant.

name

(Object(DS_C_NAME)). The name of the target object entry. Any aliases in the name are not dereferenced.

changes

(Object(DS_C_ENTRY_MOD_LIST)). A sequence of modifications to the named entry.

Output

invoke_id_return

(Integer). Not supported.

DESCRIPTION

The ds_modify_entry() function is used to make a series of one or more of the following changes to a single directory entry:

• Add a new attribute (DS_ADD_ATTRIBUTE).
• Remove an attribute (DS_REMOVE_ATTRIBUTE).
• Add attribute values (DS_ADD_VALUES).
• Remove attribute values (DS_REMOVE_VALUES).

Values can be replaced by a combination of adding values and removing values in a single operation. The RDN can only be changed by using ds_modify_rdn().

The result of the operation is as if each modification is made in the order specified in the changes parameter. If any of the individual modifications fails, then a DS_C_ATTRIBUTE_ERROR is reported and the entry is left as it was prior to the whole operation. The operation is atomic; that is, either all or none of the changes are made. The Directory checks that the resulting entry conforms to the Directory schema.

NOTES

Although the user ideally is not aware whether naming operations are being handled by GDS or CDS, there are some situations where naming results can differ between the two services. (See the xds_intro(3xds) reference page for XDS functions for the general differences between operations on GDS and CDS.)

Note the following issues for the ds_modify_entry() operation:

• Naming schema rules do not apply in CDS. Thus, the following attribute errors are never returned by CDS:

  • DS_E_NO_SUCH_ATTRIBUTE_OR_VALUE
  • DS_E_ATTRIBUTE_OR_VALUE_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.
• GDS-structured attribute types are not supported by CDS. If a GDS-structured attribute type is used as a parameter to ds_modify_entry() on a CDS object, then it returns with a DS_C_ATTRIBUTE_ERROR (DS_E_CONSTRAINT_VIOLATION). In CDS, ds_modify_entry() can only be used on leaf objects; otherwise, a DS_C_NAME_ERROR (DS_E_NO_SUCH_OBJECT) is returned.

RETURN VALUES

DS_status

Takes the value DS_SUCCESS if all the modifications succeeded and takes an error value if not.

ERRORS

This function can return a DS_C_SYSTEM_ERROR or one of the following DS_C_LIBRARY_ERRORs:

• DS_E_BAD_ARGUMENT
• DS_E_BAD_CONTEXT
• DS_E_BAD_NAME
• DS_E_BAD_SESSION
• DS_E_MISCELLANEOUS
• DS_E_MISSING_TYPE
• DS_E_TOO_MANY_OPERATIONS

The following directory errors can be returned by the function:

• DS_C_ATTRIBUTE_ERROR
• DS_C_NAME_ERROR
• DS_C_REFERRAL
• DS_C_SECURITY_ERROR
• DS_C_SERVICE_ERROR
• DS_C_UPDATE_ERROR

This function can return a DS_C_COMMUNICATIONS_ERROR, as well as the error constant DS_NO_WORKSPACE.

The following situations apply to GDS:

• An attempt to use DS_ADD_ATTRIBUTE to add an existing attribute results in a DS_C_ATTRIBUTE_ERROR.
• An attempt to use DS_ADD_VALUES to add an existing value results in a DS_C_ATTRIBUTE_ERROR, as does an attempt to add a value to a nonexistent attribute type.
• An attempt to use DS_REMOVE_ATTRIBUTE to remove a nonexisting attribute results in a DS_C_ATTRIBUTE_ERROR, whereas an attempt to remove an attribute that is part of the object's RDN results in a DS_C_UPDATE_ERROR.
• An attempt to use DS_REMOVE_VALUES to remove a nonexisting value results in a DS_C_ATTRIBUTE_ERROR, whereas an attempt to remove a value of an attribute that is part of the object's RDN, or to modify the object class attribute, results in a DS_C_UPDATE_ERROR.