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 Context argument is assumed to have been previously defined. An example of how to define a Context argument is shown in the Add Entry function.

{ OM_workspace workspace; OM_descriptor cpub_dn[6]; OM_descriptor cpub_rdn1[3]; OM_descriptor cpub_rdn2[3]; OM_descriptor cpub_rdn3[3]; OM_descriptor cpub_rdn4[3]; OM_descriptor cpub_ava1[4]; OM_descriptor cpub_ava2[4]; OM_descriptor cpub_ava3[4]; OM_descriptor cpub_ava4[4]; OM_value_position desc_count; DS_status status; OM_sint invoke_id; OM_uint completion_flag; DS_status operation_status; OM_return_code om_status; OM_private_object name, read_result; OM_public_object spub_result; OMX_CLASS_DESC( cpub_ava1[0], DS_C_AVA); OMX_ATTR_TYPE_DESC( cpub_ava1[1], DS_ATTRIBUTE_TYPE, DS_A_COMMON_NAME); OMX_ZSTRING_DESC( cpub_ava1[2], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "Albert Einstein"); OMX_OM_NULL_DESC( cpub_ava1[3]); OMX_CLASS_DESC( cpub_ava2[0], DS_C_AVA); OMX_ATTR_TYPE_DESC( cpub_ava2[1], DS_ATTRIBUTE_TYPE, DS_A_ORG_UNIT_NAME); OMX_ZSTRING_DESC( cpub_ava2[2], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "Research"); OMX_OM_NULL_DESC( cpub_ava2[3]); OMX_CLASS_DESC( cpub_ava3[0], DS_C_AVA); OMX_ATTR_TYPE_DESC( cpub_ava3[1], DS_ATTRIBUTE_TYPE, DS_A_ORG_NAME); OMX_ZSTRING_DESC( cpub_ava3[2], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "Digital Equipment Corporation"); OMX_OM_NULL_DESC( cpub_ava3[3]); OMX_CLASS_DESC( cpub_ava4[0], DS_C_AVA); OMX_ATTR_TYPE_DESC( cpub_ava4[1], DS_ATTRIBUTE_TYPE, DS_A_COUNTRY_NAME); OMX_ZSTRING_DESC( cpub_ava4[2], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "US"); OMX_OM_NULL_DESC( cpub_ava4[3]); OMX_CLASS_DESC( cpub_rdn1[0], DS_C_DS_RDN); OMX_OBJECT_DESC( cpub_rdn1[1], DS_AVAS, cpub_ava1); OMX_OM_NULL_DESC( cpub_rdn1[2]); OMX_CLASS_DESC( cpub_rdn2[0], DS_C_DS_RDN); OMX_OBJECT_DESC( cpub_rdn2[1], DS_AVAS, cpub_ava2); OMX_OM_NULL_DESC( cpub_rdn2[2]); OMX_CLASS_DESC( cpub_rdn3[0], DS_C_DS_RDN); OMX_OBJECT_DESC( cpub_rdn3[1], DS_AVAS, cpub_ava3); OMX_OM_NULL_DESC( cpub_rdn3[2]); OMX_CLASS_DESC( cpub_rdn4[0], DS_C_DS_RDN); OMX_OBJECT_DESC( cpub_rdn4[1], DS_AVAS, cpub_ava4); OMX_OM_NULL_DESC( cpub_rdn4[2]); OMX_CLASS_DESC( cpub_dn[0], DS_C_DS_DN); OMX_OBJECT_DESC( cpub_dn[1], DS_RDNS, cpub_rdn4); OMX_OBJECT_DESC( cpub_dn[2], DS_RDNS, cpub_rdn3); OMX_OBJECT_DESC( cpub_dn[3], DS_RDNS, cpub_rdn2); OMX_OBJECT_DESC( cpub_dn[4], DS_RDNS, cpub_rdn1); OMX_OM_NULL_DESC( cpub_dn[5]); /* create the OM private object: name */ om_status = om_create(DS_C_DS_DN, OM_FALSE, workspace, &name); /* Copy the attribute list from the cpub_dn public object into */ /* the name private object */ om_status = om_put(name, OM_REPLACE_ALL, cpub_dn, 0,0,0); /* call the ds_read function using Name as a parameter and */ /* select only the information specified by rdn_type_list */ status = ds_read(bound_session, context, name, DS_SELECT_ALL_TYPES_AND_VALUES, &read_result, &invoke_id); if (status == DS_SUCCESS) { printf("READ request was successful\n"); } else { printf("READ request 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, &read_result, &invoke_id); if (status == DS_SUCCESS) { switch (completion_flag) { case DS_COMPLETED_OPERATION: /* we have a completed operation */ /* now see what we have got back ... */ if (operation_status == DS_SUCCESS) { om_status = om_get(read_result, OM_NO_EXCLUSIONS, 0, 0, 0, OM_ALL_VALUES, &spub_result, &desc_count); if (om_status == OM_SUCCESS) { /* check desc_count != 0 */ /* results now available in public object */ /* spub_result */ } else { /* error getting results */ /* search_result not deleted */ } } else {...} break; case DS_OUTSTANDING_OPERATIONS: ... break; case DS_NO_OUTSTANDING_OPERATION: ... break; } } } }

The above example shows:

• How to define a private object containing a distinguished name.
• How to define a DS-DN OM public object (cpub_dn) containing the entry's distinguished name: /C=US/O=Digital Equipment Corporation/OU=Research/CN=Albert Einstein
• How to use the OM Create function to create a DS-DN OM private object (name) and how to use the OM Put function to copy the distinguished name from the public object (cpub_dn) into the newly created private object (name).
• How to use the Receive Result function to obtain the result of the Read function.
• How to use the OM Get function to copy the attributes of the Read-Result OM private object into the Read-Result OM public object (Spub_Result) for examination.
  The OM Create, OM Put, and the OM Get functions are assumed to succeed.

  OM_private_object bound_session, name, context; { DS_status status; OM_private_object name; status = ds_read(bound_session, DS_DEFAULT_CONTEXT, name, selection, &info, NULL); if (status == DS_SUCCESS) { printf("READ was successful\n"); } else { printf("READ failed\n"); } }

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

  { OM_workspace workspace; OM_descriptor cpub_dn[7]; OM_descriptor cpub_rdn0[3]; OM_descriptor cpub_rdn1[3]; OM_descriptor cpub_rdn2[3]; OM_descriptor cpub_rdn3[3]; OM_descriptor cpub_rdn4[3]; OM_descriptor cpub_ava0[4]; OM_descriptor cpub_ava1[4]; OM_descriptor cpub_ava2[4]; OM_descriptor cpub_ava3[4]; OM_descriptor cpub_ava4[4]; OM_value_position desc_count; DS_status status; OM_sint invoke_id; OM_uint completion_flag; DS_status operation_status; OM_return_code om_status; OM_private_object name, read_result; OM_public_object spub_result; OMX_CLASS_DESC( cpub_ava0[0], DS_C_AVA); OMX_ATTR_TYPE_DESC( cpub_ava0[1], DS_ATTRIBUTE_TYPE, DSX_TYPELESS_RDN); OMX_ZSTRING_DESC( cpub_ava0[2], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "CDS"); OMX_OM_NULL_DESC( cpub_ava0[3]); OMX_CLASS_DESC( cpub_ava1[0], DS_C_AVA); OMX_ATTR_TYPE_DESC( cpub_ava1[1], DS_ATTRIBUTE_TYPE, DSX_TYPELESS_RDN); OMX_ZSTRING_DESC( cpub_ava1[2], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "Projects"); OMX_OM_NULL_DESC( cpub_ava1[3]); OMX_CLASS_DESC( cpub_ava2[0], DS_C_AVA); OMX_ATTR_TYPE_DESC( cpub_ava2[1], DS_ATTRIBUTE_TYPE, DS_A_ORG_UNIT_NAME); OMX_ZSTRING_DESC( cpub_ava2[2], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "Research"); OMX_OM_NULL_DESC( cpub_ava2[3]); OMX_CLASS_DESC( cpub_ava3[0], DS_C_AVA); OMX_ATTR_TYPE_DESC( cpub_ava3[1], DS_ATTRIBUTE_TYPE, DS_A_ORG_NAME); OMX_ZSTRING_DESC( cpub_ava3[2], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "Digital Equipment Corporation"); OMX_OM_NULL_DESC( cpub_ava3[3]); OMX_CLASS_DESC( cpub_ava4[0], DS_C_AVA); OMX_ATTR_TYPE_DESC( cpub_ava4[1], DS_ATTRIBUTE_TYPE, DS_A_COUNTRY_NAME); OMX_ZSTRING_DESC( cpub_ava4[2], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "US"); OMX_OM_NULL_DESC( cpub_ava4[3]); OMX_CLASS_DESC( cpub_rdn0[0], DS_C_DS_RDN); OMX_OBJECT_DESC( cpub_rdn0[1], DS_AVAS, cpub_ava0); OMX_OM_NULL_DESC( cpub_rdn0[2]); OMX_CLASS_DESC( cpub_rdn1[0], DS_C_DS_RDN); OMX_OBJECT_DESC( cpub_rdn1[1], DS_AVAS, cpub_ava1); OMX_OM_NULL_DESC( cpub_rdn1[2]); OMX_CLASS_DESC( cpub_rdn2[0], DS_C_DS_RDN); OMX_OBJECT_DESC( cpub_rdn2[1], DS_AVAS, cpub_ava2); OMX_OM_NULL_DESC( cpub_rdn2[2]); OMX_CLASS_DESC( cpub_rdn3[0], DS_C_DS_RDN); OMX_OBJECT_DESC( cpub_rdn3[1], DS_AVAS, cpub_ava3); OMX_OM_NULL_DESC( cpub_rdn3[2]); OMX_CLASS_DESC( cpub_rdn4[0], DS_C_DS_RDN); OMX_OBJECT_DESC( cpub_rdn4[1], DS_AVAS, cpub_ava4); OMX_OM_NULL_DESC( cpub_rdn4[2]); OMX_CLASS_DESC( cpub_dn[0], DS_C_DS_DN); OMX_OBJECT_DESC( cpub_dn[1], DS_RDNS, cpub_rdn4); OMX_OBJECT_DESC( cpub_dn[2], DS_RDNS, cpub_rdn3); OMX_OBJECT_DESC( cpub_dn[3], DS_RDNS, cpub_rdn2); OMX_OBJECT_DESC( cpub_dn[4], DS_RDNS, cpub_rdn1); OMX_OBJECT_DESC( cpub_dn[5], DS_RDNS, cpub_rdn0); OMX_OM_NULL_DESC( cpub_dn[6]); /* create the OM private object: name */ om_status = om_create(DS_C_DS_DN, OM_FALSE, workspace, &name); /* Copy the attribute list from the cpub_dn public object into */ /* the name private object */ om_status = om_put(name, OM_REPLACE_ALL, cpub_dn, 0,0,0); /* call the ds_read function using Name as a parameter and */ /* specify that all attribute types and values be read. */ /* Note that invoke_id parameter is may be set NULL in the */ /* case of synchronous operation. */ status = ds_read(bound_session, DS_DEFAULT_CONTEXT, name, DS_SELECT_ALL_TYPES_AND_VALUES, &read_result, NULL); if (status == DS_SUCCESS) { printf("READ request was successful\n"); om_status = om_get(read_result, OM_NO_EXCLUSIONS, 0, 0, 0, OM_ALL_VALUES, &spub_result, &desc_count); if (om_status == OM_SUCCESS) { /* check desc_count != 0 */ /* results now available in public object */ /* spub_result */ } else { /* error getting results */ /* search_result not deleted */ } } else { printf("READ request failed\n"); } }

  
  The above example shows the synchronous reading of all attribute types and values from the CDS entry /.../C=US/O=Digital Equipment Corporation/OU=Research/Projects/CDS
  Note the use of the special attribute type DSX_TYPELESS_RDN in the rightmost RDNs of the name. The presence of one or more occurrences of this attribute type indicates to the XDS API that a name is a CDS distinguished name.
  Note that the CDS global naming root /... need not be explicitly supplied as the first RDN in a CDS distinguished name. When the XDS API encounters a CDS distinguished name, it will internally prepend the CDS global naming root, unless one of the CDS local naming roots such as /.: or /: has been explicitly supplied.
  A CDS local naming root, if desired, must be explicitly supplied as the first RDN of a distinguished name. It is specified with an attribute type of DSX_TYPELESS_RDN and an attribute value of .: or : as appropriate.
  Note that the Invoke-ID argument is not needed for synchronous operation and is therefore set to NULL. The Bound-Session argument is assumed to have been set up as in Example 1.

Retrieves the result of an asynchronously executed operation.

Syntax

Status = ds_receive_result(Session, Completion-Flag, Operation-Status, Result, Invoke-ID)

C Binding

DS_status ds_receive_result(session, completion_flag, operation_status, result, invoke_id)

DS_status ds_receive_result (
OM_private_object session
OM_uint context<completion_flag_returned>(indent\3) DS_status operation_status_return
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 in which the operation was performed.

Completion-Flag

One of the following values to indicate the status of outstanding asynchronous operations:

• Completed-Operation. At least one outstanding asynchronous operation is completed and its result is available.
• Outstanding-Operations. There are outstanding asynchronous operations but none is completed.
• No-Outstanding-Operation. There are no outstanding asynchronous operations.
  The result of the Completion-Flag parameter is valid if Status has the value Success.
  Upon successful return with Completion-Flag having the value completed-operation, Status and Invoke-ID parameter values for the completed operation are returned.

  Operation-Status	Takes an error value if an error occurred during the execution of the asynchronous directory operation. If no error occurred, then it takes the value success. The possible error values are listed for each individual operation in the corresponding function description.
  	This result is valid only if the status has the value success and Completion-Flag has the value completed-operation.
  Result	The result of the completed asynchronous operation. Its value is the constant Null-Result if the operation was one that does not return a result (Add-Entry, Modify-Entry, Modify-RDN, or Remove-Entry). Otherwise, it is an OM object of the appropriate OM class for the result of the asynchronous operation. You can check the class of the Result by using the OM functions.
  	This result is valid only if the following conditions are true: Status has the value success Completion-Flag has the value completed-operation Operation-Status has the value success
  Invoke-ID	The Invoke-ID of the operation whose result is being returned.
  	This result is valid if the Status has the value success and Completion-Flag has the value completed-operation.

Description

This function is used to retrieve the completed results of an outstanding asynchronous operation.

The function results include two status indications. One, called Status, indicates that the function call itself was successful and is always returned. The other, called Operation-Status, is used to return the status of the completed asynchronous operation and is only returned if there is one. See DEC X.500 Directory Service Programming for information about calling functions asynchronously.

Return Values

Possible return values are as follows:

Return	Description
DS_SUCCESS	The operation completed successfully.
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.

Errors

This function can return pointers to the following error object:

• Library-Error, with problem attribute values of bad-session or miscellaneous
• Any errors related to the completed asynchronous operation are reported in Operation-Status as described above.

Examples

The following code extract shows an example call to the Receive Result function. The Receive Result function is used to obtain the result of an outstanding asynchronous operation.

{ /* Call the Modify Entry function asynchronously using the */ /* changes object as a parameter. The Asynchronous attribute */ /* on the OM Context object has value True */ status = ds_modify_entry(session,context,name,changes,&invoke_id); if (status == DS_SUCCESS) {...} else {...} /* 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: /* operation is complete */ break; case DS_OUTSTANDING_OPERATIONS: ... break; case DS_NO_OUTSTANDING_OPERATION: ... break; } } } }

The Receive Result function uses, as input, the Invoke-ID argument output from the asynchronous function.

Removes an entry from the Directory Information Tree (DIT).

Syntax

Status = ds_remove_entry(Session, Context, Name, Invoke-ID)

C Binding

DS_status ds_remove_entry(session, context, name, invoke_id_return)

DS_status ds_remove_entry (
OM_private_object session
OM_private_object context
OM_object name
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 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 name of the target entry. Any aliases in the name will not be dereferenced.

Invoke_ID

The Invoke-ID of an asynchronous directory operation.

Description

This function is used to remove an entry from the Directory. This may be an object entry or an alias entry. The entry must not have any subordinate entries.

Note 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 Remove 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.
• In CDS, the name parameter supplied to the Remove 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	The entry was removed, 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.

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
• Name-Error, no-such-object
• Referral
• Security-Error
• Service-Error
• Update-Error
• Communications-Error

Examples

The following code extracts show an example call to the Remove Entry function. The Remove Entry function is used to remove an existing directory entry.

There are two examples. The first example shows how to perform an asynchronous Remove Entry operation. The second example shows how to perform a synchronous Remove 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 and the Context argument are 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. An example of how to define a Context argument is shown in the Add Entry function.

OM_private_object bound_session, context, name; { DS_status status; OM_sint invoke_id; OM_uint completion_flag; DS_status operation_status; OM_private_object remove_entry_result; /* Call the Remove Entry function */ status = ds_remove_entry(bound_session, context, name, &invoke_id); if (status == DS_SUCCESS) { printf("REMOVE ENTRY request was successful\n"); } else { printf("REMOVE ENTRY request 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, &remove_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 removes the directory entry, identified in the Name argument, from the directory. Since the operation is executed asynchronously, an invoke identifier is returned in the Invoke-ID argument. This uniquely identifies this specific operation and is therefore used in the subsequent Receive Result function to obtain the result of the operation.

---

Previous

Next

Contents

Index