NAME

utc  — A dcecp object that manipulates UTC timestamps

SYNOPSIS

utc add timestamp relative_timestamp

utc compare absolute_timestamp absolute_timestamp  [noinaccuracy ]

utc convert absolute_timestamp  [gmt ]

utc help  [operation | verbose  ]

utc multiply relative_timestamp  {integer | floating_point_factor }

utc operations

utc subtract timestamp timestamp

Arguments

absolute_timestamp
An International Organization for Standardization (ISO) compliant time format of the following form:

CCYY-MMDD-hh:mm:ss.fff[+|-]hh:mmIsss.fff 

The Time Differential Factor (TDF) component [+|−]hh.mm, if present, indicates the offset from Universal Time Coordinated (UTC) time and implies local system time.  The inaccuracy component Iss.fff, if present, specifies the duration of the time interval that contains the absolute time. 

floating_point_factor
A floating-point number such as 53.234.

integerA whole number such as 79. 

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

relative_timestamp
A Distributed Time Service (DTS) timestamp of the following form:

[-]DD-hh:mm:ss.fffIss.fff 

Relative times often omit fractions of seconds (the leftmost .fff sequence) and generally lack an inaccuracy component (Iss.fff).  For example, a relative time of 21 days, 8 hours, and 15 minutes is expressed as 21-08:15:00. 

timestampA utc  timestamp that can be a relative or absolute time.  See the relative_timestamp and absolute_timestamp argument descriptions for the format of these timestamps. 

Description

The utc  object lets you add, compare, and convert timestamps in DTS and ISO formats. 

Errors

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

Operations

utc add

Adds two timestamps.  The syntax is as follows:

utc add timestamp relative_timestamp

The add operation returns the sum of two timestamps.  The timestamps can be two relative times or an absolute time and a relative time. 

Privileges Required

No special privileges are needed to use the utc add command. 

Examples

dcecp> utc add 1994-10-18-13:21:50.419-04:00I----- +0-00:02:00.000I-----
1994-10-18-13:23:50.419-04:00I-----
dcecp>

utc compare

Compares two absolute timestamps indicating the temporal order.  The syntax is as follows:

utc compare absolute_timestamp absolute_timestamp [noinaccuracy ]

The compare operation compares two timestamps and returns −1 if the first is earlier, 1 if the second is earlier, and 0 if the difference is indeterminate.  Specify the noinaccuracy  option to ignore inaccuracies in comparisons; in this case a return of 0 indicates the times are the same. 

Privileges Required

No special privileges are needed to use the utc compare command. 

Examples

dcecp> utc compare 1994-10-18-13:22:32.816-04:00I-----
> 1994-10-18-13:21:50.419-04:00I----- -noinaccuracy
1
dcecp> 

utc convert

Converts a timestamp from UTC to local time.  The syntax is as follows:

utc convert absolute_timestamp [gmt ]

The convert operation accepts a timestamp and returns another timestamp that expresses the same time in the local time zone.  If called with the gmt option it returns a Greenwich mean time (GMT) formatted timestamp. 

Privileges Required

No special privileges are needed to use the utc convert command. 

Examples

dcecp> utc convert 1994-10-18-13:22:32.816-00:00I-----
1994-10-18-09:22:32.816-04:00I-----
dcecp>

utc help

Returns help information about the utc  object and its operations.  The syntax is as follows:

utc help [operation | verbose ]

Options

verboseDisplays information about the utc  object. 

Used without an argument or option, the utc help  command returns brief information about each utc  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 utc  object itself. 

Privileges Required

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

Examples

dcecp> utc help
add             Adds a relative and absolute, or two relative, timestamps.
compare         Compares two timestamps to determine which is earlier.
convert         Converts a timestamp into the local timezone or GMT.
multiply        Multiplies a relative timestamp by a number.
subtract        Returns the difference between two timestamps.
help            Prints a summary of command-line options.
operations      Returns a list of the valid operations for this command.
dcecp> 

utc multiply

Multiplies a relative time (a length of time) by an integer or floating-point factor.  The syntax is as follows:

utc multiply relative_timestamp {integer | floating_point_factor}

The multiply operation accepts two arguments:  a relative timestamp and an integer or floating-point factor.  It multiplies the length of time (specified by the relative timestamp) by the integer or floating-point factor, returning the product as a relative timestamp. 

Privileges Required

No special privileges are needed to use the utc multiply  command. 

Examples

dcecp> utc multiply +0-00:00:05.000I----- 3
+0-00:00:15.000I-----
dcecp> 

utc operations

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

utc 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 utc operations command. 

Examples

dcecp> utc operations
add compare convert multiply subtract help operations
dcecp> 

utc subtract

Subtracts one timestamp from another, returning the difference as a relative timestamp.  The syntax is as follows:

utc subtract timestamp timestamp

The subtract operation returns the difference between two timestamps that express either an absolute time and a relative time, two relative times, or two absolute times.  The return value is a relative timestamp. 

Privileges Required

No special privileges are needed to use the utc subtract  command. 

Examples

dcecp> utc subtract 1994-10-18-13:22:32.816-00:00I----- +0-00:00:15.000I-----
1994-10-18-13:22:17.816+00:00I-----
dcecp>

Related Information

Commands: clock(8dce), dcecp(8dce), dts(8dce), dtsd(8dts).