HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

Converts a binary timestamp to a tm structure, using the time differential factor (TDF) information contained in the timestamp to determine the TDF returned with the tm structure.

Format

#include <utc.h>

int utc_anytime( timetm, *tns, *inacctm, *ins, *tdf, *utc)

• struct tm timetm ;
• long *tns;
• struct tm *inacctm;
• long *ins;
• long *tdf;
• const utc_t *utc;

Input

utc

Binary timestamp.

Output

timetm

Time component of the binary timestamp expressed in the timestamp's local time.

tns

Nanoseconds since time component of the binary timestamp.

inacctm

Seconds of inaccuracy component of the binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of --1 and tm_mon and tm_year return values of 0. The field tm_yday contains the inaccuracy in days. If the inaccuracy is infinite, all tm structure fields return values of --1.

ins

Nanoseconds of inaccuracy component of the binary timestamp.

tdf

TDF component of the binary timestamp in units of seconds east or west of GMT.

Description

The Any Time routine converts a binary timestamp to a tm structure. The TDF information contained in the timestamp is returned with the time and inaccuracy components; the TDF component determines the offset from GMT and the local time value of the tm structure. Additional returns include nanoseconds since Time and nanoseconds of inaccuracy.

utc_t               evnt;
struct tm           tmevnt;
timespec_t          tevnt, ievnt;
char                tznam[80];

/*
 *   Assume evnt contains the timestamp to convert...
 *
 *   Get time as a tm structure, using the time zone information in
 *   the timestamp...
 */
utc_anytime(&tmevnt,         /* Out: tm struct of time of evnt  */
            (long *)0,       /* Out: nanosec of time of evnt    */
            (struct tm *)0,  /* Out: tm struct of inacc of evnt */
            (long *)0,       /* Out: nanosec of inacc of evnt   */
            (int *)0,        /* Out: tdf of evnt                */
            &evnt);          /* In:  binary timestamp of evnt   */

/*
 *   Get the time and inaccuracy as timespec structures...
 */
utc_bintime(&tevnt,          /* Out: timespec of time of evnt   */
            &ievnt,          /* Out: timespec of inacc of evnt  */
            (int *)0,        /* Out: tdf of evnt                */
            &evnt);          /* In:  Binary timestamp of evnt   */

/*
 *   Construct the time zone name from time zone information in the
 *   timestamp...
 */
utc_anyzone(tznam,           /* Out: Time zone name             */
            80,              /* In:  Size of time zone name     */
            (long *)0,       /* Out: tdf of event               */
            (long *)0,       /* Out: Daylight saving flag       */
            &evnt);          /* In:  Binary timestamp of evnt   */

/*
 *   Print timestamp in the format:
 *
 *           1991-03-05-21:27:50.023I0.140 (GMT-5:00)
 *           1992-04-02-12:37:24.003Iinf (GMT+7:00)
 *
 */

printf("%d-%02d-%02d-%02d:%02d:%02d.%03d",
        tmevnt.tm_year+1900, tmevnt.tm_mon+1, tmevnt.tm_mday,
        tmevnt.tm_hour, tmevnt.tm_min, tmevnt.tm_sec,
        (tevnt.tv_nsec/1000000));

if ((long)ievnt.tv_sec == -1)
    printf("Iinf");
else
    printf("I%d.%03d", ievnt.tv_sec, (ievnt.tv_nsec/1000000));

printf(" (%s)\n", tznam);

Gets the time zone label and offset from GMT, using the TDF contained in the input utc .

Format

#include <utc.h>

int utc_anyzone( tzname, tzlen, *tdf, isdst, *utc)

• char tzname ;
• size_t tzlen ;
• long *tdf;
• int *isdst;
• const utc_t *utc;

Input

tzlen

Length of the tzname buffer.

utc

Binary time.

Output

tzname

Character string that is long enough to hold the time zone label.

tdf

Longword with differential in seconds east or west of GMT.

isdst

Integer with a value of --1, indicating that no information is supplied as to whether it is standard time or daylight saving time. A value of --1 is always returned.

Description

The Any Zone routine gets the time zone label and offset from GMT, using the TDF contained in the input utc . The label returned is always of the form GMT + n or GMT - n, where n is the TDF expressed in hours:minutes. (The label associated with an arbitrary time zone is not known; only the offset is known.)

Converts a binary timestamp to an ASCII string that represents an arbitrary time zone.

Format

#include <utc.h>

int utc_ascanytime( *cp, stringlen, *utc)

• char *cp;
• size_t stringlen ;
• const utc_t *utc;

Input

stringlen

The length of the cp buffer.

utc

Binary timestamp.

Output

cp

ASCII string that represents the time.

Description

The ASCII Any Time routine converts a binary timestamp to an ASCII string that expresses a time. The TDF component in the timestamp determines the local time used in the conversion.

utc_t      evnt;
char       localTime[UTC_MAX_STR_LEN];

/*
 *   Assuming that evnt contains the timestamp to convert, convert
 *   the time to ASCII in the following format:
 *
 *          1991-04-01-12:27:38.37-8:00I2.00
 */

utc_ascanytime(localtime,         /* Out: Converted time      */
               UTC_MAX_STR_LEN,   /* In:  Length of string    */
               &evnt);            /* In:  Time to convert     */

Converts a binary timestamp to an ASCII string that expresses a GMT time.

Format

#include <utc.h>

int utc_ascgmtime( *cp, stringlen, *utc)

• char *cp;
• size_t stringlen ;
• const utc_t *utc;

Input

stringlen

Length of the cp buffer.

utc

Binary timestamp.

Output

cp

ASCII string that represents the time.

Description

The ASCII GMT Time routine converts a binary timestamp to an ASCII string that expresses a time in GMT.

char   gmTime[UTC_MAX_STR_LEN];

/*
 *   Convert the current time to ASCII in the following format:
 *
 *          1991-04-01-12:27:38.37I2.00
 */

utc_ascgmtime(gmTime,                /* Out: Converted time     */
              UTC_MAX_STR_LEN,       /* In:  Length of string   */
              (utc_t*) NULL);        /* In:  Time to convert    */
                                     /* Default is current time */

Converts a binary timestamp to an ASCII string that represents a local time.

Format

#include <utc.h>

int utc_asclocaltime( *cp, stringlen, *utc)

• char *cp;
• size_t stringlen ;
• const utc_t *utc;

Input

stringlen

Length of the cp buffer.

utc

Binary timestamp.

Output

cp

ASCII string that represents the time.

Description

The ASCII Local Time routine converts a binary timestamp to an ASCII string that expresses local time.

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 .

char   localTime[UTC_MAX_STR_LEN];

/*
 *   Convert the current time...
 */

utc_asclocaltime(localTime,      /* Out: Converted time          */
                UTC_MAX_STR_LEN, /* In:  Length of string        */
                (utc_t*) NULL);  /* In:  Time to convert         */
                                 /*      Default is current time */

Converts a relative binary timestamp to an ASCII string that represents the time.

Format

#include <utc.h>

int utc_ascreltime( *cp, stringlen, *utc)

• char *cp;
• const size_t stringlen ;
• const utc_t *utc;

Input

utc

Relative binary timestamp.

stringlen

Length of the cp buffer.

Output

cp

ASCII string that represents the time.

Description

The ASCII Relative Time routine converts a relative binary timestamp to an ASCII string that represents the time.

Converts a relative binary timestamp to two timespec structures that express relative time and inaccuracy.

Format

#include <utc.h>

int utc_binreltime( *timesp, *inaccsp, *utc)

• reltimespec_t *timesp;
• timespec_t *inaccsp;
• const utc_t *utc;

Input

utc

Relative binary timestamp.

Output

timesp

Time component of the relative binary timestamp, in the form of seconds and nanoseconds since the base time (1970-01-01:00:00:00.0 + 00:00I0).

inaccsp

Inaccuracy component of the relative binary timestamp, in the form of seconds and nanoseconds.

Description

The Binary Relative Time routine converts a relative binary timestamp to two timespec structures that express relative time and inaccuracy. These timespec structures describe a time interval.

utc_t               before, duration;
reltimespec_t       tduration;
timespec_t          iduration;

/*
 *   Get the time before the start of the operation...
 */

utc_gettime(&before);      /* Out: Before binary timestamp    */

/*
 * ...Later...
 *
 * Subtract, getting the duration as a relative time.
 *
 *    NOTE: The NULL argument is used to obtain the current time.
 */

utc_subtime(&duration,     /* Out: Duration rel bin timestamp  */
            (utc_t *)0,    /* In:  After binary timestamp      */
            &before);      /* In:  Before binary timestamp     */

/*
 *    Convert the relative times to timespec structures...
 */

utc_binreltime(&tduration, /* Out: Duration time timespec      */
               &iduration, /* Out: Duration inacc timespec     */
               &duration); /* In:  Duration rel bin timestamp  */

/*
 *    Print the duration...
 */

printf("%d.%04d", tduration.tv_sec, (tduration.tv_nsec/10000));

if ((long)iduration.tv_sec == -1)
    printf("Iinf\n");
else
printf("I%d.%04d\n", iduration.tv_sec, (iduration.tv_nsec/100000));

Converts a binary timestamp to a timespec structure.

Format

#include <utc.h>

int utc_bintime( *timesp, *inaccsp, *tdf, *utc)

• timespec_t *timesp;
• timespec_t *inaccsp;
• long *tdf;
• const utc_t *utc;

Input

utc

Binary timestamp.

Output

timesp

Time component of the binary timestamp, in the form of seconds and nanoseconds since the base time.

inaccsp

Inaccuracy component of the binary timestamp, in the form of seconds and nanoseconds.

tdf

TDF component of the binary timestamp in the form of signed number of seconds east or west of GMT.

Description

The Binary Time routine converts a binary timestamp to a timespec structure. The TDF information contained in the timestamp is returned.

Given two UTC times, one before and one after an event, returns a single UTC time whose inaccuracy includes the event.

Format

#include <utc.h>

int utc_boundtime( *result, *utc1, *utc2)

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

Input

utc1

Before binary timestamp or relative binary timestamp.

utc2

After binary timestamp or relative binary timestamp.

Output

result

Spanning timestamp.

Description

Given two UTC times, the Bound Time routine returns a single UTC time whose inaccuracy bounds the two input times. This is useful for timestamping events; the routine gets the utc values before and after the event, then calls utc_boundtime to build a timestamp that includes the event.

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 .

utc_t               before, after, evnt;

/*
 *   Get the time before the event...
 */

utc_getusertime(&before);  /* Out: Before binary timestamp     */

/*
 *   Get the time after the event...
 */

utc_getusertime(&after);   /* Out: After binary timestamp      */

/*
 *   Construct a single timestamp that describes the time of the
 *   event...
 */

utc_boundtime(&evnt,   /* Out: Timestamp that bounds event */
              &before, /* In:  Before binary timestamp     */
              &after); /* In:  After binary timestamp      */

Compares two binary timestamps or two relative binary timestamps.

Format

#include <utc.h>

int utc_cmpintervaltime( *relation, *utc1, *utc2)

• enum utc_cmptype *relation;
• const utc_t *utc1;
• const utc_t *utc2;

Input

utc1

Binary timestamp or relative binary timestamp.

utc2

Binary timestamp or relative binary timestamp.

Output

relation

Receives the result of the comparison of utc1:utc2, where the result is an enumerated type with one of the following values:

• utc_equalTo
• utc_lessThan
• utc_greaterThan
• utc_indeterminate

Description

The Compare Interval Time routine compares two binary timestamps and returns a flag indicating that the first time is greater than, less than, equal to, or overlapping with the second time. Two times overlap if the intervals (time - inaccuracy, time + inaccuracy) of the two times intersect.

The input binary timestamps express two absolute or two relative times. Do not compare relative binary timestamps and binary timestamps. If you do, no meaningful results and no errors are returned.

This routine does a temporal ordering of the time intervals.

utc1 is utc_lessThan utc2 iff utc1.time + utc1.inacc < utc2.time - utc2.inacc utc1 is utc_greaterThan utc2 iff utc1.time - utc1.inacc > utc2.time + utc2.inacc utc1 utc_equalTo utc2 iff utc1.time == utc2.time and utc1.inacc == 0 and utc2.inacc == 0 utc1 is utc_indeterminate with respect to utc2 if the intervals overlap.

struct tm           tmtime, tmzero;
enum utc_cmptype    relation;
utc_t               testtime;

/*
 *   Zero the tm structure for inaccuracy...
 */

memset(&tmzero, 0, sizeof(tmzero));

/*
 *   Get the current time, mapped to a tm structure...
 *
 *        NOTE: The NULL argument is used to get the current time.
 */

utc_gmtime(&tmtime,      /* Out: Current GMT time in tm struct   */
         (long *)0,      /* Out: Nanoseconds of time             */
         (struct tm *)0, /* Out: Current inaccuracy in tm struct */
         (long *)0,      /* Out: Nanoseconds of inaccuracy       */
         (utc_t *)0);    /* In:  Current timestamp               */

/*
 *   Construct a tm structure that corresponds to 1:00 PM...
 */

tmtime.tm_hour = 13;
tmtime.tm_min = 0;
tmtime.tm_sec = 0;

/*
 *   Convert to a binary timestamp...
 */

utc_mkgmtime(&testtime,  /* Out: Binary timestamp of 1:00 PM  */
             &tmtime,    /* In:  1:00 PM in tm struct         */
             0,          /* In:  Nanoseconds of time          */
             &tmzero,    /* In:  Zero inaccuracy in tm struct */
             0);         /* In:  Nanoseconds of inaccuracy    */

/*
 *   Compare to the current time, noting the use of the
 *   NULL argument...
 */

utc_cmpintervaltime(&relation,    /* Out: Comparison relation */
                    (utc_t *)0,   /* In:  Current timestamp   */
                    &testtime);   /* In:  1:00 PM timestamp   */

/*
 *   If it is not later - wait, print a message, etc.
 */

if (relation != utc_greaterThan) {

/*
 *     Note: It could be earlier than 1:00 PM or it could be
 *           indeterminate. If indeterminate, for some applications
 *           it might be worth waiting.
 */
}