HP OpenVMS Utility Routines Manual


Previous Contents Index


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)

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.

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.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument or invalid results.
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); 
Related Functions utc_mkanytime , utc_anyzone , utc_gettime , utc_getusertime , utc_gmtime , utc_localtime


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)

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.

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.)
Notes All of the output parameters are optional. No value is returned and no error occurs if the pointer is null. Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument or an insufficient buffer.
Example See the sample program for the utc_anytime routine. Related Functions utc_anytime , utc_gmtzone , utc_localzone

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)

Parameters

Input

stringlen

The length of the cp buffer.

utc

Binary timestamp.

Output

cp

ASCII string that represents the time.

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.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time parameter or invalid results.
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     */ 
Related Functions utc_ascgmtime , utc_asclocaltime


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)

Parameters

Input

stringlen

Length of the cp buffer.

utc

Binary timestamp.

Output

cp

ASCII string that represents the time.

Description

The ASCII GMT Time routine converts a binary timestamp to an ASCII string that expresses a time in GMT.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time parameter or invalid results.
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 */ 
Related Functions utc_ascanytime , utc_asclocaltime


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)

Parameters

Input

stringlen

Length of the cp buffer.

utc

Binary timestamp.

Output

cp

ASCII string that represents the time.

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 .

Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time parameter or invalid results.
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 */ 
Related Functions utc_ascanytime , utc_ascgmtime


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)

Parameters

Input

utc

Relative binary timestamp.

stringlen

Length of the cp buffer.

Output

cp

ASCII string that represents the time.

Description

The ASCII Relative Time routine converts a relative binary timestamp to an ASCII string that represents the time.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time parameter or invalid results.
Example See the sample program for the utc_abstime routine. Related Functions utc_mkascreltime

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)

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.

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.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument or invalid results.
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)); 
Related Functions utc_mkbinreltime


utc_bintime

Converts a binary timestamp to a timespec structure.

Format

#include <utc.h>

int utc_bintime( *timesp, *inaccsp, *tdf, *utc)

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.

Description

The Binary Time routine converts a binary timestamp to a timespec structure. The TDF information contained in the timestamp is returned.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument or invalid results.
Example See the sample program for the utc_anytime routine. Related Functions utc_binreltime , utc_mkbintime

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)

Parameters

Input

utc1

Before binary timestamp or relative binary timestamp.

utc2

After binary timestamp or relative binary timestamp.

Output

result

Spanning timestamp.

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.
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. Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time parameter or invalid parameter order.
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      */ 
Related Functions utc_gettime , utc_pointtime , utc_spantime


utc_cmpintervaltime

Compares two binary timestamps or two relative binary timestamps.

Format

#include <utc.h>

int utc_cmpintervaltime( *relation, *utc1, *utc2)

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:

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. 

Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument.
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. 
 */ 
} 
Related Functions utc_cmpmidtime


Previous Next Contents Index