Readme file for script.exe

That's right, yet another Windows script program.  The big difference is that this one is free
_and_ you get the source, but wait if you order now we'll throw in the Ginsu knives, the apple
peeler and the four-in-one kitchen wonder.  That also means that if you want to change it you
can, but don't come back to the author with your 300 line hack wanting him to fix "his" program.
You break it, you own it.  I kept script simple because I had simple needs.  If your needs are
more complex you probably want to look elsewhere, there are several excellent scripting programs
available which will undoubtedly fit the bill.

Script is a small program which allows automation of Windows (95/NT) tasks through the use of files
containing command lists.  It is, with the exception of the actual scripts, self contained.  That means
no external dll's, no registry entries, no ini files.  To install script, just copy script.exe to an
appropriate directory.  If the scripts are in a different directory than the executable then the full
path to them will need to be specified.

Script was written in (gasp) C using Microsoft Visual C/C++ 4.2. I don't have any other compiler so
if you make changes and can't get it to compile correctly using the compiler you got from Burger King
with the kiddie meal, you are on your own. If you are successful and want to send me the necessary steps,
(readme's, makefiles, etc.) to include in the package I will be glad to, however, your name will be
prominently displayed and all questions will be forwarded to you.

The input to script is a text file with a default extension of .scr.  Commands are contained one
on each line and blank lines and lines whose first nonblank character is a ; are ignored.  Lines
which begin with a : are labels and may not contain commands.  Commands are not case sensitive: Start,
start and sTaRt are equivalent.

The commands available are:

	start

	description:
	
		start is used to run a program.  The full path name and the file extension
		are required.  Command line options may be included after the executable.
		Quotes are not necessary and the backslash character _must_ be escaped (i.e. \\).
		start may be followed optionally by min or max which will cause the window to
		open minimized (an icon) or normally.  The default is max.  A startup directory
		may be optionally included as well.  If the startup directory is appended then
		min or max _must_ be specified (no place holders).
		
	syntax:

		start,program[,min|max][,startup directory]

	example:

		start,c:\\winnt\\notepad.exe
		start,c:\\winnt\\system32\\command.com /c h:\\temp\\test.bat,min
		start,c:\\winnt\\welcome.exe,max,c:\\winnt


	wait

	description:

		wait will cause the program to loop waiting for a window whose title text matches
		the text string which follows the wait command.  An optional timeout value may be
		specified (in .001 second increments), if this value is not given then the default
		value is "wait forever".  If a timeout occurs the internal error flag is set to true
		and onerr can be used to branch to a handler.  Special characters contained
		in the text string must be escaped (, \ % ^ ? *).  The string _is_ case sensitive
		and must match _exactly_.  The exception to this is the use of the two wild card
		characters: ? and *.  The question mark is a single character wild card and will match
		any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but
		not abc or a11b11c.  The asterisk is an n character wild card and will match 0 or more
		characters appearing in the same position, i.e. a*b*c will match abc, alphabet soup can,
		or aabbc.  Note: two windows with exactly the same title text (i.e.
		script.c - Notepad) are undifferentiable and the command will act on the first
		one encountered in the task list which may not produce the expected results.  A clever
		programmer will realize that wait/onerror can also be used to test if a program
		is already running.

	syntax:

		wait,window title[,timeout]

	example:

		wait,readme - Notepad
		wait,Microsoft Word - Document1,10000


	send

	description:

		send is used to force characters to a window whose title text matches the
		text string which follows the send command.    The string _is_ case sensitive
		and must match _exactly_.  The exception to this is the use of the two wild card
		characters: ? and *.  The question mark is a single character wild card and will match
		any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but
		not abc or a11b11c.  The asterisk is an n character wild card and will match 0 or more
		characters appearing in the same position, i.e. a*b*c will match abc, alphabet soup can,
		or aabbc.   The string sent is the last parameter on the line.  Special characters
		contained in the text string must be escaped (, \ % ^ ? * $ #).  The % and ^ characters have
		special meaning: unescaped the % will cause an Alt-key sequence to be sent and the ^ will
		cause the character immediately following to be converted to a control character.
		The unescaped $ character indicates that the two characters following it are a function key
		number.  The two characters _must_ be numeric in the range of 1-12 inclusive.  The
		unescaped # character indicates that the two characters following it are a hexidecimal
		representation.  Legal values are 0-9, A-F, and a-f.  (Yeah, I know, it's awkward).
		Additional escape sequences are defined: \n will cause a return to be sent
		and \t will send a tab.  ? and * must be escaped even though they have no special meaning 
		here.  Note: two windows with exactly the same title text (i.e.
		script.c - Notepad) are undifferentiable and the command will act on the first
		one encountered in the task list which may not produce the expected results.

	syntax:

		send,window title,text string

	example:

		send,readme - Notepad,This is a line\nand this is the second line


	delay

	description:

		delay causes the script to pause for the number of .01 second increments
		specified after the delay command.

	syntax:

		delay,number

	example:

		delay,500


	msgbox

	description:

		Display text in a message box.  Use $syserr for the text string to print the text
		of the last system error.  Default display mode is MB_OK | MB_SYSTEMMODAL.
		Legitimate values are any combination of the following (the numeric sum must be
		used not the symbol).
			MB_OK                       0x00000000L
			MB_OKCANCEL                 0x00000001L
			MB_ABORTRETRYIGNORE         0x00000002L
			MB_YESNOCANCEL              0x00000003L
			MB_YESNO                    0x00000004L
			MB_RETRYCANCEL              0x00000005L

			MB_ICONHAND                 0x00000010L
			MB_ICONQUESTION             0x00000020L
			MB_ICONEXCLAMATION          0x00000030L
			MB_ICONASTERISK             0x00000040L

			MB_USERICON                 0x00000080L
			MB_ICONWARNING              MB_ICONEXCLAMATION
			MB_ICONERROR                MB_ICONHAND

			MB_ICONINFORMATION          MB_ICONASTERISK
			MB_ICONSTOP                 MB_ICONHAND

			MB_DEFBUTTON1               0x00000000L
			MB_DEFBUTTON2               0x00000100L
			MB_DEFBUTTON3               0x00000200L
			MB_DEFBUTTON4               0x00000300L

			MB_APPLMODAL                0x00000000L
			MB_SYSTEMMODAL              0x00001000L
			MB_TASKMODAL                0x00002000L
			MB_HELP                     0x00004000L // Help Button

			MB_NOFOCUS                  0x00008000L
			MB_SETFOREGROUND            0x00010000L
			MB_DEFAULT_DESKTOP_ONLY     0x00020000L

			MB_TOPMOST                  0x00040000L
			MB_RIGHT                    0x00080000L
			MB_RTLREADING               0x00100000L
			MB_SERVICE_NOTIFICATION     0x00200000L
			MB_TYPEMASK                 0x0000000FL
			MB_ICONMASK                 0x000000F0L
			MB_DEFMASK                  0x00000F00L
			MB_MODEMASK                 0x00003000L
			MB_MISCMASK                 0x0000C000L


	syntax:

		msgbox,text string[,display mode]

	example:

		msgbox,this is a test,3


	onerror

	descripton:

		Onerror allows conditional branching based on the results of the last start or wait
		command.  Control is transferred to the label name contained in the onerror line.
		Labels can be before or after the current line.

	syntax:

		onerror,label

	example:

		onerror,exit
		.
		.
		.
		:exit


	goto

	description:

		goto allows unconditional branching.  Control is transferred to the label name
		contained in the goto line.  Labels can be be before or after the current line.

	syntax:

		goto,label

	example:

		goto,exit
		.
		.
		.
		:exit   


	while

	description:

		while waits for a window to close.  The text of the window must match the text
		following the while command exactly.  The exception to this is the use of the two wild card
		characters: ? and *.  The question mark is a single character wild card and will match
		any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but
		not abc or a11b11c.  The asterisk is an n character wild card and will match 0 or more
		characters appearing in the same position, i.e. a*b*c will match abc, alphabet soup can,
		or aabbc.  An optional timeout value may be specified (in .001 second increments), if
		this value is not given then the default value is "wait forever".  If a timeout occurs
		the internal error flag is set to true and onerr can be used to branch to a handler.

	syntax:

		while,window title[,timeout]

	example:

		while,Untitled - Notepad



	onexist

	descripton:

		onexist checks for the file specified immediately after the onexist command.  If the file
		exists, control is transferred to the label whose name appears immediately after the filename.
		Special characters (, \ % ^ ? * $ #) which appear in the filename string must be escaped.

	syntax:

		onexist,filename,label

	example:

		onexist,c:\\winnt\\notepad.exe,loop


	onmsgrtn

	description

		onmsgrtn is used to branch on the button pressed in a message box.  The legal values are:
		ABORT, CANCEL, IGNORE, NO, OK, RETRY, and YES.

	syntax:

		onmsgrtn,button,label

	example:

		onmsgrtn,YES,exit


Special character sequences:

%       Alt             Character following is alt-char
^       Control         Character following is a control character
!		Shift			Character following is a shift character
\n      newline         Equivalent to pressing the enter key
\t      tab             Equivalent to pressing the tab key
\,      comma           Commas must be escaped within literal strings to avoid being interpreted as separators
\>      right           Equivalent to pressing the cursor right arrow
\<      left            Equivalent to pressing the cursor left arrow
\^      up              Equivalent to pressing the cursor up arrow
\v      down            Equivalent to pressing the cursor down arrow
\\      backslash       Backslashes must be escaped within literal strings to avoid being interpreted as escapes
\?	question mark	Must be escaped within literal strings to avoid being interpreted as wildcards
\*	asterisk	Must be escaped within literal strings to avoid being interpreted as wildcards
\$	dollar sign	Must be escaped within literal strings to avoid being interpreted as a function key
\#	pound sign	Must be escaped within literal strings to avoid being interpreted as a hex preamble
\!  exclamation			Must be escaped within literal strings to avoid being interpreted as a shift shift


Things to do:
	branching on message box return values
	improve error checking wrt use of attributes

Known Bugs:
	Windows 95 dos box doesn't accept keystrokes