Document revision date: 5 July 2000 | |
Previous | Contents | Index |
Deletes a specified soft link and replaces it with a new soft link to redirect lookups from the original location to the new location.
cdscp replace link link-name [with] link newtree-name
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.
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.
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
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.
cdscp replace object object-name [with] link newtree-name
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.
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.
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
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.
cdscp replace subtree tree-name [with] link newtree-name [norecurse] [exclude entry-type ]
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
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.
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
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:
Introduces the X/OPEN Directory Services (XDS) functions.
#include <xom.h>
#include <xds.h>
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.
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.
Status = ds_abandon(Session, Invoke-ID )
Argument | Data Type | Access |
---|---|---|
Session | OM_private_object | read |
Invoke_ID | Integer | write |
Status | DS_status |
DS_status ds_abandon(session, invoke_id)
DS_status ds_abandon (
OM_private_object session
OM_sint invoke_id)
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.
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.
The DCE XDS interface does not support asynchronous operations. |
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.
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.
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.
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 |
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)
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.
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.
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.
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.
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.
(void ) dsX_trace_object(Object )
Argument | Data Type | Access |
---|---|---|
Object | OM_object | read |
dsX_trace_object(object)
dsX_trace_objectobject
OM_object object
OM_Object
The object whose content you want to inspect.
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.
None.
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 |