WinCron (C)1997-1999 Steve J. Gray
======= FREEWARE

Version: 1.34, May 17/1999

Please see the readme file for program history and requirements.

Introduction
------------

  WinCron is a Windows task scheduler/runner/controller. It can run
Windows or DOS programs, or batch files (EXE, COM or BAT). Tasks can
be set up to execute manually, on startup, or on a scheduled basis.
A schedule can be a specific day or range of days, specific days of
the week, or during specific months. Tasks can be set to run once or
at specific intervals between two times, or excluded between two times.
Tasks can be individually enabled or disabled or all tasks can be
disabled. When run, tasks can be recorded in a log file for later
verification.

Special internal WinCron commands allow automated messages, log
comments, and log backups. Command-line variable substitutions allow
passing of date/time/count etc to commands or batch files. WinCron
scripts can be used for advanced application control.


Window Layout
-------------

 When run, the program window will appear. On the titlebar is the
current date. On the left side is the time. Below is the enable box
which, when checked, enables running of all tasks (provided that the
task itself is enabled). Below the enable box are three buttons:
	
	Event Log
		- Runs the Notepad program to display the "wincron.log"
		  file. Please note: If you are viewing the log and
		  a logged event occurs the log file will be changed
		  in the file but NOT in Notepad! If you then SAVE
		  the log file those events will be lost.
	Msg Log
		- Displays the Messages log window.
	Prefs
		- Displays program options and documentation.
	Save
		- Saves task information, including "last run" info.

 Below the buttons is the BUSY light. This light turns red when a
task is executing.

 On the right side of the window is the Tasks list. Hightlighting an
entry displays the date and time the task was last run. Double-clicking
an entry will edit it. A "+" will be displayed infront of all Tasks
that are enabled, and a "--" will show for those that are disabled. 

 At the bottom of the list are six buttons:

	Add	- Adds a task to the list.
	Edit	- Edit currently selected task.
	Del	- Deletes currently selected task.
	Up	- Moves the task up the list
	Dn	- Moves the task down the list
	Run Now	- Runs the currently selected task.
		  Note: Always runs the task regardless of
			schedule settings.

  The UP and DN buttons can be used to change the order that
tasks are run. Tasks at the top of the list are run first. You may
need to adjust the order of tasks if one task depends on another
(ie: if you start a program in one, then send keys to it in another).

  When you click on the Add or Edit button another window will appear
where you can define the task and schedule. In the top half of the
window you specify a description for the task, the command to run,
when to run it and how it appears on the screen. You can also define
whether the task is enabled or disabled and if the task should be
recorded in the event log.

* Desc
	Description of the task.

* Command
	Command to execute. May include a command line string if
	needed. Click on the "..." button to browse the computer to
	find the executable file. The command can be left blank to
	record comments (the description) in the log file at specific
	times.
		 
	Commands can contain variables in the form %NAME% that will be
	substituted with the appropriate value when the command is
	executed. See the VARIABLES.TXT	file for details.

	To execute special "internal" WinCron commands, start the line
	with a "$". See the COMMANDS.TXT file for details.

	NOTE!:	WinCron can NOT execute INTERNAL DOS commands directly.
		Internal DOS commands are those that are part of
		COMMAND.COM (like COPY and DIR). To use internal DOS
		commands you must run them in a batch file, or use the
		equivilent WinCron command!

* When
	Specifies when the event should run:

	* Manually - only when "Run Now" clicked.
	* At Startup - when WinCron first runs.
	* Scheduled - as specified in bottom section
	* At Shutdown - when WinCron is exited.
	
	Note: the bottom section is hidden when not required

* State
	Determines how commands are displayed when run:
	* Hidden with Focus
	* Original Size with Focus
	* Icon with Focus
	* Maximized with Focus
	* Original Size
	* Icon

* Record in Log
	Enables event recording in log file.

* Enable Event
	Enables event to run when scheduled.

* Run Count
	The number of times the task has run.

* Reset Button
	Reset the run count.

* OK Button
	Uses the settings. Updates the task info or adds the task.

* Cancel Button
	Ignores any changes or additions.

  If "When" is set to "Scheduled" the event window will expand to
display the bottom section, where you may set the dates and times that
the task will be run.

* Date Valid
	Specifies the range of dates that the event may run. To specify
	a date you must enter the year, month and day in exactly the
	following format: YYYYMMDD.
	
	IE: Tue Oct 20,1998 would be entered as 19981020.

	From	- The first day the event is valid (00000000=any day).
	To	- The last day the event is valid (00000000=any day).

* Activation
	Specifies month and day, or month and day range that the event
	will run. Month and Day values are separate. Under each column
	there is a checkbox to enable the column. If not checked, the
	column will be ignored. IE: if the DD column is not checked ANY
	day will be valid. If the DD column is checked then the day
	must match the specified day or day range.

	From	- specifies the FIRST valid month and/or day.
	To	- specifies the LAST valid month and/or day.
		- If the "To" Checkbox is NOT checked then the "From"
		  month and/or day specify a single date. If checked
		  then the month and/or days become a range.

	* TIP: the MM and DD values are separate therefore
			/ FROM: 01 05 \
			\   TO: 03 07 /
	  would NOT mean all days from Jan 5 to Mar 7, but rather only
	  the days 5 to 7 in the months Jan to Mar.
	  IE: Jan 5,6,7, Feb 5,6,7, and Mar 5,6,7.
	
	(If you need Jan 5 to Mar 7 then those dates should be
	 specified in the date range and the "from" and "to" should be
	 left un-selected!)

	NOTES:
	* When using a single day, an entry of "99" can be used to
	  specify the "last day of the month".
	* When using a day range, if you need to run a task to
	  "the end of the month", use "31" in the day "to" field.

* HHMM
	Specifies the time or time range for the event. Times must be
	specified in 24-hour format (ie: 1pm=1300).

* Time and Frequency
	The dropdown menu beside the "From" time determines if the
	time is a single time or a range and if the event is kept or
	deleted after it runs:

	* Once a day, Anytime:
		- Once per day (At midnight if wincron is left running,
		  or shortly after WinCron first runs each day)
	* Once a day, Specified Time:
		- Once per day at the exact time, provided WinCron is
		  running at that time.
	* Intervals, Between Times:
		- One or more times between From/To range.
	* Intervals, Outside Times:
		- One or more times, NOT between From/To range.
	* Once Only, Specified time:
		- Once at the specifed time provided WinCron is running.
		- The event is recorded then never runs again
		  (provided tasks are saved).
	* Once Only, then delete task:
		- Once at specified time provided WinCron is running.
		- The event will be marked deleted in the task list then
		  will be deleted when the task list is next saved.
	* Once a day, within Time Range:
		- Once per day provided the time is inside the time range

	- The dropdown menu beside the "To" time determines the
  	  frequency of events:

	* Every 1,2,5,10,15,20 or 30 minutes.
	* Every 1,2,4,6, or 8 hours.

* Day (of week)
	Specifies valid days for the event:

	* Any Day - Any day of the week.
	* Weekday - Monday to Friday.
	* Weekend - Saturday and Sunday.
	* Selected- Only the days that are indicated.

	NOTE:
	Be careful when combining day and day-of-week settings!
     	IE: if you set an event to happen only on the first of
	the month but also set the day-of-week to Monday then
	the event will only occur if the first is a monday.


Drag and Drop Adding (32-bit version only)
--------------------

  You can add a task to the tasklist by dragging a file from explorer,
a directory window or the desktop TO the task list area in the WinCron
window. A new task will be created with the name of the dropped file in
the command field. This is equivilent to clicking the ADD button from
the main window then the "..." browsing button in the task window and
browsing to locate a file.

Prefs Window
------------

  This window displays the WinCron documentation and lets you set
the program options. Options are saved automatically.

* Show Tray Icon (32-bit version only):
	- Displays an Icon in the sytem tray on the taskbar.
* Minimize on Startup:
	- Hides the main window when first run.
* Save task list when changed:
	- Saves the entire task list whenever you add/edit/delete a
	  task.
* Save task list on exit:
	- Saves the task list when WinCron exits.
* Confirm Task Deletes:
	- If selected, a popup window asks you to confirm the action.
* Disable Messages:
	- Stops messages from appearing for invalid internal commands.

  If the tray icon is enabled and you minimize the main window a button
will NOT appear on the taskbar. Left-clicking on the tray icon will
re-display the main window.  Right clicking on the tray icon will
display a menu with the following options:

	* Enable Tasks	- enables task execution
	* Disable Tasks	- disables all tasks
	* Preferences	- Display preferences window
	* View Log	- View Log file
	* Close		- Exits WinCron

  Preference settings will be saved when WinCron is exited. The "enable"
setting as well as main window position and size will be saved.


Command-line option
-------------------

  If you want WinCron to use a task list other than the default
(wincron.dat) you can specify the name of the task list file on the
command line. To do this create a shortcut to the WinCron executable
then edit the command line by appending the filename to the end.

Example: WinCron50.exe newlist.dat

Task lists must have an extension of "DAT".


Operation
---------
  When run, the program will look for the file "WINCRON.DAT" (or the
one specified on the command line) which must be in the same directory
as the WINCRON.EXE file. This file contains information for each task
in the list. WinCron updates the clock each second. When the seconds
gets to "00" the entire task list is checked from first entry to last
and all tasks that are currently set to "enabled" will be performed
provided all the specified conditions are met: Date range,
month range, day range, time range, day of week and/or frequency etc.

  When a task is performed it runs concurrently (at the same time) as
any other tasks that may be running. WinCron does NOT wait for programs
to exit before continuing. If a program can not be found there will be
NO error messages displayed. If "Record in Log" is enabled the current
date and time as well as the description will be recorded in the file
"WINCRON.LOG". If the program starts then "OKAY" will be recorded, if
not then "ERROR" will be recorded.

  If you want to disable all events (IE: to verify scheduled tasks)
simply un-check the "Enabled" box in the main window.

  If the "Save task list when changed" option is NOT enabled you must
click on the SAVE button to save the event information. Tasks
can be added, edited or deleted while WinCron is running and will be
acted on immediately, however any changes will be lost when WinCron
exits unless they are saved! Clicking the SAVE button will also record
the date and time each event was last run, which will be displayed when
a task is selected from the task list.

	NOTE:	The "last run" info is saved with the task list,
		however the task list is NOT saved when a task is RUN.
		Therefor, to ensure the last run info is saved, you
		might want to create a task that is run once a day or
		when WinCron is exited to save the task list (use the
		$SAVE internal command).

  Lastly, if not obviously, tasks will not and cannot be run unless
WinCron is actually runnning! Tasks that were scheduled and missed
when WinCron is not running will NOT be performed when WinCron first
starts again. If WinCron is vital you might consider adding it to the
STARTUP menu. Tasks that are missed can be run manually at any time
by selecting the task from the list and clicking the "Run Now" button.


Scripts
-------

  Scripts are similar to DOS batch files. A script is a text file
containing a list of commands to be executed in sequence. Scripts can
contain "external" DOS commands, or Windows commands. Unlike DOS
batch files however, scripts can also contain special WinCron commands
($ commands) and internal WinCron variables. To use scripts in WinCron
use the $RUN internal command. The syntax is:

	$RUN {scriptname}

Where {scriptname} is the name of the script file. Script files can
be called anything you want (IE: script.txt, test.scr, wincron.wcs) etc.
I recommend you use the extension "WCS". You can also associate specific
extensions with WinCron so that double-clicking a script from explorer
will launch wincron, run the script, then exit.

When you use the EDIT button to edit a task you can use the
"Edit script" button to edit your scripts using Notepad.

The following commands are useful in scripts:

	$EXISTS	- Checks if a file exists. Sets condition.
	$PROMPT	- Gets YES/NO reponse from user. Sets condition.
	$YES	- runs a command if the condition was TRUE
	$NO	- runs a command if the condition was FALSE
	$SEND	- sends keystrokes to a specified window
	$KEYS	- sends keystrokes to the currently active window
	$DELAY	- delays execution for a specified time (milliseconds)
	$WAITSEC- waits until the time gets to the the specied second
	$STOP	- stops script processing
	$SKIPTO	- jumps forward to the specified line

IMPORTANT!!!:
	WinCron runs WinCron ($) commands in sequence (IE: the next
	command runs only AFTER the first is finished, however, DOS
	and Windows commands are started as separate tasks. This means
	that the command may still be loading/running when the next
	command is executed. If you intend to send keystrokes to a
	windows application you should use the $DELAY command to give
	the windows application enough time to load and respond to
	keyboard input!

CAUTION:
	If a script contains many $DELAY commands and the task takes
	more than one minute, it may cause other tasks to be missed!

NOTE:
	WinCron scripts can NOT use DOS batch-only commands such as
	IF, FOR, GOTO, EXISTS, ERRORLEVEL, SHIFT, or %1 to %9, nor can
	it use INTERNAL DOS command such as DIR, DEL, MKDIR, COPY etc.
	Most internal DOS commands are duplicated with internal WinCron
	commands (ie: $COPY, $MKDIR, $KILL etc).

Timers
------

  There are 10 general-purpose timers available in WinCron. Timers can
be used to co-ordinate tasks that must be performed after specific
intervals. For example, when the computer turns on you might want to
start processing something that takes 10 to 15 minutes to complete.
Then 15 minutes later you want to run another task that depends on the
results of the first task.

  You wouldn't be able to schedule the second task at a set time,
because you don't know when the first task started. The anwser is to
use a timer in the first task (set to 15 minutes) then in the second
task (say set to run every 5 minutes) check the timer to see if it's
been 15 minutes or more. If it has, do the task, if not just skip it.

For example:	(NOTE: do not type in the comments!)

* Task1:
		longtask.exe		;run the task
		$countup 0		;start/enable timer#0

* Task2:
		$IFTIMER 0		;check if timer1 enabled
		$NO $STOP		;no, so forget it
		$CHECKTIMER 0 15	;has 15 minutes elapsed?
		$IFLESS $STOP		;no, bye again
		nexttask.exe		;yes, run the other task
		$TIMER 0 STOP		;disable the timer!

The same thing using a count-down timer:
* Task1:
		longtask.exe	;run the task
		$countdown 1 15	;set timer#1 to countdown from 15 minutes
* Task2:		
		$ifzero 1 nexttask.exe	;if the timer is 0 do it
		; note: the timer is automatically disabled

Some Example Tasks
------------------

Here are some example tasks and what need to be set.
"[*]" indicates checkbox is checked. "(N/A)" indicates setting not used.

A) Record each time WinCron runs:

  Desc=WinCron was started
  Command= (leave empty)			[*]Record in Log
  When=On Startup    State: (N/A)		[*]Enable Event
  ----------------------------------------------------------------
  (Event schedule info will not be shown)


B) Run a tape backup every Sunday at 1pm:

  Desc: Backup system to tape
  Command: "C:\tape\backup.exe" -auto               [*]Record in Log
  When: Scheduled   State: Original Size with Focus [*]Enable Event
  -----------------------------------------------------------------
  Date Valid: YYYYMMDD  Activation: MM DD HHMM
        From: 00000000	      From: 00 00 1300  Specified time
	  To: 00000000      To: [ ] 00 00 0000
				    [ ][ ]
  Day: Selected   [*]Sun [ ]Mon [ ]Tue [ ]Wed [ ]Thu [ ]Fri [ ]Sat


C) Display the message "Work Harder!" once every Hour from 9am to 5pm
   during the week just before a big deadline on Friday Nov 21, 1997:

  Desc: Reminder
  Command: $MSG Work Harder!			[ ]Record in Log
  When: Scheduled     State: (N/A)		[*]Enable Event
  --------------------------------------------------------------
  Date Valid: YYYYMMDD  Activation: MM DD HHMM
        From: 00000000	      From: 00 00 0900  Intervals, Between Range
	  To: 19971121      To: [ ] 00 00 1700  Every Hour
				    [ ][ ]
  Day: Weekday   [ ]Sun [ ]Mon [ ]Tue [ ]Wed [ ]Thu [ ]Fri [ ]Sat


D) Perform a task via batch file every 10 minutes starting 1 minute
   past the hour except between noon and 7pm every day during the
   months of May to July starting in the year 2001 and ending in the
   year 2010 but don't record them:

  Desc: Menial tasks in PROCESS.BAT batch file.
  Command: C:\JUNK\PROCESS.BAT			[ ]Record in Log
  When: Scheduled     State: (N/A)		[*]Enable Event
  --------------------------------------------------------------
  Date Valid: YYYYMMDD  Activation: MM DD HHMM
        From: 20010101	      From: 05 00 1201  Outside Range
	  To: 20101231      To: [*] 07 00 1900  Every 10 Minutes
				    [*][ ]
  Day: Any Day  [ ]Sun [ ]Mon [ ]Tue [ ]Wed [ ]Thu [ ]Fri [ ]Sat



FAQ - Frequently Asked Questions
--------------------------------

Q: When I run a batch file the MS-DOS window remains open.
A: You must enable the "close on exit" option in the properties for the
   batch file.

Q: My events don't seem to run.
A: Check that all events are enabled, then check that the event itself is
   enabled. The event may actually be running but is set to run "Hidden"
   so it won't appear on the screen (use CTRL-ALT-DEL to check if the
   application is running but not visible).

Q: Can I use WinCron to run tasks on a Windows NT server without anyone 
   logged in?
A: You can make WinCron a service (see the NT resource kit for details).
   NOTE: Microsoft advises against making VB programs into services.
   Use at own risk! I will not support WinCron run in this way.

Q: An application doesn't work when run from WinCron.
A: It may need to be started with a batch file, because it might need to access
   files from a default directory or drive.
A: The program may already be running hidden and may not operate as expected or
   at all (like when attempting to run WinCron twice).

Q: When I send keys to an application nothing happens.
A: The application may not be designed to handle keyboard input, or it is
   performing an operation that does not respond to input at that time.
A: The titlebar of the application may have changed.
A: The application may have a "fake" titlebar (WinCron won't know where to
   send the keys!).


WinCron Stealth Control Program (32-bit version only)
===============================

  The WinCronSC program is an additional 32-bit program that enables
or disables WinCron's "stealth" mode. When stealth mode is enabled
WinCron will run entirely in the background with NO user interface.
This can be useful for public access workstations that must perform
periodic tasks but remain invisible to the user. In order to be useful
all tasks and preferences should be set BEFORE enabling stealth mode.
To make WinCron's operation invisible while in stealth mode you should
set the State for all tasks to "Icon" so that they are not visible and
not the focus (the program that receives input).

  To change settings you must disable stealth mode before running
WinCron. If WinCron is already running you can shut down WinCron
using the Task Manager (CTRL-ALT-DEL).

  If you do not want WinCron's stealth mode to be changed simply
remove WinCronSC.exe from the machine after setting the stealth mode
to the desired state.
