You can use the Digital Distributed Time Service (DECdts)
programming routines to obtain timestamps that are based on
Coordinated Universal Time (UTC). You can also use the DECdts
routines to translate among different timestamp formats and
perform calculations on timestamps. Applications can use the
timestamps that DECdts supplies to determine event sequencing,
duration, and scheduling. Applications can call the DECdts
routines from DECdts server or clerk systems.
The Digital Distributed Time Service routines are written in
the C programming language. You should be familiar with the
basic DECdts concepts before you attempt to use the applications
programming interface (API).
The DECdts API routines can perform the following basic
functions:
o Retrieve timestamp information
o Convert between binary timestamps that use different time
structures
o Convert between binary timestamps and ASCII representations
o Convert between UTC time and local time
o Convert the binary time values in the OpenVMS (Smithsonian-
based) format to or from UTC-based binary timestamps (OpenVMS
systems only)
o Manipulate binary timestamps
o Compare two binary time values
o Calculate binary time values
o Obtain time zone information
DECdts can convert between several types of binary time
structures that are based on different calendars and time unit
measurements. DECdts uses UTC-based time structures and can
convert other types of time structures to its own presentation
of UTC-based time.
1 – Time Terminology
Absolute time is a point on a time scale; absolute time
measurements are derived from system clocks or external time-
providers. For DECdts, absolute times reference the UTC standard
and include the inaccuracy and other information. When you
display an absolute time, DECdts converts the time to ASCII text,
as shown in the following display:
1996-11-21-13:30:25.785-04:00I000.082
Relative time is a discrete time interval that is usually added
to or subtracted from an absolute time. A time differential
factor (TDF) associated with an absolute time is one example
of a relative time. Note that a relative time does not use the
calendar date fields, because these fields concern absolute time.
Coordinated Universal Time (UTC) is the international time
standard that DECdts uses. The zero hour of UTC is based on
the zero hour of Greenwich Mean Time (GMT). The documentation
consistently refers to the time zone of the Greenwich Meridian
as GMT. However, this time zone is also sometimes referred to as
UTC.
The time differential factor (TDF) is the difference between UTC
and the time in a particular 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.
The OpenVMS time structure is based on Smithsonian time,
which has a base date of November 17, 1858. The binary OpenVMS
structure is a signed, 64-bit integer that has a positive value
for absolute times. You can use the DECdts API to translate an
OpenVMS structure representing an absolute time to or from the
DECdts UTC-based binary timestamp.
For detailed information about DECdts time representations, refer
to the VSI OpenVMS Utility Routines Manual.
Unless otherwise specified, the default input and output
parameters for the DECDts API routine commands are as follows:
o If utc is not specified as an input parameter, the current
time is used.
o If inacc is not specified as an input parameter, infinity is
used.
o If no output parameter is specified, no result (or an error)
is returned.
2 – utc_abstime
Computes the absolute value of a relative binary timestamp.
Format
#include <utc.h>
int utc_abstime(result, *utc1)
utc_t result;
const utc_t *utc1;
2.1 – Parameters
Input
utc1
Relative binary timestamp.
Output
result
Absolute value of the input relative binary timestamp.
2.2 – Description
The Absolute Time routine computes the absolute value of a
relative binary timestamp. The input timestamp represents a
relative (delta) time.
2.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time parameter or invalid results.
2.4 – Example
The following example scales a relative time, computes its
absolute value, and prints the result.
utc_t relutc, scaledutc;
char timstr[UTC_MAX_STR_LEN];
/*
* Make sure relative timestamp represents a positive interval...
*/
utc_abstime(&relutc, /* Out: Abs-value of rel time */
&relutc); /* In: Relative time to scale */
/*
* Scale it by a factor of 17...
*/
utc_multime(&scaledutc, /* Out: Scaled relative time */
&relutc, /* In: Relative time to scale */
17L); /* In: Scale factor */
utc_ascreltime(timstr, /* Out: ASCII relative time */
UTC_MAX_STR_LEN, /* In: Length of input string */
&scaledutc); /* In: Relative time to */
/* convert */
printf("%s\n",timstr);
/*
* Scale it by a factor of 17.65...
*/
utc_mulftime(&scaledutc, /* Out: Scaled relative time */
&relutc, /* In: Relative time to scale */
17.65); /* In: Scale factor */
utc_ascreltime(timstr, /* Out: ASCII relative time */
UTC_MAX_STR_LEN, /* In: Length of input string */
&scaledutc); /* In: Relative time to */
/* convert */
printf("%s\n",timstr);
3 – utc_addtime
Computes the sum of two binary timestamps; the timestamps can be
two relative times or a relative time and an absolute time.
Format
#include <utc.h>
int utc_addtime(result, *utc1, *utc2)
utc_t result;
const utc_t *utc1;
const utc_t *utc2;
3.1 – Parameters
Input
utc1
Binary timestamp or relative binary timestamp.
utc2
Binary timestamp or relative binary timestamp.
Output
result
Resulting binary timestamp or relative binary timestamp,
depending on the operation performed:
o relative time + relative time = relative time
o absolute time + relative time = absolute time
o relative time + absolute time = absolute time
o absolute time + absolute time is undefined. See NOTES.
3.2 – Description
The Add Time routine adds two binary timestamps, producing a
third binary timestamp whose inaccuracy is the sum of the two
input inaccuracies. One or both of the input timestamps typically
represent a relative (delta) time. The TDF in the first input
timestamp is copied to the output.
3.3 – Notes
Although no error is returned, do not use the combination
absolute time + absolute time.
3.4 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time parameter or invalid results.
3.5 – Example
The following example shows how to compute a timestamp that
represents a time at least 5 seconds in the future.
utc_t now, future, fivesec;
reltimespec_t tfivesec;
timespec_t tzero;
/*
* Construct a timestamp that represents 5 seconds...
*/
tfivesec.tv_sec = 5;
tfivesec.tv_nsec = 0;
tzero.tv_sec = 0;
tzero.tv_nsec = 0;
utc_mkbinreltime(&fivesec, /* Out: 5 secs in binary timestamp */
&tfivesec, /* In: 5 secs in timespec */
&tzero); /* In: 0 secs inaccuracy in timespec */
/*
* Get the maximum possible current time...
* (NULL input parameter is used to specify the current time.)
*/
utc_pointtime((utc_t *)0, /* Out: Earliest possible current time */
(utc_t *)0, /* Out: Midpoint of current time */
&now, /* Out: Latest possible current time */
(utc_t *)0);/* In: Use current time */
/*
* Add 5 seconds to get future timestamp...
*/
utc_addtime(&future, /* Out: Future binary timestamp */
&now, /* In: Latest possible time now */
&fivesec); /* In: 5 secs */
3.6 – Related Functions
utc_subtime
4 – 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;
4.1 – 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.
4.2 – 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.
4.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
4.4 – 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);
4.5 – Related Functions
utc_mkanytime, utc_anyzone, utc_gettime, utc_getusertime, utc_
gmtime, utc_localtime
5 – 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;
5.1 – 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.
5.2 – 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.)
5.3 – Notes
All of the output parameters are optional. No value is returned
and no error occurs if the pointer is null.
5.4 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or an insufficient buffer.
5.5 – Example
See the sample program for the utc_anytime routine.
5.6 – Related Functions
utc_anytime, utc_gmtzone, utc_localzone
6 – 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;
6.1 – Parameters
Input
stringlen
The length of the cp buffer.
utc
Binary timestamp.
Output
cp
ASCII string that represents the time.
6.2 – 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.
6.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time parameter or invalid results.
6.4 – 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 */
6.5 – Related Functions
utc_ascgmtime, utc_asclocaltime
7 – 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;
7.1 – Parameters
Input
stringlen
Length of the cp buffer.
utc
Binary timestamp.
Output
cp
ASCII string that represents the time.
7.2 – Description
The ASCII GMT Time routine converts a binary timestamp to an
ASCII string that expresses a time in GMT.
7.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time parameter or invalid results.
7.4 – 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 */
7.5 – Related Functions
utc_ascanytime, utc_asclocaltime
8 – 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;
8.1 – Parameters
Input
stringlen
Length of the cp buffer.
utc
Binary timestamp.
Output
cp
ASCII string that represents the time.
8.2 – 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.
8.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time parameter or invalid results.
8.4 – 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 */
8.5 – Related Functions
utc_ascanytime, utc_ascgmtime
9 – 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;
9.1 – Parameters
Input
utc
Relative binary timestamp.
stringlen
Length of the cp buffer.
Output
cp
ASCII string that represents the time.
9.2 – Description
The ASCII Relative Time routine converts a relative binary
timestamp to an ASCII string that represents the time.
9.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time parameter or invalid results.
9.4 – Example
See the sample program for the utc_abstime routine.
9.5 – Related Functions
utc_mkascreltime
10 – 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;
10.1 – 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.
10.2 – 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.
10.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
10.4 – 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));
10.5 – Related Functions
utc_mkbinreltime
11 – 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;
11.1 – 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.
11.2 – Description
The Binary Time routine converts a binary timestamp to a timespec
structure. The TDF information contained in the timestamp is
returned.
11.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
11.4 – Example
See the sample program for the utc_anytime routine.
11.5 – Related Functions
utc_binreltime, utc_mkbintime
12 – 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;
12.1 – Parameters
Input
utc1
Before binary timestamp or relative binary timestamp.
utc2
After binary timestamp or relative binary timestamp.
Output
result
Spanning timestamp.
12.2 – 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.
12.3 – 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.
12.4 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time parameter or invalid parameter
order.
12.5 – 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 */
12.6 – Related Functions
utc_gettime, utc_pointtime, utc_spantime
13 – 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;
13.1 – 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:
o utc_equalTo
o utc_lessThan
o utc_greaterThan
o utc_indeterminate
13.2 – 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.
13.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument.
13.4 – 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.
*/
}
13.5 – Related Functions
utc_cmpmidtime
14 – utc_cmpmidtime
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;
14.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
14.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
14.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument.
14.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.
*/
}
14.5 – Related Functions
utc_cmpintervaltime
15 – utc_gettime
Returns the current system time and inaccuracy as a binary
timestamp.
Format
#include <utc.h>
int utc_gettime(*utc)
utc_t *utc;
15.1 – Parameters
Input
None.
Output
utc
System time as a binary timestamp.
15.2 – Description
The Get Time routine returns the current system time and
inaccuracy in a binary timestamp. The routine takes the TDF
from the operating system's kernel; the TDF is specified in a
system-dependent manner.
15.3 – Returns
0 Indicates that the routine executed successfully.
-1 Generic error that indicates the time service cannot be
accessed.
15.4 – Example
See the sample program for the utc_binreltime routine.
16 – utc_getusertime
Returns the time and process-specific TDF, rather than the
system-specific TDF.
Format
#include <utc.h>
int utc_getusertime(*utc)
utc_t *utc;
16.1 – Parameters
Input
None.
Output
utc
System time as a binary timestamp.
16.2 – Description
The Get User Time routine returns the system time and inaccuracy
in a binary timestamp. The routine takes the TDF from the
user's environment, which determines the time zone rule.
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.
16.3 – Returns
0 Indicates that the routine executed successfully.
-1 Generic error that indicates the time service cannot be
accessed.
16.4 – Example
See the sample program for the utc_boundtime routine.
16.5 – Related Functions
utc_gettime
17 – utc_gmtime
Converts a binary timestamp to a tm structure that expresses GMT
or the equivalent UTC.
Format
#include <utc.h>
int utc_gmtime(*timetm, *tns, *inacctm, *ins, *utc)
struct tm *timetm;
long *tns;
struct tm *inacctm;
long *ins;
const utc_t *utc;
17.1 – Parameters
Input
utc
Binary timestamp to be converted to tm structure components.
Output
timetm
Time component of the binary timestamp.
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 zero. 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. If
the inaccuracy is infinite, ins returns a value of -1.
17.2 – Description
The Greenwich Mean Time (GMT) routine converts a binary timestamp
to a tm structure that expresses GMT (or the equivalent UTC).
Additional returns include nanoseconds since time and nanoseconds
of inaccuracy.
17.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
17.4 – Example
See the sample program for the utc_cmpintervaltime routine.
17.5 – Related Functions
utc_anytime, utc_gmtzone, utc_localtime, utc_mkgmtime
18 – utc_gmtzone
Gets the time zone label for GMT.
Format
#include <utc.h>
int utc_gmtzone(*tzname, tzlen, *tdf, *isdst, *utc)
char *tzname;
size_t tzlen;
long *tdf;
int *isdst;
const utc_t *utc;
18.1 – Parameters
Input
tzlen
Length of buffer tzname.
utc
Binary timestamp. This parameter is ignored.
Output
tzname
Character string long enough to hold the time zone label.
tdf
Longword with differential in seconds east or west of GMT. A
value of zero is always returned.
isdst
Integer with a value of zero, indicating that daylight saving
time is not in effect. A value of zero is always returned.
18.2 – Description
The Greenwich Mean Time Zone routine gets the time zone label
and zero offset from GMT. Outputs are always tdf = 0 and tzname
anyzone) and the Local Zone (utc_localzone) routines.
18.3 – Notes
All of the output parameters are optional. No value is returned
and no error occurs if the tzname pointer is NULL.
18.4 – Returns
0 Indicates that the routine executed successfully (always
returned).
18.5 – Example
The following example prints out the current time in both local
time and GMT time.
utc_t now;
struct tm tmlocal, tmgmt;
long tzoffset;
int tzdaylight;
char tzlocal[80], tzgmt[80];
/*
* Get the current time once, so both conversions use the same
* time...
*/
utc_gettime(&now);
/*
* Convert to local time, using the process TZ environment
* variable...
*/
utc_localtime(&tmlocal, /* Out: Local time tm structure */
(long *)0, /* Out: Nanosec of time */
(struct tm *)0, /* Out: Inaccuracy tm structure */
(long *)0, /* Out: Nanosec of inaccuracy */
&now); /* In: Current binary timestamp */
/*
* Get the local time zone name, offset from GMT, and current
* daylight savings flag...
*/
utc_localzone(tzlocal, /* Out: Local time zone name */
80, /* In: Length of loc time zone name */
&tzoffset, /* Out: Loc time zone offset in secs */
&tzdaylight, /* Out: Local time zone daylight flag */
&now); /* In: Current binary timestamp */
/*
* Convert to GMT...
*/
utc_gmtime(&tmgmt, /* Out: GMT tm structure */
(long *)0, /* Out: Nanoseconds of time */
(struct tm *)0, /* Out: Inaccuracy tm structure */
(long *)0, /* Out: Nanoseconds of inaccuracy */
&now); /* In: Current binary timestamp */
/*
* Get the GMT time zone name...
*/
utc_gmtzone(tzgmt, /* Out: GMT time zone name */
80, /* In: Size of GMT time zone name */
(long *)0, /* Out: GMT time zone offset in secs */
(int *)0, /* Out: GMT time zone daylight flag */
&now); /* In: Current binary timestamp */
/*
* Print out times and time zone information in the following
* format:
*
* 12:00:37 (EDT) = 16:00:37 (GMT)
* EDT is -240 minutes ahead of Greenwich Mean Time.
* Daylight savings time is in effect.
*/
printf("%d:%02d:%02d (%s) = %d:%02d:%02d (%s)\n",
tmlocal.tm_hour, tmlocal.tm_min, tmlocal.tm_sec, tzlocal,
tmgmt.tm_hour, tmgmt.tm_min, tmgmt.tm_sec, tzgmt);
printf("%s is %d minutes ahead of Greenwich Mean Time\n",
tzlocal, tzoffset/60);
if (tzdaylight != 0)
printf("Daylight savings time is in effect\n");
18.6 – Related Functions
utc_anyzone, utc_gmtime, utc_localzone
19 – utc_localtime
Converts a binary timestamp to a tm structure that expresses
local time.
Format
#include <utc.h>
int utc_localtime(*timetm, *tns, *inacctm, *ins, *utc)
struct tm *timetm;
long *tns;
struct tm *inacctm;
long *ins;
const utc_t *utc;
19.1 – Parameters
Input
utc
Binary timestamp.
Output
timetm
Time component of the binary timestamp, expressing 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 zero. 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. If
the inaccuracy is infinite, ins returns a value of -1.
19.2 – Description
The Local Time routine converts a binary timestamp to a tm
structure 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.
Additional returns include nanoseconds since time and nanoseconds
of inaccuracy.
19.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
19.4 – Example
See the sample program for the utc_gmtzone routine.
19.5 – Related Functions
utc_anytime, utc_gmtime, utc_localzone, utc_mklocaltime
20 – utc_localzone
Gets the local time zone label and offset from GMT, given utc.
Format
#include <utc.h>
int utc_localzone(*tzname, tzlen, *tdf, *isdst, *utc)
char *tzname;
size_t tzlen;
long *tdf;
int *isdst;
const utc_t *utc;
#include <utc.h>
int utc_localzone(*tzname, tzlen, *tdf, *isdst, *utc)
20.1 – Parameters
Input
tzlen
Length of the tzname buffer.
utc
Binary timestamp.
Output
tzname
Character string 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 zero if standard time is in effect or a
value of 1 if daylight savings time is in effect.
20.2 – Description
The Local Zone routine gets the local time zone label and offset
from GMT, given utc.
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.
20.3 – Notes
All of the output parameters are optional. No value is returned
and no error occurs if the pointer is null.
20.4 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or an insufficient buffer.
20.5 – Example
See the sample program for the utc_gmtzone routine.
20.6 – Related Functions
utc_anyzone, utc_gmtzone, utc_localtime
21 – utc_mkanytime
Converts a tm structure and TDF (expressing the time in an
arbitrary time zone) to a binary timestamp.
Format
#include <utc.h>
int utc_mkanytime(*utc, *timetm, tns, *inacctm, ins, tdf)
utc_t *utc;
const struct tm *timetm;
long tns;
const struct tm *inacctm;
long ins;
long tdf;
21.1 – Parameters
Input
timetm
A tm structure that expresses the local time; tm_wday and tm_yday
are ignored on input.
tns
Nanoseconds since time component.
inacctm
A tm structure that expresses days, hours, minutes, and seconds
of inaccuracy. If tm_yday is negative, the inaccuracy is
considered to be infinite; tm_mday, tm_mon, tm_wday, tm_isdst,
tm_gmtoff, and tm_zone are ignored on input.
ins
Nanoseconds of inaccuracy component.
tdf
Time differential factor to use in conversion.
Output
utc
Resulting binary timestamp.
21.2 – Description
The Make Any Time routine converts a tm structure and TDF
(expressing the time in an arbitrary time zone) to a binary
timestamp. Required inputs include nanoseconds since time and
nanoseconds of inaccuracy.
21.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
21.4 – Example
The following example converts a string ISO format time in an
arbitrary time zone to a binary timestamp. This may be part of
an input timestamp routine, although a real implementation will
include range checking.
utc_t utc;
struct tm tmtime, tminacc;
float tsec, isec;
double tmp;
long tnsec, insec;
int i, offset, tzhour, tzmin, year, mon;
char *string;
/* Try to convert the string... */
if(sscanf(string, "%d-%d-%d-%d:%d:%e+%d:%dI%e",
&year, &mon, &tmtime.tm_mday, &tmtime.tm_hour,
&tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) {
/* Try again with a negative TDF... */
if (sscanf(string, "%d-%d-%d-%d:%d:%e-%d:%dI%e",
&year, &mon, &tmtime.tm_mday, &tmtime.tm_hour,
&tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) {
/* ERROR */
exit(1);
}
/* TDF is negative */
tzhour = -tzhour;
tzmin = -tzmin;
}
/* Fill in the fields... */
tmtime.tm_year = year - 1900;
tmtime.tm_mon = --mon;
tmtime.tm_sec = tsec;
tnsec = (modf(tsec, &tmp)*1.0E9);
offset = tzhour*3600 + tzmin*60;
tminacc.tm_sec = isec;
insec = (modf(isec, &tmp)*1.0E9);
/* Convert to a binary timestamp... */
utc_mkanytime(&utc, /* Out: Resultant binary timestamp */
&tmtime, /* In: tm struct that represents input */
tnsec, /* In: Nanoseconds from input */
&tminacc, /* In: tm struct that represents inacc */
insec, /* In: Nanoseconds from input */
offset); /* In: TDF from input */
21.5 – Related Functions
utc_anytime, utc_anyzone
22 – utc_mkascreltime
Converts a null-terminated character string that represents a
relative timestamp to a binary timestamp.
Format
#include <utc.h>
int utc_mkascreltime(*utc, *string)
utc_t *utc;
char *string;
22.1 – Parameters
Input
string
A null-terminated string that expresses a relative timestamp in
its ISO format.
Output
utc
Resulting binary timestamp.
22.2 – Description
The Make ASCII Relative Time routine converts a null-terminated
string, which represents a relative timestamp, to a binary
timestamp.
22.3 – Notes
The ASCII string must be null-terminated.
22.4 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time parameter or invalid results.
22.5 – Example
The following example converts an ASCII relative time string to
its binary equivalent.
utc_t utc;
char str[UTC_MAX_STR_LEN];
/*
* Relative time of 333 days, 12 hours, 1 minute, 37.223 seconds
* Inaccuracy of 50.22 sec. in the format: -333-12:01:37.223I50.22
*/
(void)strcpy((void *)str,
"-333-12:01:37.223I50.22");
utc_mkascreltime(&utc, /* Out: Binary utc */
str); /* In: String */
22.6 – Related Functions
utc_ascreltime
23 – utc_mkasctime
Converts a null-terminated character string that represents an
absolute time to a binary timestamp.
Format
#include <utc.h>
int utc_mkasctime(*utc, *string)
utc_t *utc;
char *string;
23.1 – Parameters
Input
string
A null-terminated string that expresses an absolute time.
Output
utc
Resulting binary timestamp.
23.2 – Description
The Make ASCII Time routine converts a null-terminated string
that represents an absolute time to a binary timestamp.
23.3 – Notes
The ASCII string must be null-terminated.
23.4 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time parameter or invalid results.
23.5 – Example
The following example converts an ASCII time string to its binary
equivalent.
utc_t utc;
char str[UTC_MAX_STR_LEN];
/*
* July 4, 1776, 12:01:37.223 local time
* TDF of -5:00 hours
* Inaccuracy of 3600.32 seconds
*/
(void)strcpy((void *)str,
"1776-07-04-12:01:37.223-5:00 I 3600.32");
utc_mkasctime(&utc, /* Out: Binary utc */
str); /* In: String */
23.6 – Related Functions
utc_ascanytime, utc_ascgmtime, utc_asclocaltime
24 – utc_mkbinreltime
Converts a timespec structure expressing a relative time to a
binary timestamp.
Format
#include <utc.h>
int utc_mkbinreltime(*utc, *timesp, *inaccsp)
utc_t *utc;
const reltimespec_t *timesp;
const timespec_t *inaccsp;
24.1 – Parameters
Input
timesp
A reltimespec structure that expresses a relative time.
inaccsp
A timespec structure that expresses inaccuracy. If tv_sec is set
to a value of -1, the inaccuracy is considered to be infinite.
Output
utc
Resulting relative binary timestamp.
24.2 – Description
The Make Binary Relative Time routine converts a timespec
structure that expresses relative time to a binary timestamp.
24.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
24.4 – Example
See the sample program for the utc_addtime routine.
24.5 – Related Functions
utc_binreltime, utc_mkbintime
25 – utc_mkbintime
Converts a timespec structure to a binary timestamp.
Format
#include <utc.h>
int utc_mkbintime(*utc, *timesp, *inaccsp)
utc_t *utc;
const timespec_t *timesp;
const timespec_t *inaccsp;
long tdf;
25.1 – Parameters
Input
timesp
A timespec structure that expresses time since 1970-01-
01:00:00:00.0+0:00I0.
inaccsp
A timespec structure that expresses inaccuracy. If tv_sec is set
to a value of -1, the inaccuracy is considered to be infinite.
tdf
TDF component of the binary timestamp.
Output
utc
Resulting binary timestamp.
25.2 – Description
The Make Binary Time routine converts a timespec structure time
to a binary timestamp. The TDF input is used as the TDF of the
binary timestamp.
25.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
25.4 – Example
The following example obtains the current time from time(),
converts it to a binary timestamp with an inaccuracy of 5.2
seconds, and specifies GMT.
timespec_t ttime, tinacc;
utc_t utc;
/*
* Obtain the current time (without the inaccuracy)...
*/
ttime.tv_sec = time((time_t *)0);
ttime.tv_nsec = 0;
/*
* Specify the inaccuracy...
*/
tinacc.tv_sec = 5;
tinacc.tv_nsec = 200000000;
/*
* Convert to a binary timestamp...
*/
utc_mkbintime(&utc, /* Out: Binary timestamp */
&ttime, /* In: Current time in timespec */
&tinacc, /* In: 5.2 seconds in timespec */
0); /* In: TDF of GMT */
25.5 – Related Functions
utc_bintime, utc_mkbinreltime
26 – utc_mkgmtime
Converts a tm structure that expresses GMT or UTC to a binary
timestamp.
Format
#include <utc.h>
int utc_mkgmtime(*utc, *timetm, tns, *inacctm, ins)
utc_t *utc;
const struct tm *timetm;
long tns;
const struct tm *inacctm;
long ins;
26.1 – Parameters
Input
timetm
A tm structure that expresses GMT. On input, tm_wday and tm_yday
are ignored.
tns
Nanoseconds since time component.
inacctm
A tm structure that expresses days, hours, minutes, and seconds
of inaccuracy. If tm_yday is negative, the inaccuracy is
considered to be infinite. On input, tm_mday, tm_mon, tm_wday,
tm_isdst, tm_gmtoff, and tm_zone are ignored.
ins
Nanoseconds of inaccuracy component.
Output
utc
Resulting binary timestamp.
26.2 – Description
The Make Greenwich Mean Time routine converts a tm structure that
expresses GMT or UTC to a binary timestamp. Additional inputs
include nanoseconds since the last second of time and nanoseconds
of inaccuracy.
26.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
26.4 – Example
See the sample program for the utc_cmpintervaltime routine.
26.5 – Related Functions
utc_gmtime
27 – utc_mklocaltime
Converts a tm structure that expresses local time to a binary
timestamp.
Format
#include <utc.h>
int utc_mklocaltime(*utc, *timetm, tns, *inacctm, ins)
utc_t *utc;
const struct tm *timetm;
long tns;
const struct tm *inacctm;
long ins;
27.1 – Parameters
Input
timetm
A tm structure that expresses the local time. On input, tm_wday
and tm_yday are ignored.
tns
Nanoseconds since time component.
inacctm
A tm structure that expresses days, hours, minutes, and seconds
of inaccuracy. If tm_yday is negative, the inaccuracy is
considered to be infinite. On input, tm_mday, tm_mon, tm_wday,
tm_isdst, tm_gmtoff, and tm_zone are ignored.
ins
Nanoseconds of inaccuracy component.
Output
utc
Resulting binary timestamp.
27.2 – Description
The Make Local Time routine converts a tm structure that
expresses local time to a binary timestamp.
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.
Additional inputs include nanoseconds since the last second of
time and nanoseconds of inaccuracy.
27.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
27.4 – Example
See the sample program for the utc_cmpmidtime routine.
27.5 – Related Functions
utc_localtime
28 – utc_mkreltime
Converts a tm structure that expresses relative time to a
relative binary timestamp.
Format
#include <utc.h>
int utc_mkreltime(*utc, *timetm, tns, *inacctm, ins)
utc_t *utc;
const struct tm *timetm;
long tns;
const struct tm *inacctm;
long ins;
28.1 – Parameters
Input
timetm
A tm structure that expresses a relative time. On input, tm_wday
and tm_yday are ignored.
tns
Nanoseconds since time component.
inacctm
A tm structure that expresses seconds of inaccuracy. If tm_yday
is negative, the inaccuracy is considered to be infinite. On
input, tm_mday, tm_mon, tm_year, tm_wday, tm_isdst, and tm_zone
are ignored.
ins
Nanoseconds of inaccuracy component.
Output
utc
Resulting relative binary timestamp.
28.2 – Description
The Make Relative Time routine converts a tm structure that
expresses relative time to a relative binary timestamp.
Additional inputs include nanoseconds since the last second of
time and nanoseconds of inaccuracy.
28.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
28.4 – Example
The following example converts a string relative time in the
format (1991-04-01-12:12:12.12I12.12) to a binary timestamp. This
may be part of an input relative timestamp routine, though a real
implementation will include range checking.
utc_t utc;
struct tm tmtime, tminacc;
float tsec, isec;
double tmp;
long tnsec, insec;
int i, tzhour, tzmin, year, mon;
char *string;
/*
* Try to convert the string...
*/
if(sscanf(string, "%d-%d-%d-%d:%d:%eI%e",
&year, &mon, &tmtime.tm_mday, &tmtime.tm_hour,
&tmtime.tm_min, &tsec, &isec) != 7) {
/*
* ERROR...
*/
exit(1);
}
/*
* Fill in the fields...
*/
tmtime.tm_year = year - 1900;
tmtime.tm_mon = --mon;
tmtime.tm_sec = tsec;
tnsec = (modf(tsec, &tmp)*1.0E9);
tminacc.tm_sec = isec;
insec = (modf(isec, &tmp)*1.0E9);
/*
* Convert to a binary timestamp...
*/
utc_mkreltime(&utc, /* Out: Resultant binary timestamp */
&tmtime, /* In: tm struct that represents input */
tnsec, /* In: Nanoseconds from input */
&tminacc, /* In: tm struct that represents inacc */
insec); /* In: Nanoseconds from input */
28.5 – Related Functions
utc_reltime
29 – utc_mkvmsanytime
Converts a binary OpenVMS format time and TDF (expressing the
time in an arbitrary time zone) to a binary timestamp.
Format
#include <utc.h>
int utc_mkvmsanytime(*utc, *timadr, tdf)
utc_t *utc;
const long *timadr;
const long tdf;
29.1 – Parameters
Input
*timadr
Binary OpenVMS format time.
tdf
Time differential factor to use in conversion.
Output
*utc
Binary timestamp.
29.2 – Description
The Make VMS Any Time routine converts a binary time in the
OpenVMS (Smithsonian) format and an arbitrary TDF to a UTC-based
binary timestamp. Because the input and output values are based
on different time standards, any input representing a value after
A.D. 30,000 returns an error.
29.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
29.4 – Example
The following example shows how to convert between OpenVMS format
binary timestamps and UTC binary timestamps, while specifying the
TDF for each. The TDF value determines the offset from GMT and
the local time.
/*****
start example mkvmsanytime,vmsanytime
*****/
#include <utc.h>
main()
{
struct utc utcTime;
int vmsTime[2];
SYS$GETTIM(vmsTime); /* read the current time */
/*
* convert the VMS local time to a UTC, applying a TDF of
* -300 minutes (the timezone is -5 hours from GMT)
*/
if (utc_mkvmsanytime(&utcTime,vmsTime,-300))
exit(1);
/*
* convert UTC back to VMS local time. A TDF of -300 is applied
* to the UTC, since utcTime was constructed with that same value.
* This effectively gives us the same VMS time value we started
* with.
*/
if (utc_vmsanytime(vmsTime,&utcTime))
exit(2);
}
/****
end example
****/
29.5 – Related Functions
Function: utc_vmsanytime
30 – utc_mkvmsgmtime
Converts a binary OpenVMS format time expressing GMT (or the
equivalent UTC) into a binary timestamp.
Format
#include <utc.h>
int utc_mkvmsgmtime(*utc, *timadr)
utc_t *utc;
const long *timadr;
30.1 – Parameters
Input
*timadr
Binary OpenVMS format time representing GMT or the UTC
equivalent.
Output
*utc
Binary timestamp.
30.2 – Description
The Make VMS Greenwich Mean Time routine converts an OpenVMS
format binary time representing GMT to a binary timestamp with
the equivalent UTC value. Since the input and output values are
based on different time standards, any input representing a value
after A.D. 30,000 returns an error.
30.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
30.4 – Example
See the sample program for the vmsgmtime routine.
30.5 – Related Functions
Function: utc_vmsgmtime
31 – utc_mkvmslocaltime
Converts a local binary OpenVMS format time to a binary
timestamp, using the host system's time differential factor.
Format
#include <utc.h>
int utc_mkvmslocaltime(*utc, *timadr)
const long *timadr;
utc_t *utc;
31.1 – Parameters
Input
*timadr
Binary OpenVMS format time expressing local time.
Output
*utc
Binary timestamp expressing the system's local time.
31.2 – Description
The Make VMS Local Time routine converts a binary OpenVMS format
time, representing the local time of the host system, to a binary
timestamp. The system's local time value is defined by the time
zone rule in sys$timezone_rule, which is created by the system
configuration process sys$manager:net$configure.com.
31.3 – Notes
If the routine call is made during a seasonal time zone change
when the local time is indeterminate, an error is returned. For
example, if the time zone change occurs at the current local time
of 2:00 A.M. to a new local time of 1:00 A.M., and the routine is
called between 1:00 A.M. and 2:00 A.M., it cannot be determined
which TDF applies.
31.4 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument, invalid results, or
invalid routine call during a time zone change.
31.5 – Example
The following example shows how to retrieve the current local
time of the system in the binary OpenVMS format, convert the
OpenVMS format time to a UTC-based binary timestamp (using the
system's TDF), and print an ASCII representation of the binary
timestamp.
31.5.1 /*********
start example mkvmslocaltime
*********/
#include <utc.h>
main()
{
char outstring[UTC_MAX_STR_LEN];
struct utc utcTime;
int vmsTime[2];
SYS$GETTIM(vmsTime); /* read current time */
if (utc_mkvmslocaltime(&utcTime,vmsTime)) /* convert the local time */
exit(1); /* vmsTime to UTC using */
/* the system tdf. */
31.5.2 /* convert to ISO ascii*/
utc_asclocaltime(outstring,UTC_MAX_STR_LEN,&utcTime);
31.5.3 /* format and print */
printf("Current time=> %s\n",outstring);
}
31.5.4 /*****
end example *****/
31.6 – Related Functions
Function: utc_vmslocaltime
32 – utc_mulftime
Multiplies a relative binary timestamp by a floating-point value.
Format
#include <utc.h>
int utc_mulftime(*result, *utc1, factor)
utc_t *result;
const utc_t *utc1;
const double factor;
32.1 – Parameters
Input
utc1
Relative binary timestamp.
factor
Real scale factor (double-precision floating-point)
Output
result
Resulting relative binary timestamp.
32.2 – Description
The Multiply a Relative Time by a Real Factor routine multiplies
a relative binary timestamp by a floating-point value. Either
or both may be negative; the resulting relative binary timestamp
has the appropriate sign. The unsigned inaccuracy in the relative
binary timestamp is also multiplied by the absolute value of the
floating-point value.
32.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
32.4 – Example
The following example scales and prints a relative time.
utc_t relutc, scaledutc;
struct tm sacledreltm;
char timstr[UTC_MAX_STR_LEN];
/*
* Assume relutc contains the time to scale.
* Scale it by a factor of 17...
*/
utc_multime(&scaledutc, /* Out: Scaled rel time */
&relutc, /* In: Rel time to scale */
17L); /* In: Scale factor */
utc_ascreltime(timstr, /* Out: ASCII rel time */
UTC_MAX_STR_LEN, /* In: Length of input str */
&scaledutc); /* In: Rel time to convert */
printf("%s\n",timstr);
/*
* Scale it by a factor of 17.65...
*/
utc_mulftime(&scaledutc, /* Out: Scaled rel time */
&relutc, /* In: Rel time to scale */
17.65); /* In: Scale factor */
utc_ascreltime(timstr, /* Out: ASCII rel time */
UTC_MAX_STR_LEN, /* In: Input str length */
&scaledutc); /* In: Rel time to convert */
printf("%s\n",timstr);
/*
* Convert it to a tm structure and print it.
*/
utc_reltime(&scaledreltm, /* Out: Scaled rel tm */
(long *)0, /* Out: Scaled rel nano-sec */
(struct tm *)0, /* Out: Scaled rel inacc tm */
(long *)0, /* Out: Scd rel inacc nanos */
&scaledutc); /* In: Rel time to convert */
printf("Approximately %d days, %d hours and %d minutes\n",
scaledreltm.tm_yday, scaledreltm.tm_hour, scaledreltm.tm_min);
32.5 – Related Functions
utc_multime
33 – utc_multime
Multiplies a relative binary timestamp by an integer factor.
Format
#include <utc.h>
int utc_multime(*result, *utc1, factor)
utc_t *result;
const utc_t *utc1;
long factor;
33.1 – Parameters
Input
utc1
Relative binary timestamp.
factor
Integer scale factor.
Output
result
Resulting relative binary timestamp.
33.2 – Description
The Multiply Relative Time by an Integer Factor routine
multiplies a relative binary timestamp by an integer. Either
or both may be negative; the resulting binary timestamp has the
appropriate sign. The unsigned inaccuracy in the binary timestamp
is also multiplied by the absolute value of the integer.
33.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
33.4 – Example
See the sample program for the utc_mulftime routine.
33.5 – Related Functions
utc_mulftime
34 – utc_pointtime
Converts a binary timestamp to three binary timestamps that
represent the earliest, most likely, and latest time.
Format
#include <utc.h>
int utc_pointtime(*utclp, *utcmp, *utchp, *utc)
utc_t *utclp;
utc_t *utcmp;
utc_t *utchp;
const utc_t *utc;
34.1 – Parameters
Input
utc
Binary timestamp or relative binary timestamp.
Output
utclp
Lowest (earliest) possible time that the input binary timestamp
or shortest possible relative time that the relative binary
timestamp can represent.
utcmp
Midpoint of the input binary timestamp or the midpoint of the
input relative binary timestamp.
utchp
Highest (latest) possible time that the input binary timestamp
or the longest possible relative time that the relative binary
timestamp can represent.
34.2 – Description
The Point Time routine converts a binary timestamp to three
binary timestamps that represent the earliest, latest, and most
likely (midpoint) times. If the input is a relative binary time,
the outputs represent relative binary times.
34.3 – Notes
All outputs have zero inaccuracy. An error is returned if the
input binary timestamp has an infinite inaccuracy.
34.4 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument.
34.5 – Example
See the sample program for the utc_addtime routine.
34.6 – Related Functions
utc_boundtime, utc_spantime
35 – utc_reltime
Converts a relative binary timestamp to a tm structure.
Format
#include <utc.h>
int utc_reltime(*timetm, *tns, *inacctm, *ins, *utc)
struct tm *timetm;
long *tns;
struct tm *inacctm;
long *ins;
const utc_t *utc;
35.1 – Parameters
Input
utc
Relative binary timestamp.
Output
timetm
Relative time component of the relative binary timestamp. The
field tm_mday returns a value of -1 and the fields tm_year and
tm_mon return values of zero. The field tm_yday contains the
number of days of relative time.
tns
Nanoseconds since time component of the relative binary
timestamp.
inacctm
Seconds of inaccuracy component of the relative binary timestamp.
If the inaccuracy is finite, then tm_mday returns a value of -1
and tm_mon and tm_year return values of zero. 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 relative binary
timestamp.
35.2 – Description
The Relative Time routine converts a relative binary timestamp to
a tm structure. Additional returns include nanoseconds since time
and nanoseconds of inaccuracy.
35.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
35.4 – Example
See the sample program for the utc_mulftime routine.
35.5 – Related Functions
utc_mkreltime
36 – utc_spantime
Given two (possibly unordered) binary timestamps, returns a
single UTC time interval whose inaccuracy spans the two input
binary timestamps.
Format
#include <utc.h>
int utc_spantime(*result, *utc1, *utc2)
utc_t *result;
const utc_t *utc1;
const utc_t *utc2;
36.1 – Parameters
Input
utc1
Binary timestamp.
utc2
Binary timestamp.
Output
result
Spanning timestamp.
36.2 – Description
Given two binary timestamps, the Span Time routine returns a
single UTC time interval whose inaccuracy spans the two input
timestamps (that is, the interval resulting from the earliest
possible time of either timestamp to the latest possible time of
either timestamp).
36.3 – Notes
The tdf in the output UTC value is copied from the utc2 input.
If either input binary timestamp has an infinite inaccuracy, an
error is returned.
36.4 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument.
36.5 – Example
The following example computes the earliest and latest times for
an array of 10 timestamps.
utc_t time_array[10], testtime, earliest, latest;
int i;
/*
* Set the running timestamp to the first entry...
*/
testtime = time_array[0];
for (i=1; i<10; i++) {
/*
* Compute the minimum and the maximum against the next
* element...
*/
utc_spantime(&testtime, /* Out: Resultant interval */
&testtime, /* In: Largest previous interval */
&time_array[i]); /* In: Element under test */
}
/*
* Compute the earliest possible time...
*/
utc_pointtime(&earliest, /* Out: Earliest poss time in array */
(utc_t *)0, /* Out: Midpoint */
&latest, /* Out: Latest poss time in array */
&testtime); /* In: Spanning interval */
36.6 – Related Functions
utc_boundtime, utc_gettime, utc_pointtime
37 – utc_subtime
Computes the difference between two binary timestamps that
express either an absolute time and a relative time, two relative
times, or two absolute times.
Format
#include <utc.h>
int utc_subtime(*result, *utc1, *utc2)
utc_t *result;
const utc_t *utc1;
const utc_t *utc2;
37.1 – Parameters
Input
utc1
Binary timestamp or relative binary timestamp.
utc2
Binary timestamp or relative binary timestamp.
Output
result
Resulting binary timestamp or relative binary timestamp,
depending on the operation performed:
o absolute time - absolute time = relative time
o relative time - relative time = relative time
o absolute time - relative time = absolute time
o relative time - absolute time is undefined. See NOTES.
37.2 – Description
The Subtract Time routine subtracts one binary timestamp
from another. The resulting timestamp is utc1 minus utc2.
The inaccuracies of the two input timestamps are combined and
included in the output timestamp. The TDF in the first timestamp
is copied to the output.
37.3 – Notes
Although no error is returned, do not use the combination
relative time - absolute time.
37.4 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
37.5 – Example
See the sample program for the utc_binreltime routine.
37.6 – Related Functions
utc_addtime
38 – utc_vmsanytime
Converts a binary timestamp to a binary OpenVMS format time.
The TDF encoded in the input timestamp determines the TDF of the
output.
Format
#include <utc.h>
int utc_vmsanytime(*timadr, *utc)
const utc_t *utc;
long *timadr;
38.1 – Parameters
Input
*utc
Binary timestamp.
Output
*timadr
Binary OpenVMS format time.
38.2 – Description
The VMS Any Time routine converts a UTC-based binary timestamp
to a 64-bit binary time in the OpenVMS (Smithsonian) format.
Because the input and output values are based on different time
standards, any input representing a value before the Smithsonian
base time of November 17, 1858 returns an error.
38.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
38.4 – Example
See the sample program for the mkvmsanytime routine.
38.5 – Related Functions
Function: utc_mkvmsanytime
39 – utc_vmsgmtime
Converts a binary timestamp to a binary OpenVMS format time
expressing GMT or the equivalent UTC.
Format
#include <utc.h>
int utc_vmsgmtime(*timadr, *utc)
const utc_t *utc;
long *timadr;
39.1 – Parameters
Input
*utc
Binary timestamp to be converted.
Output
*timadr
Binary OpenVMS format time representing GMT or the UTC
equivalent.
39.2 – Description
The OpenVMS Greenwich Mean Time routine converts a UTC-based
binary timestamp to a 64-bit binary time in the OpenVMS
(Smithsonian) format. The OpenVMS format time represents
Greenwich Mean Time or the equivalent UTC. Because the input and
output values are based on different time standards, any input
representing a value before the Smithsonian base time of November
17, 1858 returns an error.
39.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
39.4 – Example
The following example shows the following time zone and time
format conversions:
1. Retrieve a binary timestamp representing UTC with the
sys$getutc system service.
2. Convert the binary timestamp to a OpenVMS format binary time
representing GMT
3. Convert the OpenVMS format binary time representing GMT back
to a UTC-based binary timestamp with a TDF of 0 (zero)
4. Convert the UTC-based binary time to a binary OpenVMS format
time representing the local time; use the TDF from the system
/*****
start example vmsgmtime, mkvmsgmtime, vmslocaltime
*****/
#include <utc.h>
main()
{
int status;
struct utc utcTime;
int vmsTime[2];
if (!((status=SYS$GETUTC(&utcTime))&1))
exit(status); /* read curr time as a utc */
/*
* convert the utcvalue into a vms time, with a timezone of 0
* (GMT). Printing the resultant vmstime yields the time at
* the prime meridian in Greenwich, not (necessarily) the
* local time.
*/
if (utc_vmsgmtime(vmsTime,&utcTime))
exit(1);
/*
* Convert the vmstime (which is in GMT) to a utc
*/
if (utc_mkvmsgmtime(&utcTime, vmsTime))
exit(2);
/*
* convert the UTC to local 64-bit time. Note that this is the
* value we would have read if we had issued a 'SYS$GETTIM' in
* the initial statement.
*/
if (utc_vmslocaltime(vmsTime, &utcTime))
exit(3);
}
/*****
end example
*****/
39.5 – Related Functions
Function: utc_mkvmsgmtime
40 – utc_vmslocaltime
Converts a binary timestamp to a local binary OpenVMS format
time, using the host system's time differential factor.
Format
#include <utc.h>
int utc_vmslocaltime(*timadr, *utc)
const utc_t *utc;
long *timadr;
40.1 – Parameters
Input
*utc
Binary timestamp.
Output
*timadr
Binary OpenVMS format time expressing local time.
40.2 – Description
The VMS Local Time routine converts a binary timestamp to a
binary OpenVMS format time; the output value represents the
local time of the host system. The system's offset from UTC
and the local time value are defined by the time zone rule in
sys$timezone_rule, which is created by the system configuration
process sys$manager:net$configure.com.
40.3 – Returns
0 Indicates that the routine executed successfully.
-1 Indicates an invalid time argument or invalid results.
40.4 – Example
See the sample program for the vmsgmtime routine.
40.5 – Related Functions
Function: utc_vmsmklocaltime
41 – Example
The following C programming example shows a practical application
of the DECdts API programming routines. The program performs the
following actions:
o Prompts the user to enter time coordinates.
o Stores those coordinates in a tm structure.
o Converts the tm structure to a utc structure.
o Determines which event occurred first.
o Determines if Event 1 may have caused Event 2 by comparing the
intervals.
o Prints out the utc structure in ISO text format.
#include <time.h> /* time data structures */
#include <utc.h> /* utc structure definitions */
void ReadTime();
void PrintTime();
/*
* This program requests user input about events, then prints out
* information about those events.
*/
main()
{
struct utc event1,event2;
enum utc_cmptype relation;
/*
* Read in the two events.
*/
ReadTime(&event1);
ReadTime(&event2);
/*
* Print out the two events.
*/
printf("The first event is : ");
PrintTime(&event1);
printf("\nThe second event is : ");
PrintTime(&event2);
printf("\n");
/*
* Determine which event occurred first.
*/
if (utc_cmpmidtime(&relation,&event1,&event2))
exit(1);
switch( relation )
{
case utc_lessThan:
printf("comparing midpoints: Event1 < Event2\n");
break;
case utc_greaterThan:
printf("comparing midpoints: Event1 > Event2\n");
break;
case utc_equalTo:
printf("comparing midpoints: Event1 == Event2\n");
break;
default:
exit(1);
break;
}
/*
* Could Event 1 have caused Event 2? Compare the intervals.
*/
if (utc_cmpintervaltime(&relation,&event1,&event2))
exit(1);
switch( relation )
{
case utc_lessThan:
printf("comparing intervals: Event1 < Event2\n");
break;
case utc_greaterThan:
printf("comparing intervals: Event1 > Event2\n");
break;
case utc_equalTo:
printf("comparing intervals: Event1 == Event2\n");
break;
case utc_indeterminate:
printf("comparing intervals: Event1 ? Event2\n");
default:
exit(1);
break;
}
}
/*
* Print out a utc structure in ISO text format.
*/
void PrintTime(utcTime)
struct utc *utcTime;
{
char string[50];
/*
* Break up the time string.
*/
if (utc_ascgmtime(string, /* Out: Converted time */
50, /* In: String length */
utcTime)) /* In: Time to convert */
exit(1);
printf("%s\n",string);
}
/*
* Prompt the user to enter time coordinates. Store the
* coordinates in a tm structure and then convert the
* tm structure to a utc structure.
*/
void ReadTime(utcTime)
struct utc *utcTime;
{
struct tm tmTime,tmInacc;
(void)memset((void *)&tmTime, 0,sizeof(tmTime));
(void)memset((void *)&tmInacc, 0,sizeof(tmInacc));
(void)printf("Year? ");
(void)scanf("%d",&tmTime.tm_year);
tmTime.tm_year -= 1900;
(void)printf("Month? ");
(void)scanf("%d",&tmTime.tm_mon);
tmTime.tm_mon -= 1;
(void)printf("Day? ");
(void)scanf("%d",&tmTime.tm_mday);
(void)printf("Hour? ");
(void)scanf("%d",&tmTime.tm_hour);
(void)printf("Minute? ");
(void)scanf("%d",&tmTime.tm_min);
(void)printf("Inacc Secs? ");
(void)scanf("%d",&tmInacc.tm_sec);
if (utc_mkanytime(utcTime,
&tmTime,
(long)0,
&tmInacc,
(long)0,
(long)0))
exit(1);
}
Assume the preceding program is named compare_events.c. To
compile and link the program on a DECnet-Plus for OpenVMS system,
enter the following command:
$ cc compare_events.c/output=compare_events.obj
$ link compare_events.obj, sys$input:/options<Return>
sys$library:dtss$shr.exe/share<Ctrl-z>
$