HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

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 count of 100-nanosecond units since 00:00:00.00, 15 October 1582 (the date of the Gregorian reform to the Christian calendar)
• The count of 100-nanosecond units of inaccuracy applied to the above
• The time differential factor (TDF), expressed as the signed quantity
• The timestamp version number

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.

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;

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;

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

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

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:

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

The following command reference section includes all DECdts API routines.

Computes the absolute value of a relative binary timestamp.

Format

#include <utc.h>

int utc_abstime( result, *utc1)

• utc_t result ;
• const utc_t *utc1;

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.

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);

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)

• utc_t result ;
• const utc_t *utc1;
• const utc_t *utc2;

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:

• relative time + relative time = relative time
• absolute time + relative time = absolute time
• relative time + absolute time = absolute time
• absolute time + absolute time is undefined. See NOTES.

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.

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                         */