NAME

clearinghouse - A dcecp object that manages a clearinghouse in CDS

SYNOPSIS

clearinghouse catalog [cell_name] [-simplename] clearinghouse create clearinghouse_name_list clearinghouse delete clearinghouse_name_list clearinghouse disable clearinghouse_name_list clearinghouse help [operation | -verbose] clearinghouse initiate clearinghouse_name_list -checkpoint clearinghouse operations clearinghouse repair clearinghouse_name_list -timestamps clearinghouse show clearinghouse_name_list [-schema | -all | [-counters] [ -attributes]] clearinghouse verify clearinghouse_name_list

ARGUMENTS

cell_nameThe name of a single cell.  The name must be a fully qualified cell name as shown in either of the following:

/.:
 
/.../their_cell.goodco.com

clearinghouse_name_list
A list of one or more names of clearinghouses you want to operate on. A clearinghouse can be specified in either of the following forms:

/.:/name_ch
 
/.../cell_name/name_ch

operationThe name of the clearinghouse operation for which to display help information. 

DESCRIPTION

The clearinghouse object represents Cell Directory Service (CDS) clearinghouses.  Clearinghouses are databases located on CDS server machines that store data (directories, objects, and links) in CDS.  On the server machines are files that contain the actual clearinghouse data.  Clearinghouses are also represented in the CDS namespace by an entry that contains information about the clearinghouse.  You must run the create operation on the host where you want to create the new clearinghouse and the delete, disable, initiate, repair, and verify operations on the host where the clearinghouse to be operated on resides. 

ATTRIBUTES

The following are the CDS-defined attributes that may be present in CDS clearinghouse objects:

CDS_AllUpTo
Indicates the date and time the clearinghouse object has been updated to reflect the CDS_CHDirectories attribute.

CDS_CHDirectories
Specifies the full name and Universal Unique Identifier (UUID) of every directory that has a replica in this clearinghouse.

CDS_CHLastAddress
Specifies the current reported network address of the clearinghouse.

CDS_CHName
Specifies the full name of the clearinghouse.

CDS_CHState
Specifies the state of the clearinghouse.  The state on indicates the clearinghouse is running and available.

CDS_CTSSpecifies the creation timestamp (CTS) of the clearinghouse. 

CDS_DirectoryVersion
Specifies the current version of the directory in the clearinghouse in which the directory was created.

CDS_NSCellname
Specifies the name of the cell in which the clearinghouse resides.

CDS_ObjectUUID
Specifies the UUID of the clearinghouse.  This read-only attribute is set by the system when the clearinghouse is created and cannot be modified by the user.

CDS_ReplicaVersion
Specifies the current version of the replica in which the directory was created.  The default is 3.0.  If an upgrade has taken place, the value will upgrade to 4.0.

CDS_UpgradeTo
A single-valued attribute used to control the upgrading of a clearinghouse from one version of CDS to another.  By modifying this attribute, the process of upgrading a clearinghouse to a newer version of CDS may be initiated.

CDS_UTSSpecifies the DTS-style, read-only timestamp of the most recent update to an attribute of the clearinghouse.  The value is set by the system. 

Counters

corruptionsSpecifies the number of times that a clearinghouse generated a data corruption event. 

disablesSpecifies the number of times that the clearinghouse was disabled since it was last started. 

enablesSpecifies the number of times that the clearinghouse was enabled since it was last started, not including the initial startup. 

failedupgrades
Specifies the number of times that upgrades failed when using the CDS-UpgradeTo attribute.

missingentries
Specifies the number of times the clearinghouse entry missing event was generated.

readsSpecifies the number of read operations directed to this clearinghouse. 

returnedrefsSpecifies the number of requests directed to this clearinghouse that resulted in the return of a partial answer instead of satisfying the client’s entire request. 

rootunreachables
Specifies the number of times the root lost event was generated by the clearinghouse.

skulkfailuresSpecifies the number of times that a skulk of a directory, initiated from this clearinghouse, failed to complete (usually because one of the replicas in the replica set was unreachable). 

writesSpecifies the number of write operations directed to this clearinghouse. 

See the OSF DCE Administration Guide for more information about clearinghouse attributes and counters. 

OPERATIONS

clearinghouse catalog

Returns a list of the names of all clearinghouses in a cell.  The syntax is as follows: clearinghouse catalog [cell_name] [-simplename] Option

-simplenameReturns a list of clearinghouse names in a cell without prepending the cellname. 

The catalog operation returns a list of the names of all clearinghouses in a cell.  If you do not specify the optional cell_name argument, the cell name defaults to /.:.  Privileges Required No special privileges are needed to use the clearinghouse catalog command.  Examples

dcecp> clearinghouse catalog
/.../dcecp.cell.osf.org/frick_ch
dcecp>
 dcecp> clearinghouse catalog -simplename
frick_ch
dcecp>

clearinghouse create

Creates a new clearinghouse on the local machine.  The syntax is as follows: clearinghouse create clearinghouse_name_list The create operation creates a new clearinghouse on the local machine.  The clearinghouse_name_list argument is a list of one or more names of the clearinghouses you want to create. Clearinghouses should only be named in the root directory (that is, /.:).  This operation also stores a read-only replica of the root directory in the new clearinghouse.  The process that creates the new clearinghouse initiates a skulk of the root directory, so all replicas of the root should be reachable when you enter the clearinghouse create command.  To ensure this, perform an immediate skulk of /.: prior to invoking the command, using the directory synchronize /.: command. This operation returns an empty string on sucess. Privileges Required You need w (write) permission to the server on which you intend to create the clearinghouse, and A (Admin) permission to the cell root directory.  The server principal needs r (read), w (write), and A (Admin) permission to the cell root directory. Examples The following command creates a clearinghouse named /.:/Boston_CH on the local server system:

dcecp> clearinghouse create /.:/Boston_CH
dcecp>

clearinghouse delete

Deletes the specified clearinghouse from the local machine.  The syntax is as follows: clearinghouse delete clearinghouse_name_list The delete operation deletes the specified clearinghouse from the local server system. The clearinghouse_name_list argument is a list of one or more names of the clearinghouses you want to delete. Clearinghouses that contain master replicas of directories are not deleted (and also return errors).  This command also automatically deletes all read-only replicas from the clearinghouse; however, you should delete all read-only replicas by hand (see directory delete ­-replica) before invoking this command since invoking many skulks will cause the command to execute more slowly.  This operation returns an empty string on success. CDS does not permit you to delete a disabled (cleared) clearinghouse. Before you can delete a disabled (cleared) clearinghouse, you must recreate it using the clearinghouse create command. Privileges Required You must have w (write) and d (delete) permission to the clearinghouse and A (Admin) permission to all directories that store replicas in the clearinghouse.  The server principal must have d (delete) permission to the associated clearinghouse object entry and A (Admin) permission to all directories that store replicas in the clearinghouse. Examples The following command deletes a clearinghouse named /.:/Orion_CH from the local server system:

dcecp> clearinghouse delete /.:/Orion_CH
dcecp>

clearinghouse disable

Removes knowledge of the specified clearinghouse from the local server’s memory.  The syntax is as follows: clearinghouse disable clearinghouse_name_list The disable operation removes knowledge of the specified clearinghouse from the local server’s memory. The clearinghouse_name_list argument is a list of names of one or more clearinghouses you want to disable. Use this command when relocating a clearinghouse. This command removes the name of the prefix of the clearinghouse files from the /opt/dcelocal/var/directory/cds/cds_files file and notifies the local CDS server that the clearinghouse is disabled.  The clearinghouse entry is not removed from the namespace, nor are the datafiles associated with the clearinghouse removed.  This operation returns an empty string on success. Privileges Required You must have w (write) permission to the CDS server on which the clearinghouse resides. Examples The following command disables the clearinghouse /.:/Paris2_CH so that it can be moved to another server:

dcecp> clearinghouse disable /.:/Paris2_CH
dcecp>

clearinghouse help

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

-verboseDisplays information about the clearinghouse object. 

Used without an argument or option, the clearinghouse help command returns brief information about each clearinghouse 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 clearinghouse object itself.  Privileges Required No special privileges are needed to use the clearinghouse help command.  Examples

dcecp> clearinghouse help
catalog             Returns the names of all clearinghouses in a cell.
create              Creates the named clearinghouse.
delete              Deletes the named clearinghouse.
disable             Disables the named clearinghouse.
initiate            Initiates an action on the named CDS clearinghouse.
repair              Repairs an aspect of the named CDS clearinghouse.
show                Returns the attributes of a clearinghouse.
verify              Verifies the consistency of the clearinghouse.
help                Prints a summary of command-line options.
operations          Returns a list of the valid operations for this command.
dcecp>

clearinghouse initiate

Initiates a defined action on the specified clearinghouse on the local machine.  The syntax is clearinghouse initiate clearinghouse_name_list -checkpoint Options

-checkpointForces the clearinghouse to checkpont to disk. 

The initiate operation initiates a defined action on the specified clearinghouse.  The required clearinghouse_name_list argument is a list of one or more names of clearinghouses you want to initiate actions on.  Currently, only a checkpoint action is available.  This operation returns an empty string on success.  Privileges Required You need w (write) permission on the clearinghouse server and A (admin) permission on the cell root directory.  The server principal needs rwA (*Lread, write, and administer) permission on the cell root directory.  Examples The following command initiates a checkpoint operation on the clearinghouse named /.:/oddball_ch on the local system. 

dcecp> clearinghouse initiate /.:/oddball_ch -checkpoint
dcecp>

clearinghouse operations

Returns a list of the operations supported by the clearinghouse object.  The syntax is as follows: clearinghouse 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 clearinghouse operations command. Examples

dcecp> clearinghouse operations
catalog create delete disable initiate repair show verify help operations
dcecp>

clearinghouse repair

Repairs a specific problem on a specified clearinghouse on the local machine.  The syntax is clearinghouse repair clearinghouse_name_list -timestamps Options

-timestampsAnalyzes and repairs invalid timestamps found in a clearinghouse. 

Use the repair operation to fix various problems that can occur in a clearinghouse.  The required clearinghouse_name_list argument is a list of one or more names of clearinghouses you want to initiate repair actions on.  Currently, only invalid timestamps can be repaired.  This operation returns an empty string on success.  Privileges Required You need w (write) permission to the clearinghouse server and A (Admin) permission to the cell root directory.  The server principal needs r (read), w (write), and A (Admin) permission to the cell root directory.  Examples The following command repairs invalid timestamps in a clearinghouse named /.:/blech_ch on the local system. 

dcecp> clearinghouse repair /.:/blech_ch -timestamps
dcecp>

clearinghouse show

Returns attribute and counter information associated with the specified clearinghouses on local or remote machines.  The syntax is as follows: clearinghouse show clearinghouse_name_list [-schema | -all | [-counters] [-attributes]] Options

-schemaIndicates whether attributes are single-valued or multi-valued. 

-allReturns the attributes and counters for the clearinghouse. 

-attributesReturns the attributes for the clearinghouse. 

-countersReturns the counters for the clearinghouse. 

The show operation displays attribute and counter information associated with the clearinghouses specified by clearinghouse_name_list, which is a list of one or more names of the clearinghouses.  If more than one clearinghouse is specified, the attributes of all the clearinghouses are concatenated into one list.  The order of the returned attributes is the lexical order of the object identifiers (OIDs) of each attribute for each clearinghouse.  If you supply no options, clearinghouse show returns the attributes associated with the specified clearinghouse.  Privileges Required You must have r (read) permission to the clearinghouse.  Examples

dcecp> clearinghouse show /.:/drkstr_ch
{CDS_CTS 1994-06-18-20:16:22.150-05:00I0.000/00-00-c0-f7-de-56}
{CDS_UTS 1994-06-19-17:17:43.911-05:00I0.000/00-00-c0-f7-de-56}
{CDS_ObjectUUID 0066ccea-d978-1db3-8259-0000c0f7de56}
{CDS_AllUpTo 1994-07-01-21:30:18.948-05:00I0.000/00-00-c0-f7-de-56}
{CDS_DirectoryVersion 3.0}
{CDS_CHName /.../terrapin/drkstr_ch}
{CDS_CHLastAddress
 {Tower ncacn_ip_tcp 130.105.5.16}
 {Tower ncadg_ip_udp 130.105.5.16}}
{CDS_CHState on}
{CDS_CHDirectories
 {{Dir_UUID 00146037-d97b-1db3-8259-0000c0f7de56}
  {Dir_Name /.../terrapin}}
 {{Dir_UUID 0043797a-d991-1db3-8259-0000c0f7de56}
  {Dir_Name /.../terrapin/subsys}}
 {{Dir_UUID 004faa42-d992-1db3-8259-0000c0f7de56}
  {Dir_Name /.../terrapin/subsys/HP}}
 {{Dir_UUID 004fa65a-d993-1db3-8259-0000c0f7de56}
  {Dir_Name /.../terrapin/subsys/HP/sample-apps}}
 {{Dir_UUID 004b1130-d994-1db3-8259-0000c0f7de56}
  {Dir_Name /.../terrapin/subsys/dce}}
 {{Dir_UUID 00498a0e-d995-1db3-8259-0000c0f7de56}
  {Dir_Name /.../terrapin/subsys/dce/sec}}
 {{Dir_UUID 003ed80c-d996-1db3-8259-0000c0f7de56}
  {Dir_Name /.../terrapin/subsys/dce/dfs}}
 {{Dir_UUID 003d4d8e-d997-1db3-8259-0000c0f7de56}
  {Dir_Name /.../terrapin/hosts}}
 {{Dir_UUID 003bc522-d998-1db3-8259-0000c0f7de56}
  {Dir_Name /.../terrapin/hosts/drkstr}}
 {{Dir_UUID 0089ee8c-44e0-1dbe-929b-0000c0f7de56}
  {Dir_Name /.../terrapin/help}}
 {{Dir_UUID 001c6cea-00fb-1dc5-929b-0000c0f7de56}
  {Dir_Name /.../terrapin/test_1}}
 {{Dir_UUID 00440fe8-02a1-1dc5-929b-0000c0f7de56}
  {Dir_Name /.../terrapin/dirmod}}}
{CDS_ReplicaVersion 3.0}
{CDS_NSCellname /.../terrapin}
dcecp>

dcecp> clearinghouse show /.:/Chicago1_CH -counters
{corruptions 0}
{disables 0}
{enables 1}
{failedupgrades 0}
{missingentries 0}
{reads 2336}
{returnedrefs 2}
{rootunreachables 0}
{skulkfailures 0}
{writes 68}
dcecp>

clearinghouse verify

Verifies the consistency of the specified clearinghouse on the local machine.  The syntax is clearinghouse verify clearinghouse_name_list The verify operation verifies the consistency of the specified clearinghouse by checking internal attributes.  The required clearinghouse_name_list argument is a list of one or more names of clearinghouses you want to verify.  This operation returns an empty string on success. Privileges Required You need w (write) permission to the clearinghouse server and A (Admin) permission to the cell root directory.  The server principal needs r (read), w (write), and A (Admin) permission to the cell root directory. Examples The following command verifies the consistency of clearinghouses named /.:/gumby_ch and /.:/pokey_ch.

dcecp> clearinghouse verify {/.:/gumby_ch /.:/pokey_ch}
dcecp>

RELATED INFORMATION

Commands:

cdsd(1m) dcecp(1m), dcecp_cdscache(1m), dcecp_directory(1m), dcecp_link(1m), dcecp_object(1m). 

Hewlett-Packard Company  —  OSF DCE 1.1/HP DCE 1.5