Document revision date: 5 July 2000

Deletes a specified soft link and replaces it with a new soft link to redirect lookups from the original location to the new location.

Synopsis

cdscp replace link link-name [with] link newtree-name

Parameters

link-name

The full name of the soft link in its old location.

newtree-name

The full name of the directory into which the soft link has moved.

Description

The replace link command deletes a specified soft link and replaces it with a soft link whose link target is the corresponding entry in the directory you specify in the newtree-name argument. This command is useful when you need to redirect lookups for only a subset of a directory's contents.

Permissions Required

You must have insert permission to the directory in which you intend to create the soft link. You also need either delete permission to the soft link or administer permission to the directory that stores the soft link.

Example

The following command replaces the soft link /.:/eng/link1 with a new soft link whose link target is the corresponding entry in the /.:/rnd directory. The link target attribute (CDS_LinkTarget) of the new soft link will point to /.:/rnd/eng/link1 .

cdscp> replace link /.:/eng/link1 with link /.:/rnd

See Also

replace_object
replace_subtree

Deletes a specified object entry and replaces it with a new soft link whose link target is the corresponding entry in a new location.

Synopsis

cdscp replace object object-name [with] link newtree-name

Parameters

object-name

The full name of the object entry in its old location.

newtree-name

The full name of the directory into which the object entry has moved.

Description

The replace object command deletes a specified object entry and replaces it with a soft link whose link target is the corresponding entry in the directory you specify in newtree-name. This command is useful when you need to redirect lookups only for a subset of a directory's contents.

Permissions Required

You must have insert permission to the directory in which you intend to create the soft link. You also need either delete permission to the object entry or administer permission to the directory that stores the object entry.

Example

The following command replaces the object entry /.:/admin/obj2 with a soft link whose link target is the corresponding entry in the directory /.:/sales. The link target attribute (CDS_LinkTarget) of the new soft link will point to /.:/sales/admin/obj2.

cdscp> replace object /.:/admin/obj2 with link /.:/sales

See Also

replace_link
replace_subtree

Deletes the contents of a subtree that has just been merged or appended to a new location and replaces the information with soft links whose link targets are the corresponding entries in the new location.

Synopsis

cdscp replace subtree tree-name [with] link newtree-name [norecurse] [exclude entry-type ]

Parameters

tree-name

The full name of the topmost directory in the subtree.

newtree-name

The full name of the topmost directory in the target subtree.

entry-type

One or more of the following types of entries to exclude from the change: object entries, soft links, or directories. Use any combination of the following entry-type specifiers, separating multiple arguments with commas. You must leave a blank character space after each comma and after each directory-name specification.

acls
objects
links
directory directory-name

Description

The replace subtree command deletes the contents of a subtree that has just been merged or appended to a new location and replaces the information with soft links whose link targets are the corresponding entries in the new location. This command is especially useful after you merge or append the CDS namespaces of different cells.

For all entries except clearinghouse object entries, this command deletes the entries in a directory specified in tree-name and replaces them with soft links. These soft links redirect lookups of the names from their old (source) locations to their new (target) locations. The replace subtree command preserves both the clearinghouse object entry and its enclosing directory while deleting the directory's contents and replacing each name with an individual soft link. You can use the optional norecurse keyword to restrict the replacement operation to only the directory (and contents) you specify in tree-name.

Permissions Required

You must have insert permission to the directory in which you intend to create the soft links. You also need either delete permission to the entries in the source directory or administer permission to that directory.

Example

The following command deletes the entries in the directory /.:/sales/quar1 and replaces them with soft links whose link targets are their corresponding entries in /.:/total/quar1 .

cdscp> replace subtree /.:/sales/quar1 with link /.:/total/quar1

See Also

replace_link
replace_object

This part provides two chapters that contain additional reference pages for the Compaq X/Open XDS API functions. Compaq's XDS implementation supports additional directory services functions beyond those supported in OSF DCE. The structure of this part and the additional Compaq services are described here.

For a description of the standard DCE directory service functions, refer to Chapter 4 in the OSF DCE Application Development Reference Manual.

This chapter provides additional reference pages for the X/Open Directory Services (XDS) API functions. Compaq's XDS implementation supports two additional XDS functions, which support asynchronous operations. The functions are as follows:

• The ds_abandon function abandons the outstanding asynchronous function call.
• The ds_receive_result function retrieves completed results of an outstanding asynchronous operation.

Introduces the X/OPEN Directory Services (XDS) functions.

Syntax

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

Description

This reference page lists the XDS interface functions supported in the Compaq X.500 product. XDS provides a C language binding.

Function	Description
ds_abandon	Abandons an outstanding asynchronous operation.
ds_add_entry	Adds a leaf entry to the Directory Information Tree (DIT).
ds_bind	Opens a session with a directory user agent.
ds_compare	Compares a purported attribute value with the attribute value stored in the directory for a particular entry.
ds_initialize	Initializes the interface.
ds_list	Enumerates the immediate subordinates of a particular directory entry.
ds_modify_entry	Performs an atomic modification of a directory entry.
ds_modify_rdn	Changes the Relative Distinguished Name (RDN) of a leaf entry.
ds_read	Queries information on a directory entry by name.
ds_receive_result	Retrieves the result of an asynchronously executed operation.
ds_remove_entry	Removes a leaf entry from the DIT.
ds_search	Finds entries of interest in a portion of the DIT.
ds_shutdown	Shuts down the interface.
ds_unbind	Unbinds from a directory session.
ds_version	Negotiates features of the interface and service.
dsX_trace_object	Displays an explanation of the content of an object.

DCE Notes

The DEC X.500 Directory Service supports asynchronous operations, which the Distributed Computing Environment (DCE) XDS interface does not. Thus, the Abandon and Receive Result functions are included in the Compaq product.

The differences between the X.500 Directory Service and the Cell Directory Service (CDS) are as follows:

• All functions operate on the X.500 name space.
• CDS does not support the Modify RDN or Search functions. The Service-Error unwilling-to-perform is returned if either function is attempted on CDS.
• CDS does not support the X.500 schema. Therefore, CDS does not have:
  • The concept of an object class
  • Mandatory attributes for a given object
  • A set of attributes expressly permitted for a given object
  • A predefined definition of single and multivalued attributes
  
  The absence of the schema means that the usual errors, which are returned by X.500 for breach of the rules, are not returned by CDS.
• The CDS naming Directory Information Tree (DIT) is modeled on a typical file system architecture, in which directories are used to store objects and can contain subdirectories. Leaf objects in the CDS DIT are similar to X.500 naming objects. However, subtree objects are called directories as in a file system directory. All new objects must be added to an existing directory. CDS directory objects cannot be added, removed, modified, or compared using the XDS programming interface.
• In CDS, the naming attribute of an object is not stored in the object. Consequently, in CDS the Read operation never returns this attribute, and the Compare operation applied to this attribute returns with the Attribute-Error \fIconstraint-violation\fP.

See the notes in the relevant reference page for function-specific differences.

Abandons an outstanding asynchronous operation.

Syntax

Status = ds_abandon(Session, Invoke-ID )

C Binding

DS_status ds_abandon(session, invoke_id)

DS_status ds_abandon (
OM_private_object session
OM_sint invoke_id)

Arguments

Session

The Session OM private object that was returned by the Bind function, identifying the directory session in which the operation was submitted to the directory.

Invoke-ID

Identifies the operation that is to be abandoned. You can only abandon interrogatory operations (Compare, List, Read, and Search).

The value of Invoke-ID must be that which was returned by the function call that initiated the asynchronous directory operation that is now to be abandoned.

Description

This function abandons the outstanding asynchronous function call. The asynchronous function is no longer outstanding after the Abandon function returns, and the results of the asynchronous function will never be returned by the Receive-Result function.

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 objects:

• Abandon-Failed
• Communications-Error
• Library-Error, with problem attribute values of bad-session or miscellaneous

The result of the asynchronous operation will not be returned even if an Abandon-Failed error is returned.

Example

The following code extract shows an example call to the Abandon function.

OM_private_object bound_session; OM_sint invoke_id; { DS_status status; status = ds_abandon(bound_session, invoke_id); if (status == DS_SUCCESS) { printf("ABANDON was successful\n"); } else { printf("ABANDON failed\n"); } }

The abandon function abandons the results of the asynchronous operation identified by the Invoke-ID argument.

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.

Displays an explanation of the content of an object on the current output device.

Syntax

(void ) dsX_trace_object(Object )

C Binding

dsX_trace_object(object)

dsX_trace_objectobject
OM_object object

Arguments

OM_Object

The object whose content you want to inspect.

Description

This function displays on the current output device information about the content of an OM object, as follows:

• A full expansion of a public object
• The type of a private object
• Details of the content of an error object
• For a name object or AVA encoded in ASN.1, both the ASCII and hexadecimal representations of the ASN.1 encoding

The routine also checks for null pointers.

Errors

None.

Examples

The following code extract shows an example call to the Trace Object function:

{ OM_workspace workspace; OM_return_code status; OM_object session = NULL; status = om_create(DS_C_SESSION,OM_TRUE,workspace,&session); if (status == OM_SUCCESS) { dsX_trace_object(session); } }

	privacy and legal statement
6533_DCE_REF_PRO_007.HTML