NAME

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

 SYNOPSIS

   #include <dce/utc.h>

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

 PARAMETERS

   Input

   utc1
       Before binary timestamp or relative binary timestamp.  Use
       NULL if you want this routine to use the current time for
       this parameter.

   utc2
       After binary timestamp or relative binary timestamp.  Use
       NULL if you want this routine to use the current time for
       this parameter.

   Output

   result
       Spanning timestamp.

 DESCRIPTION

   Given two UTC times, the utc_boundtime() 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.

 NOTES

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

 RETURN VALUES

    0    Indicates that the routine executed successfully.

   -1    Indicates an invalid time parameter or invalid parameter order.

 EXAMPLES

   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.

   The user's environment determines the time zone rule (details are
   system dependent).

   If the user's environment does not specify a time zone rule, the
   system's rule is used (details of the rule are system dependent).
   For example, on OpenVMS systems, the rule pointed to by the filename
   in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies.

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

 RELATED INFORMATION

   Functions: utc_gettime
              utc_pointtime
              utc_spantime