HP OpenVMS Utility Routines Manual
Previous Contents Index

9.2.1 The utc Structure

Coordinated Universal Time (UTC) is useful for measuring time across local time zones and for avoiding the seasonal changes (summer time or daylight saving time) that can affect the local time. DECdts uses 128-bit binary numbers to represent time values internally; throughout this manual, these binary numbers representing time values are referred to as binary timestamps. The DECdts utc structure determines the ordering of the bits in a binary timestamp; all binary timestamps that are based on the utc structure contain the following information:

The binary timestamps that are derived from the DECdts utc structure have an opaque format. This format is a cryptic character sequence that DECdts uses and stores internally. The opaque binary timestamp is designed for use in programs, protocols, and databases.

Note
Applications use the opaque binary timestamps when storing time values or when passing them to DECdts.

The API provides the necessary routines for converting between opaque binary timestamps and character strings that can be displayed and read by users.

9.2.2 The tm Structure

The tm structure is based on the time in years, months, days, hours, minutes, and seconds since 00:00:00 GMT (Greenwich Mean Time), 1 January 1900. The tm structure is defined in the <time.h> header file.

The tm structure declaration follows: 


struct tm { 
               int tm_sec;    /* Seconds (0 - 59)                   */ 
               int tm_min;    /* Minutes (0 - 59)                   */ 
               int tm_hour;   /* Hours (0 - 23)                     */ 
               int tm_mday;   /* Day of Month (1 - 31)              */ 
               int tm_mon;    /* Month of Year (0 - 11)             */ 
               int tm_year;   /* Year - 1900                        */ 
               int tm_wday;   /* Day of Week (Sunday = 0)           */ 
               int tm_yday;   /* Day of Year (0 - 364)              */ 
               int tm_isdst;  /* Nonzero if Daylight Savings Time   */ 
                              /*  is in effect                      */ 
          };

Not all of the tm structure fields are used for each routine that converts between tm structures and utc structures. See the parameter descriptions that accompany the routines in Chapter 9 for additional information about which fields are used for specific routines.

9.2.3 The timespec Structure

The timespec structure is normally used in combination with or in place of the tm structure to provide finer resolution for binary times. The timespec structure is similar to the tm structure, but the timespec structure specifies the number of seconds and nanoseconds since the base time of 00:00:00 GMT, 1 January 1970. You can find the structure in the <utc.h> header file.

The timespec structure declaration follows: 


struct timespec { 
 
                 unsigned long tv_sec; /*  Seconds since 00:00:00 GMT,     */ 
                                       /*   1 January 1970                 */ 
                 long tv_nsec;         /*  Additional nanoseconds since    */ 
                                       /*   tv_sec                         */ 
 
                }         timespec_t;

9.2.4 The reltimespec Structure

The reltimespec structure represents relative time. This structure is similar to the timespec structure, except that the first field is signed in the reltimespec structure. (The field is unsigned in the timespec structure.) You can find the reltimespec structure in the <utc.h> header file.

The reltimespec structure declaration follows: 


struct reltimespec { 
 
                    long tv_sec;   /*  Seconds of relative time     */ 
                    long tv_nsec;  /*  Additional nanoseconds of    */ 
                                   /*   relative time               */ 
 
                   }   reltimespec_t;

9.2.5 The OpenVMS Time Structure

The OpenVMS time structure is based on Smithsonian time, which has a base date of November 17, 1858. The binary OpenVMS structure is a signed, 64-bit integer that has a positive value for absolute times. You can use the DECdts API to translate an OpenVMS structure representing an absolute time to or from the DECdts UTC-based binary timestamp.

9.3 DECdts API Header Files

On OpenVMS systems, the header files are located in the SYS$LIBRARY directory. The <time.h> and <utc.h> header files contain the data structures, type definitions, and define statements that are referenced by the DECdts API routines. The <time.h> header file is present on all OpenVMS systems. The <utc.h> header file includes <time.h> and contains the timespec , reltimespec , and utc structures.

9.4 Linking Programs with the DECdts API

The DECdts API is implemented by a shared image. To use the API with your program, you must link the program with this shared image. On DECnet-Plus for OpenVMS systems, the DECdts API is implemented by the shared image SYS$LIBRARY:DTSS$SHR.EXE. The following example shows how to link a program with the DECdts shared image: 


$ CC MYPROGRAM.C/OUTPUT=MYPROGRAM.OBJ
$ LINK MYPROGRAM.OBJ, SYS$INPUT:/OPTIONS[Return]
SYS$LIBRARY:DTSS$SHR.EXE/SHARE[Ctrl-z]
$

9.5 DECdts API Routine Functions

Figure 9-5 categorizes the DECdts portable interface routines by function.

Figure 9-5 DTS Portable Interface Categories

An alphabetical listing of the DECdts portable interface routines and a brief description of each one follows:
utc_abstime Computes the absolute value of a binary relative time.
utc_addtime Computes the sum of two binary timestamps; the timestamps can be two relative times or a relative time and an absolute time.
utc_anytime Converts a binary timestamp into a tm structure, using the TDF information contained in the timestamp to determine the TDF returned with the tm structure.
utc_anyzone Gets the time zone label and offset from GMT, using the TDF contained in the input utc .
utc_ascanytime Converts a binary timestamp into an ASCII string that represents an arbitrary time zone.
utc_ascgmtime Converts a binary timestamp into an ASCII string that expresses a GMT time.
utc_asclocaltime Converts a binary timestamp to an ASCII string that represents a local time.
utc_ascreltime Converts a binary timestamp that expresses a relative time to its ASCII representation.
utc_binreltime Converts a relative binary timestamp into timespec structures that express relative time and inaccuracy.
utc_bintime Converts a binary timestamp into a timespec structure.
utc_boundtime Given two UTC times, one before and one after an event, returns a single UTC time whose inaccuracy includes the event.
utc_cmpintervaltime Compares two binary timestamps or two relative binary timestamps.
utc_cmpmidtime Compares two binary timestamps or two relative binary timestamps, ignoring inaccuracies.
utc_gettime Returns the current system time and inaccuracy as an opaque binary timestamp.
utc_getusertime Returns the time and process-specific TDF, rather than the system-specific TDF.
utc_gmtime Converts a binary timestamp into a tm structure that expresses GMT or the equivalent UTC.
utc_gmtzone Gets the time zone label and zero offset from GMT, given utc .
utc_localtime Converts a binary timestamp into a tm structure that expresses local time.
utc_localzone Gets the time zone label and offset from GMT, given utc .
utc_mkanytime Converts a tm structure and TDF (expressing the time in an arbitrary time zone) into a binary timestamp.
utc_mkascreltime Converts a null-terminated character string, which represents a relative timestamp to a binary timestamp.
utc_mkasctime Converts a null-terminated character string, which represents an absolute timestamp, to a binary timestamp.
utc_mkbinreltime Converts a timespec structure expressing a relative time to a binary timestamp.
utc_mkbintime Converts a timespec structure into a binary timestamp.
utc_mkgmtime Converts a tm structure that expresses GMT or UTC to a binary timestamp.
utc_mklocaltime Converts a tm structure that expresses local time to a binary timestamp.
utc_mkreltime Converts a tm structure that expresses relative time to a binary timestamp.
utc_mkvmsanytime Converts a binary OpenVMS format time and TDF (expressing the time in an arbitrary time zone) to a binary timestamp.
utc_mkvmsgmtime Converts a binary OpenVMS format time expressing GMT (or the equivalent UTC) into a binary timestamp.
utc_mkvmslocaltime Converts a local binary OpenVMS format time to a binary timestamp, using the host system's TDF.
utc_mulftime Multiplies a relative binary timestamp by a floating-point value.
utc_multime Multiplies a relative binary timestamp by an integer factor.
utc_pointtime Converts a binary timestamp to three binary timestamps that represent the earliest, most likely, and latest time.
utc_reltime Converts a binary timestamp that expresses a relative time into a tm structure.
utc_spantime Given two (possibly unordered) UTC timestamps, returns a single UTC time interval whose inaccuracy spans the two input timestamps.
utc_subtime Computes the difference between two binary timestamps that express two relative times (an absolute time and a relative time, two relative times, or two absolute times).
utc_vmsanytime Converts a binary timestamp to a binary OpenVMS-format time, using the TDF contained in the binary timestamp.
utc_vmsgmtime Converts a binary timestamp to a binary OpenVMS-format time expressing GMT or the equivalent UTC.
utc_vmslocaltime Converts a binary timestamp to a local binary OpenVMS format time, using the host system's time differential factor.

Notes
Absolute time is a point on a time scale; absolute time measurements are derived from system clocks or external time-providers. For DECdts, absolute times reference the UTC standard and include the inaccuracy and other information. When you display an absolute time, DECdts converts the time to ASCII text, as shown in the following display: 


1996-11-21-13:30:25.785-04:00I000.082

Relative time is a discrete time interval that is usually added to or subtracted from an absolute time. A time differential factor (TDF) associated with an absolute time is one example of a relative time. Note that a relative time does not use the calendar date fields, because these fields concern absolute time.

Coordinated Universal Time (UTC) is the international time standard that DECdts uses. The zero hour of UTC is based on the zero hour of Greenwich Mean Time (GMT). The documentation consistently refers to the time zone of the Greenwich Meridian as GMT. However, this time zone is also sometimes referred to as UTC.

The time differential factor (TDF) is the difference between UTC and the time in a particular time zone.

OpenVMS systems do not have a default time zone rule. You select a time zone by defining sys$timezone_rule during the sys$manager:net$configure.com procedure, or by explicitly defining sys$timezone_rule .

Unless otherwise specified, the default input and output parameters for the DECDts API routine commands are as follows:

  • If utc is not specified as an input parameter, the current time is used.
  • If inacc is not specified as an input parameter, infinity is used.
  • If no output parameter is specified, no result (or an error) is returned.

The following command reference section includes all DECdts API routines.

utc_abstime

Computes the absolute value of a relative binary timestamp.

Format

#include <utc.h>

int utc_abstime( result, *utc1)

Parameters

Input

utc1

Relative binary timestamp.

Output

result

Absolute value of the input relative binary timestamp.

Description

The Absolute Time routine computes the absolute value of a relative binary timestamp. The input timestamp represents a relative (delta) time.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time parameter or invalid results.
Example The following example scales a relative time, computes its absolute value, and prints the result. 


 
utc_t       relutc, scaledutc; 
char        timstr[UTC_MAX_STR_LEN]; 
 
/* 
 *   Make sure relative timestamp represents a positive interval... 
 */ 
 
utc_abstime(&relutc,            /* Out: Abs-value of rel time  */ 
            &relutc);           /* In:  Relative time to scale */ 
 
/* 
 *   Scale it by a factor of 17... 
 */ 
 
utc_multime(&scaledutc,         /* Out: Scaled relative time   */ 
            &relutc,            /* In:  Relative time to scale */ 
            17L);               /* In:  Scale factor           */ 
 
utc_ascreltime(timstr,          /* Out: ASCII relative time    */ 
               UTC_MAX_STR_LEN, /* In:  Length of input string */ 
               &scaledutc);     /* In:  Relative time to       */ 
                                /*      convert                */ 
                                      
printf("%s\n",timstr);                
 
/* 
 *   Scale it by a factor of 17.65... 
 */ 
 
utc_mulftime(&scaledutc,        /* Out: Scaled relative time   */ 
             &relutc,           /* In:  Relative time to scale */ 
             17.65);            /* In:  Scale factor           */ 
 
utc_ascreltime(timstr,          /* Out: ASCII relative time    */ 
               UTC_MAX_STR_LEN, /* In:  Length of input string */ 
               &scaledutc);     /* In:  Relative time to       */ 
                                /*      convert                */ 
                                      
printf("%s\n",timstr);

utc_addtime

Computes the sum of two binary timestamps; the timestamps can be two relative times or a relative time and an absolute time.

Format

#include <utc.h>

int utc_addtime( result, *utc1, *utc2)

Parameters

Input

utc1

Binary timestamp or relative binary timestamp.

utc2

Binary timestamp or relative binary timestamp.

Output

result

Resulting binary timestamp or relative binary timestamp, depending on the operation performed:

Description

The Add Time routine adds two binary timestamps, producing a third binary timestamp whose inaccuracy is the sum of the two input inaccuracies. One or both of the input timestamps typically represent a relative (delta) time. The TDF in the first input timestamp is copied to the output.
Notes Although no error is returned, do not use the combination absolute time + absolute time. Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time parameter or invalid results.
Example The following example shows how to compute a timestamp that represents a time at least 5 seconds in the future. 


utc_t               now, future, fivesec; 
reltimespec_t       tfivesec; 
timespec_t          tzero; 
 
/* 
 *   Construct a timestamp that represents 5 seconds... 
 */ 
tfivesec.tv_sec = 5; 
tfivesec.tv_nsec = 0; 
tzero.tv_sec = 0; 
tzero.tv_nsec = 0; 
utc_mkbinreltime(&fivesec, /* Out: 5 secs in binary timestamp */ 
                &tfivesec, /* In:  5 secs in timespec         */ 
                &tzero);   /* In:  0 secs inaccuracy in timespec */ 
 
/* 
 *  Get the maximum possible current time... 
 *  (NULL input parameter is used to specify the current time.) 
 */ 
utc_pointtime((utc_t *)0, /* Out: Earliest possible current time */ 
             (utc_t *)0, /* Out: Midpoint of current time       */ 
             &now,       /* Out: Latest possible current time   */ 
             (utc_t *)0);/* In:  Use current time               */ 
 
/* 
 *   Add 5 seconds to get future timestamp... 
 */ 
utc_addtime(&future,     /* Out: Future binary timestamp        */ 
            &now,        /* In:  Latest possible time now       */ 
            &fivesec);   /* In:  5 secs                         */
Related Functions utc_subtime

Previous Next Contents Index