WinCron - Internal Commands Reference
=====================================

  INTERNAL commands are built into WinCron. All internal commands
begin with a "$". If a command does not begin with a "$" WinCron
assumes it is an EXTERNAL command and tries to execute it. External
commands are EXE, COM, or BAT files that reside on the hard drive.
WinCron cannot run internal DOS commands (like DIR, COPY etc), however
most internal DOS commands are duplicated with WinCron commands.

  Most internal WinCron commands take parameters such as filenames,
strings, or numeric values. Multiple parameters must be separated by
spaces. If a parameter consists of a filename or string that contains
spaces, it must be enclosed within quotes. Some commands (such as
commands that display messages or send keys) should not contain quotes,
or, if included, will be treates as regular characters (see detailed
reference).

Example:
	Quotes not required:	$COPY file1.txt file2.txt
	Quotes required:	$COPY "file 1.txt" "file 2.txt"


Command	Description
-------	-----------
$ASK 	- Asks if you want to run a command.
$COPY	- Copies a single file.
$DELAY	- Delays execution.
$DIAL	- Display/start dial-up connection.
$DISABLE - Disables a specified task.
$DISPLAY	- Displays bitmap pictures.
$ENABLE	- Enables a specified task.
$EXIT	- Exits the WinCron program.
$EXITWIN 	- Exits Windows in a specific way.
$IFEXISTS	- Checks if a file exists.
$IFWINDOW	- Checks if a window is open.
$KILL	- Deletes a file.
$LOAD	- Re-loads the task list file.
$LOADNEW	- Loads new task list.
$LOG	- Writes a string to the WinCron log file.
$LOGBACK	- Backs up the wincron log file with the current date.
$MKDIR	- Creates a new directory.
$MSG	- Displays a message string and waits for OK.
$MSGLOG	- Writes a string to the Message log file and displays the log.
$NEWLOG	- Saves the log file using the current date .
$NO	- Executes commandline only if condition was false.
$PLAY	- Plays a media file.
$PROMPT	- Displays a prompt and waits for YES/NO.
$RENAME	- Renames or moves a file.
$RMDIR	- Removes a directory.
$RUN 	- Runs a script.
$SAVE	- Saves task list (IE: to record "Last-Run" info).
$SEND	- Sends keys to a specific window.
$KEYS	- Sends keys to the currently active window.
$SETSTRING	- Assigns a string to a variable
$SKIPTO	- skips forward to a labelled line.
$STOP	- Aborts processing of the current script.
$WAITSEC - Waits for a specific time.
$WAITWINDOW	- Waits for windows to open or close.
$WRITE	- appends a string to a text file.
$YES	- Executes commandline if condition was true.

**Timer Commands:
$COUNTDOWN	- Starts a count-down timer.
$COUNTUP	- Starts a count-up timer.
$IFZERO	- Runs a command if the timer is zero.
$SETTIMER	- Sets the specified timer (0-9).
$TIMER	- Controls the timer operation.
$IFTIMER	- Checks if the timer is active.
$CHECKTIMER - Checks the timer value.
$IFEQUAL	- Runs a command if the value was equal.
$IFLESS	- Runs a command if the value was less.
$IFGREATER	- Runs a command if the value was greater.


Detailed Reference:
===================
Note:	"Sets condition" means:
		If the command was successful the condition is set
		to YES (true), otherwise it is set to NO (false).
	Use the $YES and $NO commands to test the condition
	
	
Command	Description
-------	-----------
$ASK {commandline}
	Displays the task description and commandline and asks you if
	you would like to execute the task.

	Note:
	* Processing of additional tasks is halted until a button is
	  clicked, so make sure someone is around to see the message!

$COPY {source} {destination}
	Copies the source file to the destination. The destination
	MUST include a filename. Filename wildcards (*,?) are NOT
	supported. Sets condition.

	Example:
	$COPY C:\MY FILES\TEST.TXT C:\FOLDER\TEST.TXT

$DELAY {milliseconds}
	Delays for the specified period (Max 60 seconds). One second
	EQUALS 1000 milliseconds. Useful in scripts to delay keystrokes
	sent to other applications with the $SEND or $KEYS commands.

	See Also: $WAITSEC, $WAITWINDOW, $IFWINDOW

$DIAL {connection} {NOW}
	Brings up a pre-configured and named dial-up-networking
	connection. If NOW is specified the connection will be
	started immediately.

	Notes:
	* For Windows 9x ONLY!
	* for un-attended operation the password must be set in
	  conjunction with the "Save password" option.
	* If the connection is active this command will display
	  the connection status window. The connection can be
	  shut down by sending appropriate keystrokes.

$DISABLE {ME|taskdescription}
	Disables the specified task from running. To disable the
	current task specify "ME" as the task description.

	Note:
	* Can't be used in scripts run from the command-line
	* Matches partial task descriptions. Be careful when naming
	  tasks with similar descriptions!


$DISPLAY {option} {picturefile}
	Displays bitmap pictures in BMP, GIF or JPG format. Displays
	the picture but does NOT stop script execution.

	OPTIONS:
	* OPEN: Opens a full-screen window with a black background
		and displays the picture centred in the window.
		Clicking the window closes it.
	* NOCLICK: As above but cannot be closed with mouse click.		
	* CLOSE: closes the display window.

	Example: $DISPLAY OPEN splash.bmp

$ENABLE {taskdescription}
	Enables the specified task. Useful for enabling tasks that
	only need to run after other tasks have finished or certain
	conditions are met.

	Note:
	* Can't be used in scripts run from the command-line
	* Matches partial task descriptions. Be careful when naming
	  tasks with similar descriptions!

$EXIT
	Exits WinCron immediately.

$EXITWIN {method}
	Exits Windows using the specified method:
		LOGOFF, SHUTDOWN, REBOOT, or POWEROFF

	The system will exit in a friendly way. If other programs
	are running that can't be terminated the operation will fail.
	If you want to FORCE the method, and make other programs
	exit regardless, add an "!" to the end (IE: REBOOT!).

	Note:
	* For Windows 9x ONLY!

	CAUTION!:
	* Use this command carefully.
	* Data may be lost if applications are forced to exit!

$GETENV {n} {variable}
	Gets the system environment variable and assigns it to the
	numbered string variable {n}.

	Example:
		$GETENV 0 path
		$MSG The path is set to: %S0%
	Produces a message similar to:
		The path is set to: C:\DOS;C:\WINDOWS;C:\WINDOWS\COMMAND

$IFEXISTS {filename}
$EXISTS {filename}
	Checks if a file exists. Sets the condition to YES if the file
	exists, or NO if it doesn't.

	Example script:
		$EXISTS c:\test.txt
		$YES $MSG The file exists.
		$NO $MSG The file does not exist.

$IFWINDOW "{title}"
	Sets the condition to YES if a window is open, or NO if it is not.

	Notes:
	* True when any window is open whose titlebar BEGINS with {title}.
	* Not case sensitive.
	* Begin the title with "*" to match string anywhere in the titlebar.
	* Title MUST be enclosed in quotes

$KEYS {keylist}
	Sends keys to the currently active window/dialog. Similar
	to the $SEND command except does not activate a window.	See
	the $SEND command for details. ALL keys including quotes if
	specified will be sent. Sets condition.

$KILL {filename}
	Deletes a file. Sets condition.

$LOAD
	Re-loads the task list file (wincron.dat). Useful if you'd
	like to update tasks while wincron is running.

	Notes:
	* Always loads even if tasklist is the same.
	* Caution: "Last run" info from current task list will be lost!

$LOADNEW
	Looks for the file "wincron.new" and if it exists replaces the
	current "wincron.dat" file and re-loads the new task list.
	Similar to $LOAD except only updates when nessesary.

	Note:	
	* Caution: "Last run" info from current task list will be lost!

$LOG {string}
	Writes the string to the event log file (wincron.log). Always
	writes even if logging for the event is not enabled. Writes
	exact string, including quotes.

	Note:
	* If no string is specified then the event description will
	  be written to the log (the same as if you had left the exe
	  field blank).

$LOGBACK
	Backs up the log file with the current date (YYYYMMDD.log).
	The current log is NOT erased.

$MKDIR {directoryname}
	Creates (makes) a new directory. Sets condition.

$MSG {string}
	Displays the message string and waits for OK. Writes exact
	string, including quotes.

	Example:  $MSG Time to go home!

	Note:
	* Processing of additional tasks is halted until the OK button
	  is clicked, so make sure someone is around to respond!
	* See also $MSGLOG

$MSGLOG {string}
	Writes the string to the Message log file (message.log) and
	displays the messages window if not visible. The CLEAR button
	will erase all messages and start a new log file. Use this
	command when you need to display messages but do not wish to
	stop processing of additional tasks (like the $MSG command).

	Note:
	* Maximum log size that can be displayed is 32,000 bytes.

$NEWLOG
	Saves the event log using the current date (YYYYMMDD.log) then
	clears the log.

	Notes:
	* Make sure this is only done ONCE a day or the old log will
	  be overwritten!
	* A good idea is to set an event to run at 23:59 each day.

$NO {commandline}
	Executes the commandline only if previous condition was false.

$PLAY {mediafile} {OFF|NOWAIT}
	Uses ActiveMovie2 to play the specified mediafile. Supported
	formats include:
	  WAV, MID, MPG, MP3, AVI, MOV, QT, RAM and others.

	Notes:
	* $PLAY waits for the file to finish playing before continuing
	  unless the NOWAIT option is specified!
	* To stop whatever is currently playing use $PLAY or $PLAY OFF
	* Refer to the README file for instructions on installing
	  the ActiveMovie MCI driver.

$PROMPT {promptstring}
	Displays the prompt string with YES and NO buttons. Displays
	the exact string, including quotes. The condition is set to
	YES or NO depending on the user's response.

	Note:
	* Processing of additional tasks is halted until a button is
	  clicked, so make sure someone is around to respond!

$RENAME {filename} {new_filename}
	Renames the file to the new filename. Can also move files by
	specifying a different path for "new_filename". Sets condition.

	Examples:
	  $RENAME TEST.TXT TEST.BAK
	  $RENAME "C:\TEST 2.TXT" "C:\BACKUPS\TEST.TXT"

$RMDIR {directoryname}
	Removes a directory provided it is completely empty.
	Sets condition.
		  
$RUN {scriptname}
	Runs a script (text file) containing WinCron, EXE, or COM
	commands. The script is executed line-by-line. Internal
	variables may be used in any line. See the SCRIPTS section in
	the main documentation file for more details.

	Note: Do not use the $RUN command inside a script!

$SAVE
	Saves the task list. The "Last run" and "Run count" are also
	saved as part of the task list. 

$SEND "{Title}" {keylist}

	Activates the window or dialog box with a titlebar containing
	the specified {Title} string, then sends keys to the window.
	The title MUST be enclosed in quotes and there must be a space
	between the title and the keylist. The {keylist} is a list
	consisting of one or more standard or special keys and/or
	key-control commands. See the SENDKEYS reference file for
	{keylist} details.

	Notes:
	* If there is no exact match for {Title}, any window/dialog
	   whose title string BEGINS with {Title} is activated.
	* To find windows that contain the {Title} string ANYWHERE
	  in the title, start the title with a "*".

		IE: $SEND "*Netscape" %{F4}

		Will send ALT-F4 to the FIRST netscape window.

	* If no window can be activated the condition is set to NO.
	* Only works with Windows applications! Does NOT work with
	  DOS commands even when run in a window.
	* Keys can't be sent to minimized windows.
	* Title MUST be enclosed in quotes
	* The {keylist} can include quotes anywhere and will be sent
	  just like any normal character.

	Example:
	To calculate the square root of 69 using the standard
	Windows calculator enter the following command:
		$SEND "Calculator" {DEL}69@

	Will send the keys: DELETE,6,9, and @  to the window.
	Special keys are sent by enclosing them in braces. In this
	example the "@" symbol is the keyboard equivilent to clicking
	on the SQRT button inside the calculator.

$SETSTRING {n} {string}
	Assigns the string to the numbered string variable (0 to 9).
	The entire string including quotes if included will be assigned
	to the string variable. To use a string variable in another
	command use the form %sN% where 'N' is 0 to 9.

	Example:
		$SETSTRING 0 "This is a test"
		$MSG The string is: %s0%

	Will display:
		The string is: "This is a test"

$SKIPTO {label}
	Skips FORWARD in the script to the specified label. Labels are
	not case sensitive and must be on a line by themselves. Any
	line in a script with a ":" as the first character of the line
	is considered a label.

	Script Example:

		$IFTIMER 0
		$NO $SKIPTO NoTimer
		$MSG The timer is running
		$SKIPTO Exit
		:NoTimer
		$MSG The timer is not running
		:Exit

$STOP
	Aborts processing of the current script. Can be used in
	conjunction with the $YES and $NO commands or to stop scripts
	from continuing to labeled lines below.

$WAITSEC {seconds}
	Waits until the seconds value of the current time is equal to
	or past the specified value (Max 59 seconds). Could be used in
	place of $DELAY when you need to syncronize to a specific time.

$WAITWINDOW {OPEN|CLOSE} {Title} {Timeout}
	Waits for window with specified title to open or close. The
	Timeout value determines how long to wait (seconds) before
	continuing. Maximum wait is 60 seconds.

	Example: $WAITWINDOW CLOSE "Calculator" 10

$WRITE "{filename}" {string}
	Appends the string to the specified file. The filename MUST
	be enclosed in quotes and must be followed by a single space.
	The entire string, including quotes if specified, will be
	written to the file.

	Note:	A carriage return will NOT be written to the file unless
		specifically included using the %CR% or %CRLF% variable.

$YES {commandline}
	Executes the commandline only if previous condition was	true.


**** Timer Commands ****

There are 10 timers, numbered 0 to 9 that you can use for general
purpose timing. Timers work using minutes only.
	* Timers can be STOPPED or ACTIVE
	* Active timers can count UP or DOWN.
	* Active timers can be COUNTING or PAUSED.

$COUNTDOWN {n} {minutes}
	Starts a countdown timer from specified minute.

$COUNTUP {n}
	Starts an up-counter at zero.

$IFZERO {n} {commandline}
	Runs the commandline if the selected timer is zero. If the
	timer is zero this command will stop the timer to ensure the
	commandline only runs once.

	Note:
	* The COUNTDOWN/COUNTUP and IFZERO commands are designed
	  for simple (non-script) timer operations. For complex
	  timing use the commands below.

$SETTIMER {n} {minutes}
	Sets the value of the specified timer (0-9).

$TIMER {n} {option}
	Controls the timer operation. Valid options are:
	* STARTUP	- Starts timer going up.
	* STARTDOWN	- Starts timer going down.
	* PAUSE		- Pauses the timer.
	* RESUME	- Continues the timer.
	* STOP		- Stops the timer.

	Example: $TIMER 0 STARTUP

$IFTIMER {n}
	Checks if the timer is active (timing up or down) and sets the
	condition to YES or NO.

$CHECKTIMER {n} {minutes}
	Checks the timer and sets the condition to EQUAL, LESS or
	GREATER. Use the $IFEQUAL, $IFLESS or $IFGREATER commands
	to check the result.
	
	NOTE:
	* Does NOT change the timer status (in comparison to $IFZERO)

$IFEQUAL {commandline}
$IFLESS {commandline}
$IFGREATER {commandline}
	Runs the commandline if the condition matches. You can also
	use the shorthand equivilents: $EQ, $LT, $GT

	Timer example:

	Task 1:	DESC: Start timer 0 to count up
		EXE : $COUNTUP 0

	Task 2:	DESC: Display message based on 10 minute mark
		EXE : $RUN timer.wcs
		When: Schedule the task to run every minute

	TIMER.WCS Script:	 	
		$IFTIMER 0			;Is the timer active?
		$NO $STOP			;No, stop the script
		$CHECKTIMER 0 10		;Has 10 minutes elapsed?
		$IFLESS $MSG Wait some more...	;LESS
		$IFEQUAL $MSG 10 minutes is up!	;EQUAL
		$IFGREATER $MSG Overtime!	;GREATER
		$IFGREATER $TIMER 0 STOP	;Stop timer counting

<END>