/sys$common/syshlp/helplib.hlb DCE_DTS, Application Routines, utc_anytime  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME

   utc_anytime - Converts a binary timestamp to a tm structure

 SYNOPSIS

   #include <dce/utc.h>

   int utc_anytime( struct tm *timetm,
                    long *tns,
                    struct tm *inacctm,
                    long *ins,
                    long *tdf,
                    utc_t *utc );

 PARAMETERS

   Input

   utc
       Binary timestamp. Use NULL if you want this routine to use the
       current time for this parameter.

   Output

   timetm
       Time component of the binary timestamp expressed in the timestamp's
       local time.

   tns Nanoseconds since the Time component of the binary timestamp.

   inacctm
       Seconds of the 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 (zero). The field tm_yday contains
       the inaccuracy in days. If the inaccuracy is unspecified, all tm
       structure fields return values of -1.

   ins
       Nanoseconds of the inaccuracy component of the binary timestamp.

   tdf
       TDF component of the binary timestamp in units of seconds east of
       GMT.

 DESCRIPTION

   The utc_anytime() routine converts a binary timestamp to a tm structure
   by using the TDF information contained in the timestamp to determine the
   TDF returned with the 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.

 RETURN VALUES

    0    Indicates that the routine executed successfully.

   -1    Indicates an invalid time argument or invalid results.

 EXAMPLES

   The following example converts a timestamp by using the TDF information
   in the timestamp, and 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);

 RELATED INFORMATION

   Functions: utc_mkanytime
              utc_anyzone
              utc_gettime
              utc_getusertime
              utc_gmtime
              utc_localtime