Status Window
Version: 0.08 (2nd Nov 2007)
Visit CronTool Homepage
CronTool is a utility for executing commands and simple script files at preset times of the day. It can simplify automated tasks as well as providing a simple and more flexible alternative to using Task Alarms. Do read the disclaimer before you start using CronTool in earnest though.
This manual is still under contruction, so please bear with me if it's not as comprehensive as it could be.
Contents
Although fully featured, the demo version is limited to 15 minutes use, after which it will quit automatically.
You can convert it back to an unregistered demo by deleting the Choices$Write.CronTool directory, as these files are generated automatically if they doesn't exist.
If you find CronTool useful or continue using it after the 14 day evaluation period, you are encouraged to support RISC OS software development by registering it.
The registration fee is £20.00 and can be paid via personal cheque or PayPal. Cheques should be made payable to "Digital Phenomena Ltd" who handle payments on my behalf, and posted to the contact address shown below.
When your registration fee is received, you will be sent a unique registration code which will turn the demo version into the full version. This registration code can also be used for future updates, which are free to registered users.
Extract from the archive and copy somewhere on your hard disc. The first time you run CronTool it will create the relevant choices files and empty 'cron' files (placing them inside Boot:Choices.CronTool). It will then display the 'nag screen' telling you it's unregistered. At this point, either enter a valid registration code, or click 'Register later' to run in Demo mode.
As it stands, CronTool won't do anything (other than tell you when the next cron file will execute. This is because the default cron files are all blank and have no actions assigned to them.
The status window can be dragged around the screen and the coordinates are stored within the main choices file, so wherever you position the window is where it will open next time you load CronTool. Of course, you may not want the status window open at all, preferring CronTool to run invisibly in the background. This is no problem and you can disable the status window from the main choices.
Clicking menu over the status window will display the main menu, from which you can select the Choices... option to open the window shown to the left.
Most of the options in this window are self-explanatory:-
Open Cron Directory - This opens the main choices directory window, from where you can edit the relevant cron files (see below).
Enable status window - Sets whether or not the small status window is open or not. If this is turned off, CronTool will effectively run in the background as there'll be no visual indication on the desktop that it's actually running.
Enable logging - If this option is on, CronTool will save a log of all it's operations - so that you can see what's happening if something goes wrong, or doesn't do as you would expect.
Open Log File - Clicking on this button will load the log file into a text editor, if loaded.
Beep on warning - By default, CronTool sounds a bleep if a warning window is opened. This option will allow you to disable this so that you receive a visual warning only.
Safe Mode - Some of the script commands in CronTool are potentially dangerous, such as being able to shutdown the machine, reset it or wipe specific directories from the filer. For this reason, you can enable a Safe mode which will force CronTool to ignore any dangerous commands. Of course, this may prevent you carrying out some tasks - but at least you stand less chance of doing damage if something goes wrong.
N.B. Enabling Safe Mode generates a checksum for the main choices file, which means you can no longer manually edit the file. Should you wish to edit the file manually, you should go into the choices and disable Safe Mode.
i - Clicking on the i icon will load this manual.
Cancel and OK should be fairly obvious! :-)
Clicking MENU (middle mouse button) over either the status or choices window will display the main menu. This has a number of options:-
| Info | Display info about CronTools | |||||||||||||||||||||||||||
| Help... | Display this manual | |||||||||||||||||||||||||||
| Tools | Tools sub-menu
| |||||||||||||||||||||||||||
| Choices... | Open the Chocies window | |||||||||||||||||||||||||||
| Status... | Display the Status window | |||||||||||||||||||||||||||
| Quit | Quit CronTool |
crontab and how to configure when things occur
With the exception of the custom cron file, all cron files run at a specific time each day. There are five main cron files; cron.hourly, cron.daily, cron.weekly, cron.monthly and cron.yearly. By default these execute (understandibly) hourly, daily, weekly, monthly and yearly at specific times set by what's known as a crontab file.
In normal usage you shouldn't need to alter the crontab file at all, as I've chosen relatively standard default values to pre-load the file with. However, should you want to tweak the values to suite individual requirements, you can simply edit the values in the file.
There are five lines of values - one for each cron file. Each line consists of five numeric values and the name of the file they apply to. From the left-hand column these are:-
Minute 00 - 59 to define the active minute to activate on.
Hour 00 - 23 to define the active hour to activate on.
Day of Month 00 - 31 to define the active day of the month to activate on.
Month 1 - 12 to define the active month to activate on.
Day of Week 1 - 7 to define the active day of the week (Sunday to Saturday, 1-7) to activate on.
Please note that no error checking is carried out on which are valid parameters, so if you enter something invalid line a month value of 14, the corresponding cron file will never be run - because the date/time will never match.
The status window will calculate when the next cron event or file will be and display this in the 'Next Event' box.
There are five files - corresponding to the five lines in the crontab file - and these are stored inside Boot:Choices.CronTool.
There is actually a sixth one; custom but that's a special case which will be explained later.
The five normal cron files; hourly, daily, weekly, monthly and yearly all have the same data format in that they consist of a number of lines containing the commands you require (see examples). Each parameter is divided by either a space or a tab character (the 'divchar'). This can be edited for the more technical people, by changing the value stored in the main choices file. However, a space should always be recognised, irrespective of what you define the divchar as.
The best tactic is to experiment and see what effects you get. Examine some of the examples below and/or edit them to suit your own needs. The command parser is reasonably intelligent and can allow for some quite complex flexibility. However, make sure each parameter is correctly spaced out if required. For example, just entering alarmon (ie. no space) will be ignored.
Important Disclaimer: Because some potentially dangerous commands can be placed in cron files, capable of deleting files on your hard disc, I won't accept responsibility or be held to blame for any loss or corruption of data howsoever it may be caused. You write cron files at your own risk.
I also cannot guarantee no 'show stopping' bugs don't still exist, although I have endeavoured to give CronTool an extensive testing.
However, I have implemented a Safe Mode which will disable any potentially dangerous commands from being executed, although that may prevent some scripts from running properly. Again, I'll leave you to experiment and familiarise yourself with the way things work.
The custom cron file is a slight variation on the other files in that you can specify preset times for commands to be executed. The format is exactly the same as the other files, except that each line starts with a four digit time in the format hhmm followed by a space or divider character (tab). For instance, to sound a beep at 8:15am, you would include the following line;
0815 beep
The custom cron file doesn't have an execute time assigned to it, so there's no entry for it in the crontab file. Instead, the custom file will begin execution as soon as you load CronTool. It will read the first line from the file and only execute the command when the alloted time occurs.
If you enter -1-1 for the time, the command will be executed immediately, with no waiting. This allows you to perform several commands one after the other. An example may explain a bit better.
0815 wipelog
0820 beep
1000 email user@domain.com autoack
-1-1 warning hello
OK, so it's a bit of a trivial or pointless example, but this will wait until 8.15 am (could be the following morning if you don't load CronTool until 3pm or something) and then wipe the log file. It will then wait until 8.20am and make a bleep sound.
It will then wait until 10am before emailing user@domain.com with an autoack email and then immediately after sending the email (ie. time = -1-1) print a warning message saying "hello" on the screen.
Frequently Asked Questions (FAQ)
1. Why doesn't the status window use standard RISC OS tool icons?
Commands should be placed all on one line and parameters should be separated by a single space character. Ensure you don't have rogue or extra spaces, or you may get unexpected actions occurring.
In alphabetical order
| .label | Define a new label to enable jumping via the goto command. |
| after xx yyy | After xx seconds execute command yyy. eg. after 90 wipelog will automatically wipe the log file after 90 seconds. You can suffix the number of seconds with 'm' or 'h' to signify minutes or hours if you want. eg. after 15m wipelog will perform the same task but after 15 minutes instead of 90 seconds. Minimum time period is 5secs. |
| alarm on | Start sounding alarm. |
| alarm off | Stop sounding alarm. It will turn off automatically after the alarmtime (default 60 seconds) period. |
| beep | Sound a system beep. |
| cli xxx yy zz | Pass xxx yy zz onto the RISC OS CLI interface. USE WITH CARE! |
| email xxx yyy | Send an email to email address xxx with email template yyy. eg. email user@domain autoack |
| email xx yy | Email user xx with message template yy |
| every xx yyy | Every xx seconds execute command yyy. eg. every 90 wipelog will automatically wipe the log file every 90 seconds. You can suffix the number of seconds with 'm' or 'h' to signify minutes or hours if you want. eg. every 15m wipelog will perform the same task but every 15 minutes instead of 90 seconds. Minimum time period is 5secs. See also: kill every |
| ftp user pass host directory | Invokes a plugin for !FTPc to upload everything in directory directory to a remote host, using the login details supplied. eg. ftp paul wibble ftp.domain.co.uk ADFS::HardDisc4.$.site.files will login to ftp.domain.co.uk with username paul and password wibble and then upload the contents of directory ADFS::HardDisc4.$.site.files N.B. FTPc will be loaded automatically if seen, and quit automatically after the upload is complete. |
| goto xxx | Jump to label xxx where the label is defined as .xxx (see above) |
| if | Test for condition (see below) |
| kill every | Reset and delete all every repeating processes. |
| loadapp xxx | Load application xxx. eg. loadapp ADFS::HardDisc4.$.Utilities.Graphics.!ChangeFSI will load !ChangeFSI |
| log xxx | Write "xxx" to the CronTool log file (inside Wimp$Scrap). |
| mkdir xxx | Make a new directory. Can also use cdir |
| nextslot xxx | Change NextSlot to xxx. Can be suffixed by K or M for KB/MB. |
| ping host | Ping host host. By itself this command just sets the internal 'packetloss' variable. However, used in conjunction with set pingalarm and set pingwarning can alert you to non responding servers. See example 2 |
| prequitapp xxx | Send a wimp Pre-Quit message to application xxx (where xxx is the task name as listed in the main Tasks window. Can also use prekillapp |
| quitapp xxx | Quit application xx (where xx is the task name as listed in the main Tasks window. Can also use killapp |
| reset | Reset and reboot the computer. USE WITH CARE! |
| respawn xx yy | Setup a background watcher so that if application xx (as listed in Tasks window) is not loaded, or quits unexpectedly, task yy will be started. eg. respawn POPstar ADFS::HardDisc4.$.Internet.!POPstar will automatically reload POPstar if it quits. |
| rmdir xxx | Delete directory and all files contained within it. USE WITH CARE as no confirmation is required. |
| screensave xxx | Save the current screen as a file called xxx. If no pathname is given, will save in current directory. |
| set alarmtime xx | Set the alarm time to xx seconds (min 5 secs), so that when the alarm sounds, its duration will be xx seconds. Unless specifically changed, its default value is 60. |
| set dnsalarm | Sound alarm if future WHOIS matches dnswarnstatus. |
| set dnswarning | Enables dnswarning, which will display a warning message on screen if future WHOIS matches dnswarnstatus. |
| set dnswarnstatus xxx | Sets the WHOIS status variable for future WHOIS status matching. eg. set dnswarnstatus deletepending will scan the deletepending status of future domains checked using whois. |
| set mta xx | Set Mail Transport Agent (MTA) to xx, where xx is; popstar voyager ant A warning message will be given if CronTool can't locate the relevant MTA. This command will set the outgoing transport mechanism for sending automated emails. |
| set pingalarm | Sound alarm if future pings fail. |
| set pingwarning | Enables pingwarning, which will display a warning message on screen if future pings fail. |
| shutdown | Force a shutdown of the machine. USE WITH CARE! |
| unset pingalarm | Don't sound alarm if future pings fail. |
| unset pingwarning | Disable pingwarning, so future ping failures will not display a warning message on screen. |
| unspawn xxx | Remove application xxx from the respawn list so that it will no longer respawn if quit. |
| url xxx | Launch URL xxx |
| wait xx | Wait for xx seconds doing nothing. (where 0 < xx <= 60) |
| warning message | Open a warning window displaying message. |
| whois xxx | Do a WHOIS lookup on domain xxx. See example 4 |
| wipelog | Wipe the CronTool log file. |
| zip create xxx | Create a new ZIP archive with filename xxx. eg. zip create ADFS::HardDisc4.$.new/zip will create a ZIP archive called new/zip in the root directory of your hard drive. |
| zip add xxx | Add a new file/directory to the ZIP archive opened with the zip create command. xxx should be the full filename. |
If you have any requests for additional commands to be implemented, please contact me.
A number of additional tests can be carried out via the IF command. These are listed below.
Note the spacing of commands vs =
| if day=5 xxx | If day of week is Thursday (5) then execute command xxx. |
| if not day=1 xxx | If day of week is NOT Sunday (1) then execute command xxx. |
| if tue xxx | If day is Tuesday then execute command xxx. |
| if apr xxx | If month is April then execute command xxx. |
| if date=0205 xxx | If the date is 2nd May then execute command xxx. |
| if year=2006 xxx | If year is 2006 then execute command xxx. |
| if xxx=loaded yyy | If application xxx (name as per Tasks window) is loaded then execute command xxx. |
| if xxx=notloaded xxx | If application xxx (name as per Tasks widnow) is NOT loaded then execute command xxx. |
| if ping=0 host xxx | Ping host xxx and if packet loss equals 0 then do command xxx. eg. if ping=0 www.bbc.co.uk beep will sound a system beep if there is no packet loss contacting www.bbc.co.uk See example 1 for an example of setting up an automated server alert system. |
| if whois=yyy host xxx | Do a WHOIS lookup on domain 'host' and if the status code equals yyy then do command xxx. eg. if whois=deletepending vigay.com warning Vigay.com about to expire. will issue an expiry warning if my domain is about to expire. See example 4. |
List of useful Email related Commands
You can set a number of variables to enable you to make the automated email system more flexible. These allow you to change the default header details as per the table below.
Note the spacing of commands vs =
| set from xxx | Set the From: address. eg. set from user@yourdomain.co.uk |
| set name xxx [yyy] | Set your real name to xxx yyy where yyy (surname) is optional. eg. set name Paul set name Paul Vigay |
| set reply-to xxx | Set a reply-to address of xxx where xxx is a valid email address. |
| set subject xxx | Set the Subject: to xxx |
There are a number of pre-defined email templates you can use for the automated email system. There are currently:
| autoack | A straight forward 'auto acknowledgement' email, which is useful if you want an unattended machine to send you emails each day, to let you know it's still running ok. |
| Birthday | Send a Happy Birthday greeting - useful if you're sad and forgetful, as you can program all your friends birthdays into a custom cron file and surprise them by 'remembering' their birthday at 12 midnight on the relevant day. :-) |
| Christmas | As above, but send a Christmas greeting. |
| noping | A simple email to alert you to a non-responding website or server. This can be useful for automatic monitoring of important servers. |
You can add your own ones by saving a plain text file inside the !CronTool.Templates.email directory.
Each email template can have a number of embedded commands which will be expanded when an automatic email is generated. These are currently:
| #from | Substitute the From: email address |
| #name | Substitute the full/real name. |
| #date | Expand to today's full date. |
| #time | Expand to the current time. |
| #host | Substitute the last used hostname (used for ping or FTP). |
Any lines starting with # or | will be ignored, assuming they're comments.
Example 1 - Custom log to check the status of a remote server
# Cron custom generated by CronTool on Sat,17 Jun 2006.21:46:50 # -1-1 wipelog -1-1 set mta popstar -1-1 every 600 if not ping=0 pop.orpheusnet.co.uk email youremail@yourdomain.com noping
This example cron file will execute commands immediately (-1-1 for times) and wipe the log file. The second line tells it to set the mail transport agent to POPstar (so that any future emails will be sent via POPstar (assuming it's loaded and running) before setting up a background task to ping pop.orpheusnet.co.uk (in this example) every 10 minutes. If the response is not 0% packet loss, the email template 'noping' will be emailed to youremail@yourdomain.com
Example 2 - Another custom log to check the status of a remote server
# cron.custom generated by CronTool on Tue,20 Jun 2006.19:32:18 # -1-1 set pingalarm -1-1 set pingwarning -1-1 every 30m ping www.vigay.com
This script also monitors a remote server, but in a slightly different manner and without sending an automated email response if the server is unavailable.
Instead the first two lines will set the status for the pingalarm and pingwarning internal variables. This means that any future failed pings will set off the alarm and also display a warning message on screen.
The third line will setup a background task to ping www.vigay.com every 30 minutes.
N.B. In this particular example the alarm and warning will go every every 30 minutes anyway because my particular server (www.vigay.com) is setup not to respond to ping requests anyway.
Example 3 - Perform an automated offsite backup once a day.
Example cron.daily (ie. no times at beginning of lines)
# Custom cron file to make offsite backup of files. # wipelog rmdir RAM::RamDisc0.$.backup mkdir RAM::RamDisc0.$.backup if sparkfiler=notloaded loadapp ADFS::Iyonix.$.Utilities.Archivers.!SparkFS zip create RAM::RamDisc0.$.backup.Orpheus-backup INC2 zip add ADFS::Iyonix.$.Orpheus.2005accounts zip add ADFS::Iyonix.$.Orpheus.correspondence zip add ADFS::Iyonix.$.Orpheus.database zip create RAM::RamDisc0.$.backup.DP-backup INC2 zip add ADFS::Iyonix.$.DigitalP.accounts zip add ADFS::Iyonix.$.DigitalP.communications zip add ADFS::Iyonix.$.DigitalP.invoices zip add ADFS::Iyonix.$.DigitalP.receipts wait 8 ftp username password offsite.server.co.uk RAM::RamDisc0.$.backup quit sparkfiler
Annotated listing of lines above;
1. Wipe the log
2. Remove any previous directory (which will later prevent 'archive already exists errors' if you don't subsequently delete the files after making the backup).
3. Make a new directory (using a RAM disc for convenience - can be anywhere)
4. Check to see if SparkFS is loaded. If not, load it automatically.
5. Create a new archive with incremental (type2) filenames. This means that every two days the filename will get incremented (INC1 increments every day), so that you can leave the script running for ever and each 15 backups will be saved each month, each month overwriting the previous months.
6 - 8. Add various folders to the backup (in this example, I'm backing up my Orpheus accounts and data.
9 - 13. Duplicate the entire process for my Digital Phenomena accounts and data.
14. Wait 8 seconds - to give SparkFS enough time to close the previously updated archive file.
15. Upload the contents of the backup directory (ie. the two archive files) to an offsite server (login details anonymised for security in this example).
16. Quit SparkFS - so we're back to how we were before the script was run. As this is cron.daily it will be run at 4am in the morning, so it will all be done nicely whilst I'm asleep and I can check the log in the morning in the case of any errors or problems.
CronTool reponds to the wimp message protocol, through which it can receive instructions from other applications. At present only limited support is provided.
Message_PVaction (&58AC0)
Information in the message block is as follows:
| R1+20 | 1 (application wake-up code - should always be one, to signify CronTool) | |||||
| R1+24 | CronTool action code
|
CronTool also defines the system variable <CronTool$LogDir> which points to the location of the directory holding the log file (if used).
If you do anything network related (ie. ping, FTP etc) when there is no network connection (ie. lead disconnected), the machine will hang for sometime until the network connection times out. I can't seem to find a way of bypassing this. Non-responding pings etc are detected in a couple of seconds, but there doesn't appear to be a way of checking a network connection.
CronTool will only run continuously for approx 31 years, due to storing the number of elapsed seconds in an integer variable. Therefore the maximum length of time CronTool can run for is approx 1E9 seconds.
Maximum of 30 parameters per line.
Maximum of 20 'every' events.
Maximum of 20 'after' events.
Maximum of 20 'respawn' applications.
Think of new commands to add. :-)
Write some decent instructions/documentation
Any further suggestions?
CronTool is written by Paul Vigay who can be contacted via the following ways;
Email: You can contact me via the webform at www.vigay.com/feedback/
Web: http://www.vigay.com/
Post: PO Box 813,
Portsmouth,
Hampshire,
PO1 9EY
England
v0.08 (2nd Nov 2006)
a) Bug fix: Amended quit code so that applications quit cleanly without leaving files open.
b) Added "prequitapp" command, to send a wimp 'pre-quit' message to specific
applications.
c) Added new misc timer function - run bath, with a 9 minute delay.
d) Bug fix: Corrected format of auto-email generation for the Ant Suite.
v0.07 (13th Sep 2006)
a) Amended logging to use SysLog if available, otherwise falling back to Wimp$Scrap.
b) Edited !Run file slightly to improve ABCLib detection.
v0.06 (26th Jun 2006)
a) Fixed a few spelling mistakes and discrepancies in the manual.
b) Amended 'every' and 'after' code so that simultaneous events don't clash with
each other.
c) Improved logging of FTP events.
d) Added support for ---- to represent immediate events (as well as -1-1)
e) Added Tools->Log->Show to menu, to open logfile.
f) Added new Tools->Show sub-menu.
g) Added FAQ section to manual.
h) Added 'Memo' facility.
i) Added 'Tea' easter egg. ;-)
j) Adjusted wimp_poll timing slightly.
k) Added 'screensave' and 'nextslot' commands.
v0.05 (23rd Jun 2006)
First version - should be all working ok.
©2006-7 Paul Vigay