1  DECdts
   You can use the Digital Distributed Time Service (DECdts)
   programming routines to obtain timestamps that are based on
   Coordinated Universal Time (UTC). You can also use the DECdts
   routines to translate among different timestamp formats and
   perform calculations on timestamps. Applications can use the
   timestamps that DECdts supplies to determine event sequencing,
   duration, and scheduling. Applications can call the DECdts
   routines from DECdts server or clerk systems.

   The Digital Distributed Time Service routines are written in
   the C programming language. You should be familiar with the
   basic DECdts concepts before you attempt to use the applications
   programming interface (API).

   The DECdts API routines can perform the following basic
   functions:

   o  Retrieve timestamp information

   o  Convert between binary timestamps that use different time
      structures

   o  Convert between binary timestamps and ASCII representations

   o  Convert between UTC time and local time

   o  Convert the binary time values in the OpenVMS (Smithsonian-
      based) format to or from UTC-based binary timestamps (OpenVMS
      systems only)

   o  Manipulate binary timestamps

   o  Compare two binary time values

   o  Calculate binary time values

   o  Obtain time zone information

   DECdts can convert between several types of binary time
   structures that are based on different calendars and time unit
   measurements. DECdts uses UTC-based time structures and can
   convert other types of time structures to its own presentation
   of UTC-based time.
 

2  Time_Terminology
   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.

   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.

   For detailed information about DECdts time representations, refer
   to the HP OpenVMS Utility Routines Manual.

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

   o  If utc is not specified as an input parameter, the current
      time is used.

   o  If inacc is not specified as an input parameter, infinity is
      used.

   o  If no output parameter is specified, no result (or an error)
      is returned.
 

2  utc_abstime
   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;
 

3  Parameters

   Input
 

utc1

   Relative binary timestamp.

   Output
 

result

   Absolute value of the input relative binary timestamp.
 

3  Description
   The Absolute Time routine computes the absolute value of a
   relative binary timestamp. The input timestamp represents a
   relative (delta) time.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time parameter or invalid results.
 

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

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

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

3  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:

   o  relative time + relative time = relative time

   o  absolute time + relative time = absolute time

   o  relative time + absolute time = absolute time

   o  absolute time + absolute time is undefined. See NOTES.
 

3  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.
 

3  Notes
   Although no error is returned, do not use the combination
   absolute time + absolute time.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time parameter or invalid results.
 

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

3  Related_Functions
   utc_subtime
 

2  utc_anytime
   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;
 

3  Parameters

   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.
 

3  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.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   The following example converts a timestamp, using the TDF
   information in the timestamp, then prints the result.

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

3  Related_Functions
   utc_mkanytime, utc_anyzone, utc_gettime, utc_getusertime, utc_
   gmtime, utc_localtime
 

2  utc_anyzone
   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;
 

3  Parameters

   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.
 

3  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.)
 

3  Notes
   All of the output parameters are optional. No value is returned
   and no error occurs if the pointer is null.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or an insufficient buffer.
 

3  Example
   See the sample program for the utc_anytime routine.
 

3  Related_Functions
   utc_anytime, utc_gmtzone, utc_localzone
 

2  utc_ascanytime
   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;
 

3  Parameters

   Input
 

stringlen

   The length of the cp buffer.
 

utc

   Binary timestamp.

   Output
 

cp

   ASCII string that represents the time.
 

3  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.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time parameter or invalid results.
 

3  Example
   The following example converts a time to an ASCII string that
   expresses the time in the time zone where the timestamp was
   generated.

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

3  Related_Functions
   utc_ascgmtime, utc_asclocaltime
 

2  utc_ascgmtime
   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;
 

3  Parameters

   Input
 

stringlen

   Length of the cp buffer.
 

utc

   Binary timestamp.

   Output
 

cp

   ASCII string that represents the time.
 

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

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time parameter or invalid results.
 

3  Example
   The following example converts the current time to GMT format.

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

3  Related_Functions
   utc_ascanytime, utc_asclocaltime
 

2  utc_asclocaltime
   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;
 

3  Parameters

   Input
 

stringlen

   Length of the cp buffer.
 

utc

   Binary timestamp.

   Output
 

cp

   ASCII string that represents the time.
 

3  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.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time parameter or invalid results.
 

3  Example
   The following example converts the current time to local time.

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

3  Related_Functions
   utc_ascanytime, utc_ascgmtime
 

2  utc_ascreltime
   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;
 

3  Parameters

   Input
 

utc

   Relative binary timestamp.
 

stringlen

   Length of the cp buffer.

   Output
 

cp

   ASCII string that represents the time.
 

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

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time parameter or invalid results.
 

3  Example
   See the sample program for the utc_abstime routine.
 

3  Related_Functions
   utc_mkascreltime
 

2  utc_binreltime
   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;
 

3  Parameters

   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.
 

3  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.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   The following example measures the duration of a process, then
   prints the resulting relative time and inaccuracy.

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

3  Related_Functions
   utc_mkbinreltime
 

2  utc_bintime
   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;
 

3  Parameters

   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.
 

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

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the utc_anytime routine.
 

3  Related_Functions
   utc_binreltime, utc_mkbintime
 

2  utc_boundtime
   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;
 

3  Parameters

   Input
 

utc1

   Before binary timestamp or relative binary timestamp.
 

utc2

   After binary timestamp or relative binary timestamp.

   Output
 

result

   Spanning timestamp.
 

3  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.
 

3  Notes
   The TDF in the output UTC value is copied from the utc2 input. If
   one or both input values have infinite inaccuracies, the returned
   time value also has an infinite inaccuracy and is the average of
   the two input values.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time parameter or invalid parameter
        order.
 

3  Example
   The following example records the time of an event and constructs
   a single timestamp, which includes the time of the event. Note
   that the utc_getusertime routine is called so the time zone
   information that is included in the timestamp references the
   user's environment rather than the system's default 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.

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

3  Related_Functions
   utc_gettime, utc_pointtime, utc_spantime
 

2  utc_cmpintervaltime
   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;
 

3  Parameters

   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:

   o  utc_equalTo

   o  utc_lessThan

   o  utc_greaterThan

   o  utc_indeterminate
 

3  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.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument.
 

3  Example
   The following example checks to see if the current time is
   definitely after 1:00 P.M. today GMT.

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

3  Related_Functions
   utc_cmpmidtime
 

2  utc_cmpmidtime
   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;
 

3  Parameters

   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:

   o  utc_equalTo

   o  utc_lessThan

   o  utc_greaterThan
 

3  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
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument.
 

3  Example
   The following example checks if the current time (ignoring
   inaccuracies) is after 1:00 P.M. today local 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.
    */
   }
 

3  Related_Functions
   utc_cmpintervaltime
 

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

   Format

     #include <utc.h>

     int utc_gettime(*utc)

        utc_t *utc;
 

3  Parameters

   Input

   None.

   Output
 

utc

   System time as a binary timestamp.
 

3  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.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Generic error that indicates the time service cannot be
        accessed.
 

3  Example
   See the sample program for the utc_binreltime routine.
 

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

   Format

     #include <utc.h>

     int utc_getusertime(*utc)

        utc_t *utc;
 

3  Parameters

   Input

   None.

   Output
 

utc

   System time as a binary timestamp.
 

3  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.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Generic error that indicates the time service cannot be
        accessed.
 

3  Example
   See the sample program for the utc_boundtime routine.
 

3  Related_Functions
   utc_gettime
 

2  utc_gmtime
   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;
 

3  Parameters

   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.
 

3  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.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the utc_cmpintervaltime routine.
 

3  Related_Functions
   utc_anytime, utc_gmtzone, utc_localtime, utc_mkgmtime
 

2  utc_gmtzone
   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;
 

3  Parameters

   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.
 

3  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.
 

3  Notes
   All of the output parameters are optional. No value is returned
   and no error occurs if the tzname pointer is NULL.
 

3  Returns

    0   Indicates that the routine executed successfully (always
        returned).
 

3  Example
   The following example prints out the current time in both local
   time and GMT time.

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

3  Related_Functions
   utc_anyzone, utc_gmtime, utc_localzone
 

2  utc_localtime
   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;
 

3  Parameters

   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.
 

3  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.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the utc_gmtzone routine.
 

3  Related_Functions
   utc_anytime, utc_gmtime, utc_localzone, utc_mklocaltime
 

2  utc_localzone
   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)
 

3  Parameters

   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.
 

3  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.
 

3  Notes
   All of the output parameters are optional. No value is returned
   and no error occurs if the pointer is null.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or an insufficient buffer.
 

3  Example
   See the sample program for the utc_gmtzone routine.
 

3  Related_Functions
   utc_anyzone, utc_gmtzone, utc_localtime
 

2  utc_mkanytime
   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;
 

3  Parameters

   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.
 

3  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.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   The following example converts a string ISO format time in an
   arbitrary time zone to a binary timestamp. This may be part of
   an input timestamp routine, although a real implementation will
   include range checking.

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

3  Related_Functions
   utc_anytime, utc_anyzone
 

2  utc_mkascreltime
   Converts a null-terminated character string that represents a
   relative timestamp to a binary timestamp.

   Format

     #include <utc.h>

     int utc_mkascreltime(*utc, *string)

        utc_t *utc;
        char *string;
 

3  Parameters

   Input
 

string

   A null-terminated string that expresses a relative timestamp in
   its ISO format.

   Output
 

utc

   Resulting binary timestamp.
 

3  Description
   The Make ASCII Relative Time routine converts a null-terminated
   string, which represents a relative timestamp, to a binary
   timestamp.
 

3  Notes
   The ASCII string must be null-terminated.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time parameter or invalid results.
 

3  Example
   The following example converts an ASCII relative time string to
   its binary equivalent.

   utc_t      utc;
   char       str[UTC_MAX_STR_LEN];

   /*
    * Relative time of 333 days, 12 hours, 1 minute, 37.223 seconds
    * Inaccuracy of 50.22 sec. in the format: -333-12:01:37.223I50.22
    */

   (void)strcpy((void *)str,
                "-333-12:01:37.223I50.22");

   utc_mkascreltime(&utc,   /* Out: Binary utc               */
                    str);   /* In:  String                   */
 

3  Related_Functions
   utc_ascreltime
 

2  utc_mkasctime
   Converts a null-terminated character string that represents an
   absolute time to a binary timestamp.

   Format

     #include <utc.h>

     int utc_mkasctime(*utc, *string)

        utc_t *utc;
        char *string;
 

3  Parameters

   Input
 

string

   A null-terminated string that expresses an absolute time.

   Output
 

utc

   Resulting binary timestamp.
 

3  Description
   The Make ASCII Time routine converts a null-terminated string
   that represents an absolute time to a binary timestamp.
 

3  Notes
   The ASCII string must be null-terminated.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time parameter or invalid results.
 

3  Example
   The following example converts an ASCII time string to its binary
   equivalent.

   utc_t     utc;
   char      str[UTC_MAX_STR_LEN];

   /*
    *   July 4, 1776, 12:01:37.223 local time
    *   TDF of -5:00 hours
    *   Inaccuracy of 3600.32 seconds
    */

   (void)strcpy((void *)str,
                "1776-07-04-12:01:37.223-5:00 I 3600.32");

   utc_mkasctime(&utc,    /* Out: Binary utc            */
                 str);    /* In:  String                */
 

3  Related_Functions
   utc_ascanytime, utc_ascgmtime, utc_asclocaltime
 

2  utc_mkbinreltime
   Converts a timespec structure expressing a relative time to a
   binary timestamp.

   Format

     #include <utc.h>

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

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

3  Parameters

   Input
 

timesp

   A reltimespec structure that expresses a relative time.
 

inaccsp

   A timespec structure that expresses inaccuracy. If tv_sec is set
   to a value of -1, the inaccuracy is considered to be infinite.

   Output
 

utc

   Resulting relative binary timestamp.
 

3  Description
   The Make Binary Relative Time routine converts a timespec
   structure that expresses relative time to a binary timestamp.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the utc_addtime routine.
 

3  Related_Functions
   utc_binreltime, utc_mkbintime
 

2  utc_mkbintime
   Converts a timespec structure to a binary timestamp.

   Format

     #include <utc.h>

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

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

3  Parameters

   Input
 

timesp

   A timespec structure that expresses time since 1970-01-
   01:00:00:00.0+0:00I0.
 

inaccsp

   A timespec structure that expresses inaccuracy. If tv_sec is set
   to a value of -1, the inaccuracy is considered to be infinite.
 

tdf

   TDF component of the binary timestamp.

   Output
 

utc

   Resulting binary timestamp.
 

3  Description
   The Make Binary Time routine converts a timespec structure time
   to a binary timestamp. The TDF input is used as the TDF of the
   binary timestamp.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   The following example obtains the current time from time(),
   converts it to a binary timestamp with an inaccuracy of 5.2
   seconds, and specifies GMT.

   timespec_t   ttime, tinacc;
   utc_t        utc;

   /*
    *   Obtain the current time (without the inaccuracy)...
    */

   ttime.tv_sec = time((time_t *)0);
   ttime.tv_nsec = 0;

   /*
    *   Specify the inaccuracy...
    */

   tinacc.tv_sec = 5;
   tinacc.tv_nsec = 200000000;

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

   utc_mkbintime(&utc,       /* Out: Binary timestamp          */
                 &ttime,     /* In:  Current time in timespec  */
                 &tinacc,    /* In:  5.2 seconds in timespec   */
                 0);         /* In:  TDF of GMT                */
 

3  Related_Functions
   utc_bintime, utc_mkbinreltime
 

2  utc_mkgmtime
   Converts a tm structure that expresses GMT or UTC to a binary
   timestamp.

   Format

     #include <utc.h>

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

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

3  Parameters

   Input
 

timetm

   A tm structure that expresses GMT. On input, tm_wday and tm_yday
   are ignored.
 

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. On input, tm_mday, tm_mon, tm_wday,
   tm_isdst, tm_gmtoff, and tm_zone are ignored.
 

ins

   Nanoseconds of inaccuracy component.

   Output
 

utc

   Resulting binary timestamp.
 

3  Description
   The Make Greenwich Mean Time routine converts a tm structure that
   expresses GMT or UTC to a binary timestamp. Additional inputs
   include nanoseconds since the last second of time and nanoseconds
   of inaccuracy.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the utc_cmpintervaltime routine.
 

3  Related_Functions
   utc_gmtime
 

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

   Format

     #include <utc.h>

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

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

3  Parameters

   Input
 

timetm

   A tm structure that expresses the local time. On input, tm_wday
   and tm_yday are ignored.
 

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. On input, tm_mday, tm_mon, tm_wday,
   tm_isdst, tm_gmtoff, and tm_zone are ignored.
 

ins

   Nanoseconds of inaccuracy component.

   Output
 

utc

   Resulting binary timestamp.
 

3  Description
   The Make Local Time routine converts a tm structure that
   expresses local time to a binary timestamp.

   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 inputs include nanoseconds since the last second of
   time and nanoseconds of inaccuracy.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the utc_cmpmidtime routine.
 

3  Related_Functions
   utc_localtime
 

2  utc_mkreltime
   Converts a tm structure that expresses relative time to a
   relative binary timestamp.

   Format

     #include <utc.h>

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

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

3  Parameters

   Input
 

timetm

   A tm structure that expresses a relative time. On input, tm_wday
   and tm_yday are ignored.
 

tns

   Nanoseconds since time component.
 

inacctm

   A tm structure that expresses seconds of inaccuracy. If tm_yday
   is negative, the inaccuracy is considered to be infinite. On
   input, tm_mday, tm_mon, tm_year, tm_wday, tm_isdst, and tm_zone
   are ignored.
 

ins

   Nanoseconds of inaccuracy component.

   Output
 

utc

   Resulting relative binary timestamp.
 

3  Description
   The Make Relative Time routine converts a tm structure that
   expresses relative time to a relative binary timestamp.
   Additional inputs include nanoseconds since the last second of
   time and nanoseconds of inaccuracy.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   The following example converts a string relative time in the
   format (1991-04-01-12:12:12.12I12.12) to a binary timestamp. This
   may be part of an input relative timestamp routine, though a real
   implementation will include range checking.

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

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

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

   /*
    *   ERROR...
    */
       exit(1);

   }

   /*
    *   Fill in the fields...
    */

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

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

   utc_mkreltime(&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          */
 

3  Related_Functions
   utc_reltime
 

2  utc_mkvmsanytime
   Converts a binary OpenVMS format time and TDF (expressing the
   time in an arbitrary time zone) to a binary timestamp.

   Format

     #include <utc.h>

     int utc_mkvmsanytime(*utc, *timadr, tdf)

        utc_t *utc;
        const long *timadr;
        const long tdf;
 

3  Parameters

   Input
 

*timadr

   Binary OpenVMS format time.
 

tdf

   Time differential factor to use in conversion.

   Output
 

*utc

   Binary timestamp.
 

3  Description
   The Make VMS Any Time routine converts a binary time in the
   OpenVMS (Smithsonian) format and an arbitrary TDF to a UTC-based
   binary timestamp. Because the input and output values are based
   on different time standards, any input representing a value after
   A.D. 30,000 returns an error.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example

   The following example shows how to convert between OpenVMS format
   binary timestamps and UTC binary timestamps, while specifying the
   TDF for each. The TDF value determines the offset from GMT and
   the local time.

   /*****
    start example mkvmsanytime,vmsanytime
    *****/
   #include <utc.h>

   main()
   {
   struct utc utcTime;
   int vmsTime[2];

   SYS$GETTIM(vmsTime);    /* read the current time */

   /*
    * convert the VMS local time to a UTC, applying a TDF of
    * -300 minutes (the timezone is -5 hours from GMT)
    */
   if (utc_mkvmsanytime(&utcTime,vmsTime,-300))
       exit(1);

   /*
    * convert UTC back to VMS local time.  A TDF of -300 is applied
    * to the UTC, since utcTime was constructed with that same value.
    * This effectively gives us the same VMS time value we started
    * with.
    */
   if (utc_vmsanytime(vmsTime,&utcTime))
       exit(2);
   }
   /****
     end example
    ****/
 

3  Related_Functions
   Function: utc_vmsanytime
 

2  utc_mkvmsgmtime
   Converts a binary OpenVMS format time expressing GMT (or the
   equivalent UTC) into a binary timestamp.

   Format

     #include <utc.h>

     int utc_mkvmsgmtime(*utc, *timadr)

        utc_t *utc;
        const long *timadr;
 

3  Parameters

   Input
 

*timadr

   Binary OpenVMS format time representing GMT or the UTC
   equivalent.

   Output
 

*utc

   Binary timestamp.
 

3  Description
   The Make VMS Greenwich Mean Time routine converts an OpenVMS
   format binary time representing GMT to a binary timestamp with
   the equivalent UTC value. Since the input and output values are
   based on different time standards, any input representing a value
   after A.D. 30,000 returns an error.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the vmsgmtime routine.
 

3  Related_Functions
   Function: utc_vmsgmtime
 

2  utc_mkvmslocaltime
   Converts a local binary OpenVMS format time to a binary
   timestamp, using the host system's time differential factor.

   Format

     #include <utc.h>

     int utc_mkvmslocaltime(*utc, *timadr)

        const long *timadr;
        utc_t *utc;
 

3  Parameters

   Input
 

*timadr

   Binary OpenVMS format time expressing local time.

   Output
 

*utc

   Binary timestamp expressing the system's local time.
 

3  Description
   The Make VMS Local Time routine converts a binary OpenVMS format
   time, representing the local time of the host system, to a binary
   timestamp. The system's local time value is defined by the time
   zone rule in sys$timezone_rule, which is created by the system
   configuration process sys$manager:net$configure.com.
 

3  Notes
   If the routine call is made during a seasonal time zone change
   when the local time is indeterminate, an error is returned. For
   example, if the time zone change occurs at the current local time
   of 2:00 A.M. to a new local time of 1:00 A.M., and the routine is
   called between 1:00 A.M. and 2:00 A.M., it cannot be determined
   which TDF applies.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument, invalid results, or
        invalid routine call during a time zone change.
 

3  Example

   The following example shows how to retrieve the current local
   time of the system in the binary OpenVMS format, convert the
   OpenVMS format time to a UTC-based binary timestamp (using the
   system's TDF), and print an ASCII representation of the binary
   timestamp.

/*********
  start example mkvmslocaltime
 *********/
#include <utc.h>

main()
{
char outstring[UTC_MAX_STR_LEN];
struct utc utcTime;
int vmsTime[2];

SYS$GETTIM(vmsTime);                      /* read current time      */

if (utc_mkvmslocaltime(&utcTime,vmsTime)) /* convert the local time */
    exit(1);                              /* vmsTime to UTC using   */
                                          /* the system tdf.        */

/* convert to ISO ascii*/
   utc_asclocaltime(outstring,UTC_MAX_STR_LEN,&utcTime);
/* format and print */
   printf("Current time=> %s\n",outstring);
}
/*****
 end example
 *****/
 

3  Related_Functions
   Function: utc_vmslocaltime
 

2  utc_mulftime
   Multiplies a relative binary timestamp by a floating-point value.

   Format

     #include <utc.h>

     int utc_mulftime(*result, *utc1, factor)

        utc_t *result;
        const utc_t *utc1;
        const double factor;
 

3  Parameters

   Input
 

utc1

   Relative binary timestamp.
 

factor

   Real scale factor (double-precision floating-point)

   Output
 

result

   Resulting relative binary timestamp.
 

3  Description
   The Multiply a Relative Time by a Real Factor routine multiplies
   a relative binary timestamp by a floating-point value. Either
   or both may be negative; the resulting relative binary timestamp
   has the appropriate sign. The unsigned inaccuracy in the relative
   binary timestamp is also multiplied by the absolute value of the
   floating-point value.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example

   The following example scales and prints a relative time.

   utc_t       relutc, scaledutc;
   struct tm   sacledreltm;
   char        timstr[UTC_MAX_STR_LEN];

   /*
    * Assume relutc contains the time to scale.
    * Scale it by a factor of 17...
    */

   utc_multime(&scaledutc,          /* Out: Scaled rel time     */
               &relutc,             /* In:  Rel time to scale   */
               17L);                /* In:  Scale factor        */

   utc_ascreltime(timstr,           /* Out: ASCII rel time      */
                  UTC_MAX_STR_LEN,  /* In:  Length of input str */
                  &scaledutc);      /* In:  Rel time to convert */

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

   /*
    *   Scale it by a factor of 17.65...
    */

   utc_mulftime(&scaledutc,         /* Out: Scaled rel time     */
                &relutc,            /* In:  Rel time to scale   */
                17.65);             /* In:  Scale factor        */

   utc_ascreltime(timstr,           /* Out: ASCII rel time      */
                  UTC_MAX_STR_LEN,  /* In:  Input str length    */
                  &scaledutc);      /* In:  Rel time to convert */

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

   /*
    *    Convert it to a tm structure and print it.
    */

   utc_reltime(&scaledreltm,        /* Out: Scaled rel tm       */
               (long *)0,           /* Out: Scaled rel nano-sec */
               (struct tm *)0,      /* Out: Scaled rel inacc tm */
               (long *)0,           /* Out: Scd rel inacc nanos */
               &scaledutc);         /* In:  Rel time to convert */

   printf("Approximately %d days, %d hours and %d minutes\n",
    scaledreltm.tm_yday, scaledreltm.tm_hour, scaledreltm.tm_min);
 

3  Related_Functions
   utc_multime
 

2  utc_multime
   Multiplies a relative binary timestamp by an integer factor.

   Format

     #include <utc.h>

     int utc_multime(*result, *utc1, factor)

        utc_t *result;
        const utc_t *utc1;
        long factor;
 

3  Parameters

   Input
 

utc1

   Relative binary timestamp.
 

factor

   Integer scale factor.

   Output
 

result

   Resulting relative binary timestamp.
 

3  Description
   The Multiply Relative Time by an Integer Factor routine
   multiplies a relative binary timestamp by an integer. Either
   or both may be negative; the resulting binary timestamp has the
   appropriate sign. The unsigned inaccuracy in the binary timestamp
   is also multiplied by the absolute value of the integer.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the utc_mulftime routine.
 

3  Related_Functions
   utc_mulftime
 

2  utc_pointtime
   Converts a binary timestamp to three binary timestamps that
   represent the earliest, most likely, and latest time.

   Format

     #include <utc.h>

     int utc_pointtime(*utclp, *utcmp, *utchp, *utc)

        utc_t *utclp;
        utc_t *utcmp;
        utc_t *utchp;
        const utc_t *utc;
 

3  Parameters

   Input
 

utc

   Binary timestamp or relative binary timestamp.

   Output
 

utclp

   Lowest (earliest) possible time that the input binary timestamp
   or shortest possible relative time that the relative binary
   timestamp can represent.
 

utcmp

   Midpoint of the input binary timestamp or the midpoint of the
   input relative binary timestamp.
 

utchp

   Highest (latest) possible time that the input binary timestamp
   or the longest possible relative time that the relative binary
   timestamp can represent.
 

3  Description
   The Point Time routine converts a binary timestamp to three
   binary timestamps that represent the earliest, latest, and most
   likely (midpoint) times. If the input is a relative binary time,
   the outputs represent relative binary times.
 

3  Notes
   All outputs have zero inaccuracy. An error is returned if the
   input binary timestamp has an infinite inaccuracy.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument.
 

3  Example
   See the sample program for the utc_addtime routine.
 

3  Related_Functions
   utc_boundtime, utc_spantime
 

2  utc_reltime
   Converts a relative binary timestamp to a tm structure.

   Format

     #include <utc.h>

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

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

3  Parameters

   Input
 

utc

   Relative binary timestamp.

   Output
 

timetm

   Relative time component of the relative binary timestamp. The
   field tm_mday returns a value of -1 and the fields tm_year and
   tm_mon return values of zero. The field tm_yday contains the
   number of days of relative time.
 

tns

   Nanoseconds since time component of the relative binary
   timestamp.
 

inacctm

   Seconds of inaccuracy component of the relative 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 relative binary
   timestamp.
 

3  Description
   The Relative Time routine converts a relative binary timestamp to
   a tm structure. Additional returns include nanoseconds since time
   and nanoseconds of inaccuracy.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the utc_mulftime routine.
 

3  Related_Functions
   utc_mkreltime
 

2  utc_spantime
   Given two (possibly unordered) binary timestamps, returns a
   single UTC time interval whose inaccuracy spans the two input
   binary timestamps.

   Format

     #include <utc.h>

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

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

3  Parameters

   Input
 

utc1

   Binary timestamp.
 

utc2

   Binary timestamp.

   Output
 

result

   Spanning timestamp.
 

3  Description
   Given two binary timestamps, the Span Time routine returns a
   single UTC time interval whose inaccuracy spans the two input
   timestamps (that is, the interval resulting from the earliest
   possible time of either timestamp to the latest possible time of
   either timestamp).
 

3  Notes
   The tdf in the output UTC value is copied from the utc2 input.
   If either input binary timestamp has an infinite inaccuracy, an
   error is returned.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument.
 

3  Example
   The following example computes the earliest and latest times for
   an array of 10 timestamps.

   utc_t               time_array[10], testtime, earliest, latest;
   int                 i;

   /*
    *   Set the running timestamp to the first entry...
    */

   testtime = time_array[0];

   for (i=1; i<10; i++) {

      /*
       *   Compute the minimum and the maximum against the next
       *   element...
       */

   utc_spantime(&testtime,       /* Out: Resultant interval        */
                &testtime,       /* In:  Largest previous interval */
                &time_array[i]); /* In:  Element under test        */
   }

   /*
    *   Compute the earliest possible time...
    */

   utc_pointtime(&earliest,    /* Out: Earliest poss time in array */
                (utc_t *)0,    /* Out: Midpoint                    */
                &latest,       /* Out: Latest poss time in array   */
                &testtime);    /* In:  Spanning interval           */
 

3  Related_Functions
   utc_boundtime, utc_gettime, utc_pointtime
 

2  utc_subtime
   Computes the difference between two binary timestamps that
   express either an absolute time and a relative time, two relative
   times, or two absolute times.

   Format

     #include <utc.h>

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

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

3  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:

   o  absolute time - absolute time = relative time

   o  relative time - relative time = relative time

   o  absolute time - relative time = absolute time

   o  relative time - absolute time is undefined. See NOTES.
 

3  Description
   The Subtract Time routine subtracts one binary timestamp
   from another. The resulting timestamp is utc1 minus utc2.
   The inaccuracies of the two input timestamps are combined and
   included in the output timestamp. The TDF in the first timestamp
   is copied to the output.
 

3  Notes
   Although no error is returned, do not use the combination
   relative time - absolute time.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the utc_binreltime routine.
 

3  Related_Functions
   utc_addtime
 

2  utc_vmsanytime
   Converts a binary timestamp to a binary OpenVMS format time.
   The TDF encoded in the input timestamp determines the TDF of the
   output.

   Format

     #include <utc.h>

     int utc_vmsanytime(*timadr, *utc)

        const utc_t *utc;
        long *timadr;
 

3  Parameters

   Input
 

*utc

   Binary timestamp.

   Output
 

*timadr

   Binary OpenVMS format time.
 

3  Description
   The VMS Any Time routine converts a UTC-based binary timestamp
   to a 64-bit binary time in the OpenVMS (Smithsonian) format.
   Because the input and output values are based on different time
   standards, any input representing a value before the Smithsonian
   base time of November 17, 1858 returns an error.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the mkvmsanytime routine.
 

3  Related_Functions
   Function: utc_mkvmsanytime
 

2  utc_vmsgmtime
   Converts a binary timestamp to a binary OpenVMS format time
   expressing GMT or the equivalent UTC.

   Format

     #include <utc.h>

     int utc_vmsgmtime(*timadr, *utc)

        const utc_t *utc;
        long *timadr;
 

3  Parameters

   Input
 

*utc

   Binary timestamp to be converted.

   Output
 

*timadr

   Binary OpenVMS format time representing GMT or the UTC
   equivalent.
 

3  Description
   The OpenVMS Greenwich Mean Time routine converts a UTC-based
   binary timestamp to a 64-bit binary time in the OpenVMS
   (Smithsonian) format. The OpenVMS format time represents
   Greenwich Mean Time or the equivalent UTC. Because the input and
   output values are based on different time standards, any input
   representing a value before the Smithsonian base time of November
   17, 1858 returns an error.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example

   The following example shows the following time zone and time
   format conversions:

   1. Retrieve a binary timestamp representing UTC with the
      sys$getutc system service.

   2. Convert the binary timestamp to a OpenVMS format binary time
      representing GMT

   3. Convert the OpenVMS format binary time representing GMT back
      to a UTC-based binary timestamp with a TDF of 0 (zero)

   4. Convert the UTC-based binary time to a binary OpenVMS format
      time representing the local time; use the TDF from the system

   /*****
     start example vmsgmtime, mkvmsgmtime, vmslocaltime
    *****/
   #include <utc.h>

   main()
   {
   int status;
   struct utc utcTime;
   int vmsTime[2];

    if (!((status=SYS$GETUTC(&utcTime))&1))
        exit(status);              /* read curr time as a utc */

   /*
    * convert the utcvalue into a vms time, with a timezone of 0
    * (GMT).  Printing the resultant vmstime yields the time at
    * the prime meridian in Greenwich, not (necessarily) the
    * local time.
    */
    if (utc_vmsgmtime(vmsTime,&utcTime))
       exit(1);

   /*
    * Convert the vmstime (which is in GMT) to a utc
    */
   if (utc_mkvmsgmtime(&utcTime, vmsTime))
       exit(2);

   /*
    *  convert the UTC to local 64-bit time.  Note that this is the
    *  value we would have read if we had issued a 'SYS$GETTIM' in
    *  the initial statement.
    */
   if (utc_vmslocaltime(vmsTime, &utcTime))
       exit(3);
   }
   /*****
    end example
    *****/
 

3  Related_Functions
   Function: utc_mkvmsgmtime
 

2  utc_vmslocaltime
   Converts a binary timestamp to a local binary OpenVMS format
   time, using the host system's time differential factor.

   Format

     #include <utc.h>

     int utc_vmslocaltime(*timadr, *utc)

        const utc_t *utc;
        long *timadr;
 

3  Parameters

   Input
 

*utc

   Binary timestamp.

   Output
 

*timadr

   Binary OpenVMS format time expressing local time.
 

3  Description
   The VMS Local Time routine converts a binary timestamp to a
   binary OpenVMS format time; the output value represents the
   local time of the host system. The system's offset from UTC
   and the local time value are defined by the time zone rule in
   sys$timezone_rule, which is created by the system configuration
   process sys$manager:net$configure.com.
 

3  Returns

    0   Indicates that the routine executed successfully.
   -1   Indicates an invalid time argument or invalid results.
 

3  Example
   See the sample program for the vmsgmtime routine.
 

3  Related_Functions
   Function: utc_vmsmklocaltime
 

2  Example
The following C programming example shows a practical application
of the DECdts API programming routines. The program performs the
following actions:

   o  Prompts the user to enter time coordinates.

   o  Stores those coordinates in a tm structure.

   o  Converts the tm structure to a utc structure.

   o  Determines which event occurred first.

   o  Determines if Event 1 may have caused Event 2 by comparing the
      intervals.

   o  Prints out the utc structure in ISO text format.

   #include <time.h>   /* time data structures                   */
   #include <utc.h>    /* utc structure definitions              */

   void ReadTime();
   void PrintTime();

   /*
    * This program requests user input about events, then prints out
    * information about those events.
    */

   main()
   {
       struct utc event1,event2;
       enum utc_cmptype relation;

       /*
        * Read in the two events.
        */

       ReadTime(&event1);
       ReadTime(&event2);

       /*
        * Print out the two events.
        */

       printf("The first event is : ");
       PrintTime(&event1);
       printf("\nThe second event is : ");
       PrintTime(&event2);
       printf("\n");

       /*
        * Determine which event occurred first.
        */
       if (utc_cmpmidtime(&relation,&event1,&event2))
           exit(1);

       switch( relation )
       {
           case utc_lessThan:
           printf("comparing midpoints: Event1 < Event2\n");
           break;
           case utc_greaterThan:
           printf("comparing midpoints: Event1 > Event2\n");
           break;
           case utc_equalTo:
           printf("comparing midpoints: Event1 == Event2\n");
           break;
           default:
           exit(1);
           break;
       }

       /*
        * Could Event 1 have caused Event 2?  Compare the intervals.
        */

       if (utc_cmpintervaltime(&relation,&event1,&event2))
           exit(1);

       switch( relation )
       {
           case utc_lessThan:
           printf("comparing intervals: Event1 < Event2\n");
           break;
           case utc_greaterThan:
           printf("comparing intervals: Event1 > Event2\n");
           break;
           case utc_equalTo:
           printf("comparing intervals: Event1 == Event2\n");
           break;
           case utc_indeterminate:
           printf("comparing intervals: Event1 ? Event2\n");
           default:
           exit(1);
           break;
       }

   }

   /*
    * Print out a utc structure in ISO text format.
    */

   void PrintTime(utcTime)
   struct utc *utcTime;
   {

       char   string[50];

       /*
        * Break up the time string.
        */

       if (utc_ascgmtime(string,      /* Out: Converted time    */
                         50,          /* In:  String length     */
                         utcTime))    /* In:  Time to convert   */
           exit(1);
       printf("%s\n",string);
   }

   /*
    * Prompt the user to enter time coordinates.  Store the
    * coordinates in a tm structure and then convert the
    * tm structure to a utc structure.
    */

   void ReadTime(utcTime)
   struct utc *utcTime;
   {
   struct tm tmTime,tmInacc;

       (void)memset((void *)&tmTime,  0,sizeof(tmTime));
       (void)memset((void *)&tmInacc, 0,sizeof(tmInacc));
       (void)printf("Year? ");
       (void)scanf("%d",&tmTime.tm_year);
       tmTime.tm_year -= 1900;
       (void)printf("Month? ");
       (void)scanf("%d",&tmTime.tm_mon);
       tmTime.tm_mon -= 1;
       (void)printf("Day? ");
       (void)scanf("%d",&tmTime.tm_mday);
       (void)printf("Hour? ");
       (void)scanf("%d",&tmTime.tm_hour);
       (void)printf("Minute? ");
       (void)scanf("%d",&tmTime.tm_min);
       (void)printf("Inacc Secs? ");
       (void)scanf("%d",&tmInacc.tm_sec);

       if (utc_mkanytime(utcTime,
                         &tmTime,
                         (long)0,
                         &tmInacc,
                         (long)0,
                         (long)0))
           exit(1);

   }

   Assume the preceding program is named compare_events.c. To
   compile and link the program on a DECnet-Plus for OpenVMS system,
   enter the following command:

   $ cc compare_events.c/output=compare_events.obj
   $ link compare_events.obj, sys$input:/options<Return>
   sys$library:dtss$shr.exe/share<Ctrl-z>
   $