|
OpenVMS Utility Routines Manual
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)
Parameters
Input
string
A null-terminated string that expresses a relative timestamp in its ISO
format.
Output
utc
Resulting binary timestamp.
Description
The Make ASCII Relative Time routine converts a
null-terminated string, which represents a relative timestamp, to a
binary timestamp.
Notes The ASCII string must be null-terminated. Returns
0
|
Indicates that the routine executed successfully.
|
--1
|
Indicates an invalid time parameter or invalid results.
|
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 */
|
Related Functions
utc_ascreltime
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)
Parameters
Input
string
A null-terminated string that expresses an absolute time.
Output
utc
Resulting binary timestamp.
Description
The Make ASCII Time routine converts a null-terminated
string that represents an absolute time to a binary timestamp.
Notes The ASCII string must be null-terminated. Returns
0
|
Indicates that the routine executed successfully.
|
--1
|
Indicates an invalid time parameter or invalid results.
|
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 */
|
Related Functions
utc_ascanytime
,
utc_ascgmtime
,
utc_asclocaltime
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;
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.
Description
The Make Binary Relative Time routine converts a
timespec
structure that expresses relative time to a binary timestamp.
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_addtime
routine. Related Functions
utc_binreltime
,
utc_mkbintime
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 ;
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.
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.
Returns
0
|
Indicates that the routine executed successfully.
|
--1
|
Indicates an invalid time argument or invalid results.
|
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 */
|
Related Functions
utc_bintime
,
utc_mkbinreltime
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 ;
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.
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.
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_gmtime
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 ;
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.
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.
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_cmpmidtime
routine. Related Functions
utc_localtime
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 ;
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.
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.
Returns
0
|
Indicates that the routine executed successfully.
|
--1
|
Indicates an invalid time argument or invalid results.
|
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 */
|
Related Functions
utc_reltime
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 ;
Parameters
Input
*timadr
Binary OpenVMS format time.
tdf
Time differential factor to use in conversion.
Output
*utc
Binary timestamp.
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.
Returns
0
|
Indicates that the routine executed successfully.
|
--1
|
Indicates an invalid time argument or invalid results.
|
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
****/
|
Related Functions Function: utc_vmsanytime
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;
Parameters
Input
*timadr
Binary OpenVMS format time representing GMT or the UTC equivalent.
Output
*utc
Binary timestamp.
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.
Returns
0
|
Indicates that the routine executed successfully.
|
--1
|
Indicates an invalid time argument or invalid results.
|
Example See the sample program for the vmsgmtime
routine. Related Functions Function: utc_vmsgmtime
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;
Parameters
Input
*timadr
Binary OpenVMS format time expressing local time.
Output
*utc
Binary timestamp expressing the system's local time.
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
.
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. 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.
|
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.
/*********
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. */
/* convert to ISO ascii*/
utc_asclocaltime(outstring,UTC_MAX_STR_LEN,&utcTime);
/* format and print */
printf("Current time=> %s\n",outstring);
}
/*****
end example
*****/
|
Related Functions Function: utc_vmslocaltime
|