CyberCron

                Copyright © 1992 by Christopher A. Wichura
                           All rights reserved.

                        e-mail: caw@miroc.chi.il.us
                                 BIX: caw

Legal Mumbo Jumbo
~~~~~~~~~~~~~~~~~

CyberCron is copyrighted material.  You are free to redistribute it so long
as no charge is made on its distribution, except for costs of media and/or
shipping.

In using CyberCron, you assume all liabilities for damage, loss of money,
productivity or data that may occur while CyberCron is active.  Mr.
Wichura can not and will not be held accountable.

Why another cron for the Amiga?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Because this one is meant for KickStart 2.04+ machines only!  It uses the
new System() call instead of Execute(), giving more power over the commands
run.  It also offers an extended set of options that may be specified for
any given event.  An event can be either a normal executable or an ARexx
script.  An ARexx port, based heavily on the one used in NazCron, is also
available.  CyberCron also uses file notification to determine when the
crontab has been changed.

Credits
~~~~~~~

Don Nafis, author of NazCron, from which I pretty much stole the idea for
the initial ARexx command set recognized by CyberCron.

Thomas Rokicki for a little bit of magic in the GetSystemTime() routine.

Loren Rittle for, well, many things.  He's responsible for getting me to
add the stuff needed to support writing 'at' and 'batch' UNIX like commands
(though I hope to have done it in a means general and flexible enough that
others may be able to use the event options in their own, new ways) and
writing the at.rexx and batch.rexx scripts, despite the time presure he is
under right now.  He also helped catch a number of bugs, offered little
suggestions about functionality here and there and then there's always the
__emit() trick in MySPrintfSupp() (I nearly cried when I saw it in his
ls-4.5 code --- it never dawned on me to do anything so simple :->).

Usage
~~~~~

You can start CyberCron from either the CLI or Workbench.  No Workbench
icon has been provided, however.  This is mainly for two reasons:  1) I'm a
dreadfully bad artist and could never in my wildest dreams make a nice
looking icon (if anyone wants to do it and send it to me, I'd appreciate
it) and 2) the CLI is the recommended means to start CyberCron because it
will have a CLI structure, and hence a path to propigate to the commands it
starts.

CyberCron takes the following arguments:

    CronTab <filespec>
	This specifies the crontab file to try and read.  If not specified,
	it defaults to s:CronTab

    Logfile <filespec>
	This indicates where CyberCron is to log activities.  If no
	filespec is given, logging will be turned off.

    SendMail <sendmail command and opts>
	CyberCron supports sending the output of a command it has run
	to a user via e-mail.  For this to work, however, it needs to
	know how to actually send the mail.  This command tells it
	how to do this.  If it is omitted, entries which try to specify
	output to e-mail will not have mail sent.

	The argument for this command should be in the form of

	    "<sendmail command> <from switch> %s <realname switch> *"%s*""

	For example, for AmigaUUCP's sendmail, one would use

	    "UUCP:c/SendMail -f %s -R *"%s*""

	The sendmail command __MUST__ support reading the mail file from
	its standard input, as CyberCron sets up a pipe to redirect the
	output into sendmail.  This also means that you must have PIPE:
	mounted before mail can be sent.  The sendmail command must
	also expect the To: and Subject: fields to be in the input instead
	of on the command line, and must generate the Message-ID: itself.
	AmigaUUCP's SendMail command does all this correctly.

    DefStack <stacksize>
	This is the default stack to launch executables at.  Values less
	than 2048 will be rejected.  This is ignored by ARexx events.
	If not specified, the stack size that CyberCron was started
	with will be used as the default.

    DefPriority <priority>
	The default priority to launch executables at.  Also ignored
	by ARexx events.  Defaults to 0.

    ConPri <priority>
	This is the priority CyberCron should run at.  Defaults to no
	change (i.e., it will remain at the priority it was started at).

To use these options from a Workbench icon, simply make each tooltype be in
the form of <option>=<setting>.  For example, if you wanted to specify a
logfile of T:CyberCronLog, you would have a tooltype that looked like

	LOGFILE=T:CyberCronLog

The CronTab File
~~~~~~~~~~~~~~~~

Lines in this file must be blank, a comment, or an event.  Comments are
denoted by lines that start with a "#" symbol.  Events take the form of

	min hour day month dow command <command's args, if any>

in their simplest form.  Each of min, hour, day, month and dow (day of the
week) are specifications for what range of values this command is to be run
at.  A * indicates any value is acceptable.  Numeric digits specify
specific values and can be seperated by a , (seperates distinct entries) or
a - (used to indicate a range of entries).  For example,

	* * * * * Date

would run the command date every minute of every hour of every day of every
month regardless of the day of the week.

	0 * * * * Date

is similar, but only runs the date command on the zeroth minute of each
hour.

	1,5-10,25 * * * * Date

would run the date command on minutes 1, 5, 6, 7, 8, 9, 10 and 25 of each
hour.

CyberCron also supports a number of extensions to the traditional event
format.  These may occur anywhere in the event, and are

	:NAME <name>
	The formal name this event will be known under when CyberCron is
	accessed via its ARexx port.  You may use the same name multiple
	times, but it is not recommended.

	< <filespec>
	Specify where input is to be redirected from.

	> <filespec>
	Specify where output is to be redirected.  If >> is used instead
	of >, the filespec will the appended to instead of overwritten.

	:MAILUSER <username>
	Specifies a user to send mail to with the output of the event
	that was run.  If the SENDMAIL command line option was not
	specified, this will be ignored when the event is started, and
	any output redirection specified will be used, instead.

	The username may be any e-mail address, so mail can be sent
	to both local and remote systems.  If your sendmail supports
	it, you could even specify an alias and have it send mail to
	multiple people.

	2> <filespec>
	Specify where standard error is to be redirected.  If 2>> is used
	instead of 2>, the filespec will be appended to instead of
	overwritten.

	Note that this is currently ignored by the event launcher per a
	discussion I had with Randell Jesup.  Standard error support
	wasn't really finished for 2.0, and that makes it difficult
	to support this at this time.

	:EXECONCE
	After the event has been started, remove it from the event list.

	:OBEYQUEUE <queue name>
	Select a specific queue to schedule this event under.  See the
	section on queues below for more information.

	Using this, :EXECONCE, :MAILUSER and some ARexx macros, one could
	simulate the 'at' and 'batch' commands under UNIX.  (See Loren's
	'at' stuff for an example of how.)

	:NOLOG
	If you specified a logfile then every time an event is started or
	ends a message gets sent to the log file.  This turns off logging
	for the specific event.  Handy for things one runs many, many
	times, in keeping the size of your logfile from exploding.

	:REXX
	Start this command using ARexx rather than trying to run it as a
	system call.  If the first character of the command is "`" then
	it will be started as an ARexx string rather than a command.

	:STACK <bytes>
	The stacksize to use when launching this event.  Ignored for
	ARexx events.  If the value specified is less than 2048, or this
	option is omitted, then the default stack size will be used instead.

	:PRI <priority>
	The priority to launch this event at.  Ignored for ARexx events.
	If this option is omitted then the default priority will be used.

	:CUSTOMSH <shell name>
	Use a specific custom shell when launching the event.  Ignored by
	ARexx events.

	:SYSSH
	If no custom shell is specified and this is not an ARexx event,
	CyberCron will try and launch the command using the specified
	User Shell.  If you do not want the User Shell to be used for
	a specific event, specifying this flag will cause CyberCron to
	use the system shell.

Please note that these above options are parsed with the dos.library
ReadArgs() command.  Because of this, those options which take a variable
must have whitespace between the option's keyword and its assignment.  This
generally isn't a problem, except that most people I know are used to
specifying redirection as

	>ram:foo

while the proper method for CyberCron would be

	> ram:foo

The other implication of using ReadArgs() is that quotes will be stripped
out, as will extra spaces.  To retain spaces, you must inclose the element
they proceed or follow with quotes.  For example, one might use

	date > "Ram:Two  Spaces"

To retain quotes, you will have to quote the argument as you would for
spaces, but escape a quote character withing the quoted string.  For
example.

	"This has a *" quote in it"

Job Queues and CyberCron
~~~~~~~~~~~~~~~~~~~~~~~~

CyberCron supports 26 job queues, named 'a' through 'z'.  Each queue has a
maximum number of jobs associated with it.  If an event has a queue
specified, not only must it be the appropriate time to run that event, but
the number of events currently running under that queue must be less that
the maximum allowed for the queue for the event to actually be executed.

Events that don't specify an :OBEYQUEUE argument are run under the default
queue (not included in the 26 named queues that are user accessable), which
allows an unlimited number of jobs to be executed at the same time.

All job queues are initilized with their maximum number of events to
execute set to one.  ARexx commands exist to read and change the maximum
number for specific queues.

Jobs that could not be started because the queue maximum would be exceeded
are marked as delayed.  They will be run the next time the queue is
available, regardless of whether or not their time spec matches the current
time they are up for scheduling.

Job queues were originally added to support writting ARexx scripts that
simulate the UNIX 'at' and 'batch' commands.  However, I've tried to make
the interface flexible and useful in other areas.  For example, queues can
be used to insure sequencing of events.  Make sure that the queue you will
use has its maximum set to one (which is the default for all queues).
Specify when the first job is to run.  Specify that the second job should
run one minute after the first job.  If the first job is still running when
the second comes up for scheduling, the second job will be delayed.
CyberCron will check every minute after that to see if the first job has
completed and will run the second job when it is safe.  Any number of jobs
could be sequenced together using a queue in this manner.

CyberCron's ARexx Function Host
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

CyberCron's ARexx port name is CYBERCRON.  The following commands are
supported:

	SHUTDOWN
	Causes CyberCron to quit.  Can also be accomplished by sending
	a break signal to CyberCron.  Once SHUTDOWN is started, CyberCron
	will not accept any more ARexx commands.  It may take a while
	for CyberCron to actually quit, however, because it must wait
	for any currently running events to terminate.

	VERSION
	Returns the version, revision and date of CyberCron in the form

	    <version>.<revision> (<day>.<month>.<year>)

	This is returned in the RESULT string, so you must issue an
	OPTIONS RESULTS command before you can use this command.

	SUSPEND
	Stop processing events.  File notifcation on the crontab file
	remains active, however, so changes will be processed normally.

	RESUME
	Resume processing of events.

	NEW_EVENT_FILE <filespec>
	Change the crontab file to <filespec>.  This checks to make
	sure the file actually exists before making the change.
	However, parse errors will not be noticed until the current
	crontab has been purged and CyberCron actually starts reading
	the new file.  If something goes wrong (crontab file not found
	or its name is too long) which doesn't cause the previous
	crontab file to have been purged yet then this will return
	RC_WARN (5).  If a fatal error occurs (couldn't restart
	notification on the new file) and the previous crontab has
	been purged, but the new one not read in, this will return
	RC_ERROR (10).

	CLOSE_EVENT_FILE
	Free all entries from the CronTab.  Processing of entries
	added by the ARexx ADD_EVENT command (see below) will still
	continue.  Use NEW_EVENT_FILE to read a crontab file again,
	if you so desire.

	NEW_LOG_FILE <filespec>
	Changes the logfile to <filespec>.  If an error occurs (the
	new name is too long, for example) then RC_WARN (5) will
	be returned and the old logfile, if specified, will remain
	active.

	CLOSE_LOG_FILE
	Turns off logging.  You can re-enable logging with the
	NEW_LOG_FILE command, if you so desire.

	SHOW_STATUS
	Returns a couple bits of information about CyberCron's
	status.  This is in the form of

	    <activity> <crontab filespec> <logfile filespec>

	where <activity> is either ACTIVE or SUSPENDED.

	PURGE_REXX_EVENTS
	All events added with the ARexx ADD_EVENT command (see
	below) will be purged.  Processing of entries from the
	crontab file will continue normally.

	ADD_EVENT <event>
	Adds an event to CyberCron's active list.  Use the same
	format as if you were specifying an event in a crontab
	file.  Comments are not allowed.  If an error occurs
	in parsing the event, RC_ERROR (10) will be returned.

	DELETE_REXX_EVENT <event>
	Deletes the specified event, but only if it is was added
	with the ARexx ADD_EVENT command.  See below for information
	on naming of events.  If the event was not found, RC_ERROR
	(10) will be returned.

	DELETE_EVENT <event>
	Same as DELETE_REXX_EVENT, but can be used to delete any
	event, even those read from the crontab file.

	LIST_EVENTS
	Returns a list of all the current events CyberCron is
	tracking, seperated by spaces.  Note that the events are
	listed in CyberCron's internal coding.  See below for
	more information on event name coding.  The result is returned
	in a result string, so you must use OPTIONS RESULTS before
	calling this command, or you will get an error.  If there
	are no events, then the string "<None>" is returned.  If
	an error occured, an empty string will be returned.

	SHOW_EVENT <event>
	Returns the full specification for the specified event, as
	it would be given in a crontab file, except that it will have
	the event's internal name prepended.  Note that events
	may not look exactly the same as when they were added.  This
	is because CyberCron converts events into an internalized
	structure and unconverts them when this command is called.
	If the event was not found then an empty string will be
	returned.  You must specify OPTIONS RESULTS before using
	this command, or you will get an error.

	SET_QUEUE_MAX <queue name> <max jobs executable at a time>
	Set's the maximum number of jobs that may be run under the
	specified queue at any given time.  If an illegal queue
	name is specified, RC_ERROR (10) will be returned.  Setting
	the maximum to zero is legal, and will result in no jobs
	for the specified queue being executed until such a time
	as the queue maximum is raised to greater than zero again.

	GET_QUEUE_MAX <queue name>
	Get the current maximum number of jobs that can be run
	under the specified queue at any given time.  If an
	illegal queue name is specified, -1 is returned.

CyberCron's Internal Event Naming
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

CyberCron's LIST_EVENTS command will return event names in an internalized
format.  These names are in the form of 0x???????? where ? indicates a hex
digit.  This is done so that events that have no formal name can be
specified from ARexx.  It also allows events to be specified unambigously,
which is useful if you have more than one event with the same formal name
and you wish to delete/show/etc a specific one.  To prevent naming
conflicts, CyberCron will not let you specify a formal name that begins
with the characters 0x (or 0X, as the case of the "x" doesn't matter).

When asking CyberCron to delete/show/etc an event, you can either use its
internal name, or, if it has a formal name, you may use that.  Internal
names are cumbersome to use by hand, and are impractical to handle except by
using console snap or under the control of an ARexx script.  Formal names
are much easier to deal with, which is why they are present.  If you wanted
to add a quick test event, you might give it a formal name of TestEvent and
then use that to delete it instead of having to figure out it's internal
name and then using it to delete the event.

Supplied files
~~~~~~~~~~~~~~

All source to CyberCron is included in the Source/* directory.  Please do
not redistribute changes you make.  Instead, send them to me for inclusion
in the master distribution.

The s directory contains a sample crontab file.  This is the one I am using
on my system.

The rexx directory contains two rexx scripts.  The first, CyberCron.rexx,
is what I use to start CyberCron from my user-startup and adds a few more
events which are used mainly to wake me up in the morning.  You will
definately want to modify this before attempting to use it.

The second, CCShow.rexx, is based on the NCShow.rexx script that came with
NazCron.  It will call LIST_EVENTS and if there are active events, it will
loop through the list calling SHOW_EVENT to display each one.

Also in the rexx directory you will find the files at.rexx, batch.rexx and
id.lha.  These are the files Loren Rittle sent me that implement UNIX 'at'
and 'batch' commands using CyberCron.  To use them, you need to extract the
ID: device drivers into l:, extract the mountlist entry into devs: and then
mount the ID: device.  Because of a strange bug in the id: device, you must
us something along the lines of

	type id: >nil:

before you can use the at.rexx script.  I do this as part of my
user-startup, just after the mount commamd.

Have fun and enjoy!
~~~~~~~~~~~~~~~~~~~

Christopher A. Wichura
5450 East View Park
Chicago, Il.  60615
(312)/684-2941 (evenings only, please -- I'm in the central time zone)