Document revision date: 5 July 2000

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

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

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

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

## 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:
> - 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.

## 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:
> - 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.

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

Previous | Next | Contents | Index

| privacy and legal statement |
6533_DCE_REF_PRO_007.HTML