Document revision date: 5 July 2000
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

Compaq DCE for OpenVMS VAX and OpenVMS Alpha
Reference Guide


Previous Contents Index


replace link(8cds)

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

replace object(8cds)

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

replace subtree(8cds)

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


Part 3
XDS Reference

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.


Chapter 6
XDS Directory Services Reference Pages

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:


ds_intro(3xds)

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:

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


ds_abandon(3xds)

Abandons an outstanding asynchronous operation.

Syntax

Status = ds_abandon(Session, Invoke-ID )

Argument Data Type Access
Session OM_private_object read
Invoke_ID Integer write
Status DS_status  

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.

Note

The DCE XDS interface does not support asynchronous operations.

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:

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.


ds_receive_result(3xds)

Retrieves the result of an asynchronously executed operation.

Syntax

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

Argument Data Type Access
Session OM_private_object read
Completion-Flag Unsigned Integer write
Operation-Status DS_status write
Result OM_private_object write
Invoke-ID Integer write
Status DS_status  

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:

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:

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.


dsX_trace_object(3xds)

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

Syntax

(void ) dsX_trace_object(Object )

Argument Data Type Access
Object OM_object read

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:

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); 
    }  
} 
 


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6533_DCE_REF_PRO_007.HTML