Almathera Ten Pack 3: CDPD 3

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

/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 076-100 / scopedisk90 / nzcron / nazcron.doc < prev next >

Wrap

Text File | 1995-03-19 | 24.7 KB | 592 lines

#1zz July 20, 1989 NazCron V1.0 - Cron type event manager Page 1 Overview -------- NazCron executes CLI commands and programs that can be started from a CLI at those times you specify in an event list. This event list is a memory resident list that can be loaded from the file named CRONTAB located in the S: directory and/or from ARexx scripts. Every minute, NazCron examines the file timestamp. If it has changed in the last minute it reloads the event list from the CRONTAB file. NazCron then searches the event list for all commands that need to be executed, executes each such command and then issues a timer request to be re-activated a minute later. NazCron accepts the Unix Cron file format (see below) with minor improvements, establishes itself as an ARexx host process and operates in the background by disconnecting itself from the initiating CLI. A number of functions are controlled through the ARexx interface asynchronously to event timing, i.e all such functions are executed as soon as the initiating ARexx command message is retrieved from the public message port. NazCron is a redesign and rewrite of an Amiga public domain program called AmiCron which, in turn, is an Amiga version of the Unix program Cron. Written by ---------- Don Nafis NazCron may be copied and freely distributed for personal use. NazCron is shareware, user-supported software. If you like NazCron and continue to use it after a trial period, please send the $10 shareware fee to the address listed on the following page and become a registered user. As a registered user, you will be assured of timely information on upgrades, you will be given membership in the support section of our BBS, Viva! Amiga!, and you will feel good about contributing to the development of new utility programs for the Amiga. By supporting all shareware authors, you will be in the driver's seat when it comes to deciding where future Amiga programs will be going; you will have a loud voice when we programmers are trying to hear what Amiga owners want in programs of the future. Copyright 1989 by Don Nafis and Nazlo Associates Ltd. All rights reserved. z July 20, 1989 NazCron V1.0 - Cron type event manager Page 2 Send your check for $10.00 to Don Nafis Nazlo Associates Ltd. P.O. Box 1515 Laurel Springs, NJ 08021 Please make your check payable to "Nazlo Associates Ltd.". Commercial vendors may distribute NazCron with their products as long as they distribute all files provided here and make it clear that NazCron is shareware. Before distributing NazCron with your package, you must send for written permission. This way I can make sure that you will be distributing the latest version. If you find this program lacking in any way and thus choose not to register, I would like to hear your suggestions or complaints. Please contact me at one of the following and give me a piece of your mind: Nazlo Associates Ltd. P.O. Box 1515 Laurel Springs, NJ 08021 (609) 228-8088 Voice (609) 227-8278 BBS - Viva! Amiga! 3/12/24 - 8/N/1 - 24 hours 130 Megabytes Online Compuserve 70656, 133 Usage ----- From the CLI, type: NazCron<cr> NazCron detaches itself from the initiating CLI as soon as it begins execution. Thus you can terminate the CLI, endcli, and let NazCron go on working in the background. From the Workbench: Place the pointer on the NazCron Icon and double click with the left mouse button. Copyright 1989 by Don Nafis and Nazlo Associates Ltd. All rights reserved. z July 20, 1989 NazCron V1.0 - Cron type event manager Page 3 You will see no evidence that NazCron has begun executing in either case unless you have a command in your CRONTAB that sends a message to the console. Should you panic and start NazCron again, either from the CLI or Workbench, NazCron will detect that there is a version already started and retire gracefully with no harm done. NazCron begins execution by loading the event list from the file CRONTAB located in the S: directory. (See below for the CRONTAB file format.) If CRONTAB is not present, NazCron simply waits for further instruction through its ARexx port. Since NazCron doesn't need ARexx to run, it makes no attempt to determine if ARexx is installed on the system. Therefore you need not start REXXMAST before you start NazCron. If you have neither a CRONTAB file in the S: directory nor ARexx, you will simply waste memory by starting the program because you will be handling no events and you have no way of terminating NazCron. Note that in order to detach itself completely from the initiating CLI, NazCron must open a zero length file named "ram:*". This is a kludge to get around a quirk in "nil:" file handling in the Execute() function of AmigaDos (no relation to the AmigaDOS Execute command in the C: directory). This file will do no harm and, after terminating NazCron, you may delete the it with no ill effects. CRONTAB event format -------------------- The CRONTAB file is an ASCII text file which you must create with a text editor and place in the S: directory. Each entry in the CRONTAB file is either a comment or a event. Each entry must begin in column 1 with the individual parameters separated by "white space", i.e. one or more spaces or tabs. The entry format is: ; comment - or - [eventname] min hour day month weekday eventcommand Where: [eventname] - an optional name you can supply which identifies the event for ARexx processing. If you don't supply a name, the event will be invisible to ARexx scripts. "eventname" must begin with an alpha character. You can specify as many events as you wish with the same eventname, Copyright 1989 by Don Nafis and Nazlo Associates Ltd. All rights reserved. z July 20, 1989 NazCron V1.0 - Cron type event manager Page 4 but ARexx commands that use "eventname" will only affect the first event encountered, so it doesn't make any sense to do so. Since "eventname" is not used for actual event processing, each identically named event will be processed. Note, "eventname" is not case sensitive, NazCron converts all event names to uppercase before adding them to the event list. Thus "ImportantEvent" and "IMPORTANTEVENT" are the same eventnames for NazCron purposes. The remainder of the fields are required. min - the minute at which "eventcommand" will be executed. Code the actual minute, minutes, range of minutes or "*" to indicate every minute. The numeric values may be provided as: a single minute, e.g. 5 a group of minutes, e.g. 0,10,20,30 a range of minutes, e.g. 30-45 or a combination, e.g. 0,10,30,47-50,59 hour, day, month and weekday - use the same format as "min". Ranges of time values are: min: 0-59 hour: 0-23 (0 = midnight) day: 1-31 (day is not checked for month. This means that day 31, month 2 will be allowed but, of course, never executed) month: 1-12 weekday: 0-6 (0=Sunday, 6=Saturday) eventcommand - is the AmigaDOS CLI command to be executed. It must contain all parameters as if typed from a CLI. Note that there will be no CLI window for this command's output. If you wish to see the output, you must use redirection when you type the command. Example: Date >ram:date Redirection is indicated by the ">" character. Output that would normally be sent to the CLI window for this command would, instead, be sent to the file ram:date. Cron event examples ------------------- * * * * * Date Executes the ADOS Date command every minute. Since re- direction was not specified in the command, you will see no Copyright 1989 by Don Nafis and Nazlo Associates Ltd. All rights reserved. z July 20, 1989 NazCron V1.0 - Cron type event manager Page 5 evidence that Date was actually executed. DateToRam * * * * * Date >ram:date Also executes the ADOS Date command every minute but the date is written to the file "date" on the ram: disk. Note, "DateToRam" is the event name for this event, allowing it to be manipulated from an ARexx script. 0 19 * * * NewShell "newcon:0/30/640/30/BIX Time" from s:Bixtime At 7pm every day, a shell will be opened, initially executing the startup script "Bixtime" from the S: directory. This script is probably a reminder that it is now ok to logon to BIX for non-prime time access. The script "Bixtime" might look something like: echo "It is 7pm. It is now ok to logon to BIX" wait 10 endcli 0 10 * * 6 Access! Every Saturday at 10am, NazCron will initiate the terminal program Access! 0 0,12,17 * * 1-5 Execute ChangingOfTheGuard The script "ChangingOfTheGuard" will be executed at midnight, noon and 5pm every Monday through Friday. ARexx command processing ------------------------ NazCron supports a rich body of commands that may be introduced from ARexx scripts or other ARexx interfaced programs. In order to send these commands to NazCron, the ARexx script must execute the ARexx "address NAZCRON" statement prior to sending any NazCron commands. "NAZCRON" (note that this MUST be uppercase) is the NazCron ARexx host address and must be the current host when any NazCron command is invoked. Consult the ARexx manual for further information on communicating with ARexx host processes. The return code settings for all commands will be the standard ARexx values as defined in the ARexx supplied header file "errors.h". These values are: RC_OK = 0 RC_WARN = 5 RC_ERROR = 10 RC_FATAL = 20 NazCron returns RC_OK when execution has completed successfully Copyright 1989 by Don Nafis and Nazlo Associates Ltd. All rights reserved. z July 20, 1989 NazCron V1.0 - Cron type event manager Page 6 and RC_WARN when a secondary result should have been returned from the command but the script did not execute the 'options results' statement. RC_ERROR is returned for most errors including unrecognized command and errors in command syntax. RC_FATAL is returned when NazCron is unable to allocate enough memory to return the secondary result, or if a command is received after shutdown is under way. Individual NazCron ARexx commands --------------------------------- SHUTDOWN Terminates NazCron immediately. All outstanding events are purged and the timer is stopped. No events will be executed after SHUTDOWN is received, even if a timeout was about to occur. SUSPEND All event processing will be stopped until a RESUME is sent. NazCron will stop looking at events in the event list and will ignore the CRONTAB file, even if the file has been modified. All ARexx commands may be executed and events in the event list may still be manipulated with ARexx commands. RESUME Resumes all event processing. LOCK_EVENTS This locks file events in the event list. Normally, the CRONTAB file info block is examined each minute to determine if the contents of the file have changed. If the file timestamp is different from the timestamp recorded the last time the file was loaded, all events loaded from the file are purged from the event list and the file is reloaded into the event list. CRONTAB date checking is NOT done when events are locked. If you are processing a CRONTAB file that never changes, you can LOCK_EVENTS, thereby eliminating the unnecessary overhead of examining the CRONTAB file each minute. Events may still be added or deleted from the event list via ARexx commands; only the CRONTAB events are locked. UNLOCK_EVENTS This unlocks the file events in the event list. After this command is executed, the CRONTAB file will be examined again each minute. NEW_EVENT_FILE filename "filename" must be the full path/file name of a new CRONTAB file. NazCron begins processing from the new file Copyright 1989 by Don Nafis and Nazlo Associates Ltd. All rights reserved. z July 20, 1989 NazCron V1.0 - Cron type event manager Page 7 immediately. If events are "locked" (see LOCK_EVENTS above) "filename" will be the file to be used once events have been unlocked again. Note that it is not necessary to issue CLOSE_EVENT_FILE prior to opening a new file. Caution: while NazCron assures that the file exists before doing the switch, it does not verify the contents of the file. Consequently, the command may return with a successful execution masking an error in the contents of the file. If there is a syntax error in the new file, all file events will be purged. CLOSE_EVENT_FILE Purges all events previously loaded from the event file and stops examining the file. Only ARexx introduced events will be processed until the NEW_EVENT_FILE command is executed. ADD_EVENT cronevent Adds "cronevent" to the event list. "cronevent" must be in the same format as defined above. Note that if "eventname" is not supplied, the event will be invisible to most ARexx commands. DELETE_REXX_EVENT eventname Deletes the event with "eventname" from the event list only if the event was added from an ARexx script. This command may not be used to delete a CRONTAB event. If the event doesn't exist, RC_ERROR is set. If there are more than one ARexx event in the event list with the same "eventname", only the first one in the list will be deleted. DELETE_EVENT eventname Deletes any event with "eventname" from the event list. If the event doesn't exist, RC_ERROR is set. If there are more than one event in the event list with the same "eventname", only the first one in the list will be deleted. PURGE_REXX_EVENTS Deletes all ARexx introduced events from the event list, even those that are invisible. Events loaded from CRONTAB will remain in the list untouched. SHOW_EVENT eventname Returns the actual ASCII cronevent string in the 'result' variable for the event named "eventname". If the event doesn't exist, RC_ERROR is set. Both ARexx and CRONTAB introduced events may be retrieved. If there are more than one event in the event list with the same "eventname", only the first one in the list will be returned. LIST_EVENTS Copyright 1989 by Don Nafis and Nazlo Associates Ltd. All rights reserved. z July 20, 1989 NazCron V1.0 - Cron type event manager Page 8 Returns the eventnames of all named events in the event list as a string of names separated by blanks. If there are more than one event in the event list with the same "eventname", all will be returned. Note, this command makes no differentiation between events introduced by ARexx commands and CRONTAB loaded events. SHOW_STATUS Returns the status of NazCron. The format of the returned message is: eventstate filestate cronfilename where "eventstate" is either "ACTIVE" or "SUSPENDED", "filestate" is either "LOCKED" or "UNLOCKED", and "cronfilename" is the full path name of the current event file. NazCron ARexx script example ---------------------------- /* NazCron ARexx script example*/ /* Make sure we send all of our commands to NazCron */ address 'NAZCRON' /* Don't bother looking at the file again, it will not change */ 'LOCK_EVENTS' 'ADD_EVENT sidevent 48 15 * * * dh1:sid' if (rc ~= 0) then say "ADD_EVENT error "|| rc 'ADD_EVENT myevent * * * * * date >ram:rexxcron.date' if (rc ~= 0) then say "ADD_EVENT error "|| rc 'ADD_EVENT anotherevent * * * * * date >ram:anotherrexxcron.date' if (rc ~= 0) then say "ADD_EVENT error "|| rc /* Get a list of all named events */ options results 'LIST_EVENTS' if (rc ~= 0) then say "LIST_EVENTS error " || rc else do eventlist = result /* display the names */ say eventlist numwords = words(eventlist) /* If the list isn't empty, display the event connected with Copyright 1989 by Don Nafis and Nazlo Associates Ltd. All rights reserved. z July 20, 1989 NazCron V1.0 - Cron type event manager Page 9 each name */ if numwords > 0 then do do j=1 to numwords event = word(eventlist,j) 'SHOW_EVENT '|| event if (rc = 0) then say 'Event: ' || event || ', ' || result else say 'Event: ' || event || ' not found.' end end end Historical notes ---------------- A short while ago, I stumbled on and installed a copy of AmiCron to help with unattended maintenance on our BBS, Viva! Amiga! While AmiCron was serviceable, and did pretty much what we wanted, there was the problem of it requiring a CLI window. With the AmiCron window up 24 hours a day amidst lots of activity, it was very easy to type a character into the window by mistake, thus freezing AmiCron; it would simply stop working until I noticed the stray characters and backspaced them out. This problem, and my fumble fingers, led to too many missed events. Since Rick Schaeffer and Christian Balzar, AmiCron authors, were kind enough to include source with the package, I decided to remove the CLI requirement by using the Lattice 5.0 startup routine CBack.o. On perusing the source, I discovered other things about AmiCron that, I felt, could be improved. AmiCron woke up every minute, opened the CRONTAB file, read all of the records to execute any commands that were due, closed the file and went back to sleep. The process of sleeping for a minute also required some unnecessary I/O. It would create a message port, allocate an EXTIO block, open the timer device, go to sleep, wake up, close the timer device, free the EXTIO block and delete the message port. It went through all of these steps every minute. With the thought to make improvements to some of this code, I began to modify the source. I hadn't edited too many lines before I realized that I really had to redesign the thing to do what I wanted. The timer routines have been simplified, eliminating the DoIO which waited for the timer to complete. Instead NazCron does a SendIO and the wait for timer completion occurs in a central loop in "main". In fact, I lifted this code from a commercial program we are developing. With this done, I was able to fold in Arexx command handling so that the resulting program is an ARexx host. The timer request is allocated once when the program starts so that each minute the timer functions simply compute the next Copyright 1989 by Don Nafis and Nazlo Associates Ltd. All rights reserved. z July 20, 1989 NazCron V1.0 - Cron type event manager Page 10 timeout period and issue another SendIO. A bigger change involves the actual handling of the events themselves. NazCron reads the CRONTAB file on startup, loads the events into Exec Node structures and chains them in a List. Each time NazCron wakes up, it locks the current CRONTAB file, examines the FileInfoBlock structure to determine, via timestamp, if the file has changed since it was last loaded. If it has, all events previously loaded from the CRONTAB file are deleted from the list and the file is reread and loaded back into memory with any changes that were made to the file. If the timestamp was not changed, no more file accesses are necessary. The list is then scanned for events to be executed. Of course, ARexx handling was not present at all in the original program. NazCron was my first attempt to make useful ARexx functions available in a program. My initial design included a small number of commands, but as I began programming, I couldn't help but add virtually everything I could think of. It was easy to do. Surprisingly, with all of the new code for event list handling, ARexx commands and new file I/O, the resulting program size is about 1500 bytes SMALLER than the AmiCron program it replaces. Most of the decrease is probably attributable to the fact that I Amiga-tized it, the rest to the superb Lattice 5.0 optimization algorithms. NazCron has no remaining traces of portability, so don't expect to see it on your local GS or COCO real soon now. Thanks to: ---------- Lattice for the great 5.0 package - especially CPR, Bill Hawes for ARexx, Eric Lavitsky for his well structured and information-packed Amiga programming course, Rick Schaeffer and Christian Balzar for the original AmiCron, Jay Miner (and friends) for the Amiga and My family for putting up with me programming while they baked their brains out on the beach. I wouldn't have written this program without you guys. Copyright 1989 by Don Nafis and Nazlo Associates Ltd. All rights reserved. c