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;

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

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

3  –  Returns

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

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

5  –  Related Functions

    utc_cmpintervaltime