Name

ds_add_entry - Adds a leaf entry to the DIT

Synopsis

#include <xom.h>
#include <xds.h> DS_status ds_add_entry(
OM_private_object session,
OM_private_object context,
OM_object name,
OM_object entry,
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.  This parameter must be a private object or the DS_DEFAULT_CONTEXT constant.  Note that DS_­DONT_­DEREFERENCE_­ALIASES and DS_­SIZE_­LIMIT do not apply to this operation. 

name(Object(DS_C_NAME)).  The name of the entry to be added.  The immediate superior of the new entry is determined by removing the last RDN component, which belongs to the new entry.  The immediate superior must exist in the same Directory Service Agent, or the function can fail with DS_C_UPDATE_ERROR (DS_E_AFFECTS_MULTIPLE_DSAS).  Any aliases in the name are not dereferenced. 

entry(Object(DS_C_ATTRIBUTE_LIST)).  The attribute information that, together with that from the RDN, constitutes the entry to be created.  Note that an instance of OM class DS_C_ENTRY_INFO can be supplied as the value of this parameter, since OM class DS_C_ENTRY_INFO is a subclass of OM class DS_­C_­ATTRIBUTE_­LIST. 

Output

invoke_id_return
(Integer).  Not supported.

Description

The ds_add_entry() function adds a leaf entry to the directory.  The entry can be either an object or an alias.  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_add_entry() operation:

       •Only leaf objects (that is, objects that are not CDS directory objects) can be added to CDS through the XDS interface.  In other words, the immediate superior of the new entry must exist. 

       •Only the DS_A_COMMON_NAME and DS_A_MEMBER attributes are valid for the DS_O_GROUP_OF_NAMES object in CDS. 

       •GDS-structured attribute types are not supported by CDS. If an attempt is made to add a GDS-structured attribute type to CDS, then it returns with a DS_C_ATTRIBUTE_ERROR (DS_E_CONSTRAINT_VIOLATION). 

Since CDS does not implement the X.500 schema rules, some CDS objects may not contain mandatory attributes like object class and so on. 

Return Values

DS_statusDS_SUCCESS is returned if the entry was added; otherwise, an error is returned. 

Errors

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

This function can return a DS_C_SYSTEM_ERROR or one of the following DS_C_LIBRARY_ERROR 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 function can return the following directory errors:

       •DS_C_ATTRIBUTE_ERROR

       •DS_C_NAME_ERROR

       •DS_C_REFERRAL

       •DS_C_SECURITY_ERROR

       •DS_C_SERVICE_ERROR

       •DS_C_UPDATE_ERROR

The DS_C_UPDATE_ERROR (DS_E_AFFECTS_MULTIPLE_DSAS) error, referred to earlier in this reference page, need not be returned if there is local agreement between the DSAs to allow the entry to be added. 

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