HP OpenVMS Utility Routines Manual

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;

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:

utc_equalTo
utc_lessThan
utc_greaterThan

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

Returns

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

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

Related Functions utc_cmpintervaltime

utc_gettime

Returns the current system time and inaccuracy as a binary timestamp.

Format

#include <utc.h>
int utc_gettime( *utc)

utc_t *utc;

Parameters

Input

None.

Output

utc
System time as a binary timestamp.

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.

Returns

0	Indicates that the routine executed successfully.
--1	Generic error that indicates the time service cannot be accessed.

Example See the sample program for the utc_binreltime routine.

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;

Parameters

Input

None.

Output

utc
System time as a binary timestamp.

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 .

Returns

0	Indicates that the routine executed successfully.
--1	Generic error that indicates the time service cannot be accessed.

Example See the sample program for the utc_boundtime routine. Related Functions utc_gettime

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;

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.

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.

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_cmpintervaltime routine. Related Functions utc_anytime , utc_gmtzone , utc_localtime , utc_mkgmtime

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;

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.

Description

The Greenwich Mean Time Zone routine gets the time zone label and zero offset from GMT. Outputs are always tdf = 0 and tzname = GMT. This routine exists for symmetry with the Any Zone ( utc_anyzone ) and the Local Zone ( utc_localzone ) routines.

Notes All of the output parameters are optional. No value is returned and no error occurs if the tzname pointer is NULL. Returns

0	Indicates that the routine executed successfully (always returned).

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");

Related Functions utc_anyzone , utc_gmtime , utc_localzone

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;

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.

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.

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_gmtzone routine. Related Functions utc_anytime , utc_gmtime , utc_localzone , utc_mklocaltime

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)

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.

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 .

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_gmtzone routine. Related Functions utc_anyzone , utc_gmtzone , utc_localtime

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 ;

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.

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.

Returns

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

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

Related Functions utc_anytime , utc_anyzone

Contents

Index