HP OpenVMS Utility Routines Manual

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)

struct tm timetm ;
long *tns;
struct tm *inacctm;
long *ins;
long *tdf;
const utc_t *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)

char tzname ;
size_t tzlen ;
long *tdf;
int *isdst;
const utc_t *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)

char *cp;
size_t stringlen ;
const utc_t *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)

char *cp;
size_t stringlen ;
const utc_t *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)

char *cp;
size_t stringlen ;
const utc_t *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)

char *cp;
const size_t stringlen ;
const utc_t *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)

reltimespec_t *timesp;
timespec_t *inaccsp;
const utc_t *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)

timespec_t *timesp;
timespec_t *inaccsp;
long *tdf;
const utc_t *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)

utc_t *result;
const utc_t *utc1;
const utc_t *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)

enum utc_cmptype *relation;
const utc_t *utc1;
const utc_t *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:

utc_equalTo
utc_lessThan
utc_greaterThan
utc_indeterminate

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

Contents

Index