HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

Compares two binary timestamps or two relative binary timestamps, ignoring inaccuracies.

Format

#include <utc.h>

int utc_cmpmidtime( *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

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

Description

The Compare Midpoint Times routine compares two binary timestamps and returns a flag indicating that the first timestamp is greater than, less than, or equal to the second timestamp. Inaccuracy information is ignored for this comparison; the input values are, therefore, equivalent to the midpoints of the time intervals described by the input binary timestamps.

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.

The following routine does a lexical ordering on the time interval midpoints.

utc1 is utc_lessThan utc2 iff utc1.time < utc2.time utc1 is utc_greaterThan utc2 iff utc1.time > utc2.time utc1 is utc_equalTo utc2 iff utc1.time == utc2.time

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_localtime(&tmtime,   /* Out: Current local time in tm struct */
         (long *)0,      /* Out: Nanoseconds of time             */
         (struct tm *)0, /* Out: Current inacc in tm struct      */
         (long *)0,      /* Out: Nanoseconds of inaccuracy       */
         (utc_t *)0);    /* In:  Current timestamp               */

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

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

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

utc_mklocaltime(&testtime, /* Out: Binary timestamp of 1:00 P.M. */
                &tmtime,   /* In:  1:00 P.M. 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_cmpmidtime(&relation,    /* Out: Comparison relation         */
               (utc_t *)0,   /* In:  Current timestamp           */
               &testtime);   /* In:  1:00 P.M. timestamp         */

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

if (relation != utc_greaterThan) {

/*          It is not later then 1:00 P.M. local time. Note that
 *          this depends on the setting of the user's environment.
 */
}

Returns the current system time and inaccuracy as a binary timestamp.

Format

#include <utc.h>

int utc_gettime( *utc)

• utc_t *utc;

Input

None.

Output

utc

System time as a binary timestamp.

Description

The Get Time routine returns the current system time and inaccuracy in a binary timestamp. The routine takes the TDF from the operating system's kernel; the TDF is specified in a system-dependent manner.

Returns the time and process-specific TDF, rather than the system-specific TDF.

Format

#include <utc.h>

int utc_getusertime( *utc)

• utc_t *utc;

Input

None.

Output

utc

System time as a binary timestamp.

Description

The Get User Time routine returns the system time and inaccuracy in a binary timestamp. The routine takes the TDF from the user's environment, which determines the time zone rule. 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 .

Converts a binary timestamp to a tm structure that expresses GMT or the equivalent UTC.

Format

#include <utc.h>

int utc_gmtime( *timetm, *tns, *inacctm, *ins, *utc)

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

Input

utc

Binary timestamp to be converted to tm structure components.

Output

timetm

Time component of the binary timestamp.

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 zero. 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. If the inaccuracy is infinite, ins returns a value of --1.

Description

The Greenwich Mean Time (GMT) routine converts a binary timestamp to a tm structure that expresses GMT (or the equivalent UTC). Additional returns include nanoseconds since time and nanoseconds of inaccuracy.

Gets the time zone label for GMT.

Format

#include <utc.h>

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

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

Input

tzlen

Length of buffer tzname.

utc

Binary timestamp. This parameter is ignored.

Output

tzname

Character string long enough to hold the time zone label.

tdf

Longword with differential in seconds east or west of GMT. A value of zero is always returned.

isdst

Integer with a value of zero, indicating that daylight saving time is not in effect. A value of zero is always returned.

Description

The Greenwich Mean Time Zone routine gets the time zone label and zero offset from GMT. Outputs are always tdf = 0 and tzname = GMT. This routine exists for symmetry with the Any Zone ( utc_anyzone ) and the Local Zone ( utc_localzone ) routines.

utc_t       now;
struct tm   tmlocal, tmgmt;
long        tzoffset;
int         tzdaylight;
char        tzlocal[80], tzgmt[80];

/*
 *   Get the current time once, so both conversions use the same
 *   time...
 */

utc_gettime(&now);

/*
 *   Convert to local time, using the process TZ environment
 *   variable...
 */

utc_localtime(&tmlocal,       /* Out: Local time tm structure  */
              (long *)0,      /* Out: Nanosec of time          */
              (struct tm *)0, /* Out: Inaccuracy tm structure  */
              (long *)0,      /* Out: Nanosec of inaccuracy    */
              &now);          /* In:  Current binary timestamp */

/*
 *   Get the local time zone name, offset from GMT, and current
 *   daylight savings flag...
 */

utc_localzone(tzlocal,     /* Out: Local time zone name          */
              80,          /* In:  Length of loc time zone name  */
              &tzoffset,   /* Out: Loc time zone offset in secs  */
              &tzdaylight, /* Out: Local time zone daylight flag */
              &now);       /* In:  Current binary timestamp      */

/*
 *   Convert to GMT...
 */

utc_gmtime(&tmgmt,         /* Out: GMT tm structure              */
           (long *)0,      /* Out: Nanoseconds of time           */
           (struct tm *)0, /* Out: Inaccuracy tm structure       */
           (long *)0,      /* Out: Nanoseconds of inaccuracy     */
           &now);          /* In:  Current binary timestamp      */

/*
 *   Get the GMT time zone name...
 */

utc_gmtzone(tzgmt,         /* Out: GMT time zone name            */
            80,            /* In:  Size of GMT time zone name    */
            (long *)0,     /* Out: GMT time zone offset in secs  */
            (int *)0,      /* Out: GMT time zone daylight flag   */
            &now);         /* In:  Current binary timestamp      */

/*
 *   Print out times and time zone information in the following
 *   format:
 *
 *          12:00:37 (EDT) = 16:00:37 (GMT)
 *          EDT is -240 minutes ahead of Greenwich Mean Time.
 *          Daylight savings time is in effect.
 */

printf("%d:%02d:%02d (%s) = %d:%02d:%02d (%s)\n",
       tmlocal.tm_hour, tmlocal.tm_min, tmlocal.tm_sec, tzlocal,
       tmgmt.tm_hour, tmgmt.tm_min, tmgmt.tm_sec, tzgmt);
printf("%s is %d minutes ahead of Greenwich Mean Time\n",
       tzlocal, tzoffset/60);
if (tzdaylight != 0)
    printf("Daylight savings time is in effect\n");

Converts a binary timestamp to a tm structure that expresses local time.

Format

#include <utc.h>

int utc_localtime( *timetm, *tns, *inacctm, *ins, *utc)

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

Input

utc

Binary timestamp.

Output

timetm

Time component of the binary timestamp, expressing 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 zero. 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. If the inaccuracy is infinite, ins returns a value of --1.

Description

The Local Time routine converts a binary timestamp to a tm structure 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 .

Additional returns include nanoseconds since time and nanoseconds of inaccuracy.

Gets the local time zone label and offset from GMT, given utc .

Format

#include <utc.h>

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

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

#include <utc.h>

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

Input

tzlen

Length of the tzname buffer.

utc

Binary timestamp.

Output

tzname

Character string 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 zero if standard time is in effect or a value of 1 if daylight savings time is in effect.

Description

The Local Zone routine gets the local time zone label and offset from GMT, given utc .

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 .

Converts a tm structure and TDF (expressing the time in an arbitrary time zone) to a binary timestamp.

Format

#include <utc.h>

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

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

Input

timetm

A tm structure that expresses the local time; tm_wday and tm_yday are ignored on input.

tns

Nanoseconds since time component.

inacctm

A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If tm_yday is negative, the inaccuracy is considered to be infinite; tm_mday , tm_mon , tm_wday , tm_isdst , tm_gmtoff , and tm_zone are ignored on input.

ins

Nanoseconds of inaccuracy component.

tdf

Time differential factor to use in conversion.

Output

utc

Resulting binary timestamp.

Description

The Make Any Time routine converts a tm structure and TDF (expressing the time in an arbitrary time zone) to a binary timestamp. Required inputs include nanoseconds since time and nanoseconds of inaccuracy.

utc_t       utc;
struct tm   tmtime, tminacc;
float       tsec, isec;
double      tmp;
long        tnsec, insec;
int         i, offset, tzhour, tzmin, year, mon;
char        *string;

/*  Try to convert the string...                               */

if(sscanf(string, "%d-%d-%d-%d:%d:%e+%d:%dI%e",
          &year, &mon, &tmtime.tm_mday, &tmtime.tm_hour,
          &tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) {

/*  Try again with a negative TDF...                           */

if (sscanf(string, "%d-%d-%d-%d:%d:%e-%d:%dI%e",
           &year, &mon, &tmtime.tm_mday, &tmtime.tm_hour,
           &tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) {

/*  ERROR                                                      */

        exit(1);
    }

/*  TDF is negative                                            */

    tzhour = -tzhour;
    tzmin = -tzmin;

}

/*  Fill in the fields...                                      */

tmtime.tm_year = year - 1900;
tmtime.tm_mon = --mon;
tmtime.tm_sec = tsec;
tnsec = (modf(tsec, &tmp)*1.0E9);
offset = tzhour*3600 + tzmin*60;
tminacc.tm_sec = isec;
insec = (modf(isec, &tmp)*1.0E9);

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

utc_mkanytime(&utc,     /* Out: Resultant binary timestamp      */
              &tmtime,  /* In:  tm struct that represents input */
              tnsec,    /* In:  Nanoseconds from input          */
              &tminacc, /* In:  tm struct that represents inacc */
              insec,    /* In:  Nanoseconds from input          */
              offset);  /* In:  TDF from input                  */