Library /sys$common/syshlp/helplib.hlb  —  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.

1  –  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 VSI 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;

2.1  –  Parameters

    Input

 utc1

    Relative binary timestamp.

    Output

 result

    Absolute value of the input relative binary timestamp.

2.2  –  Description

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

2.3  –  Returns

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

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

3  –  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.1  –  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.2  –  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.3  –  Notes

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

3.4  –  Returns

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

3.5  –  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.6  –  Related Functions

    utc_subtime

4  –  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;

4.1  –  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.

4.2  –  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.

4.3  –  Returns

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

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

4.5  –  Related Functions

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

5  –  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;

5.1  –  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.

5.2  –  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.)

5.3  –  Notes

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

5.4  –  Returns

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

5.5  –  Example

    See the sample program for the utc_anytime routine.

5.6  –  Related Functions

    utc_anytime, utc_gmtzone, utc_localzone

6  –  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;

6.1  –  Parameters

    Input

 stringlen

    The length of the cp buffer.

 utc

    Binary timestamp.

    Output

 cp

    ASCII string that represents the time.

6.2  –  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.

6.3  –  Returns

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

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

6.5  –  Related Functions

    utc_ascgmtime, utc_asclocaltime

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

7.1  –  Parameters

    Input

 stringlen

    Length of the cp buffer.

 utc

    Binary timestamp.

    Output

 cp

    ASCII string that represents the time.

7.2  –  Description

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

7.3  –  Returns

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

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

7.5  –  Related Functions

    utc_ascanytime, utc_asclocaltime

8  –  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;

8.1  –  Parameters

    Input

 stringlen

    Length of the cp buffer.

 utc

    Binary timestamp.

    Output

 cp

    ASCII string that represents the time.

8.2  –  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.

8.3  –  Returns

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

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

8.5  –  Related Functions

    utc_ascanytime, utc_ascgmtime

9  –  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;

9.1  –  Parameters

    Input

 utc

    Relative binary timestamp.

 stringlen

    Length of the cp buffer.

    Output

 cp

    ASCII string that represents the time.

9.2  –  Description

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

9.3  –  Returns

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

9.4  –  Example

    See the sample program for the utc_abstime routine.

9.5  –  Related Functions

    utc_mkascreltime

10  –  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;

10.1  –  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.

10.2  –  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.

10.3  –  Returns

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

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

10.5  –  Related Functions

    utc_mkbinreltime

11  –  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;

11.1  –  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.

11.2  –  Description

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

11.3  –  Returns

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

11.4  –  Example

    See the sample program for the utc_anytime routine.

11.5  –  Related Functions

    utc_binreltime, utc_mkbintime

12  –  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;

12.1  –  Parameters

    Input

 utc1

    Before binary timestamp or relative binary timestamp.

 utc2

    After binary timestamp or relative binary timestamp.

    Output

 result

    Spanning timestamp.

12.2  –  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.

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

12.4  –  Returns

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

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

12.6  –  Related Functions

    utc_gettime, utc_pointtime, utc_spantime

13  –  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;

13.1  –  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

13.2  –  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.

13.3  –  Returns

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

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

13.5  –  Related Functions

    utc_cmpmidtime

14  –  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;

14.1  –  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

14.2  –  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

14.3  –  Returns

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

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

14.5  –  Related Functions

    utc_cmpintervaltime

15  –  utc_gettime

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

    Format

      #include <utc.h>

      int utc_gettime(*utc)

         utc_t *utc;

15.1  –  Parameters

    Input

    None.

    Output

 utc

    System time as a binary timestamp.

15.2  –  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.

15.3  –  Returns

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

15.4  –  Example

    See the sample program for the utc_binreltime routine.

16  –  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;

16.1  –  Parameters

    Input

    None.

    Output

 utc

    System time as a binary timestamp.

16.2  –  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.

16.3  –  Returns

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

16.4  –  Example

    See the sample program for the utc_boundtime routine.

16.5  –  Related Functions

    utc_gettime

17  –  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;

17.1  –  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.

17.2  –  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.

17.3  –  Returns

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

17.4  –  Example

    See the sample program for the utc_cmpintervaltime routine.

17.5  –  Related Functions

    utc_anytime, utc_gmtzone, utc_localtime, utc_mkgmtime

18  –  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;

18.1  –  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.

18.2  –  Description

    The Greenwich Mean Time Zone routine gets the time zone label
    and zero offset from GMT. Outputs are always tdf = 0 and tzname
    anyzone) and the Local Zone (utc_localzone) routines.

18.3  –  Notes

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

18.4  –  Returns

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

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

18.6  –  Related Functions

    utc_anyzone, utc_gmtime, utc_localzone

19  –  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;

19.1  –  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.

19.2  –  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.

19.3  –  Returns

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

19.4  –  Example

    See the sample program for the utc_gmtzone routine.

19.5  –  Related Functions

    utc_anytime, utc_gmtime, utc_localzone, utc_mklocaltime

20  –  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)

20.1  –  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.

20.2  –  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.

20.3  –  Notes

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

20.4  –  Returns

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

20.5  –  Example

    See the sample program for the utc_gmtzone routine.

20.6  –  Related Functions

    utc_anyzone, utc_gmtzone, utc_localtime

21  –  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;

21.1  –  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.

21.2  –  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.

21.3  –  Returns

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

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

21.5  –  Related Functions

    utc_anytime, utc_anyzone

22  –  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;

22.1  –  Parameters

    Input

 string

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

    Output

 utc

    Resulting binary timestamp.

22.2  –  Description

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

22.3  –  Notes

    The ASCII string must be null-terminated.

22.4  –  Returns

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

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

22.6  –  Related Functions

    utc_ascreltime

23  –  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;

23.1  –  Parameters

    Input

 string

    A null-terminated string that expresses an absolute time.

    Output

 utc

    Resulting binary timestamp.

23.2  –  Description

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

23.3  –  Notes

    The ASCII string must be null-terminated.

23.4  –  Returns

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

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

23.6  –  Related Functions

    utc_ascanytime, utc_ascgmtime, utc_asclocaltime

24  –  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;

24.1  –  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.

24.2  –  Description

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

24.3  –  Returns

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

24.4  –  Example

    See the sample program for the utc_addtime routine.

24.5  –  Related Functions

    utc_binreltime, utc_mkbintime

25  –  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;

25.1  –  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.

25.2  –  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.

25.3  –  Returns

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

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

25.5  –  Related Functions

    utc_bintime, utc_mkbinreltime

26  –  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;

26.1  –  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.

26.2  –  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.

26.3  –  Returns

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

26.4  –  Example

    See the sample program for the utc_cmpintervaltime routine.

26.5  –  Related Functions

    utc_gmtime

27  –  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;

27.1  –  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.

27.2  –  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.

27.3  –  Returns

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

27.4  –  Example

    See the sample program for the utc_cmpmidtime routine.

27.5  –  Related Functions

    utc_localtime

28  –  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;

28.1  –  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.

28.2  –  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.

28.3  –  Returns

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

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

28.5  –  Related Functions

    utc_reltime

29  –  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;

29.1  –  Parameters

    Input

 *timadr

    Binary OpenVMS format time.

 tdf

    Time differential factor to use in conversion.

    Output

 *utc

    Binary timestamp.

29.2  –  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.

29.3  –  Returns

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

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

29.5  –  Related Functions

    Function: utc_vmsanytime

30  –  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;

30.1  –  Parameters

    Input

 *timadr

    Binary OpenVMS format time representing GMT or the UTC
    equivalent.

    Output

 *utc

    Binary timestamp.

30.2  –  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.

30.3  –  Returns

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

30.4  –  Example

    See the sample program for the vmsgmtime routine.

30.5  –  Related Functions

    Function: utc_vmsgmtime

31  –  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;

31.1  –  Parameters

    Input

 *timadr

    Binary OpenVMS format time expressing local time.

    Output

 *utc

    Binary timestamp expressing the system's local time.

31.2  –  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.

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

31.4  –  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.

31.5  –  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.

31.5.1    /*********

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

31.5.2    /* convert to ISO ascii*/

    utc_asclocaltime(outstring,UTC_MAX_STR_LEN,&utcTime);

31.5.3    /* format and print */

    printf("Current time=> %s\n",outstring);
 }

31.5.4    /*****

  end example
  *****/

31.6  –  Related Functions

    Function: utc_vmslocaltime

32  –  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;

32.1  –  Parameters

    Input

 utc1

    Relative binary timestamp.

 factor

    Real scale factor (double-precision floating-point)

    Output

 result

    Resulting relative binary timestamp.

32.2  –  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.

32.3  –  Returns

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

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

32.5  –  Related Functions

    utc_multime

33  –  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;

33.1  –  Parameters

    Input

 utc1

    Relative binary timestamp.

 factor

    Integer scale factor.

    Output

 result

    Resulting relative binary timestamp.

33.2  –  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.

33.3  –  Returns

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

33.4  –  Example

    See the sample program for the utc_mulftime routine.

33.5  –  Related Functions

    utc_mulftime

34  –  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;

34.1  –  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.

34.2  –  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.

34.3  –  Notes

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

34.4  –  Returns

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

34.5  –  Example

    See the sample program for the utc_addtime routine.

34.6  –  Related Functions

    utc_boundtime, utc_spantime

35  –  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;

35.1  –  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.

35.2  –  Description

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

35.3  –  Returns

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

35.4  –  Example

    See the sample program for the utc_mulftime routine.

35.5  –  Related Functions

    utc_mkreltime

36  –  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;

36.1  –  Parameters

    Input

 utc1

    Binary timestamp.

 utc2

    Binary timestamp.

    Output

 result

    Spanning timestamp.

36.2  –  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).

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

36.4  –  Returns

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

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

36.6  –  Related Functions

    utc_boundtime, utc_gettime, utc_pointtime

37  –  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;

37.1  –  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.

37.2  –  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.

37.3  –  Notes

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

37.4  –  Returns

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

37.5  –  Example

    See the sample program for the utc_binreltime routine.

37.6  –  Related Functions

    utc_addtime

38  –  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;

38.1  –  Parameters

    Input

 *utc

    Binary timestamp.

    Output

 *timadr

    Binary OpenVMS format time.

38.2  –  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.

38.3  –  Returns

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

38.4  –  Example

    See the sample program for the mkvmsanytime routine.

38.5  –  Related Functions

    Function: utc_mkvmsanytime

39  –  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;

39.1  –  Parameters

    Input

 *utc

    Binary timestamp to be converted.

    Output

 *timadr

    Binary OpenVMS format time representing GMT or the UTC
    equivalent.

39.2  –  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.

39.3  –  Returns

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

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

39.5  –  Related Functions

    Function: utc_mkvmsgmtime

40  –  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;

40.1  –  Parameters

    Input

 *utc

    Binary timestamp.

    Output

 *timadr

    Binary OpenVMS format time expressing local time.

40.2  –  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.

40.3  –  Returns

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

40.4  –  Example

    See the sample program for the vmsgmtime routine.

40.5  –  Related Functions

    Function: utc_vmsmklocaltime

41  –  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>
    $
Close Help