CAL_$INTRO Domain/OS CAL_$INTRO
NAME
intro - the Domain/OS calendar service
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/cal.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/cal.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/cal.ins.ftn'
DESCRIPTION
Domain/OS represents time as the number of 4-microsecond intervals that
have elapsed since midnight (00:00) on 1 January 1980 (UTC). ("UTC" is
an abbreviation for "Coordinated Universal Time," which is just another,
less parochial, term for Greenwich Mean Time or "GMT.") Each 4-
microsecond interval is called a "clock tick." The count of elapsed
clock ticks since 1 January 1980 (UTC) is the "system clock value," a
48-bit integer value of type time_$clock_t. An integer of type
time_$clock_t is called a "clock value."
The Domain/OS calendar service reports system and local time, converts
between different date and time formats, facilitates arithmetic on clock
values, and establishes and reports time zone information.
The following is a list of the cal_$ calls.
cal_$add_clock add two clock values
cal_$apply_local_offset convert a UTC clock value to a local one
cal_$clock_to_sec convert clock ticks into whole seconds
cal_$cmp_clock compare two clock values
cal_$decode_ascii_date decode an ASCII date
cal_$decode_ascii_time decode an ascii time
cal_$decode_ascii_tzdif decode an ASCII time zone
cal_$decode_local_time get the local date and time
cal_$decode_time decode a clock value
cal_$encode_time encode a date and time
cal_$float_clock convert clock ticks into seconds
cal_$get_info get the local time zone
cal_$get_local_time get the local time
cal_$remove_local_offset convert local time to UTC
cal_$sec_to_clock convert seconds to a clock value
cal_$sub_clock subtract two clock values
cal_$weekday return the weekday for a date
cal_$write_timezone set the local time zone
Constants
cal_$string_size
The number of bytes in a string of type cal_$string_t.
Data Types
cal_$dpval_t
A double-precision floating-point value used by calendar calls.
cal_$string_t
An ASCII string used by calendar calls.
cal_$timedate_rec_t
A record type for representing a date and time. It has the follow-
ing format:
15 0
______________________________________________________________
| year |
|_____________________________________________________________|
| month |
|_____________________________________________________________|
| day |
|_____________________________________________________________|
| hour |
|_____________________________________________________________|
| minute |
|_____________________________________________________________|
| second |
______________________________________________________________
15 0
year Integer representing the year.
month
Integer representing the month.
day Integer representing the day.
hour Integer representing the hour (from 0 to 24).
minute
Integer representing the minute.
second
Integer representing the second.
cal_$timezone_rec_t
A record type for specifying time zone information. It has the fol-
lowing format:
15 0
______________________________________________________________
| utc_delta |
|_____________________________________________________________|
| utc_delta |
|_____________________________________________________________|
| tz_name |
|_____________________________________________________________|
| tz_name |
|_____________________________________________________________|
| drift |
|_____________________________________________________________|
| drift |
______________________________________________________________
15 0
utc_delta
The number of minutes by which the time zone is offset from
UTC.
tz_name
A 4-byte ASCII string representing the time zone's name. The
Domain/OS calendar service recognizes the following strings to
designate Coordinated Universal Time (UTC), or Greenwich Mean
Time (GMT), and the eight standard U.S. time zones:
________________________________________
|Time Zone | Time Zone |
| Name | Represented |
|__________|____________________________|
| CDT | Central Daylight Time |
| CST | Central Standard Time |
| EDT | Eastern Daylight Time |
| EST | Eastern Standard Time |
| GMT | Greenwich Mean Time |
| MDT | Mountain Daylight Time |
| MST | Mountain Standard Time |
| PDT | Pacific Daylight Time |
| PST | Pacific Standard Time |
| UTC | Coordinated Universal Time |
|__________|____________________________|
drift
Drift adjustment.
cal_$tz_name_t
A 4-byte array for an ASCII time zone name.
cal_$weekday_t
An enumerated type for the days of the week. It takes one of the
following predefined values:
cal_$sun
Sunday
cal_$mon
Monday
cal_$tue
Tuesday
cal_$wed
Wednesday
cal_$thu
Thursday
cal_$fri
Friday
cal_$sat
Saturday
Errors
cal_$bad_syntax
A date or time specification was invalid.
cal_$empty_string
An empty string was passed to a decode routine.
cal_$invalid_tzdif
A specified time zone difference was invalid.
cal_$not_operational
The calendar service is not in operation.
cal_$out_of_range
A date or time specification was invalid.
cal_$refused
During a system boot, a user was asked whether to allow the boot to
continue with an incorrect calendar; the user refused.
cal_$unknown_timezone
A time zone name was not recognized.