NAME

cdscp - Starts the CDS control program

SYNOPSIS

cdscp  [cdscp-command]

ARGUMENTS

cdscp-command

Optionally, specifies one of the following control commands:

add directory: Adds a value to a modifiable, set-valued attribute (including application-defined attributes) of a directory
add object: Adds a value to a modifiable, set-valued attribute (including application-defined attributes) of an object entry
clear cached server: Removes knowledge of a server that you had specifically defined from the local clerk's cache
clear clearinghouse: Removes knowledge of the specified clearinghouse from the server's memory
create child: Creates a child pointer at the master replica of the parent directory
create clearinghouse: Creates a clearinghouse on the local server system or makes an existing clearinghouse available
create directory: Creates a directory
create link: Creates a soft link and optionally specifies an expiration time and an extension time
create object: Creates a new object entry
create replica: Creates a replica of an existing directory in the specified clearinghouse
define cached server: Creates knowledge of a server in the local clerk's cache
delete child: Deletes a child pointer from the namespace
delete clearinghouse: Deletes the specified clearinghouse from the local server system
delete directory: Deletes a directory
delete link: Deletes a soft link
delete object: Deletes an object entry
delete replica: Deletes a read-only replica of a directory from a clearinghouse
disable clerk: Stops the clerk on the local system
disable server: Stops the server on the local system
dump clerk cache: Displays the contents of the clerk cache
help: Displays a list of the CDS control program commands
list child: Displays a list of all the child pointers whose names match the specified child name
list clearinghouse: Displays a list of all the clearinghouses whose names match the specified clearinghouse name
list directory: Displays a list of all the directories whose names match the specified directory name
list link: Displays a list of all the soft links whose names match the specified link name
list object: Displays a list of all the object entries (including clearinghouse object entries) whose names match the specified object entry name
remove directory: Removes a value from a set-valued or single-valued attribute (including application-defined attributes) of a directory
remove link: Removes a soft link's timeout value attribute
remove object: Removes a value from a set-valued or single-valued attribute (including application-defined attributes) of an object entry
set cdscp confidence: Sets the confidence level of clerk calls issued as a result of CDS control program commands
set cdscp preferred clearinghouse: Specifies a preferred clearinghouse to use for satisfying read requests that result from CDS control program commands
set directory: Changes the value of a modifiable, single-valued attribute of a directory
set directory to new epoch: Reconstructs a directory's replica set, allowing you to designate a new master replica or to exclude a replica
set directory to skulk: Starts the skulk of a directory immediately
set link: Changes the value of a modifiable, single-valued attribute of a soft link
set object: Changes the value of a modifiable, single-valued attribute of an object entry
show cached clearinghouse: Displays current information about the specified cached clearinghouse
show cached server: Displays address information of a server in the local clerk's cache
show cdscp confidence: Displays the current confidence level of clerk calls resulting from CDS control program commands
show cdscp preferred clearinghouse: Displays the preferred clearinghouse for satisfying read requests that result from CDS control program commands
show cell: Displays the information you need to create a cell entry in either DNS or GDS
show child: Displays attribute information about the specified child pointer
show clearinghouse: Displays attribute information about the specified clearinghouse
show clerk: Displays attribute information about the CDS clerk on the local system
show directory: Displays attribute information about the specified directory
show link: Displays attribute information about the specified soft link
show object: Displays attribute information about the specified object entry
show replica: Displays attribute information about the specified replica
show server: Displays attribute information about the server running on the local system

NOTES

With the exception of the following subcommands, this command is replaced at Revision 1.1 by the dcecp command. This command may be fully replaced by the dcecp command in a future release of DCE, and may no longer be supported at that time.

disable clerk
disable server
help
set cdscp confidence
set directory to new epoch
show cdscp confidence
show cell
show clerk
show server

DESCRIPTION

The Cell Directory Service (CDS) control program is a command line interface for managing the components of the Cell Directory Service and the contents of the namespace.

You can use the control program commands from within the control program or from the system prompt. To use the control program commands from inside the control program, start the control program by using the cdscp command alone, without any argument. This enters the control program, which displays the control program prompt (cdscp>).

$ cdscp 
cdscp>

At this prompt, you can enter any control program command; for example:

cdscp> show server

Use the command do filename from inside the control program to read a file of commands.

To leave the control program and return to the system prompt, use the quit command. To use the control program commands from the system prompt, enter the cdscp command with an internal command of the CDS control program as the first argument. The control program executes the command immediately, without displaying the control program prompt. For example, you can enter the show server command as follows:

$ cdscp show server

Elements of a CDS Command

All CDS control program commands must include a verb, an entity name, and all required arguments. Depending on the command, you can also specify optional arguments and attributes. A space must separate more than one attribute or argument. A space must precede and follow an equal sign (=).

Verbs

The following is a list of the definitions of verbs used in control program commands:

add: Adds a value to a modifiable, set-valued attribute
clear: Removes knowledge of a cached clearinghouse or cached server from memory
create: Creates an entity
define: Creates knowledge of a locally cached server
delete: Deletes an entity
disable: Stops operation of a clerk or server
dump: Displays the contents of a clerk cache
list: Displays a list of specified entity names
remove: Removes a value from a set-valued or single-valued attribute
set: Changes the value of a modifiable, single-valued attribute
show: Displays attribute information

Entity Names

Any individually manageable piece of CDS is called an entity. A set of commands exists for each entity. The following is a list of the entities and a description of what each entity represents:

Cached Clearinghouse: A cached clearinghouse is a clearinghouse that a clerk has discovered and cached. A clerk can learn about clearinghouses as a result of configuration information, advertisements received on a LAN, or during the process of finding a name.
Cached Server: A cached server is a server that a clerk has cached as a result of manual configuration through the control program.
Child: A child pointer connects a parent and child directory in a hierarchical namespace. The child pointer is stored in the parent directory and has the same name as the child directory.
Clearinghouse: A clearinghouse is a database containing a collection of directory replicas at a particular server.
Clerk: The clerk is the interface between client applications and servers.
Directory: A directory contains child, object, and link entries that are logically stored under one name (the directory name).
Link: A soft link is a pointer providing an alternate name for an object entry, directory, or other soft link.
Object: An object entry represents a resource (for example, an application) that is named in the namespace.
Replica: A replica is a copy of a directory. Each copy, including the original or master, is referred to as a replica.
Server: A server handles lookup requests from clerks and maintains the contents of the clearinghouse or clearinghouses at its node.

Attributes

Every CDS entity has attributes, which are pieces or sets of data associated with that entity. Attributes can reflect or affect the operational behavior of an entity, record the number of times a particular event or problem occurred since the entity was last enabled, and uniquely distinguish an entity from any other entity. Some attributes have a single value; others contain a set of values.

CDS attributes are identified by ISO object identifiers (OIDs). Every CDS attribute name maps to an OID and a corresponding data type. Usually, client applications define the name of an attribute and its data type. Application programmers should never need to modify (except for the purpose of foreign language translation) the existing CDS labels associated with the unique OIDs in the cds_attributes file. However, programmers can obtain new OIDs from the appropriate allocation authority, create new attributes for their own object entries, and then append them to the existing list. The OID and data type of each attribute are stored in the file /opt/dcelocal/etc/cds_attributes. Descriptions of the CDS data types that applications can use are in the cdsclerk.h file.

All entities have show commands that you can use to display the names and values of specific attributes or all attributes. When you display an attribute that has more than one value, the show command lists each value for the attribute separately. When there are multiple values for an attribute, the command first lists the attribute name on a line ending with a colon, then the parts of the value.

Editing the Commands

You can abbreviate commands, continue a command beyond one line, or redirect output to a file within the control program.

To abbreviate any command name, type only the first four characters. You can abbreviate a command name to fewer than four characters as long as the abbreviated name remains unique among all command names in the control program. For example, the following commands are equivalent:

cdscp> show directory /.:/sales
cdscp> sh dir /.:/sales

To continue a long command line onto the next line, type a space and then a \ (backslash) at the end of the first line, for example:

cdscp> set link /.:/sales CDS_LinkTimeout \
> (1991-12-31-12:00:00 090-00:00:00)

To add a comment, use the # (number sign). Everything following the # character on a line is ignored.

To redirect output to a file, most UNIX shell users can type >filename at the shell prompt. To redirect output of error text to a file, most UNIX shell users can type >&filename at the shell prompt.

For example, the following command redirects the display produced by the show directory command to a new text file named directory_names:

$ cdscp show directory /.:/* >directory_names

Using Wildcard Characters

When entering a name in show and list commands, you can use wildcard characters in the rightmost simple name (the name to the right of the last slash (/) in the full pathname). The asterisk (*) matches 0 or more characters in a simple name. The question mark (?) matches exactly one character in a simple name.

When you use an asterisk or a question mark as a normal character in the rightmost simple name of a show or list command, escape it with a backslash (\* or \?). Otherwise, the character is interpreted as a wildcard.

You cannot use wildcard characters in show clerk and show server commands.

Privilege Required

CDS supports the following DCE permissions: read (r), write (w), insert (i), delete (d), test (t), control (c), and administer (a). Each permission has a slightly different meaning, depending on the kind of CDS name with which it is associated. In general, the permissions are defined as follows:

Read

Allows a principal to look up a name and view the attribute values associated with it.

Write

Permission allows a principal to change the modifiable attributes associated with a name, except the name's access control list (ACL) entries.

Insert

Permission (for use with directory entries only) allows a principal to create new names in a directory.

Delete

Permission allows a principal to delete a name from the namespace.

Test

Permission allows a principal to test whether an attribute of a name has a particular value without being able to actually see any of the values (that is, without having read permission to the name).

Test permission provides application programs a more efficient way to verify a CDS attribute value. Rather than reading an entire set of values, an application can test for the presence of a particular value.

Control

Permission allows a principal to modify the ACL entries associated with a name. (Note that read permission is also necessary for modifying a CDS entry's ACLs; otherwise, acl_edit will not be able to bind to the entry.) Control permission is automatically granted to the creator of a CDS name.

Administer

Permission (for use with directory entries only) allows a principal to issue CDS control program commands that control the replication of directories.

The creator of a name is automatically granted all permissions appropriate for the type of name created. For example, a principal creating an object entry is granted read, write, delete, test, and control permission to the object entry. A principal creating a directory is granted read, write, insert, delete, test, control, and administer permission to the directory.

EXAMPLES

The following command starts the CDS control program:

$ cdscp
cdscp>

The following command operates from the system prompt to display the attributes of the CDS clerk on the local system:

$ cdscp show clerk

RELATED INFORMATION

Books: Transarc DCE Administration Guide