previous next top complete contents complete index framed top this page unframed
Table 24–1. System PROCEDUREs and Macros for Date and Time
| PROCEDURE or Macro | Function |
|---|---|
| $date | Return current date |
| $time | Return current time of day |
| $dateAndTime | Return current date and time of day |
| $dateToStr | Convert numeric date to STRING |
| $timeToStr | Convert numeric time to STRING |
| $dateAndTimeToStr | Convert numeric date/time pair to STRING |
| $strToDate | Convert STRING to numeric date |
| $strToTime | Convert STRING to numeric time |
| $strToDateAndTime | Convert STRING to numeric date/time pair |
| $assembleDate | Make numeric date from day, month, year |
| $assembleTime | Make numeric time from hour, minute, second |
| $assembleDateAndTime | Make numeric date/time pair from components |
| $disassembleDate | Convert numeric date to day, month, year |
| $disassembleTime | Convert numeric time to hour, minute, second |
| $disassembleDateAndTime | Convert numeric date/time pair to components |
| $convertDateAndTime | Convert date/time pair from local to GMT or vice versa |
| $dateFormat | Whether numeric date is local, GMT, or difference |
| $timeFormat | Whether numeric time is local, GMT, or difference |
| $addToDateAndTime | Date and time addition |
| $dateAndTimeDifference | Date and time subtraction |
| $dateAndTimeCompare | Date and time comparison |
| $timeSubcommandsSet | See if MAINSAIL date/time parameters available (required on many systems for correct GMT) |
| $setTheDate | Set the date if unavailable from the operating system |
| $cpuTime | Return CPU time used by current process |
| $cpuTimeResolution | Ticks per second for $cpuTime |
| $timeout | Suspend execution for specified time |
Local dates and times can be used, e.g., by programs that want to
print out the current date and time.
GMT dates and times are useful for timestamping data that may be
shipped across time zone boundaries.
Date and time differences represent a length of time,
e.g., the amount of time a program took to run
(as would be recorded by a benchmark).
Local and GMT dates and times are called
absolute, since a date/time pair represents a single well-defined
moment in time.
Absolute dates are represented as:
added to an appropriate bias (there is one bias value for GMT dates
and another for local dates);
absolute times are represented as:
added to the same bias as for dates.
The guaranteed date range is from 1 January, 978,077 B.C.
to 31 December, 981,792 A.D., according to the Gregorian calendar
(which is the calendar now in use in all Western countries and,
for secular purposes, in most other countries as well; it is
extrapolated for MAINSAIL's purposes
backwards or forwards to the limiting dates of the guaranteed
range even though it was not actually used anywhere until 1582 A.D.,
and may or may not be in use in 981,792 A.D.).
The absolute time of day range is from 0:00:00 to 23:59:59 on
a 24-hour clock.
Differences are absolute numbers with no bias; e.g.,
a date difference of 23L represents 23 days, and a time difference
of 23L represents 23 seconds.
Subtractions may produce a negative difference if the presumed later
date or time is actually the earlier.
The guaranteed
range of date and time differences is large enough to accommodate
the subtraction of the earliest guaranteed absolute date or time from
the latest or vice versa.
The PROCEDUREs $dateFormat and
$timeFormat may be used to determine
the format (i.e., local, GMT, difference, or invalid) of
any date or time value.
2 am on nth/last Sunday of month
This information can be made available to the MAINSAIL runtime system
by
issuing the appropriate MAINEX subcommands or
calling the appropriate system PROCEDUREs.
It is intended that the most commonly used
way to make this information available
to the runtime system will be to set the subcommands once, at MAINSAIL
installation,
using MAINEX subcommands
in a file called site.cmd on the MAINSAIL directory.
This file, if it exists, is read by MAINSAIL each time it is
initialized.
The MAINEX subcommands may
not be required on those operating systems that provide
sufficient time zone information to user programs.
At present, no operating system on which MAINSAIL is supported
provides as much information
as the MAINEX subcommands, although some operating systems do
provide part of the information.
The MAINEX time subcommands are documented in full in
Chapter 21 of the MAINSAIL Utilities User's Guide; here is a summary of the subcommands,
along with the system PROCEDUREs corresponding to each subcommand:
If the MAINEX subcommands are not given, the local date and time
facilities continue to work correctly; however,
PROCEDUREs that accept or return GMT values may not work correctly.
The BOOLEAN PROCEDURE
$timeSubcommandsSet is provided to allow a program to deal
with this situation.
The PROCEDURE $timeSubcommandsSet returns TRUE if
and only if
if any of the relevant MAINEX
subcommands has been issued;
it is assumed that if any of the time zone subcommands has been set,
all have been set correctly.
Thus, if $timeSubcommandsSet returns TRUE,
then GMT conversions may be expected to be successful.
If no subcommands describing the local time zone are given,
$timeSubcommandsSet returns FALSE,
and any PROCEDURE attempting to convert from GMT to local time
or vice versa returns the value it would return in
the Greenwich Mean Time zone
unless the operating system also provides the information.
If there is a problem in MAINSAIL's date and time PROCEDUREs
with conversion from the local time zone to
GMT or vice versa,
the first thing to check is whether the MAINEX time zone subcommands
have been set properly.
You can check whether they have been set at all by invoking
the debugger and examining
the variable $timeSubcommandsSet.
24.1. Representation of Dates and Times
MAINSAIL numeric dates and times are represented as LONG INTEGERs.
They may be local dates and times, Greenwich Mean Time
(or GMT; also known as Coordinated Universal Time) dates and times,
or date and time differences (intervals).
The three types of values are distinguished by being represented by
values located in
three different parts of the LONG INTEGER range.
the number of days since 17 November 1858
the number of seconds since midnight
24.2. Information Required by MAINSAIL
The following information needs to be available to MAINSAIL
in order to return GMT values and convert local dates and times
to GMT and vice versa:
24.3. GMT Conversions and $timeSubcommandsSet
Any PROCEDURE that does a conversion (explicit or implicit)
from GMT to local time
or vice versa acts as if local time were Greenwich Mean Time
if the GMT MAINEX subcommands have not been
issued and the operating system does not provide the required
information.
This is the same behavior produced if all subcommand values are set to
Zero.
24.4. Conversion Caveats at the Start and End of Daylight
Savings Time (or Other Adjusted Time)
It is not specified which of the two possible GMT times is returned by
any PROCEDURE that converts (implicitly or explicitly)
from local to GMT times
during the
ambiguous transition period from daylight savings time to
standard time.
If the conversion is from GMT to local time, however, it is always
possible to determine the correct local time if the
correct time zone and daylight savings time algorithm are provided
by the appropriate MAINEX subcommands.
24.5. MAINEX Time Subcommand Values Appropriate to the
Forty-Eight Contiguous United States
For the time zones of the contiguous
United States, the appropriate MAINEX subcommand values are
shown in Table 24–2.
Table 24–2. MAINEX Time Subcommand Values for the Contiguous United States
| Time Zone | GMTOFFSET | STDNAME | DSTNAME |
|---|---|---|---|
| Eastern | 18000 | EST | EDT |
| Central | 21600 | CST | CDT |
| Mountain | 25200 | MST | MDT |
| Pacific | 28800 | PST | PDT |
The subcommands shown in Table 24–3 should be given everywhere that the standard time zone abbreviations for the forty-eight contiguous United States are used. Additional subcommands may be desirable if other time zone abbreviations are commonly referred to.
Table 24–3. Subcommands Defining the Names of the Time Zones in the Forty-Eight Contiguous United States
| DEFINETIMEZONE EST 18000 DEFINETIMEZONE EDT 14400 DEFINETIMEZONE CST 21600 DEFINETIMEZONE CDT 18000 DEFINETIMEZONE MST 25200 DEFINETIMEZONE MDT 21600 DEFINETIMEZONE PST 28800 DEFINETIMEZONE PDT 25200 |
DSTOFFSET 3600 should be specified where daylight savings time is used, and DSTOFFSET 0 where it is not. As of 8 July 1986, the following should be specified where daylight savings time is in effect (and will be ignored if it is not, i.e., if DSTOFFSET 0 is set):
DSTSTARTRULE April Sunday 1 2:00
DSTENDRULE October Sunday 5 2:00
Complete sample sets of time zone subcommands for the forty-eight contiguous United States (except for those shown in Table 24–3) are shown in Tables 24–4, 24–5, 24–6, 24–7, 24–8, and 24–9. These subcommands should appear in a file site.cmd on the MAINSAIL directory, which should be created when a new version of MAINSAIL is installed.
Table 24–4. Subcommands for the Eastern Time Zone: from the Atlantic Seaboard West through Michigan, Eastern Kentucky, Eastern Tennessee, Georgia, and Florida Exclusive of the Panhandle
| GMTOFFSET 18000 DSTOFFSET 3600 STDNAME EST DSTNAME EDT DSTSTARTRULE April Sunday 1 2:00 DSTENDRULE October Sunday 5 2:00 |
Table 24–5. Subcommands for Indiana except Parts of the Extreme West
| GMTOFFSET 18000 DSTOFFSET 0 STDNAME EST |
Table 24–6. Subcommands for the Central Time Zone: Wisconsin, Illinois, Parts of Extreme Western Indiana, Western Kentucky, Western Tennessee, Alabama, the Florida Panhandle, Mississippi, Louisiana, Arkansas, Missouri, Iowa, Minnesota, Eastern North Dakota, Eastern South Dakota, Eastern Nebraska, Kansas except Parts of the Extreme West, Oklahoma, and Texas except the Extreme West
| GMTOFFSET 21600 DSTOFFSET 3600 STDNAME CST DSTNAME CDT DSTSTARTRULE April Sunday 1 2:00 DSTENDRULE October Sunday 5 2:00 |
Table 24–7. Subcommands for the Mountain Time Zone: Western North Dakota, Western South Dakota, Western Nebraska, Parts of Extreme Western Kansas, Extreme Western Texas, New Mexico, Colorado, Wyoming, Montana, Southern Idaho, Parts of Extreme Eastern Oregon, and Utah
| GMTOFFSET 25200 DSTOFFSET 3600 STDNAME MST DSTNAME MDT DSTSTARTRULE April Sunday 1 2:00 DSTENDRULE October Sunday 5 2:00 |
Table 24–9. Subcommands for the Pacific Time Zone: Northern Idaho, Washington, Oregon except Parts of the Extreme East, Nevada, and California
| GMTOFFSET 28800 DSTOFFSET 3600 STDNAME PST DSTNAME PDT DSTSTARTRULE April Sunday 1 2:00 DSTENDRULE October Sunday 5 2:00 |
MAINSAIL Language Manual, Chapter 24