ds_add_entry(3xds) — Subroutines
(c) Digital Equipment Corporation. 1994. All rights reserved.
Name
ds_add_entry − Adds an entry to the Directory Information Tree (DIT).
Syntax
Status = ds_add_entry(Session, Context, Name, Entry, 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} Entry@OM_object@T{ read T} Invoke-ID@Integer@T{ write T} Status@T{ DS_status T}
C Binding
DS_status ds_add_entry(session, context, name, entry, invoke_id_return)
OM_private_object@T{ session T} OM_private_object@T{ context T} OM_object@T{ name T} OM_object@T{ entry 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. The Size-Limit and Dont-Dereference-Aliases Context parameters do 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 distinguished name of the entry to be added. The immediate superior of the new entry is determined by removing the last RDN component that belongs to the new entry. The immediate superior should exist in the same DSA otherwise the function may fail with an Update-Error, affecting-multiple-DSAs. It does not fail if an agreement exists between the DSAs that allows the entry to be added. Any aliases in the name will not be dereferenced.
Entry
The attribute information which, together with the RDN, constitutes the entry to be created. The information must be contained in an Attribute List OM object, or an OM object that is a subclass of Attribute-List. The object parameter should not contain the value of the RDN of the entry being created.
Invoke-ID
The Invoke-ID of an asynchronous directory operation. This is passed by reference.
Description
This function adds an entry to the Directory. The entry can be either an object entry or an alias entry. The Directory checks that the resulting entry conforms to the Directory 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 Add 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.
•
Only leaf objects (that is, objects that are not CDS directory objects) can be added to CDS through the XDS interface.
•
The DS_A_OBJECT_CLASS attribute of an object is single valued in CDS and multivalued in X.500. If the Entry argument contains a DS_A_OBJECT_CLASS attribute with a value of DS_O_ALIAS, a CDS alias (soft link) will be created. If the attribute value is DS_O_GROUP_OF_NAMES, a CDS Group object will be created. Any other value for DS_A_OBJECT_CLASS, or the absence of this attribute, will result in the creation of an ordinary CDS object.
•
Only the DS_A_COMMON_NAME and DS_A_MEMBER attributes are valid for the DS_O_GROUP_OF_NAMES object in CDS.
•
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 an Add Entry operation that references CDS, then it returns the Attribute-Error constraint-violation.
Because CDS does not implement the X.500 schema rules, some CDS objects may not contain mandatory attributes like object class and so on.
Return Value
The entry was added, 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 are 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:
Attribute-Error, constraint-violation
Communications-Error
Library-Error, with Problem attribute values of bad-argument, bad-context, bad-name, bad-session, miscellaneous, missing-type, not-supported or too-many-operations
Name-Error, no-such-object
Referral
Security-Error
Service-Error
Update-Error
Examples
The following code extracts show an example call to the Add Entry function. The Add Entry function is used to create a new directory entry containing two attributes: common name and organization unit.
There are two examples. The first example shows how to perform an asynchronous Add Entry operation. The second example shows how to perform a synchronous Add Entry operation.
The Bound_Session argument contains the identity of a session returned from an earlier call to the Bind function. This object identifies the session through which the request should be issued. The Name argument is assumed to have been previously defined. Examples of how to define a Name argument, including an example of a CDS Name argument, are shown in the Read function.
Exhibit 0-0.
OM_private_object bound_session, context;
OM_workspace workspace;
OM_return_code om_status = OM_SUCCESS;
OM_descriptor ATLST_entry[4], /∗ contents of entry ∗/
ATTR_sn_Black[4],
ATTR_oc_OrgPerson[5],
Context[3]; /∗ For the context ∗/
/∗ Define the first X.500 Object Class attribute ∗/
OMX_CLASS_DESC( ATTR_oc_OrgPerson[0], DS_C_ATTRIBUTE); OMX_ATTR_TYPE_DESC( ATTR_oc_OrgPerson[1], DS_ATTRIBUTE_TYPE,
DS_A_OBJECT_CLASS); OMX_STRING_DESC( ATTR_oc_OrgPerson[2], OM_S_OBJECT_IDENTIFIER_STRING,
DS_ATTRIBUTE_VALUES,
DS_O_PERSON.elements,
DS_O_PERSON.length); OMX_STRING_DESC( ATTR_oc_OrgPerson[3], OM_S_OBJECT_IDENTIFIER_STRING,
DS_ATTRIBUTE_VALUES,
DS_O_ORG_PERSON.elements,
DS_O_ORG_PERSON.length); OMX_OM_NULL_DESC( ATTR_oc_OrgPerson[4]);
/∗ Define the X.500 Surname attribute ∗/
OMX_CLASS_DESC( ATTR_sn_Black[0], DS_C_ATTRIBUTE); OMX_ATTR_TYPE_DESC( ATTR_sn_Black[1], DS_ATTRIBUTE_TYPE,
DS_A_SURNAME); OMX_ZSTRING_DESC( ATTR_sn_Black[2], OM_S_PRINTABLE_STRING,
DS_ATTRIBUTE_VALUES,
"Black"); OMX_OM_NULL_DESC( ATTR_sn_Black[3]);
/∗ Define the Attribute List ∗/
OMX_CLASS_DESC( ATLST_entry[0], DS_C_ATTRIBUTE_LIST); OMX_OBJECT_DESC( ATLST_entry[1], DS_ATTRIBUTES, ATTR_sn_Black); OMX_OBJECT_DESC( ATLST_entry[2], DS_ATTRIBUTES, ATTR_oc_OrgPerson); OMX_OM_NULL_DESC( ATLST_entry[3]);
/∗ now create the context object and set the Asynchronous flag to ∗/ /∗ true to indicate that the operation should be asynchronous. ∗/
om_status = om_create(DS_C_CONTEXT, OM_TRUE, workspace, &context);
OMX_CLASS_DESC( Context[0], DS_C_CONTEXT); OMX_BOOLEAN_DESC(Context[1], DS_ASYNCHRONOUS,OM_TRUE); OMX_OM_NULL_DESC(Context[2]);
/∗ Now place the contents of the public object cpub_context into ∗/ /∗ the private object context ∗/
om_status = om_put(context, OM_REPLACE_ALL, Context, 0, 0, 0);
{
DS_status status;
OM_sint invoke_id;
OM_uint completion_flag;
DS_status operation_status;
OM_return_code om_status;
OM_private_object entry, add_entry_result;
/∗ create the OM private object: entry ∗/
om_status = om_create(DS_C_ATTRIBUTE_LIST, OM_FALSE, workspace,
&entry);
/∗ Copy the attribute list from the cpub_attr_list public ∗/
/∗ object into the entry private object ∗/
om_status = om_put(entry, OM_REPLACE_ALL, ATLST_entry, 0, 0, 0);
/∗ Call the Add Entry function using entry as a parameter ∗/
status = ds_add_entry(bound_session, context, name, entry,
&invoke_id);
if (status == DS_SUCCESS)
{
printf("ADD ENTRY request was successful0);
}
else
{
printf("ADD ENTRY request 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,
&add_entry_result, &invoke_id);
if (status == DS_SUCCESS)
{
switch (completion_flag)
{
case DS_COMPLETED_OPERATION:
/∗ we have a completed operation ∗/
if(operation_status == DS_SUCCESS)
{
printf("ADD ENTRY was successful0);
}
break;
case DS_OUTSTANDING_OPERATIONS:
printf("There are outstanding operations0);
break;
case DS_NO_OUTSTANDING_OPERATION:
printf("There are NO outstanding operations0);
break;
}
}
} }
Example 1 shows:
•How to define a private object containing context parameters.
•How to define a public object (cpub_attr_list) containing the attributes to be added to the new directory entry.
•How to use the OM Create function to create a private object (entry) and how to use the OM Put function to copy the entry’s attributes from the public object (cpub_attr_list) into the newly created private object (entry).
•How to use the Receive Result function to obtain the result of the Add Entry function.
The OM Create and the OM Put functions are assumed to succeed.
Exhibit 0-0.
OM_private_object bound_session, context, name;
{
DS_status status;
OM_private_object entry;
status = ds_add_entry(bound_session, DS_DEFAULT_CONTEXT, name,
entry, NULL);
if (status == DS_SUCCESS)
{
printf("ADD ENTRY was successful0);
}
else
{
printf("ADD ENTRY failed0);
} }
Example 2 shows how to perform a synchronous Add Entry operation. Note that the Invoke_id argument is not needed and therefore set to NULL. The example assumes that all other arguments have been defined as shown in Example 1.