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;

1 - Parameters

    Input

 utc1

    Before binary timestamp or relative binary timestamp.

 utc2

    After binary timestamp or relative binary timestamp.

    Output

 result

    Spanning timestamp.

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.

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.

4 - Returns

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

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

6 - Related Functions

    utc_gettime, utc_pointtime, utc_spantime