NAME

cdscache - A dcecp object for managing a local CDS cache

SYNOPSIS

cdscache create server_name -binding server_binding

cdscache delete server_name

cdscache discard [-entry entry_name] [-replica replica_name]

cdscache dump

cdscache help [operation | -verbose]

cdscache operations

cdscache show server_name {-server | -clearinghouse}

ARGUMENTS

operationThe name of the cdscache operation that displays help information. 

server_nameThe single simple name of the cached server machine.  A "simple name’ is not a cell-relative name (such as /.:/hosts/pelican).  Some examples of simple names are pelican and hosts/pelican. 

optionA specification to clarify the target of the operation (-entry, -replica). 

DESCRIPTION

The cdscache object represents the Cell Directory Service (CDS) cache on the local node.  The CDS cache contains information about servers and clearinghouses known to the local machine, and also contains user data about CDS entries that have been read.  The create and delete operations apply only to the server information.  The show and dump operations can display additional information.  The discard operation can selectively eliminate cache entries on any client (given the appropriate permissions). 

ERRORS

A representative list of errors that might be returned is not shown here.  Refer to the DCE Problem Determination Guide for complete descriptions of all error messages. 

OPERATIONS

cdscache create

Creates knowledge of a server in the local client’s cache.  The syntax is:
cdscache create server_name -binding server_binding

Options

-binding server_binding
The required ­-binding option lets you specify the binding information for a CDS server.  This option takes a server_binding argument, which is the protocol sequence and network address of the server node.  The string format is as follows:

protocol-sequence:network-address

The dcecp format is as follows:

{protocol-sequence network-address}

A protocol-sequence is a character string identifying the network protocols used to establish a relationship between a client and server.  Protocol sequences have a specific format that depends on the network address that is supplied in the binding; for example ncacn_ip_tcp (for connection-based protocol) or ncadg_ip_udp (for datagram protocol) The network-address is a string representing the network address of the server node. 

The create operation creates knowledge of a server in the local client’s cache.  The server_name argument is the simple name of a cached server.  (An example of a simple name would be pelican, as opposed to a  cell-relative name like /.:/hosts/pelican.)  This command is typically used to provide configuration information manually to a client that cannot configure itself automatically.  Providing configuration information manually may be necessary, for instance, to provide the client with addressing information about a server across a WAN.  Once the client knows about one server, it can find other servers through referrals.  This operation returns an empty string on success. 

Privileges Required

You must have w (write) permission to the client system, /.:/hosts/hostname/cds-clerk. 

Examples

The following command creates knowledge of the server pelican in the local client’s cache:

dcecp> cdscache create pelican -binding ncacn_ip_tcp:16.20.15.25
dcecp>

cdscache delete

Removes knowledge of a server that you had specifically created from the local client’s cache.  The syntax is:
cdscache delete server_name

The delete operation removes knowledge of a server that was specifically created from the local client’s cache.  The required server_name argument is the simple name of a cached server.  (An example of a simple name would be pelican, as opposed to a cell-relative name like /.:/hosts/pelican.)  You can delete only servers that you have specifically created with the cdscache create command.  This operation returns an empty string on success. 

Privileges Required

You must have w (write) permission to the client system, /.:/hosts/hostname/cds-clerk. 

Examples

The following command removes knowledge of the server gumby from the client cache:

dcecp> cdscache delete gumby
dcecp>

cdscache discard

Discards the contents of the client cache.  The syntax is:
cdscache discard [-entry entry_name] [-replica replica_name]

Options

-entry entry_name
Specifies the name of an entry in the clerk cache.

-replica replica_name
Specifies the clearinghouse name of a replica pointer.

Description

The cdscache discard operation eliminates data structures, frees memory, and shrinks the size of the client cache on the host specified by host_name. If host_name is not specified, the operation defaults to the cache that resides on the local host. Only a single host name can be specified. If both -entry and -replica options are specified, the command removes the specified replica pointer from a cached directory entry. 

If a clearinghouse becomes unreachable, attempting to contact it to look up a replica pointer can result in a very time-consuming failure.  If you use the option -replica, all replicas referencing the clearinghouse are removed from all cache directory entries. In this way, all references to an unreachable clearinghouse can be removed. If successful, this operation returns a null string. 

The operation, cdscache discard with the options -entry or -replica, does the following:

       •Deletes only the cached structures specified by the -entry and -replica options. 

       •Does not stop and restart CDS. 

       •Does not stop and restart DCE. 

Privileges Required

If it is a local operation you must have superuser (root) privileges on the client system.  No DCE permissions are required. 

If it is a remote operation you must have permissions on the srvrconf directory of the selected host:

       •I permission on /.:/hosts/<HOSTS>/config/srvrconf

       •x permission on the created server object (that is, x permission in the initial object ACL of /.:/<HOSTS>/config/srvrconf)

       •d permission on the created server object (that is, d permission in the initial object ACL of /.:/<HOSTS>/config/srvrconf)

Examples

The following command discards the entry, job_300 at the clearinghouse named gloria_ch from the client cache on the local host:

dcecp> cdscache discard -entry  /.:/ job_300 -replica /.:/gloria_ch
dcecp>

cdscache dump

Displays the entire contents of the client cache.  The syntax is:
cdscache dump

The cdscache dump operation displays the contents of the client cache on the screen. Use this command when solving CDS problems. 

Privileges Required

You must have superuser (root) privileges on the client system.  No DCE permissions are required. 

Examples

The following command displays the contents of the client cache on the screen (the output is not shown in the example):

dcecp> cdscache dump
dcecp>

cdscache help

Returns help information about the cdscache object and its operations.  The syntax is:
cdscache help [operation | -verbose]

Options

-verboseDisplays information about the cdscache object. 

Description

Used without an argument or option, the cdscache help command returns brief information about each cdscache operation. The optional operation argument is the name of an operation about which you want detailed information. Alternatively, you can use the ­-verbose option for more detailed information about the cdscache object itself. 

Privileges Required

No special privileges are needed to use the cdscache help command. 

Examples

dcecp> cdscache help
create      Adds information about named server in local cds cache.
delete      Removes information about named server from local cds cache.
discard     Discards all cdsadv (CDS advertiser) cache information on the
            specified host.
dump        Dumps all information from local cds cache.
show        Returns information stored in cds cache.
help        Prints a summary of command-line options.
operations  Returns a list of the valid operations for this command.
dcecp>

cdscache operations

Returns a list of the operations supported by the cdscache object.  The syntax is as follows:
cdscache operations

The list of available operations is in alphabetical order except for help and operations, which are listed last. 

Privileges Required

No special privileges are needed to use the cdscache operations command. 

Examples

dcecp> cdscache operations
create delete discard dump show help operations
dcecp>

cdscache show

Returns information about clearinghouses or servers stored in the cache.  The syntax is as follows:
cdscache show server_name {-server | -clearinghouse}

Options

-clearinghouse
This option displays all the names and values of the attributes in the specified cached clearinghouse.  The following are valid attributes:

Creation Time
Specifies the time at which this clearinghouse was added to the cache.

Miscellaneous Operations
Specifies the number of operations other than read and write (that is, skulks, new epochs, and so on) performed by this client on the cached clearinghouse.

Read Operations
Specifies the number of lookup operations of any sort performed by the client on the cached clearinghouse.

TowersSpecifies the protocol sequence and network address of the server that maintains the cached clearinghouse. 

Write Operations
Specifies the number of write operations performed by this client on the cached clearinghouse.

-serverThis option displays address information of a server in the local client’s cache.  The following attributes are valid:

NameThe directory cell name

TowersThe protocol sequence and network address of the server node

The show operation displays information about clearinghouses or servers stored in the cache.  The required server_name argument is the simple name of a server or a CDS name of a clearinghouse for which you want to display information.  You must use one of the ­-clearinghouse or ­-server options to select the information you want to display. 

Privileges Required

You must have r (read) permission to the CDS client. 

Examples

The following command displays all attributes of the cached clearinghouse /.:/claire_ch:

dcecp> cdscache show /.:/claire_ch -clearinghouse
{CH_Name /.../blue.cell.osf.org/claire_ch}
{Created 1994-10-07-11:41:23.131}
{Others 458}
{Reads 150221}
{Tower {ncacn_ip_tcp 130.105.4.158}}
{Tower {ncadg_ip_udp 130.105.4.158}}
{Writes 162}
dcecp>

The following command displays all attributes of the cached server mysystem:

dcecp> cdscache show mysystem -server
{CH_Name /.../terrapin_cell.osf.org/mysystem_ch}
{Tower {ncacn_ip_tcp 130.105.5.16}}
{Tower {ncadg_ip_udp 130.105.5.16}}
dcecp>

RELATED INFORMATION

Commands:

clearinghouse(8dce), dcecp(8dce), directory(8dce), link(8dce), object(8dce).  define_cached-server(8cds).  dump-clerk_cache(8cds).  show_cached-clearinghouse(8cds).  show_cached-server(8cds).