VMS Help DCE_CDS, cdscp, DESCRIPTION  *Conan The Librarian (sorry for the slow response - running on an old VAX)

   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

1 - 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 (=).

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

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

 1.3 - 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
   DCE$COMMON:[ETC]CDS_ATTRIBUTES.DAT.  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.

   For more information about CDS attributes, see the DCE Directory
   Service module in the DCE Administration Guide.

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

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

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