Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 634.lha / CyberCron_v1.3 / CyberCron.docs.pp / CyberCron.docs

Wrap

Text File | 1992-05-19 | 18.1 KB | 458 lines

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)