rainlance/AmiTimeKeeper
1
0
Fork 0
Code Issues Pull Requests Releases 8 Wiki Activity

Release 1.12

Carsten Sonne Larsen
2021-01-31 21:07:21 +01:00
parent 9b952a7c35
commit 5ef6e11a6c
6 changed files with 203 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
ARexx-interface.md

@ -9,7 +9,7 @@ The ARexx address is `TIMEKEEPER.1`
| STATUS | Get current synchronization status |
| TIMEZONE | Get current time zone |
| LASTSYNC | Get time of last synchronization operation |
| LASTAD | Get time of last clock adjustment |
| LASTADJ | Get time of last clock adjustment |
| GET | Get a runtime configuration value |
| SET | Set a runtime configuration value |
| SHOW | Show settings window |
@ -17,8 +17,74 @@ The ARexx address is `TIMEKEEPER.1`
| START | Start the time synchronization process |
| STOP | Stop the time synchronization process |
| SHUTDOWN | Shutdown TimeKeeper |
| LOGTRANS | Emit time zone transition map to log |
**Parameters**
`STATUS` accepts `NUMBER` as parameter. Result is instead formatted
as binary value.
`TIMEZONE` accepts a code as parameter. The code determines how
the result is formatted:
| Code | Description |
| ---- | ----------------------------------------------|
| 1 | Seconds ahead of UTC (+[s]) |
| 2 | Minutes ahead of UTC (+[m]) |
| 3 | TZ style long format (UTC-[hh]:[mm]) |
| 4 | TZ style short format (-[hh]:[mm]) |
| 5 | ISO 8601 style (+[hh][mm]) |
| 6 | ISO 8601 style (+[hh]:[mm]) |
| 7 | ISO 8601 short style (+[h]) |
| 8 | Common identifier (GMT+[hh]:[mm]) |
| 9 | Common identifier, offset with name in parens |
| 10 | Common identifier, name with offset in parens |
| 11 | Standard time zone |
| 12 | DST time zone |
`NOW`, `LASTSYNC` and `LASTADJ` accepts `DOS`, `ASCII`, `DATE`, `TIME`, `RFC850`,
`RFC1123`, `RFC2822`, `RFC3339` or `ISO8601` as first parameter. `DOS` is
assumed if parameter is not specified.
| Style | Description |
| ------- | ------------------------------- |
| `DOS` | AmigaDOS style |
| `ASCII` | C ASCII style |
| `DATE` | ARexx formatted as sorted date |
| `TIME` | Time in seconds since midnight |
`LOCAL` and `UTC` are accepted as second parameter. `LOCAL` is assumed
if second parameter is not specified. `RFC850` and `RFC1123` are always
GMT.
`GET` accepts `SERVER`, `PORT`, `THRESHOLD`, `INTERVAL`, `CX_PRIORITY`,
`CX_POPKEY`, `CX_POPUP`, `READONLY`, `EXPERT`, `TIMEOUT`, `ACTIVE`, `NOLOG`,
`TZD`, `TZ`, `TZNAME`, `TZVALUE` and `TZDST` as parameter. `CX_POPUP`,
`READONLY`, `EXPERT`, `ACTIVE` and `NOLOG` accepts `NUMBER` as parameter.
`SET` accepts the same parameters as `GET`, except `CX_POPKEY`, and an
addition value parameter.
`ID`, `VERSION`, `HELP`, `SHOW`, `HIDE`, `START`, `STOP`, `SHUTDOWN` and `LOGTRANS`
does not accept parameters.
**Error handling@**
The local variables TIMEKEEPER.ERRORCODE and TIMEKEEPER.ERRORTEXT
are set on each call too ARexx.
There is a number of possible error codes.
| Code | Description |
| ---- | -------------------------------------- |
| 0 | No errors |
| 10 | Unknown ARexx command |
| 11 | Unknown parameter |
| 12 | Parameter is missing |
| 13 | Invalid parameter value |
| 18 | Clock has not been adjusted |
| 19 | No responses from NTP server |
| 20 | Synchronization is already active |
| 21 | Synchronization is already deactivated |
**Examples**
Examples
Stop the the time synchronization process with:
> Address TIMEKEEPER.1 stop
@ -28,4 +94,4 @@ Start the the time synchronization process with:
Show the settings window with:
> Address TIMEKEEPER.1 show
The arexx folder contains a set of sample scripts.
The arexx folder contains a set of sample scripts.

95
Configuring-the-client.md

@ -27,51 +27,92 @@ is the NTP server port different from 123.
**Interval between requests**
The Amiga hardware clock will slowly drift away from true time. The
drift is determined by several factors and is small, but the drift is not
insignificant. Request are repeatedly sent to the NTP server in order to
keep the Amiga hardware clock as close to true time as possible.
drift is determined by several factors and is small, but the drift
is not insignificant. Request are repeatedly sent to the NTP server
in order to keep the Amiga hardware clock as close to true time as
possible.
The requests are sent in certain intervals defined by the interval
parameter. The interval should be specified using milliseconds. One
thousand (1.000) milliseconds are equal to one second.
thousand (1.000) milliseconds are equal to one second. The max value
is 172.800.000 equal to 48 hours.
**Adjustment threshold**
Due to the accuracy of NTP servers and the nature of Amiga CPUs it does
not make sense to adjust the Amiga clock on every response from the NTP
server. Processing the response could take longer time than anticipated.
The amount of accepted inaccuracy is set using the threshold parameter.
The threshold should be specified using microsecond. One million
microseconds (1.000.000) are equal to one second.
Due to the accuracy of NTP servers and the nature of Amiga CPUs
it does not make sense to adjust the Amiga clock on every response
from the NTP server. Processing the response could take longer time
than anticipated. The amount of accepted inaccuracy is set using the
threshold parameter. The threshold should be specified using micro-
seconds. One million microseconds (1.000.000) are equal to one
second.
**Read only**
It is possible to send request to the NTP server without setting the
Amiga hardware clock. This option can be handy when debugging time zone
setup and other time related parameters.
Amiga hardware clock. This option can be handy when debugging time
zone setup and other time related parameters.
**Expert mode**
Advanced settings are hidden from the settings window when expert mode
is not enabled. The advanced settings are server port, interval between
requests, adjustment threshold, connection timeout, verbosity level and
commodity priority.
Advanced settings are hidden from the settings window when expert
mode is not enabled. The advanced settings are server port, interval
between requests, adjustment threshold, connection timeout, verbosity
level and commodity priority.
**Connection timeout**
**Connection time out**
In some cases, a connection to the NTP server cannot be established or
the NTP server simply does respond. To avoid an infinitive wait for a
response the connection will instead make a time out. The timeout
interval should be specified using milliseconds. One thousand (1.000)
milliseconds are equal to one second.
In some cases, a connection to the NTP server cannot be established
or the NTP server simply does respond. To avoid an infinitive wait
for a response the connection will instead make a time out. The
timeout interval should be specified using milliseconds. One thousand
(1.000) milliseconds are equal to one second. The max value is half
of the value of interval between requests.
**Logging**
It is possible view log messages using the supplied tool TimeLogger.
It is possible view log messages using the supplied tool @{i}TimeLogger@{ui}.
The logger facility can be turned off with the NOLOG switch.
**Automatically synchronization**
Sometimes it is feasible to start without synchronization. The clock
is synchronized in the background, only when synchronization is
active. By default synchronization is not active.
**Time zone display**
Different options for displaying the current time zone exists. The
most common is a combination of time zone name and time zone offset
from GMT. The ARexx documentation describes the time zone display
methods in details.
**Time zone**
If the local time zone is expressed as a POSIX TZ compatible string,
an optional setting is available.
**Time zone value**
The most simple way to expressed the local time zone is in hours
and minutes from Greenwich Mean Time (GMT) or UTC. One hour ahead
is equal to 100. One hour behind is equal to -100. Two and a half
hour ahead is equal to 230.
**Time zone abbreviation**
If no name is given for the local time zone, the time zone is shown
as hours and minutes from Greenwich Mean Time (GMT). It is possible
to specify a time zone abbreviation for better readability.
**Daylight saving time**
Sometimes is feasible to force a standard one hour ahead daylight
saving time (DST). Use this option if needed.
**Caveats**
TimeKeeper does not start as a background process. When started in the
startup-sequence it will by default block execution. Use the run command
to avoid this behaviour:
`> RUN >NIL: TimeKeeper`
TimeKeeper does not start as a background process. When started in
the startup-sequence it will by default block execution. Use the run
command to avoid this behaviour:
> RUN >NIL: TimeKeeper

2
Control-utility.md

@ -6,6 +6,8 @@ control utility `TimeCtrl`. The following commands are available.
| ID | Get application identifier |
| VERSION | Get application version number |
| STATUS | Get current synchronization status |
| TIME | Get current time and date |
| ZONE | Get current time zone |
| START | Start the time synchronization process |
| STOP | Stop the time synchronization process |
| SHOW | Show settings window |

23
Introduction.md

@ -1,7 +1,22 @@
AmiTimeKeeper is a small program which keeps the time right on your machine. No installation is required. It is operated as a commodity and is controlled by AmigaOS. An AmiTCP compatible TCP/IP stack is required for AmiTimeKeeper to work.
Several settings determine the behaviour. The settings are passed either directly from the command line or by using the tool types of an icon. Preferences can also be saved between reboots. A utility for small tasks like starting and stopping is also included. Comprehensive control is possible using ARexx.
AmiTimeKeeper is a small program which keeps the time right on
your machine. No installation is required. It is operated as a
commodity and is controlled by AmigaOS. An AmiTCP compatible
TCP/IP stack is required for AmiTimeKeeper to work.
The default server address is pool.ntp.org. To find another server try visiting support.ntp.org or one of the other sites listing time servers. Use a fixed pool server by prefixing the domain, for example, 1.pool.ntp.org.
Several settings determine the behaviour. The settings are passed
either directly from the command line or by using the tool types
of an icon. Preferences can also be saved between reboots.
A utility for small tasks like starting and stopping is also
included. Comprehensive control is possible using ARexx.
The local time zone needs to be configured using Workbench preferences or a similar tool. In AmigaOS 3.1 and 3.9 this is available through the Locale Preferences Editor. Daylight saving time is only supported through the POSIX TZ environment variable.
The default server address is pool.ntp.org. To find another server
try visiting support.ntp.org or one of the other sites listing
time servers. Use a fixed pool server by prefixing the domain,
for example, 1.pool.ntp.org.
The time zone needs to be configured using Workbench preferences
or a similar tool. In Amiga OS this is available through the
Locale Preferences Editor. The local time zone and daylight saving
time are optionally specified manually or using a POSIX TZ
variable style.

29
Local-time-zone.md Normal file

@ -0,0 +1,29 @@
**Selecting time zone**
The local time zone is selected from 5 different options, in
the following order:
1. TZVALUE setting
2. TZ setting
3. Global TZ environment variable
4. Global TZONE environment variable
5. Workbench Locale Preferences
**TZVALUE setting**
The local time zone value setting is available from CLI, icon
tool types and ARexx. The value is specified in hours and minutes
from GMT or UTC. One hour ahead is equal to 100. One hour
behind is equal to -100.
**TZ setting**
The TZ setting is available from CLI, icon tool types and ARexx.
**Global TZ environment variable**
The Amiga DOS global environment variable TZ containing a POSIX
TZ compliant string.
**Global TZONE environment variable**
The Amiga DOS environment global variable TZONE containing a
POSIX TZ compliant string.
**Workbench Locale Preferences**
Amiga OS / Workbench Locale Preferences Editor

30
Saving-preferences.md

@ -1,22 +1,24 @@
Preferences from the setting window are saved in the file
`ENV:timekeeper.prefs`
Preferences are saved in the file:
`ENV:AmiTimeKeeper/timekeeper.prefs`
Preferences are also persisted between reboots in the file
`ENVARC:timekeeper.prefs`
Preferences are also persisted between reboots in the file:
`ENVARC:AmiTimeKeeper/timekeeper.prefs`
Depending on the setup the content of timekeeper.prefs could be:
```
CX_POPUP=NO
CX_POPKEY=lshift control t
CX_PRIORITY=25
THRESHOLD=1000000
SERVER=de.pool.ntp.org
PORT=123
TIMEOUT=5000
INTERVAL=17500
READONLY=NO
CX_POPKEY=lshift control t
CX_PRIORITY=5
THRESHOLD=1000000
SERVER=de.pool.ntp.org
PORT=123
TIMEOUT=1000
INTERVAL=17500
READONLY=NO
EXPERT=NO
ACTIVE=YES
NOLOG=YES
```
The preference file should not be edited under normal circumstances.
@ -24,5 +26,5 @@ The preference file should not be edited under normal circumstances.
**Caveats**
Not only visible settings in the settings window are saved to the
preference file. All setting are saved includes default settings and
settings from CLI and icon tooltypes.
preference file. All setting are saved includes default settings
and settings from CLI and icon tool types.