home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 321.lha / NazCron_v1.02 / NazCron.doc < prev    next >
Encoding:
Text File  |  1989-12-11  |  36.6 KB  |  988 lines

  1. #1zz
  2.  
  3.  
  4.  
  5.  
  6.  
  7.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager        Page 1
  8.  
  9.  
  10.      Overview
  11.      --------
  12.  
  13.         NazCron automatically executes CLI commands and programs that can
  14.         be started from a CLI at those times you specify in an event list. 
  15.         This event list is a memory resident list that NazCron loads from
  16.         the ASCII text file named CRONTAB located in the S: directory
  17.         and/or from ARexx scripts.  Any additions, deletions or changes you
  18.         make to the events in the CRONTAB file will be automatically
  19.         incorporated in NazCron's memory list.
  20.  
  21.         NazCron accepts the Unix Cron file format (see below for details)
  22.         with minor improvements, establishes itself as an ARexx host
  23.         process which can be used as a generalized time server and operates
  24.         in the background by disconnecting itself from its initiating CLI.
  25.  
  26.         A number of internal functions may be controlled through the ARexx
  27.         interface asynchronously to event timing, i.e. all such functions
  28.         are executed as soon as the initiating ARexx command message is
  29.         retrieved from the public message port. 
  30.  
  31.         Please note that NazCron does NOT require ARexx to run.  The ARexx
  32.         functions serve as an extension to NazCron's CRON functions, which
  33.         are complete in themselves.  
  34.  
  35.  
  36.      Written by 
  37.      ---------- 
  38.  
  39.         Don Nafis of NAZLO Associates Ltd. 
  40.  
  41.         NazCron may be copied and freely distributed for personal use.
  42.  
  43.         NazCron is shareware, user-supported software.  If you like
  44.         NazCron and continue to use it after a trial period, please send
  45.         the $10 shareware fee to the address listed on the following page
  46.         and become a registered user.  When you register, I will send you
  47.         the latest registered version of NazCron.  
  48.  
  49.         In addition, as a registered user, you will be assured of timely
  50.         information on upgrades, you will be given membership in the
  51.         support section of our BBS, Viva! Amiga!, and you will feel good
  52.         about contributing to the development of new utility programs for
  53.         the Amiga.  
  54.  
  55.         By supporting all shareware authors, you will be in the driver's
  56.         seat when it comes to deciding where future Amiga programs will be
  57.         going; you will have a loud voice when we programmers are trying to
  58.         hear what Amiga owners want in programs of the future. 
  59.  
  60.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  61.  
  62.  
  63.  
  64.  
  65.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager        Page 2
  66.  
  67.  
  68.         To register as a NazCron user, send your check for $10.00 to
  69.  
  70.             Don Nafis
  71.             Nazlo Associates Ltd.
  72.             P.O. Box 1515
  73.             Laurel Springs, NJ  08021
  74.  
  75.         Please make your check payable to "Nazlo Associates Ltd.".
  76.  
  77.  
  78.         Commercial vendors may distribute NazCron with their products only
  79.         if they distribute all files provided here and make it clear that
  80.         NazCron is shareware.  Before distributing NazCron with your
  81.         package, you must obtain written permission from Nazlo Associates
  82.         Ltd.  This way we can make sure that you will be distributing the
  83.         latest version.
  84.  
  85.  
  86.         If you find this program lacking in any way and thus choose not to
  87.         register, I would like to hear your suggestions or complaints.  
  88.  
  89.  
  90.         Please contact me at one of the following and give me a piece of
  91.         your mind:
  92.  
  93.  
  94.             Nazlo Associates Ltd.
  95.             P.O. Box 1515
  96.             Laurel Springs, NJ  08021
  97.  
  98.             (609) 228-8088 Voice
  99.  
  100.  
  101.             (609) 227-8278 BBS -
  102.                                Viva! Amiga!
  103.                          3/12/24 - 8/N/1 - 24 hours
  104.                             130 Megabytes Online
  105.  
  106.  
  107.             Compuserve 70656, 133
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  119.  
  120.  
  121.  
  122.  
  123.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager        Page 3
  124.  
  125.  
  126.      Usage
  127.      -----
  128.  
  129.         From the CLI, type:
  130.  
  131.             NazCron<cr>
  132.  
  133.         NazCron detaches itself from the initiating CLI when it begins
  134.         execution.  Thus you can terminate the CLI (endcli) and let
  135.         NazCron go on working in the background. 
  136.  
  137.         From the Workbench:
  138.  
  139.             Place the pointer on the NazCron Icon and double click with
  140.             the left mouse button.
  141.  
  142.         Un-registered users:
  143.  
  144.             If you are using the un-registered version of NazCron, you will
  145.             see a shareware reminder message in a small window.  This is to
  146.             remind you that NazCron is shareware, that the shareware fee is
  147.             $10 and where to send your check.  After the reminder has
  148.             displayed for 5 seconds, you must click the left mouse button
  149.             in the window to continue.  NazCron will delay all further
  150.             processing until you click in the window.  A similar reminder
  151.             window will display every time you modify the CRONTAB file or
  152.             tell NazCron to use a new file and it will display every hour
  153.             after loading an event file.  This periodic reminder will
  154.             disappear by itself after a 5 second pause.  It does NOT
  155.             require intervention on your part.  Note - this hourly reminder
  156.             will display after NazCron launches any events that time out
  157.             during the same minute, thus it will not affect your event
  158.             timing. 
  159.  
  160.         Registered users:
  161.  
  162.             Registered users will not see the reminder window.  Also, the
  163.             registered version is smaller.
  164.       
  165.  
  166.         NazCron starts by loading the event list from the file CRONTAB
  167.         located in the S: directory.  (See below for the CRONTAB file
  168.         format.)  If CRONTAB is not present, NazCron simply waits for
  169.         further instruction through its ARexx port.  Since NazCron doesn't
  170.         require ARexx to run, it makes no attempt to determine if ARexx is
  171.         installed on the system.  Therefore you need not start REXXMAST
  172.         before you start NazCron.  If you have neither a CRONTAB file in
  173.         the S: directory nor ARexx, you will simply waste memory by
  174.         starting the program because you will be handling no events and you
  175.  
  176.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  177.  
  178.  
  179.  
  180.  
  181.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager        Page 4
  182.  
  183.  
  184.         have no way of terminating NazCron.
  185.  
  186.         If you attempt to execute NazCron when NazCron is already running,
  187.         it will display a small status window showing you the name of the
  188.         current crontab file, whether event processing is ACTIVE or
  189.         SUSPENDED and whether the crontab file is LOCKED or UNLOCKED. If
  190.         there is no CRONTAB file active, the string
  191.  
  192.             <<no-CRONTAB-active>>
  193.  
  194.         will be displayed.  See the ARexx section below for a complete
  195.         discussion of the meaning of these terms.  You may show the status
  196.         of the executing NazCron from the CLI or from WorkBench.  
  197.  
  198.             Note: the status window will stay on the WorkBench screen until
  199.             you click the left mouse button anywhere within the window or
  200.             press any key on the keyboard, assuming that you didn't
  201.             activate some other window after the status window was
  202.             displayed.
  203.  
  204.         In order to detach itself completely from the initiating CLI,
  205.         NazCron must open a zero length file named "ram:*".  This is a
  206.         kludge to get around a quirk in "nil:" file handling in the
  207.         Execute() function of AmigaDos (no relation to the AmigaDOS Execute
  208.         command in the C: directory).  This file will do no harm and, after
  209.         terminating NazCron, you may delete it with no ill effects.
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  235.  
  236.  
  237.  
  238.  
  239.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager        Page 5
  240.  
  241.  
  242.      CRONTAB event format
  243.      --------------------
  244.  
  245.         The CRONTAB file is an ASCII text file which you must create with
  246.         a text editor and place in the S: directory.  Each entry in the
  247.         CRONTAB file is either a comment or an event.  Each entry must
  248.         begin in column 1 with the individual parameters separated by
  249.         "white space", i.e. one or more spaces or tabs.
  250.  
  251.         The entry format is:
  252.  
  253.             ; comment
  254.               - or -
  255.             [eventname] min hour day month weekday eventcommand
  256.  
  257.         Where:
  258.  
  259.             [eventname] - an optional name you can supply which identifies
  260.             the event for ARexx processing.  If you don't supply a name,
  261.             the event will be invisible to ARexx scripts.  "eventname" must
  262.             begin with an alpha character.  You can specify as many events
  263.             as you wish with the same eventname, but ARexx commands that
  264.             use "eventname" will only affect the first event encountered,
  265.             so it doesn't make any sense to do so.  Since "eventname" is
  266.             not used for actual event processing, each identically named
  267.             event will be processed.  Note, "eventname" is not case
  268.             sensitive, NazCron converts all event names to uppercase before
  269.             adding them to the event list.  Thus "ImportantEvent" and
  270.             "IMPORTANTEVENT" are the same eventnames for NazCron purposes.
  271.       
  272.             The remainder of the fields are required.
  273.  
  274.             min - the minute at which "eventcommand" will be executed. 
  275.             Code the actual minute, minutes, range of minutes or "*" to
  276.             indicate every minute.  The numeric values may be provided as:
  277.                 a single minute, e.g. 5 
  278.                 a group of minutes, e.g. 0,10,20,30  
  279.                 a range of minutes, e.g. 30-45 
  280.                 or a combination, e.g. 0,10,30,47-50,59
  281.  
  282.             hour, day, month and weekday - use the same format as "min".
  283.  
  284.                 Ranges of time values are:
  285.                     min:                0-59
  286.                     hour:               0-23 (0 = midnight)
  287.                     day:                1-31 (day is not checked for
  288.                                         month. This means that day 31,
  289.                                         month 2 will be allowed but, of
  290.                                         course, never executed)
  291.  
  292.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  293.  
  294.  
  295.  
  296.  
  297.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager        Page 6
  298.  
  299.  
  300.                     month:              1-12
  301.                     weekday:            0-6 (0=Sunday, 6=Saturday)
  302.  
  303.  
  304.             eventcommand - is the AmigaDOS CLI command to be executed.  It
  305.             must contain all parameters as if typed from a CLI. Note that
  306.             there will be no CLI window for this command's output.  If you
  307.             wish to see the output, you must use redirection when you type
  308.             the command.
  309.  
  310.             Examples of redirection:
  311.  
  312.                 Date >ram:date
  313.                 Date >"newcon:0/10/640/50/Here is the date"
  314.                 Date >prt:
  315.  
  316.             Redirection is indicated by the ">" character.  Output that
  317.             would normally be sent to the CLI window for these commands
  318.             would, instead, be sent to the file ram:date, to a new window
  319.             and to the printer.
  320.  
  321.  
  322.      Cron event examples
  323.      -------------------
  324.  
  325.         * * * * * Date
  326.             Executes the ADOS Date command every minute.  Since re-
  327.             direction was not specified in the command, you will see no
  328.             evidence that Date was actually executed.
  329.  
  330.         DateToRam * * * * * Date >ram:date
  331.             Also executes the ADOS Date command every minute but the date
  332.             is written to the file "date" on the ram: disk.  Note,
  333.             "DateToRam" is the event name for this event, allowing it to
  334.             be manipulated from an ARexx script.
  335.  
  336.         0 19 * * * NewShell "newcon:0/30/640/30/BIX Time" from s:Bixtime
  337.             At 7pm every day, a shell will be opened, initially executing
  338.             the startup script "Bixtime" from the S: directory.  This
  339.             script is probably a reminder that it is now ok to logon to BIX
  340.             for non-prime time access.  The script "Bixtime" might look
  341.             something like:
  342.                 echo "It is 7pm.  It is now ok to logon to BIX"
  343.                 wait 10
  344.                 endcli
  345.  
  346.         0 10 * * 6 Access!
  347.             Every Saturday at 10am, NazCron will initiate the terminal
  348.             program Access! 
  349.  
  350.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  351.  
  352.  
  353.  
  354.  
  355.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager        Page 7
  356.  
  357.  
  358.  
  359.         0 0,12,17 * * 1-5 Execute ChangingOfTheGuard
  360.             The script "ChangingOfTheGuard" will be executed at midnight,
  361.             noon and 5pm every Monday through Friday. 
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  409.  
  410.  
  411.  
  412.  
  413.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager        Page 8
  414.  
  415.  
  416.      ARexx command processing
  417.      ------------------------
  418.  
  419.         NazCron supports a rich body of commands that may be introduced
  420.         from ARexx scripts or other ARexx interfaced programs.  In order
  421.         to send these commands to NazCron, the ARexx script must execute
  422.         the ARexx "address NAZCRON" statement prior to sending any NazCron
  423.         commands.  "NAZCRON" (note that this MUST be uppercase) is the
  424.         NazCron ARexx host address and must be the current host when any
  425.         NazCron command is invoked.  Consult the ARexx manual for further
  426.         information on communicating with ARexx host processes.  
  427.  
  428.         The return code settings for all commands will be the standard
  429.         ARexx values as defined in the ARexx supplied header file
  430.         "errors.h".  These values are:
  431.  
  432.             RC_OK    = 0  
  433.             RC_WARN  = 5
  434.             RC_ERROR = 10
  435.             RC_FATAL = 20
  436.  
  437.         NazCron returns RC_OK when execution has completed successfully
  438.         and RC_WARN when a secondary result should have been returned from
  439.         the command but the script did not execute the 'options results'
  440.         statement.  RC_ERROR is returned for most errors including
  441.         unrecognized command and errors in command syntax.  RC_FATAL is
  442.         returned when NazCron is unable to allocate enough memory to return
  443.         the secondary result, or if a command is received after shutdown is
  444.         under way.
  445.  
  446.  
  447.      Individual NazCron ARexx commands
  448.      ---------------------------------
  449.  
  450.         SHUTDOWN
  451.             Terminates NazCron immediately.  All outstanding events are
  452.             purged and the timer is stopped.  No events will be executed
  453.             after SHUTDOWN is received, even if a timeout was about to
  454.             occur.
  455.       
  456.         SUSPEND
  457.             All event processing will be stopped until a RESUME is sent. 
  458.             NazCron will stop looking at events in the event list and will
  459.             ignore the CRONTAB file, even if the file has been modified. 
  460.             All ARexx commands may be executed and events in the event list
  461.             may still be manipulated with ARexx commands.
  462.  
  463.         RESUME
  464.             Resumes all event processing.
  465.  
  466.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  467.  
  468.  
  469.  
  470.  
  471.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager        Page 9
  472.  
  473.  
  474.  
  475.         LOCK_EVENTS
  476.             This locks file events in the event list.  Normally, the
  477.             CRONTAB file info block is examined each minute to determine
  478.             if the contents of the file have changed.  If the file
  479.             timestamp is different from the timestamp recorded the last
  480.             time the file was loaded, all events loaded from the file are
  481.             purged from the event list and the file is reloaded into the
  482.             event list.  
  483.  
  484.             CRONTAB file date checking is NOT done when events are locked. 
  485.             If you are processing a CRONTAB file that never changes, you
  486.             can LOCK_EVENTS, thereby eliminating the unnecessary overhead
  487.             of examining the CRONTAB file each minute.  Since NazCron will
  488.             no longer look at the CRONTAB file, you may also, after
  489.             executing LOCK_EVENTS, remove the disk containing the file. 
  490.             This command helps make NazCron useful in a floppy based
  491.             system.  Events may still be added or deleted from the event
  492.             list via ARexx commands; only the CRONTAB events are locked.
  493.  
  494.         UNLOCK_EVENTS
  495.             This unlocks the file events in the event list.  After this
  496.             command is executed, the CRONTAB file will be examined again
  497.             each minute.
  498.  
  499.         NEW_EVENT_FILE filename
  500.             "filename" must be the full path/file name of a new CRONTAB
  501.             file.  NazCron begins processing from the new file
  502.             immediately.  If events are "locked" (see LOCK_EVENTS above)
  503.             "filename" will be the file to be used once events have been
  504.             unlocked again.  Note that it is not necessary to issue
  505.             CLOSE_EVENT_FILE prior to opening a new file.  Caution:  while
  506.             NazCron assures that the file exists before doing the switch,
  507.             it does not verify the contents of the file.  Consequently, the
  508.             command may return with a successful execution masking an error
  509.             in the contents of the file.  If there is a syntax error in the
  510.             new file, all file events will be purged.  You will know that
  511.             there is no file event processing either by the fact that
  512.             events you expected to be launched weren't or by getting
  513.             NazCron status.  Make sure you test new files before relying on
  514.             them.
  515.  
  516.         CLOSE_EVENT_FILE
  517.             Purges all events previously loaded from the event file and
  518.             stops examining the file.  Only ARexx introduced events will
  519.             be processed until the NEW_EVENT_FILE command is executed.
  520.  
  521.         ADD_EVENT cronevent
  522.             Adds "cronevent" to the event list.  "cronevent" must be in
  523.  
  524.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  525.  
  526.  
  527.  
  528.  
  529.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager       Page 10
  530.  
  531.  
  532.             the same format as defined above.  Note that if "eventname" is
  533.             not supplied, the event will be invisible to most ARexx
  534.             commands.
  535.  
  536.         DELETE_REXX_EVENT eventname
  537.             Deletes the event with "eventname" from the event list only if
  538.             the event was added from an ARexx script.  This command may not
  539.             be used to delete a CRONTAB event.  If the event doesn't exist,
  540.             RC_ERROR is set.  If there are more than one ARexx event in the
  541.             event list with the same "eventname", only the first one in the
  542.             list will be deleted.
  543.  
  544.         DELETE_EVENT eventname
  545.             Deletes any event with "eventname" from the event list.  If
  546.             the event doesn't exist, RC_ERROR is set.  If there are more
  547.             than one event in the event list with the same "eventname",
  548.             only the first one in the list will be deleted.
  549.  
  550.         PURGE_REXX_EVENTS
  551.             Deletes all ARexx introduced events from the event list, even
  552.             those that are invisible.  Events loaded from CRONTAB will
  553.             remain in the list untouched.
  554.  
  555.         SHOW_EVENT eventname
  556.             Returns the actual ASCII cronevent string in the 'result'
  557.             variable for the event named "eventname".  If the event
  558.             doesn't exist, RC_ERROR is set.  Both ARexx and CRONTAB
  559.             introduced events may be retrieved.  If there are more than
  560.             one event in the event list with the same "eventname", only
  561.             the first one in the list will be returned.
  562.  
  563.         LIST_EVENTS
  564.             Returns the eventnames of all named events in the event list
  565.             as a string of names separated by blanks.  If there are more
  566.             than one event in the event list with the same "eventname",
  567.             all will be returned.  Note, this command makes no
  568.             differentiation between events introduced by ARexx commands
  569.             and CRONTAB loaded events.   
  570.  
  571.         SHOW_STATUS
  572.             Returns the status of NazCron.  The format of the returned
  573.             message is:
  574.                 eventstate filestate cronfilename
  575.             where "eventstate" is either "ACTIVE" or "SUSPENDED",     
  576.             "filestate" is either "LOCKED" or "UNLOCKED", and
  577.             "cronfilename" is the full path name of the current event
  578.             file.  If there is no CRONTAB file active, the string:
  579.                 <<no-CRONTAB-active>>
  580.             will be returned.
  581.  
  582.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  583.  
  584.  
  585.  
  586.  
  587.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager       Page 11
  588.  
  589.  
  590.  
  591.  
  592.      NazCron ARexx script example
  593.      ---------------------------- 
  594.  
  595.         /* NazCron ARexx script example*/
  596.  
  597.         /* Make sure we send all of our commands to NazCron */
  598.         address 'NAZCRON'
  599.  
  600.         /* Don't bother looking at the file again, it will not change */
  601.         'LOCK_EVENTS'
  602.  
  603.         'ADD_EVENT sidevent 48 15 * * * dh1:sid'
  604.         if (rc ~= 0) then say "ADD_EVENT error "|| rc
  605.  
  606.         'ADD_EVENT myevent * * * * * date >ram:rexxcron.date'
  607.         if (rc ~= 0) then say "ADD_EVENT error "|| rc
  608.  
  609.         'ADD_EVENT anotherevent * * * * * date >ram:anotherrexxcron.date'
  610.         if (rc ~= 0) then say "ADD_EVENT error "|| rc
  611.  
  612.         /* Get a list of all named events */
  613.         options results
  614.         'LIST_EVENTS'
  615.         if (rc ~= 0) then say "LIST_EVENTS error " || rc
  616.         else
  617.         do
  618.           eventlist = result
  619.  
  620.           /* display the names */
  621.           say eventlist
  622.           numwords = words(eventlist)
  623.  
  624.           /* If the list isn't empty, display the event connected with
  625.              each name */
  626.           if numwords > 0 then do
  627.             do j=1 to numwords
  628.               event = word(eventlist,j)
  629.               'SHOW_EVENT '|| event
  630.               if (rc = 0) then say 'Event: ' || event || ', ' || result
  631.               else say 'Event: ' || event || ' not found.'
  632.             end
  633.           end
  634.         end
  635.  
  636.  
  637.  
  638.  
  639.  
  640.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  641.  
  642.  
  643.  
  644.  
  645.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager       Page 12
  646.  
  647.  
  648.      Technical notes and suggestions
  649.      -------------------------------
  650.  
  651.  
  652.         1.  Command stack.
  653.  
  654.             Each command launched by NazCron inherits NazCron's stack.
  655.             The stack size has been hard coded by the custom NazCron
  656.             startup routine to 4k.  If the command you are executing
  657.             requires more than the standard 4k stack, you must build an
  658.             ARexx or ADOS Execute script to reset the stack size prior to
  659.             executing the command.  Have NazCron launch the script rather
  660.             than the program itself.  
  661.  
  662.             Although this might appear an arbitrary design choice, my
  663.             reasoning was that for the vast majority of time NazCron is
  664.             resident and using resources, it is doing nothing but waiting
  665.             and should be using as few resources as possible.  Since there
  666.             is an easy way through ARexx and standard ADOS to grab more
  667.             resources for launched programs that require them, it would
  668.             make more sense to tailor the stack allocation to the job to be
  669.             done through scripts rather than try to determine the maximum
  670.             stack size needed to cover all cases and have NazCron use that
  671.             value.  Note also that NazCron will not inherit the stack size
  672.             of the CLI or shell that launches it.
  673.  
  674.  
  675.         2.  Debugging.
  676.  
  677.             Should NazCron launch a command that executes with an error,
  678.             since ADOS has no console for error output, the user will be
  679.             given no information on what happened.  This is another good
  680.             reason to use scripts to launch programs.  A script can be
  681.             debugged independently of NazCron before being introduced into
  682.             a CRONTAB file or through ARexx.
  683.  
  684.             If you are still not convinced of the value of using scripts,
  685.             you can use output redirection from the command to try to
  686.             capture the results.  To repeat an example presented above:
  687.                 Date >ram:date
  688.             or
  689.                 Date >"newcon:0/10/640/50/Here is the date"
  690.             would show the output of date, although the second example
  691.             would go by too fast to be of any use.
  692.  
  693.             You could combine the two methods to record your script output
  694.             as in:
  695.                 rx >ram:backup.list backup
  696.             or
  697.  
  698.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  699.  
  700.  
  701.  
  702.  
  703.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager       Page 13
  704.  
  705.  
  706.                 execute >"newcon:0/10/640/190/Trace" backup TRACEON
  707.  
  708.             To make the second example more useful, you should probably
  709.             place a Delay() in the script prior to script termination so
  710.             that you have a chance to complete your analysis before the
  711.             window disappears.
  712.  
  713.             A future version of NazCron may have a debugging option if
  714.             there is sufficient interest.
  715.  
  716.  
  717.         3.  Launching scripts.
  718.  
  719.             Since NazCron launches all commands as though they were
  720.             executed from a CLI (using the Ados Execute() function), it can
  721.             not make use of any alias assignments you may have made in a
  722.             shell which launched NazCron.  Also, if you are using William
  723.             Hawes' WShell which executes ARexx scripts without requiring
  724.             you to type "rx" first or are executing scripts with the "S"
  725.             flags set that you normally enter as commands in the ADOS
  726.             shell, you will not be able to get NazCron to launch these
  727.             scripts the same way.  
  728.  
  729.             For ARexx scripts, you must use the "rx" command in your
  730.             command line, have the "rx" command present in your "C:"
  731.             directory and specify a script that is in your "rexx:"
  732.             directory unless you explicitly provide command and script
  733.             paths in the command line.
  734.  
  735.             The same holds true for ADOS Execute scripts.  You must
  736.             explicitly use the Execute command to launch ADOS scripts.
  737.  
  738.  
  739.         4.  Floppy based operations.
  740.  
  741.             Since NazCron uses only 15-20k, depending on the number of
  742.             events you supply in your CRONTAB, it can be quite useful even
  743.             in a 512k Amiga.  But to operate in a small system without a
  744.             hard disk could result in a lot of disk juggling on your part. 
  745.             NazCron has two features that can help you cut down on some of
  746.             that.
  747.  
  748.             Normally, NazCron wakes up every minute and Examines the file
  749.             info structure for the CRONTAB file.  To do so requires that
  750.             the CRONTAB file be available.  Thus, if you have removed a
  751.             floppy that contained the file, you will be told, by an Amiga
  752.             DOS requester, to insert it.  
  753.  
  754.             If you don't expect to change your CRONTAB file entries and you
  755.  
  756.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  757.  
  758.  
  759.  
  760.  
  761.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager       Page 14
  762.  
  763.  
  764.             are using ARexx, you may eliminate this inconvenience by using
  765.             the ARexx LOCK_EVENTS command.  After receiving the lock
  766.             request, NazCron will cease attempting to access the CRONTAB
  767.             file until you UNLOCK_EVENTS.  You may then remove the disk
  768.             that contained the CRONTAB file since all of the events will be
  769.             in memory.
  770.  
  771.             You must remember, though, to have the disks with the actual
  772.             event commands and programs mounted at the time NazCron tries
  773.             to launch them.
  774.  
  775.             If you have extra memory, you might want to move your CRONTAB
  776.             and the commands you want executed to Ram:.  Make sure that
  777.             your the command strings in the events specify ram: as below:
  778.  
  779.                 ram:Access!
  780.  
  781.             You must also tell NazCron that you do not want to use the
  782.             S:CRONTAB file.  Do this by sending the ARexx command
  783.             NEW_EVENT_FILE.  NazCron will switch to the new file upon
  784.             receiving it.
  785.  
  786.             The NC.rexx script is an easy way to send commands to NazCron. 
  787.             You would execute the following from a CLI or shell:
  788.  
  789.                 rx nc NEW_EVENT_FILE ram:neweventfile
  790.  
  791.             or to lock the original CRONTAB:
  792.  
  793.                 rx nc LOCK_EVENTS
  794.  
  795.  
  796.         5.  ARexx time server.
  797.  
  798.             NazCron may be used as an ARexx time server and told to ignore
  799.             any CRONTAB file events.  To do so, send NazCron the
  800.             CLOSE_EVENT_FILE ARexx command.  NazCron's events may now only
  801.             come from ARexx.  You may then use ARexx to add events, delete
  802.             individual events, purge all events or shutdown NazCron.  You
  803.             may obtain the names of all active events and retrieve the
  804.             entire event strings themselves.  
  805.  
  806.             The only thing you can not do with this version is to pass
  807.             ARexx commands, through NazCron, to other ARexx processes.  You
  808.             can, though, direct NazCron to start other ARexx scripts which
  809.             do so.
  810.  
  811.  
  812.  
  813.  
  814.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  815.  
  816.  
  817.  
  818.  
  819.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager       Page 15
  820.  
  821.  
  822.      Historical notes                    
  823.      ----------------
  824.  
  825.         A number of months ago, I stumbled on and installed a copy of
  826.         AmiCron to help with unattended maintenance on our BBS, Viva!
  827.         Amiga! While AmiCron was serviceable, and did pretty much what we
  828.         wanted, there was the problem of it requiring a CLI window.  With
  829.         the AmiCron window up 24 hours a day amidst lots of activity, it
  830.         was very easy to type a character into the window by mistake, thus
  831.         freezing AmiCron; it would simply stop working until I noticed the
  832.         stray characters and backspaced them out.  This problem, and my
  833.         fumble fingers, led to too many missed events.  Since Rick
  834.         Schaeffer and Christian Balzar, AmiCron authors, were kind enough
  835.         to include source with the package, I decided to remove the CLI
  836.         requirement by using the Lattice 5.0 startup routine CBack.o.  On
  837.         perusing the source, I discovered other things about AmiCron that,
  838.         I felt, could be improved.  
  839.  
  840.         AmiCron woke up every minute, opened the CRONTAB file, read all of
  841.         the records to execute any commands that were due, closed the file
  842.         and went back to sleep.  The process of sleeping for a minute also
  843.         required some unnecessary I/O.  It would create a message port,
  844.         allocate an EXTIO block, open the timer device, go to sleep, wake
  845.         up, close the timer device, free the EXTIO block and delete the
  846.         message port.  It went through all of these steps every minute. 
  847.         With the thought to make improvements to some of this code, I began
  848.         to modify the source.  I hadn't edited too many lines before I
  849.         realized that I really had to redesign the thing to do what I
  850.         wanted.
  851.  
  852.         The timer routines have been simplified, eliminating the DoIO
  853.         which waited for the timer to complete.  Instead NazCron does a
  854.         SendIO and the wait for timer completion occurs in a central loop
  855.         in "main".  In fact, I lifted this code from a commercial program
  856.         we are developing.  With this done, I was able to fold in Arexx
  857.         command handling so that the resulting program is an ARexx host. 
  858.         The timer request is allocated once when the program starts so
  859.         that each minute the timer functions simply compute the next
  860.         timeout period and issue another SendIO.
  861.  
  862.         A bigger change involves the actual handling of the events
  863.         themselves.  NazCron reads the CRONTAB file on startup, loads the
  864.         events into Exec Node structures and chains them in a List.  Each
  865.         time NazCron wakes up, it locks the current CRONTAB file, examines
  866.         the FileInfoBlock structure to determine, via timestamp, if the
  867.         file has changed since it was last loaded.  If it has, all events
  868.         previously loaded from the CRONTAB file are deleted from the list
  869.         and the file is reread and loaded back into memory with any changes
  870.         that were made to the file.  If the timestamp was not changed, no
  871.  
  872.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  873.  
  874.  
  875.  
  876.  
  877.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager       Page 16
  878.  
  879.  
  880.         more file accesses are necessary.  The list is then scanned for
  881.         events to be executed.
  882.  
  883.         Of course, ARexx handling was not present at all in the original
  884.         program.  NazCron was my first attempt to make useful ARexx
  885.         functions available in a program.  My initial design included a
  886.         small number of commands, but as I began programming, I couldn't
  887.         help but add virtually everything I could think of.  It was easy
  888.         to do.
  889.  
  890.         Surprisingly, with all of the new code for event list handling,
  891.         ARexx commands and new file I/O, the resulting program size is
  892.         about 1500 bytes SMALLER than the AmiCron program it replaces. 
  893.         Most of the decrease is probably attributable to the fact that I
  894.         Amiga-tized it, the rest to the superb Lattice 5.0 optimization
  895.         algorithms.  NazCron has no remaining traces of portability, so
  896.         don't expect to see it on your local GS or COCO real soon now.
  897.  
  898.  
  899.         And then there was version 1.02
  900.         -------------------------------
  901.  
  902.         A bug prompted me to start the next version.  I found a bug in the
  903.         timer completion routines that, under the right circumstances (the
  904.         right circumstances don't always come up during testing) would
  905.         occasion a visit from the GURU.  With this bug fixed and after 4
  906.         months of NazCron being on its own in the real world with ZERO
  907.         shareware registrations, I prepared this version.  
  908.  
  909.         NazCron now has one of those annoying shareware reminders to bug
  910.         the real users to send the money.  I have to admit that I had fun
  911.         imagining all kinds of mean and nasty things I could do to those
  912.         who would use the program but not register.  BUT, I actually began
  913.         coding in a peaceful and benevolent mood and the reminder is the
  914.         result.  The un-registered user is forced to click on the reminder
  915.         window when it first comes up, so I can be sure that he, at least,
  916.         knows that it is there.  Thomas Holaday suggested that I include a
  917.         periodic reminder and  make it a non-maskable event that is
  918.         executed every hour.  This is sort of what I did.  I made the
  919.         periodic reminder go away with no intervention required, unlike the
  920.         startup reminder.  If I hadn't, I probably would have gotten
  921.         bundles of hate mail as user's 3am events just died.  Still in a
  922.         benevolent mood, I made sure that the events that should have been
  923.         launched during the reminder minute were launched before I
  924.         displayed the window.
  925.  
  926.         Not wanting all of this new Intuition code go to waste for
  927.         registered users, I added a status display.  This displays
  928.         information that was only available through ARexx in version 1.00. 
  929.  
  930.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. z
  931.  
  932.  
  933.  
  934.  
  935.    December 5, 1989   NazCron V1.02 - Cron-type Event Manager       Page 17
  936.  
  937.  
  938.         Just start NazCron a second time and you'll see the new status
  939.         display.  It contains the same information you would get from the
  940.         ARexx SHOW_STATUS command.  
  941.  
  942.         This version also gives me a good opportunity to add the REMIND
  943.         ARexx script that never made it into the original version and to
  944.         discuss some of the technical problems that seemed to plague a few
  945.         of the 1.0 users. 
  946.  
  947.  
  948.  
  949.  
  950.      Thanks to:
  951.      ----------
  952.  
  953.         Lattice for the great 5.04 package - especially CPR, 
  954.         Bill Hawes for ARexx, 
  955.         Eric Lavitsky for his well structured and information-packed     
  956.             Amiga programming course, 
  957.         Rick Schaeffer and Christian Balzar for the original AmiCron,
  958.         Thomas Holaday for a little encouragement and a neat idea,
  959.         Jay Miner (and friends) for the Amiga and
  960.         My family for putting up with me programming while they baked    
  961.             their brains out on the beach.
  962.  
  963.         I couldn't have done it without you guys.
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.    Copyright 1989 by Don Nafis & NAZLO Associates Limited.  All rights reserved. c