pSetClock 1.0  A tiny replacement for SetClock,  (C) 1993 Peter Thompson  WARNING! This program has ONLY been tested on an A501 style  clock and one(1) A3000 running 2.04. It may cause system crashes  or data corruption on any other type of Amiga. Read the  installation instructions below *very carefully*.   36 -+- 36 -+- 36 -+- 36 -+- 36 -+- 36 -+- 36 -+- 36 -+- 36 -+- 36  Conditions of Distribution and Use ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - All rights are reserved by the author, unless otherwise specified. - The program, if distributed, must be accompanied by the source code aand this documentation file. - Fred Fish and Megadisc are specifically given permission to distribute the program. - No payment is required for initial or continued use of the program. - The author did not design the program to do any damage, and uses it himself, but the program is "as is" and the responsibility to ensure that no explicit or implicit damage of any kind results from use of this program lies entirely with the user. Usage ~~~~~ pSetClock is an almost drop-in replacement for SetClock. The main differences are three: a) Input: pSetClock may be started from the WorkBench. It loads the system time from the internal clock if started in this way. pSetClock does what serves for a reset (on my machine) on every save; reset is just clobbers the clock. b) Output: pSetClock does not produce any output at all, except via return codes. This means that you will have to run the date command yourself if you want to know what day the computer thinks it is. The possible return codes are 20 for catastrophic failure (including invalid command lines), 10 for invalid system (save) or clock (load) times, and 0 for normal, successful termination. c) Space and Time: pSetClock is smaller (972 bytes vs. 4972 for 1.3) and faster (About 5-10 milliseconds vs. at least 1 second for 1.3). Known program weaknesses ~~~~~~~~~~~~~~~~~~~~~~~~ - Program has only been tested under 1.3 on a single A500. - Program directly accesses clock hardware WITHOUT checking if clock is there. This may cause a system crash or invalid times. - Program is not quite a drop in replacement for SetClock; does not run the date command. - Load option does not work for clock dates after 2040. - Save option does not work for system dates after sometime in 2045-2046. Known program strengths ~~~~~~~~~~~~~~~~~~~~~~~ - It's worked for me for over a month now. - Program is tiny (around 1K) and can be made resident. - Program is not quite a drop in replacement for SetClock; does not run the date command. - Program does not need the Workbench 2 clock load/save routines, but uses them if present (I hope correctly). - Conversion routines have been tested on several hundred thousand dates (using the test routine in the source). Installation ~~~~~~~~~~~~ This program should work for all machines having 2.x and higher AND a battery backed clock. Behavoir is UNtested under 2.x both with and without a clock, except for passing the Crash and Burn test below on an A3000 with clock. This program will otherwise only work on machines having a battery backed clock installed at $dc0000, as in an A500 with the the Roctec RM2MC ram card [1], the Commodore A501 0.5Mb expansion, or other compatible card installed. The result of using it recklessly on any other machine has not been tested, but is likely to be non-trivially bad. See the "Crash and burn" test below. [1] This is the only card it has been tested on, but Roctec claims A501 compatibility. You should only really install this program if you a) have a battery backed clock b) want to save 4k on your system disk and a couple of seconds from your startup time and c) know what you are doing. Crash and burn test (DO THIS BEFORE INSTALLATION): NOTE: The system time is altered using the date command; the battery backed clock is altered using a SetClock type program. 1) Quit all important applications, save all unsaved work, park your hard drive(s); in other works, save anything you don't want to lose. 2) Change directory to your ram drive and copy pSetClock there. 3) Make sure your system and battery backed clocks are set to the same current correct time. 4) Alter the system time (to, say, midday tomorrow) and then load the system time by typing "pSetClock load". 5) Run the date command and consult the table below! a) If you got a guru, lockup, or general protection fault before running the date command then your clock is not where pSetClock likes to find it. You'll have to alter the clock address, if you know where it is, and if it likes the same format as my clock - tell you what, just stick with your current program. b) If the time is wildly inaccurate, then either your date was 1-Jan-78, past about 2040, your clock is not at $dc0000, or your clock needs to be reset. Use the reset option on your old SetClock, and go back to step 3. If you get here again, see the comments in part a), but in a lighter frame of mind. c) If you got the correct date and time, fine. go on to step 6. 6) Now comes the potentially dangerous part - testing the save option. If you got the correct time in step 5, then your clock is probably the way pSetClock likes it, so the danger is not huge. Alter the system time again. 7) Save the date to the battery backed clock by typing "pSetClock save". Now reset the system time to the correct value, and then type "pSetClock load". Run date again to find out whether pSetClock got it right; if it did, set system and battery backed clocks to the correct time and go on to step 2 of the installation procedure below. Installation: 1) Go through the crash and burn test above. 2) Make a backup of your Workbench disk. [optional, but a good idea] 3) Reboot from the backup. [ignore if you ignored step 2] 4) Copy the pSetClock program into your S: directory (or C: directory). 5) Change the line in your startup-sequence that reads SetClock opt load into S:pSetClock opt load (or C:pSetClock opt load if you put it in C:). If you still wish to have the date printed, add a line containing "date" immediately after the above. Save. 6) Now you may delete the original SetClock if you need more space. Don't forget to leave your original program on at least one other disk. Troubleshooting ~~~~~~~~~~~~~~~ Q. What are the options for pSetClock? I tried pSetClock ? and it didn't tell me anything! A. For size, pSetClock doesn't do any output. Valid options are load, save, and reset (case doesn't matter); you may type opt load, opt save, or opt reset instead. Q. Where's the date? A. For size and speed, pSetClock doesn't print the date or call the date command to do so. See step 5 in the installation procedure. Q. pSetClock doesn't change the date! How dare you foist this piece of junk on an unsuspecting public? A. Calm down. When either the system (for saves) or the clock date (for loads) is crazy, pSetClock does not change the date and sets a return code of 10. Set the correct date and time using the date command, enter "pSetClock save" and try again. Q. I installed pSetClock, and now my startup-sequence doesn't work! A. If you went through the "Crash and Burn" test above, and it worked that time, the most probable thing is that the clock time is crazy. See above. History and rationale ~~~~~~~~~~~~~~~~~~~~~ [Version 0.1] This was an unreleased version that I can't remember anything about. [Version 0.2] The 1.3 Commodore SetClock is slow. Too slow. Part of the reason is it uses the Execute() system call to run the date command to print the date and time; I hacked a copy of SetClock to remove the call to Execute, and called it pSetClock. The 1.3 Commodore SetClock is also big. Too big, given the job it does and the amount I usually run it. Unfortunately, it was also too big for me to want to spend the time to track down the secret formula for addressing the battery backed clock. Howver, on Fish 718 there was a command called SetTime; this was only two blocks and did the same job as "pSetClock load". Moreover, it had source, so I learned two things; how to set and fetch system time, and where the battery backed clock lives. Good as this was, it was not good enough; the reason being that there was no "save" option, for those times when the clock gets clobbered, so I needed to keep the old-style pSetClock around. Given that I wanted to do it and that I knew how to do it, the rest was history. [Version 0.3] The second (third?) time around, I wanted to fix a few things. These were non-WorkBench friendliness (actually, downright hostility), no reset option, really cruddy command line parsing, and an almost total lack of input validation. I also occasionally saw funny dates coming out of the load routine, and had had an idea for a much better algorithm for dealing with leap years and so on. pSetClock can now be started from Workbench (it always does a load), always does a reset when saving, has much better command line parsing, and checks every clock digit for validity. The new algorithm is faster (not that that matters much for this program) and it's got a larger valid range of inputs. And it's still only two SFS blocks. [Version 0.4] Unfortunately, 0.3 had a slight bug in it. Fortunately, I didn't release it. I also got the 2.x Native Developer's set from CBM, so I decided to add 2.x compatibility and to clean up the structure a bit. This sent it up to three SFS and FFS blocks, so I decided to sleep on it. [Version 1.0] Through painful squeeze and careful register allocation, I got it back down to just under 2 SFS and hence FFS blocks. It's just that tiny bit slower, but not significantly (about 1 millisecond max). This should be the last version, unless I decide to add some kind of date output (which will probably get it up to 3 blocks). Should you wish to send me comments, money or job offers, (any of which would be appreciated), my address is: Peter Thompson 33 Pleasant Street Pascoe Vale 3044 AUSTRALIA My 1993 Internet address is: pdt@cs.mu.oz.au Misc. Techie stuff ~~~~~~~~~~~~~~~~~~ This program requires version 1.2 or better of the operating system, but has only been tested under version 1.3. It uses only the Exec library and a few offsets in the DOS process structure. You will require A68k, the Commodore assembler include files, and a linker (Blink for preference) to assemble this program. From experiment, the format of the battery backed clock is as follows: * The clock base address is $DC0000 * Each digit takes up a long word (4 bytes) but only the least significant 4 bits are valid. * The digits are seconds, tens of seconds, minutes, tens of minutes, hours, tens of hours, days, tens of days, months, tens of months, years, and decades since 1900. 12:34:56 on the 1st of April 2000 would be stored by writing the digits 6 5 4 3 2 1 1 0 4 0 2 10 as longwords (4 bytes). Amiga, Workbench, Exec and a few other things (but not pSetClock) are registered trademarks or something of Commodore Business Machines.  36 -+- 36 -+- 36 -+- 36 -+- 36 -+- 36 -+- 36 -+- 36 -+- 36 -+- 36