SCHEDTSK and this documentation are Copyright (c) 1989-1993 Don Branson. All Rights Reserved. The programs (except for STRES.EXE and STPROC.EXE) may be distributed through normal shareware/freeware channels. STRES.EXE and STPROC.EXE are currently available only through Simian Id Software of St. Louis, Missouri. Table of Contents ----------------- I. Why SCHEDTSK? Covers typical uses for SCHEDTSK, to get you started. II. Concepts Defines and explains Tasks and Events. III. Task/Event Creation and Execution. An overview of how Tasks and Events are managed and run by the typical user. IV. Installing SCHEDTSK V. Programs A. EVENTMAN - Details of how EVENTMAN (Event Manager) is used to define and manage Tasks and Events. B. STRUN - Using STRUN to run the Events created. C. STPROC - Using STPROC to load the background scheduler, STRES. D. DTIME - Describes the utility program, DTIME (Display Time). E. DOW - Explains the use of the DOW (Day of Week) program. VI. Appendices A. Using your favorite editor to edit Tasks. B. Changing Tasks and Events while STRES is loaded. C. Upgrading from EVENTMAN 2.0 to SCHEDTSK 2.5. D. How STRES functions. E. Loading STRES into high memory. F. Using STRES with Microsoft Windows (tm). I. Why SCHEDTSK? This package was developed originally to help a friend of mine who was the manager of the network where he worked. He needed to run backups after hours, without being present himself. The software with his backup unit did not support scheduled backups. The SCHEDTSK software was designed from the beginning to be of general use, however, not just for network managers that need to schedule backups. Now, most software that comes with tape backup units includes the ability to schedule backups for off-hours. At the same time, the needs of network managers have increased in complexity, and these folks need to schedule other things as well, such as special reports, statistics reports, file transfers, and so forth. The schedulers for the tape backup units can schedule only backups, and none of these other tasks. In addition, tape backup software can typically handle only the most simple scheduling. Many networks managers need the additional capabilities of a sophisticated scheduling program such as SCHEDTSK. There are other alternative programs available, which can handle simple scheduling needs, but none have the capacity to handle the number of scheduled programs that SCHEDTSK can. SCHEDTSK can schedule as many programs as you need. They can be scheduled to run daily, weekly, monthly, even yearly. They can be scheduled to run at an interval you specify, from 1 to 99,999 minutes. They can also be scheduled to run a single time. All scheduling is done through a full-screen program called EVENTMAN, which will take advantage of 43- or 50-line screens, for those of you who use them. EVENTMAN also has complete, on-line, context-sensitive help. Once your programs are scheduled, all program execution is controlled by the program STRUN, which runs either on a stand-alone PC, or in a networked environment, on a workstation. The workstation does not need to be a dedicated workstation. STRUN displays the schedule of programs, sorted so that the next scheduled item is at the top of the list. All TSR functions are controlled by the programs STPROC and STRES. STPROC parses all the command line options for STRES. It then loads STRES, the resident program, which can occupy as little as 2400 bytes of memory or less. STRES coordinates program execution in conjunction with STRUN. While SCHEDTSK was mainly created for network managers, many other uses have been found for it. I sometimes use it in conjunction with a terminal program to sign on to a BBS early in the morning, when noone else is on, and retrieve messages to a file. A simple example is Daylight Savings time changes. Using SCHEDTSK, you can set your PC clock ahead in the spring, and back in the fall, automatically. As you use SCHEDTSK, you may find that there are many daily routines which you perform that it can handle for you. As you find new ways which SCHEDTSK works for you, please write and tell us how you are using it. This information can be included in future documentation, and will help other people as they use SCHEDTSK. II. Concepts EVENTMAN works following two basic concepts, the TASK and the EVENT. A Task is the process which you wish to run. You can think of Task in the same way as a DOS batch program. A Task performs, in order, the functions which you need done. A Task has no time-related information stored with it. It is simply a set of related instructions, like a batch file. The commands can be executable programs, or .BAT files. When executing a .BAT file from a Task, you will need to use the CALL command, which is supported by DOS versions 4 and up, and is documented in your DOS manual. The second concept is the EVENT. An Event consists of time information, plus a list of Tasks. For example, an Event might be scheduled to run daily at 11:00 P.M., starting on January 1, 1994. This Event would also include a list of Tasks to be run at that time. By separating the Task information and the Event information, general- purpose Tasks can be made which can be used by more than one Event. See the Task BELL, or DISPTIME, for example, which are included in the SCHEDTSK package. These and other Tasks can be seen by running the program EVENTMAN. Each Task in the list has an 8-character name, a 60-character description, and an associated file of DOS commands. Each Event consists of a name, an interval, a starting time, and a list of Tasks to run. III. Task/Event Creation and Execution While it is a good practice to make your Tasks small, it is not critical. You may find that simple Tasks are more easily re-used by more than one Event than complex Tasks are. Before setting up your own Tasks, you may want to take a look at some Tasks that are already defined. The Tasks included with SCHEDTSK are set up to write any output to a log file named "C:\ST.LOG". By using the Tasks DISPTIME and LINE, which display the date/time and a row of dashes, respectively, you can make this log file easier to scan. The purpose of the log file is to keep a record of the successful execution of Tasks, and and also any problems which might occur. You won't necessarily require a log file in your environment, or you might want to redirect output to a printer. When your Tasks are defined, enter the Event list, and schedule your Events to run when needed. Once the Tasks and Events are set up, use STRUN to run the Tasks. If you need to use the PC for something else, use STPROC to load STRES, which will wait in the background while you are using the PC for other purposes. You will normally run STRES via STPROC, not directly. The exception to this is when you want to load STRES into high memory. This is covered in Appendix E. IV. Installing SCHEDTSK It is recommended that you install SCHEDTSK into a directory on a local hard drive. The directory should be named SCHEDTSK. All Tasks and Events should be defined in this directory. This directory should also be added to your PATH. Copy all files from the diskette or archive you received into the SCHEDTSK directory. To install SCHEDTSK, insert the diskette into drive A and type a:install at the DOS prompt. Follow the instructions given by the installation program. If your diskette is not the proper size for your A drive, you may also use your B drive. You may want to add STPROC or STRUN to your AUTOEXEC.BAT file, so that in the event of a power failure, your machine will come back up ready to run Events when the power comes back on. V. Programs EVENTMAN -------- Starting EVENTMAN EVENTMAN has no command-line options. To run it, the SCHEDTSK directory should be the current directory. Type EVENTMAN at the DOS prompt and press Enter. Keyboard The function keys available are always shown at the bottom of the screen. Help is always available by pressing F1. In addition, the keys HOME, END, Page Up, Page Down, Insert, Delete, Backspace, Tab, Shift-Tab, and the arrow keys are functional in the Task Menu, the Event Menu, and data entry fields. The Task Menu The Task menu is displayed immediately upon entering EVENTMAN. You may use the Tab or arrow keys to select a Task to work with. Use Tab to move the cursor into the description, which may be changed right in the Task list. When a Task is selected, use F2 to edit the command file for that Task. Use F4 to delete the Task. You will always be asked to confirmed deletes. To create a new Task, press F3. You will be asked to enter a name and description. You will then be taken into the editor to edit the command file for the new Task. Appendix A discusses how you can use your own editor with EVENTMAN when editing Tasks. The Event Menu Pressing F5 takes you from the Task menu into the Event menu. The same control keys (such as Tab) that work in the Task list work identically in the Event list. The function keys available are shown at the bottom of the screen. Use F2 whenever you want to make changes to an Event. Use F3 to add an Event, and F4 to delete an Event. Whenever you add an Event, you will be asked to give it an 8-character name. You will need to indicate the interval when the Event should be run by selecting an Event type. Your options are D (daily), W (weekly), M (monthly), Y (yearly), S (single run, no repeats), and O (other - interval specified in minutes.) If you select O, you will also be prompted to enter the number of minutes between runs. For example, to run a process every hour, enter O as the Event type, and 60 as the interval in minutes. You will also need to enter a starting date and time. The date may be any date which DOS supports. This range covers years 1980-2099. The time is entered in 24-hour format. Each Event also requires a list of Tasks which will be executed as specified. The Task names are separated by commas, and each Task must be a valid Task from the Task list. Press F6 to save changes to the Event, or ESC to cancel. F4 is used to delete Events. You will be asked to confirm the delete. STRUN ----- STRUN is the program which controls the execution of all Events. This program is the program that you use to run Events, and it is also the program which STRES (the TSR) runs when an Event is scheduled to run. STRUN maintains a list of Events in order by date and time, with the next scheduled Event at the top of the list. The current time is also displayed so that you can see both the current time and the time of the next Event on the screen together. When STRUN runs an Event, it updates the list of Events on disk with the date and time when that Event will again be run. This date and time will be reflected when you use EVENTMAN to view the Events. STRUN also updates its list of Events, so that the next Event is moved to the top of the Event list. STRUN has a few command-line options, which may be chosen using a slash (/), a dash (-), or no prefix at all. For example, STRUN with the help option (H) may be run any of these formats: strun /h strun -h strun h Options do not need to be separated by spaces. These are the command- line options for STRUN: H - This option displays the list of options for STRUN. Q - Quiet mode. This option turns off the full-screen display. In this mode, STRUN runs all Events that are ready to run, then exits quietly. This mode is mainly used by STRES, to run current Events. P - Run Past processes. This option runs Events whose date and/or time have already passed without execution. This situation may occur if your system was off when an Event was scheduled, or if some program prevented the execution of STRUN when an Event was scheduled. This option is also mainly for use by STRES. F - Force run. This option forces to STRUN to run even if TSRPROC is determined to be running. TSRPROC is an old version of STRES, and STRUN should not execute when it is running. This option is needed in case STRUN decides that TSRPROC is running when it is not. When STRUN begins execution, it needs to bring all processes up-to- date. If Option P is selected, it will run each Event for each scheduled interval until the Event is brought up to the current date and time. STPROC ------ STPROC is the loader program for the TSR, STRES. This program reads the command line parameters, sets all options, then sets up and loads STRES. STRES is the program that stays resident in memory waiting for the next Event. STPROC can also be used to query the status of STRES. When STRES is loaded, it runs STRUN in order to establish the date and time of the next Event. STPROC has two sets of options. The first are options that are used when STRES is started. The format of the options is the same as for STRUN, so you may use option prefixes of /, -, or nothing. The options are: H - This option displays the list of options for STPROC. V - Verbose mode. This option sets Verbose mode on. When STRES is loaded, it will display information about its status. P - Run past processes upon initialization. This flag is passed to STRUN when it is loaded by STRES at initialization. C - This flag is used to set the Check frequency. By default, STRES checks every 5 seconds to see what the current time is, when the time of the next Event is near or has passed. See Appendix D for an explanation of the algorithm that STRES uses for checking the time. Here is the format for this option: STPROC c2 S - This option sets the stack size used by STRES. The default stack size is 256 bytes. The stack size can be set anywhere from 32 bytes to 32767 bytes. The size of the stack directly effects the size of the resident program. The minimum recommended size is 128 bytes. Using a smaller size may cause erratic behavior. This is the format for this option: STPROC s128 The second set of command-line options are only valid when STRES has already been made resident. These options are: U - Unload STRES. This option will remove STRES from memory unless other TSR's have been loaded after it which use the same interrupts which it uses. Q - Query status of STRES. This option displays the current date and time, and the date and time of the next Event, as recorded by STRES. When STRES is resident in memory, Alt-LeftShift will cause STRUN to pop up and display the current Event list. See Appendix D for limitations on pop-ups. DTIME ----- DTIME is a simple program, but it is handy to have when using SCHEDTSK. This program displays the current date and time on a single line. There are no command-line options. This program is demonstrated in the Task DISPTIME, which is provided in the SCHEDTSK package. DOW --- This is another small program (8 bytes!), but one which can add tremendous flexibilty to SCHEDTSK. It simply returns the Day Of Week as a DOS error code. This error code can then be used in a .BAT file. The following .BAT file demonstrates how this is done. It is a program that I use for daily tape backups. It will run a backup every day except Sunday. CBACKUP, which is executed by this .BAT file, is the actual tape backup program: echo off dow if errorlevel 6 goto saturday if errorlevel 5 goto friday if errorlevel 4 goto thursday if errorlevel 3 goto wednesday if errorlevel 2 goto tuesday if errorlevel 1 goto monday if errorlevel 0 goto sunday goto exit :sunday echo Today is Sunday - Don't do a backup goto exit :monday echo Today is Monday - Do a backup cbackup goto exit :tuesday echo Today is Tuesday - Do a backup cbackup goto exit :wednesday echo Today is Wednesday - Do a backup cbackup goto exit :thursday echo Today is Thursday - Do a backup cbackup goto exit :friday echo Today is Friday - Do a backup cbackup goto exit :saturday echo Today is Saturday - Do a backup cbackup goto exit :exit exit echo Procedure cbackup complete. VI. Appendices Appendix A: Using your favorite editor to edit Tasks EVENTMAN is set up so that you can specify an editor to use when editing Task command files. EVENTMAN will first look for the Editor SBE, an editor formerly available through Simian Id Software. If SBE is not present, EVENTMAN will try to execute EDIT, the editor that comes with MS-DOS 5 and later versions. Finally, EVENTMAN will try to run EDLIN, the line editor available with all versions of MS-DOS. To override this behavior, you may set a DOS environment variable with the path and name of the editor you want to use. The name of the variable is EDITOR. This may be set at the DOS prompt or in your AUTOEXEC.BAT file. For example, if the name of your favorite editor is FAV_EDIT, and it is in the directory C:\MY_FAVS, type: SET EDITOR=C:\MY_FAVS\FAV_EDIT at the DOS prompt, or enter that line into your AUTOEXEC.BAT file. Now when you use F2 to edit a Task command file, your editor will be used. Appendix B: Changing Tasks and Events while STRES is loaded EVENTMAN can be loaded and run while STRES is resident in memory. After you change any process, you should pop-up STRUN, then exit, in order to re-initialize the Event date within STRES. Appendix C: Upgrading from EVENTMAN 2.0 to SCHEDTSK 2.5 For users of prior version of SCHEDTSK (formerly known as EVENTMAN), you should run the new EVENTMAN program, which will convert files to the format used by SCHEDTSK. The concept of a Process in prior versions has become the concept of an Event. The concept of an Event in the prior versions has become a Task. Task and Event more appropriately describe the nature of these two concepts. The most significant change you will notice in the newest version of SCHEDTSK is that the TSR is significantly smaller. When STPROC is used with the smallest recommended stack, STRES occupies only 2352 bytes of your PC's memory. Appendix D: How STRES functions STRES is normally loaded using STPROC. STPROC parses the command options, setting flags, then writes these flags to the file ST_PARM.000, which STRES will read. STPROC then loads STRES, passing the path and name of the file with the flags. STRES is a TSR (Terminate and Stay Resident) program. Once loaded, it occupies typically 2.3K of memory. When it is started, it also runs STRUN as a subprogram. STRUN then reads the Task and Event lists, and determines the time of the next Event, which it then communicates to STRES via an interrupt. Dates and times in STRES are stored in the DOS system format, so that STRES can quickly check them against the current date and time, using a minimum of CPU time and stack space. STRES determines how long it will be until the next Event. If the next Event is more that a day off, it will set a timer so that it doesn't check again until 24 hours have passed, thus minimizing CPU usage. If the time is less than hour, STRES will calculate the amount of time to wait and check again. It always underestimates, so that Events are not missed due to this process. When the timer is set, STRES uses very little CPU in checking the time. It is attached to the timer interrupt, and merely decrements a counter, then returns if the counter is not zero. Every effort has been made to make STRES as efficient as possible. When an Event is ready to run, STRES needs to invoke STRUN to actually run the processes. Since the code to manage and control the running of processes is fairly large, it is important to only load it when it is time to run an Event. When an Event is ready to run, STRES determines if the system state is currently at the DOS prompt. If not, it will sleep the number of seconds determined by the STPROC 'C' option, then try again. It will continue in this fashion until it can run STRUN. STRES cannot absolutely determine that it is at a DOS prompt. If you are at the prompt of the DATE or TIME command, STRES will think that you are at a DOS prompt when you are not. In order to load STRUN, STRES stuffs keystrokes into the keyboard buffer. The first character that STRES stuffs is the ESC character, so that the DOS command line will be cleared of anything entered. The command to run STRUN is then stuffed, and STRUN executes. When STRES runs STRUN, it always uses the 'Q' option, which tells STRUN to run in quiet mode, then exit. When STRUN has completed the running of processes, it determines the date and time of the next Event, and communicates this to STRES via an interrupt. Appendix E: Loading STRES into high memory STRES is typically loaded into the lower 640K of DOS memory, but it is possible to load it into high memory indirectly. This is how it is done. First, use STPROC to load STRES with the options you want. This will create the file ST_PARM.000 in the SCHEDTSK directory. Next use the command 'STPROC U' to unload STRES. Finally, re-load STRES directly, using the DOS LOADHIGH command, and giving the name of the parameter file on the command line. Here is a typical use, where the short form of the LOADHIGH command, 'LH', has been used: \schedtsk\stproc vs128 \schedtsk\stproc u lh \schedtsk\stres \schedtsk\st_parm.000 Appendix F: Using STRES with Microsoft Windows When using STRES with Microsoft Windows, STRES should be loaded before Windows is loaded. You will need to open a DOS prompt where it can pop-up STRUN. When using STRES in this fashion, you should use the 'C' option on STPROC to specifiy that it check every second, so that it will be sure to pop-up when an Event occurs. If you do not, STRES may never check the time at the same instant when Windows has given it CPU. Even so, Events may run late when STRES is used in this fashion. Trademarks Microsoft, MS-DOS and Windows are registered trademarks of the Microsoft Corporation.