Digital 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.

Note
This command is an added-value Digital feature that is fully compatible with other DCE products.

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.

Note
This command is an added-value Digital feature that is fully compatible with other DCE products.

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.

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.

Note
This command is an added-value Digital feature that is fully compatible with other DCE products.

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 4
XDS Reference

Chapter 7
XDS Directory Services Reference Pages

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

This chapter provides reference pages for the X/Open Directory Services (XDS) API functions. Digital'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 Digital 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_add_entry(3xds)

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 read
Context OM_private_object read
Name OM_object read
Entry OM_object read
Invoke-ID Integer write
Status DS_status  

C Binding

DS_status ds_add_entry(session, context, name, entry, invoke_id_return)


DS_status ds_add_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 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:

Return Values

Possible return values are as follows:
Return Description
DS_SUCCESS The entry was added, 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 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:

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. 


 
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 successful\n"); 
     } 
     else 
     { 
        printf("ADD 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, 
                                   &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 successful\n"); 
                } 
                break; 
                case DS_OUTSTANDING_OPERATIONS: 
                printf("There are outstanding operations\n"); 
                break; 
                case DS_NO_OUTSTANDING_OPERATION: 
                printf("There are NO outstanding operations\n"); 
  
                break; 
            } 
        } 
    } 
}

The above example shows: