NAME

dts - A dcecp object that manages a dtsd process

SYNOPSIS

dts activate [dts_server] [-abruptly] dts catalog [cell_name] [-simplename] [-global] dts configure [dts_server] {-global | -notglobal} dts deactivate [dts_server] dts help [operation | -verbose] dts modify [dts_server] -change {attribute_list | -attribute value} dts operations dts show [dts_server] [-all | [-attributes] [-counters]] dts stop [dts_server] dts synchronize [dts_server] [-abruptly]

ARGUMENTS

cell_nameThe name of a single cell. This allows access to DTS servers registered in a foreign cell.  The name must be a fully qualified cell name as in either of the following:

/.:
 
/.../foreign_cellname

dts_serverIdentifies the dtsd server to act on.  Supply the name in one of the following forms:

•As a fully qualified name, for example:

/.../cellname/hosts/hostname/dts-entity

•As a string binding for the remote host on which dtsd is running in standard string-binding syntax or in dcecp string syntax, for example:

ncacn_ip_tcp:130.105.1.227
 
{ncacn_ip_tcp 130.105.1.227}

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

DESCRIPTION

The dts object represents the dtsd (DTS daemon) process running on a host.  The DTS process does not maintain stored data as some other objects.  Consequently, the dts object represents the information in and about a process rather than some data stored somewhere as other objects do.  These commands all affect the local dtsd entity by default.  Use the dts_server argument to operate on a remote DCE dtsd.  This argument is a single server entry or string binding representing a dtsd that will be contacted for the operation.  If the _s(dts) convenience variable is set, it is treated as the name of a dtsd to contact for subsequent operations.  If either of these methods is used, the specified server is the only server that will be contacted in an attempt to complete the operation.  The argument on the command line takes precedence over the value of the _s(dts) convenience variable.  These commands do not set the value of this variable after completion.  There are a number of attributes associated with the dts object.  All of these can be viewed with the show operation, and many can be changed with the modify operation.  Attribute arguments can contain a maximum of 80 characters and are recalculated to a normalized date format.  For example, if the input value is 0-0025:10:99.99999999, the result is 1-01:11:39.990.  Timestamps are specified in DTS and ISO formats.  They can be specified in both absolute and relative time formats.  See the OSF DCE Administration Guide for more information. 

ATTRIBUTES

The dts object supports attributes and counters.  Most attributes and counters pertain to dtsd processes in general.  A subset of attributes and counters pertains only to dtsd processes that are enabled as DTS server entities.  The format of all attributes of type relative_time is in DTS-style ([-]DD-HH:MM:SS). 

General Attributes

autotdfchange {yes | no}
Specifies whether automatic changes to the time differential factor are enabled or disabled.  The value is either yes or no. The value is determined by the operating system (that is, it cannot be changed with the modify operation).

clockadjrateSpecifies the rate at which the DTS server or clerk entity adjusts the node’s clock during a synchronization.  This may not be set by a user, but is built into dtsd. 

clockresolution
Specifies the amount of time between system clock ticks.  The value is determined by the operating system (that is, it cannot be changed with the modify operation).

globalservers relative-time
Specifies the set of global servers known by the node.  The information returned for each server is as follows:  the DCE name of the host followed by /self, the last time polled, the last observed time, the last observed skew, a binary value of whether the server was used in the last last synchronization, and the transport time.  These subattributes are called respectively: name, timelastpolled, lastobstime, lastobsskew, inlastsync, and transport.

globaltimeout relative-time
Specifies the amount of time the node waits for a response to a wide area network (WAN) synchronization request before sending another request or declaring a global server to be unavailable.  The number of attempts made to reach the server is controlled by the queryattempts attribute.  The default value is 0-00:00:15.000, and the range of possible values is 0-00:00:00.000 - 0-00:10:00.000.

localserversSpecifies the set of local servers known by the node.  The information returned for each server is as follows: the principal name that the server is running as, the last time polled, the last observed time, the last observed skew, a binary value indicating whether the server was used in the last synchronization, and the transport time.  These subattributes are called respectively: name, timelastpolled, lastobstime, lastobsskew, inlastsync, and transport. 

localtimeout relative-time
Specifies the amount of time the node waits for a response to a synchronization request before sending another request or declaring a server to be unavailable.  The number of attempts made to reach the server is controlled by the queryattempts attribute.  The default is 0-00:00:05.000, and the range of possible values is 0-00:00:00.000 - 0-00:01:00.000.

Note that this attribute controls only the initial contact with a time provider.  During this initial contact, the time-provider itself determines the timeout value for actually reporting back times.  This allows a time provider attached to a slow source like a modem to request that dtsd wait for a longer interval. 

maxdriftrateSpecifies the worst-case drift rate of the node’s clock, in nanoseconds per second, as determined by the manufacturer’s specifications (that is, it cannot be changed with the modify operation). 

maxinaccuracy relative-time
Specifies the inaccuracy limit for the node.  When the node exceeds the maximum inaccuracy setting, it attempts to synchronize.  The default is 0-00:00:00.100, and the range of possible values is 0-00:00:00.0 - 10675199-02:48:05.478.  The maximum number of hours is 24.  A practical value is less than 60 seconds.

minservers integer
Specifies the minimum number of servers required for a synchronization. Settings of 1 or 2 for a DTS server may cause unreliable computed times. The default is 3 for a DTS server and 1 for a DTS clerk.  The range of possible values is 1-10.

nexttdfchange
Specifies the future time at which the time differential factor is automatically changed.  The value is determined by the operating system (that is, it cannot be changed with the modify operation).

queryattempts integer
Specifies the number of attempts that a node makes to contact a server before the node considers the server unavailable.  The default is 3, and the range of possible values is 1-10.

statusSpecifies the state of the DTS entity.  This is a read-only attribute and its possible values are as follows:

disabledThe DTS entity is disabled. 

enabledThe DTS entity is enabled. 

syncingThe DTS entity is synchronizing. 

updatingThe DTS entity is updating the time. 

syncinterval relative-time
Specifies the interval a node must wait to synchronize.  Also specifies synchronization frequency when a node reaches the value specified by the maxinaccuracy attribute.  For clerks the default is 0-00:10:00.0, and the range of possible values is 0-00:00:30.0 - 01-00:00:00.00.  For servers the default is 0-00:02.00.0, and the range of possible values 0-00:00:30.0 - 01-00:00:00.00.

tdf relative-time
Specifies the time differential factor (TDF), which is the amount of time the server varies from Greenwich mean time (GMT) or Universal Time Coordinated (UTC).  The default is based on timezone information, with the range of possible values being -13-00:00:00 - 13-00:00:00.  This may not be set by a user, but rather is obtained from various timezone information repositories (such as the TZ environment variable, kernel structures, and so on).

timerepSpecifies the internal timestamp format used by the node.  This is not related to the format that is used to display the current time to the user (see the clock show command).  Currently DTS only uses V1.0.0 timestamps.  This cannot be set by a user, but is built into a dtsd. 

tolerance relative-time
Specifies the maximum separation allowed between the local clock and the computed time before synchronizations become abrupt rather than gradual (monotonic).  The default is 0-00:05:00.000, and the range of possible values is 0-00:00:00.500 - 10675199-02:48:05.478.

typeSpecifies whether the node is a DTS server or clerk. 

versionSpecifies the DTS software version installed on the node.  This attribute cannot be changed with the modify operation. 

DTS Server Attributes

actcourierroleSpecifies a server’s acting interaction with the set of global servers.  The values are the same as for the courierrole attribute below.  The difference between actcourierrole and courierrole is that even when the value of courierrole is backup there is no guarantee that the courier is acting as a courier.  The default is courier. 

checkintervalSpecifies the amount of time between checks for faulty servers.  Applicable only to servers that have external time-providers.  The default is 0-01:30:00.00, and the range of the possible values is 0-00:00:30.000 - 10675199-02:48:05.478. 

courierroleSpecifies a server’s interaction with the set of global servers.  Possible values are as follows:

backupThe local server becomes a courier if none are available on the local area network (LAN).  This is the default. 

courierThe local server synchronizes with the global set of servers. 

noncourierThe local server does not synchronize with the global set of servers. 

epochSpecifies the server’s epoch number.  The default is 0, and the range of possible values is 0-255.  This value may not be changed via the modify command; use the clock set command with the ­-epoch option to change its value. 

providerSpecifies whether or not the entity used an external time-provider at the last successful synchronization.  This attribute applies to servers only and may not be set by a user.  The value is either yes or no. 

serverentrySpecifies a server’s access control list (ACL) entry name.  The default setting is the following recommended value: hosts/hostname/dts-entity. 

servergroupSpecifies the security group name for the time servers within the cell.  The default is subsys/dce/dts-servers. 

serverprincipal
Specifies a server’s principal name for authentication purposes.  The default setting is the following recommended value: hosts/hostname/self.

uuid uuidSpecifies the entity’s unique identifier, which is generated when the entity is created. 

General Counters

abruptsSpecifies the number of times the node clock has been set nonmonotonically (abruptly). 

badlocalservers
Specifies the number of times that a local server was contacted, but it was not in the dts security group.

badprotocolsSpecifies the number of times the local node failed to process a received message containing an incompatible protocol version. 

badtimerepsSpecifies the number of times the local node failed to process a received message containing an incompatible timestamp format. 

creationtimeSpecifies the time at which the DTS entity was created and the counters were initialized. 

disablesSpecifies the number of times the DTS has been disabled. 

enablesSpecifies the number of times the DTS has been enabled. 

nolocalintersections
Specifies the number of times the node’s time interval failed to intersect with the computed interval of the servers.

nomemoriesSpecifies the number of times the node has been unable to allocate virtual memory. 

providertimeouts
Specifies the number of times a dtsd server process initiated contact with a time-provider and did not receive the initial response within the interval specified by the localtimeout attribute.

syncsSpecifies the number of times the node successfully synchronized. 

syserrorsSpecifies the number of times a DTS process detected a system error. 

toofewserversSpecifies the number of times a node failed to synchronize because it could not contact the required minimum number of servers. 

DTS Server Counters

badserversSpecifies the number of times that a nonlocal server was contacted, but it was not in the dts security group. 

diffepochsSpecifies the number of times the node received time response messages from servers or clerks that had epoch numbers different from its own. 

epochchangesSpecifies the number of times the server’s epoch has changed. 

noglobalsSpecifies the number of times the courier server could not contact any global servers. 

noresponsesSpecifies the number of times the courier server could not contact a specific global server. 

noserverintersections
Specifies the number of times a server has detected faulty servers (other than itself).

providerfailures
Specifies the number of times the external time-provider signaled a failure, or the node was unable to access the time-provider.

updatesSpecifies the number of times a server has attempted to synchronize its clock. 

See the OSF DCE Administration Guide for more information about DTS attributes. 

OPERATIONS

dts activate

Changes a DTS entity from an inactive state to an active state.  The syntax is as follows: dts activate [dts_server] [-abruptly] Options

-abruptlySpecifies to set the clock abruptly rather than gradually adjust it to the computed time. 

The activate operation changes a DTS entity from an inactive state to an active state.  The status attribute is changed to enabled.  This tells the DTS entity to begin synchronizing.  This operation takes an ­-abruptly option to determine if the first clock adjustment due to synchronization is an abrupt or gradual one, and returns an empty string on success.  Privileges Required You must have w (write) permission on the DTS entity in order to execute the command.  Examples The following example activates a dtsd on the local host:

dcecp> dts activate
dcecp>

The following example activates a dtsd on a remote host named cyclops:

dcecp> dts activate /.:/hosts/cyclops/dts-entity
dcecp>

dts catalog

Returns a list of the names of all DTS servers registered in the default LAN profile.  The syntax is as follows: dts catalog [cell_name] [-simplename]  [-global] Options

-simplenameReturns a list of registered DTS servers without prepending the cell name. 

-globalReturns a list of registered global DTS servers. 

The catalog operation returns a list of the names of all DTS servers registered in the default LAN profile.  Any DTS servers registered in an additional LAN profile will also be returned.  The additional LAN profile must exist at the root (/.:) level of the CDS namespace.  The operation takes an optional cellname argument that can return the names of DTS servers registered in a foreign cell.  By default, fully qualified names are returned in the following form:

/.../cellname/hosts/hostname/dts-entity

If the ­-simplename option is given, then the cell name is not prepended to the DTS server names.  The ­-global option returns only DTS servers that are operating as global servers.  Names are returned in lexical order.  Privileges Required You must have r (read) permission to the cell root (/.:) directory.  Examples

dcecp> dts catalog
/.../my_cell.goodcompany.com/hosts/frick/dts-entity
/.../my_cell.goodcompany.com/hosts/ice/dts-entity
/.../my_cell.goodcompany.com/hosts/ninja/dts-entity
dcecp>
 dcecp> dts catalog -simplename
hosts/frick/dts-entity
hosts/ice/dts-entity
hosts/ninja/dts-entity
dcecp>

dts configure

Configure the local dtsd as a local or global server.  The syntax is as follows: dts configure [dts_server] {-global | -notglobal} Options

globalConfigures the system as a global server by adding the server’s entry to the cell profile

notglobalConfigures the system as a local server by removing the server’s entry from the cell profile

The configure operation sets the local dtsd to be a local or global server.  You must specify either the -global or ­-notglobal option to indicate whether you want to configure the local dtsd as a global server or not.  The difference is whether they are listed in the /.:/cell-profile.  This command returns the string global or notglobal to indicate the current (new) state of the dtsd.  Privileges Required You must have w (write) permission on the DTS entity in order to execute the command.  Examples The following example sets the local dtsd to be a global DTS server:

dcecp> dts configure -global
global
dcecp>

dts deactivate

Changes a DTS entity from an active state to an inactive state.  The syntax is as follows: dts deactivate [dts_server] The deactivate operation changes a DTS entity from an active state to an inactive state.  The status attribute is changed to disabled.  This tells the DTS entity to stop synchronizing. This operation returns an empty string on success. Privileges Required You must have w (write) permission on the DTS entity in order to execute the command. Examples

dcecp> dts deactivate
dcecp>

dts help

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

-verboseDisplays information about the dts object. 

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

dcecp> dts help
activate            Activates a DTS entity.
catalog             Returns a list of DTS servers in the cell.
configure           Configures current dtsd as ’global’ or ’notglobal’.
deactivate          Deactivates a DTS entity.
modify              Modifies attributes of the DTS entity.
show                Displays attributes or counter info of the named dtsd.
stop                Stops the current dtsd process.
synchronize         Synchronizes the local dtsd with DTS servers.
help                Prints a summary of command-line options.
operations          Returns a list of the valid operations for this command.
dcecp>

dts modify

Changes attributes of dtsd processes.  The syntax is as follows: dts modify [dts_server] {-change attribute_list | -attribute value} Options

-change attribute_list
Allows you to modify attributes by using an attribute list rather than using individual attribute options.  The format of an attribute list is as follows:

{{attribute value}...{attribute value}}

-attribute value
As an alternative to using options with an attribute list, you can change individual attribute options by prepending a hyphen (-) to any attributes listed in the ATTRIBUTES section of this reference page.

The modify operation changes attributes of dtsd processes.  It allows attributes to be changed with the ­-change option.  Attribute options are also supported for all modifiable attributes.  This operation returns an empty string on success.  Privileges Required You must have w (write) permission on the DTS entity in order to execute the command.  Examples The following example sets the minimum number of servers needed for DTS operation to 5 for a remote dtsd:

dcecp> dts modify ncacn_ip_tcp:130.105.1.227 -minservers 5
dcecp>
 dcecp> dts modify ncacn_ip_tcp:130.105.1.227  -change {minservers 5}
dcecp>

dts operations

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

dcecp> dts operations
activate catalog configure deactivate modify show stop synchronize help operations
dcecp>

dts show

 
Returns attribute information for the specified dtsd processes. The syntax is as follows: dts show [dts_server] [-all | [-attributes] [-counters]] Options

-attributesReturns only the attributes for the local dtsd process. 

-countersReturns only the counters for the local dtsd process. 

-allReturn the attributes and counters for the local dtsd process. 

The show operation shows attribute information for the specified dtsd processes.  When called with the ­-attributes option, dts show returns an attribute list giving the values of the attributes listed above.  If called with the ­-counters option then counter information is returned.  If called with the -all or with both the -attributes and ­-counters options then both attribute and counter information is returned.  The default behavior (invoked by using no options) is the same as if the ­-attributes option was used.  Attributes and counters are listed in the order they are returned by the server.  Privileges Required You must have r (read) permission on the DTS entity in order to execute the command.  Examples

dcecp> dts show
{checkinterval +0-01:30:00.000I-----}
{epoch 0}
{tolerance +0-00:10:00.000I-----}
{tdf -0-05:00:00.000I-----}
{maxinaccuracy +0-00:00:00.100I-----}
{minservers 2}
{queryattempts 3}
{localtimeout +0-00:00:05.000I-----}
{globaltimeout +0-00:00:15.000I-----}
{syncinterval +0-00:02:00.000I-----}
{type server}
{courierrole backup}
{actcourierrole courier}
{clockadjrate 10000000 nsec/sec}
{maxdriftrate 1000000 nsec/sec}
{clockresolution 10000000 nsec}
{version V1.0.1}
{timerep V1.0.0}
{provider no}
{autotdfchange no}
{nexttdfchange 1994-10-30-01:00:00.000-05:00I0.000}
{serverprincipal hosts/medusa/self}
{serverentry hosts/medusa/dts-entity}
{servergroup subsys/dce/dts-servers}
{status enabled}
{uuid 000013ed-000b-0000-b8ef-03a4fcdf00a4}
dcecp>

dts stop

Stops the dtsd process.  The syntax is as follows: dts stop [dts_server] The stop operation stops the dtsd process. This operation returns an empty string on success. Privileges Required You must have w (write) permission on the DTS entity in order to execute the command. Examples The following example stops the dtsd process on remote host named cyclops:

dcecp> dts stop /.:/hosts/cyclops/dts-entity
dcecp>

dts synchronize

Causes dtsd to synchronize with DTS servers.  The syntax is as follows: dts synchronize [dts_server] [-abruptly] Options

-abruptlySpecifies to set the clock abruptly rather than gradually adjust it to the computed time. 

The synchronize operation causes dtsd to synchronize with DTS servers.  The machine’s clock is adjusted accordingly.  By default the clock is adjusted gradually.  This command also takes the optional ­-abruptly option to set the clock abruptly.  This operation returns an empty string on success.  Privileges Required You must have w (write) permission on the DTS entity in order to execute the command.  Examples The following example causes the local dtsd process to synchronize with other DTS servers in the cell:

dcecp> dts synchronize
dcecp>

The following example causes the dtsd process on a remote host named cyclops to synchronize immediately with other DTS servers in the cell:

dcecp> dts synchronize /.:/hosts/cyclops/dts-entity -abruptly
dcecp>

RELATED INFORMATION

Commands:

dcecp(1m), dcecp_clock(1m), dcecp_utc(1m), dtsd(1m), dts_intro(1m). 
 

 
 

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