DOS PHANTOM V2.9 from P2 Enterprises

    **********************************************************************
    **  See the CHANGES IN V2.9 section of this file for new features.  **
    **********************************************************************


    DOS Phantom is a keystroke record-and-playback utility. Recordings
    can be of any length and can be edited after recording.  Recordings
    can be played back at high speed or with delays.  Playback can be
    scheduled for a time in the future or invoked with a hot key. A
    powerful script language is provided which incorporates file I/O,
    looping and branching, waiting for screen text, branching on program
    exit status, file I/O, pop-up windows and menus, and more.

			   _______
		      ____|__     |               (tm)
		   --|       |    |-------------------
		     |   ____|__  |  Association of
		     |  |       |_|  Shareware
		     |__|   o   |    Professionals
		   -----|   |   |---------------------
			|___|___|    MEMBER

INSTALLATION:

    Create a directory and unzip the PTM229.ZIP file into it.

    Example:
		  C:\> MKDIR PHANTOM
		  C:\> CD PHANTOM
		  C:\PHANTOM> PKUNZIP ..\PTM229


    If you have the PTM.EXE self-extracting archive file, do this
    instead:
		  C:\> MKDIR PHANTOM
                  C:\> CD PHANTOM
                  C:\PHANTOM> ..\PTM

DEMONSTRATION:

    Make sure you are in the directory containing the PHANTOM2.EXE and
    DEMO files.  Then, type PHANTOM2 DEMO to run the demonstration.

    Now read the section in the PHANTOM.DOC file entitled "Before You
    Start" for more installation information.


REGISTRATION:

    When you register, P2 Enterprises will send you a free DOS Phantom
    Quick Reference booklet.  This booklet contains just about every-
    thing you need to use DOS Phantom without cracking the manual!
    
    You can register using Visa or MasterCard if you wish.

    See the file ORDER.FRM in this kit.


DOS Phantom is:
    - A task automation tool
    - A tool for application integration (the process of making a
        group of different applications work together automatically)
    - A tool for creating self-executing demos (with looping and
	timeout features)
    - A software testing tool (including screen and print capture)
    - A substitute for .BAT files
    - A keystroke macro utility

DOS Phantom recordings can be edited to include:
    - Pop-up text windows
    - Pop-up menus
    - Pauses for user input
    - Branching based on:
	- menu selection
	- program exit status
	- appearance of a text string on the screen
    - String variables
    - Commands to find, read, and write text files
    - Looping
    - Play music

DOS Phantom recordings can be scheduled for playback
    - daily
    - weekly
    - once only

DOS Phantom recordings can also be played back using hot keys.

The included Scraper utility allows you to take output displayed by
one program and play it into another program as if it were being typed
at the keyboard.  And the use of Scraper can be recorded like any other
keyboard activity.

DOS Phantom provides facilities similar to the scripting languages of
popular communications programs such as Procomm and CrossTalk, but
applied instead to *your* computer rather than the one you are connected
to over the phone line.  You can even use DOS Phantom to control a
Procomm session instead of using Procomm's scripting facility.

A demonstration recording and complete Users Guide are included.
DOS Phantom is shareware.  The registration fee is $40.00.  All features
are present and active in the shareware version.


CHANGES FROM PREVIOUS VERSIONS

   Version 2.1 of DOS Phantom fixes a bug introduced in V2.0 which
   prevented ALT and CTRL keys from playing back correctly into some
   application programs, including CIM (CompuServe Information Manager).

   Version 2.2 is a redistribution of V2.1 which corrects the fact that
   obsolete versions of the TXT2PTM and PTM2TXT programs were included
   in PTM221.ZIP.

   Version 2.3 adds support for the PHANTOMDIR environment variable, and
   support for scheduled playback and hot-key initiated playback with
   the programs SCHEDULE and HOTFILE.

   Version 2.4 fixes two bugs reported just after version 2.3 was released.
   Version 2.4 of PTM2TXT fixed a bug which caused the timings of certain
   keystrokes (those with scan codes under 10h) to be set to zero.  Version
   2.4 of PHANTOM2 fixes a problem where keystrokes were missed during
   auto-repeat with typematic rates set above 15.  Minor changes were made
   to the documentation.

   V2.4 also introduces the MAKEPTM program for producing DOS Phantom
   recordings from plain ASCII text files.

   V2.5 fixes a bug in MAKEPTM which prevented processing files without
   at least a 1 second line delay and incorporates changes to allow chaining
   to another recording during playback.

   V2.6 adds support for the F11 and F12 keys and their SHFT, CTRL, and ALT
   variants and fixes a bug which caused the schedule to be corrupted when
   the default RECORDNG.PTM file was used for recording.

   V2.8 replaces the keyboard NumLock, ScrollLock, CapsLock, and Insert
   keys to their pre-playback state when recording terminates unless
   the $RetainKybdFlags directive is contained in the playback file.
   (The $RetainKybdFlags directive has no arguments and may be placed anywhere
   in the playback file.)  V2.8 also fixes a bug which caused scheduled
   playbacks with days or dates specified other than the first in the list
   to be ignored.

   V2.8A of PHANTOM2.EXE correctly reports errors when invalid hot key
   combinations are specified.

   V2.8B of PHANTOM2.EXE correctly processes unused extended keyboard codes
   (actually used by some products) which previously caused erroneous
   directive processing to occur.

   V2.8C fixes a bug in which the use of ALT and CTRL hot keys with HOTFILE
   caused keyboard to appear dead when playback completed.
	
   V2.8A of TXT2PTM.EXE correctly processes delays specified as MM:SS.CCC.
   V2.8 incorrectly processed time delays of over approximately 5 minutes.

   V2.8A PTM2TXT.EXE correctly processes unused extended key codes and
   their translation as <?>.


CHANGES IN V2.9

   V2.9 adds support for the $DisableCtrlAltDel, $EnableCtrlAltDel, and
   $Reboot directives which allow you to reboot the computer from a
   Phantom playback and prevent Ctrl-Alt-Del from rebooting the computer
   during critical sections of a playback.

   The $DisableKybd directive disables all keyboard input.  $Enablekybd
   re-enables keyboard input.  An optional parameter of $DisableKybd is
   a single key which, when depressed, will re-enable the keyboard.  Valid
   keys for the $DisableKybd parameter are letters and numbers only. This
   is to allow $DisableKybd to be used in situations it is desired to
   protect against inadvertant key depressions, but where it is necessary
   to re-enable the keyboard manually.

   The new $Sleep directive behaves just like the $Pause directive, except
   that the timer is not reset after each keystroke as it is with $Pause.
   $Sleep has one parameter, the number of seconds to sleep.  The maximum
   number of seconds for all directives which accept seconds is 3600 (1 hr).

   The commands $MatchAt, $MatchTo, and $MatchFrom have been added.

   The syntax of the new Match commands is:
	$MatchAt r,c n text
	$MatchTo r,c n text
	$MatchFrom r,c n text

	where r,c is the row and column number (1,1 is the upper left corner)
	n is the timeout is seconds
	text is text to match

	$MatchAt only looks for the text at the row and column specified.
	The text must begin at that screen position for the match to succeed.
	$MatchAt accepts -1 as the timeout value.  This results in a single
	test of the screen location (effectively a timeout of zero).  A
	timeout of -1 may not be used with the other $Match directives.

	$MatchTo searches for the text anywhere before (up and left of) the
	row and column specified.

	$MatchFrom searches for the text anywhere after (down and to the
	right of) the row and column specified.

   V2.9 adds the F11 and F12 keys and their SHIFT, ALT, and CTRL variations
   as possible hot keys to the HOTFILE program.	

   V2.9 fixes an unreported bug in which control characters were
   erroneously played back when references to uninitalized command line
   parameters ($1-$9) were made.

   V2.9 adds the command line switch /T, which allows you to specify a
   "trigger" value for recording file writes.  Normally, DOS Phantom
   writes to the recording file after every 32 keystrokes.  Using /T,
   you can specify any number of characters between 1 and 32 after
   which writes are to occur.  For example, to cause the recording file
   to be updated after every character, you would include /T=1 on the
   DOS Phantom command line.  Small trigger values may result in an
   undesirably large amount of disk activity.

   V2.9 increases the maximum number of scheduled playbacks from 16 to 32.
   In the case when two or more playbacks are scheduled for the same time
   (e.g., 08/12/93-16:00 and Thu-16:00), the one appearing first in the
   SCHEDULE LIST display is executed, and any other playbacks scheduled for
   that time are ignored.

   V2.9 adds the command line switch /N which places DOS Phantom in autonomous
   mode.  When in autonomous mode, DOS Phantom ignores commands issued using
   the PHANTOM2.EXE program and hot keys defined using HOTFILE.  Scheduled
   playbacks defined with SCHEDULE are honored if recording or playback is
   not in progress at the scheduled time.  The following command line
   DOS Phantom in memory, disables the attention hot key, the mode display,
   and sounds, begins recording into file file KEYSTROK.LOG, and places
   DOS Phantom in autonomous mode.  Once this is done, DOS Phantom may not
   be removed from memory using PHANTOM2 and recording cannot be stopped.

      C:\> PHANTOM2 /R/N/S/M/K=NONE/I KEYSTROK.LOG

   The P2FLUSH.EXE program, when executed, causes DOS Phantom to flush the
   record buffer to disk.  P2FLUSH is effective even when DOS Phantom is
   operating in autonomous mode.

   V2.9 adds support for 9 string variables S1-S9.  To include the contents
   of a string variable in playback, the string variable is prefixed with a
   dollar sign, similar to command line parameters.  A number of directives
   are available for dealing with string variables:

	$Get Sn r,c len		reads len chars from screen row r column c
				into string variable Sn.
	
	$Read <file> Sn		reads a line from file <file> into string
				variable Sn.

	$Write <file> <text>	Appends <text> to <file>.  <Text> may contain
				string and command line variables, for
				example: "parm1=$1, string variable 3=$S3".
				(The quotation marks are not required syntax.)

	$Close			Closes the file currently open for read,
				if any.  Subsequent reads of the file will
				begin at the start of the file.

	$Assign Sn <text>	Assigns <text> to string variable Sn.  <Text>
				may contains string and command line variables.
	
	$IfEqual <label> Sn <text> Branches to <label> if the contents of Sn
				are equal to <text>.  <Text> may contain string
				and command line parameters.  Comparison is
				case-sensitive.

	$IfEmpty <label> Sn	Branches to <label> if the string variable Sn
				is empty.

	$Clear Sn		Empties the string variable Sn.

   The maximum length of a string variable is 79 characters.

   The $IfClosed directive can be used to detect end of file since when
   $Read encounters the end of file, the file being read is closed.  Only
   one file may be open for read at a time.  When the second filename is
   encountered, the first is automatically closed.  A subsequent $Read of
   the first file will close the second file and return the first line of
   the first file. 

   V2.9 adds support for looping using the $On directive.  The format of
   the $On directive is: $On <count> <label>.  When the $On directive is
   encountered <count> times, control is transferred to <label>. Before
   <count> times, the directive is ignored.  Here is an example of a loop
   which copies 200 lines from FILEA.TXT to FILEB.TXT unless the end of
   FILEA.TXT is encountered first:

	$Loop:
	    $Read FILEA.TXT S1
 	    $IfClosed EndLoop
            $Write FILEB.TXT $S1
	    $On 200 EndLoop
            $Goto Loop
        $EndLoop:

   A maximum of 256 $On directives may be used in a single Phantom script.
   The maximum count value is 65535.

   V2.9 adds support for the $FirstFile and $NextFile directives which
   allow you to perform directory searches from within Phantom scripts.
   
	$FirstFile Sn <filename>	locates the first file matching
					<filename> which may include
					the * and ? wildcard characters and
					disk and directory specifications.
					The filename is placed in Sn.

	$NextFile Sn			locates the next file matching the
					<filename> in the last $FirstFile
					executed.  The filename is placed in
					Sn.

   When no more files match <filename>, the string FILE NOT FOUND is placed
   in Sn.  Here is an example of a script which places the names of all the
   .PTM files in the PHANTOM directory into a file calles PTMLIST.TXT:

	$FirstFile S1 C:\PHANTOM\*.PTM
	$IfEqual EndLoop S1 FILE NOT FOUND
	$Loop:
	    $Write PTMLIST.TXT $S1
	    $NextFile S1
	    $IfEqual EndLoop S1 FILE NOT FOUND
	    $Goto Loop
        $EndLoop:
     

   V2.9 introduces a new type of directive: the $F directives.  $F
   directives are similar to functions in programming languages in that
   when a $F directive is placed in a string, the result of the $F directive
   replaces the $F directive in the string.  $F directives take their
   arguments in parenthesis immediately following the directive name.

   Three $F directives have been implemented in V2.9: $FSubStr, $FBefore,
   and $FAfter. The $FSubStr directive extracts a substring from a string
   variable.  Th format of $FSubStr is
	
	$FSubStr(Sn,<start>,<length>)

	where Sn is the string variable from which to extracts the substring
	      <start> is the character at which to start extracting (1-based)
	      <length> is the number of characters to extract

   Here is an example of $FSubStr being used to extract the characters
   EFGHTUVW from the string ABCDEFGHIJKLMNOPQRSTUVWXYZ and placing them in
   S2:

	$Assign S1 ABCDEFGHIJKLMNOPQRSTUVWXYZ
	$Assign S2 $FSubStr(S1,5,4)$FSubStr(S1,20,4)

   $FBefore selects the portion of a string which appears before a specified
   character, while $FAfter selects the portion of a string which occurs
   after a specified character.  For example,

	$Assign S1 RECORDNG.PTM
	$Assign S2 $FBefore(S1,.)
	$Assign S3 $FAfter(S1,.)

   results in S2 containing RECORDNG (the substring before the period), and
   S3 containg EXE (the substring after the period).

   $F directives can be used wherever the $Sn syntax is allowed, except in
   *-prefixed output lines.  To output a substring as if it was being typed
   at the keyboard, you must $assign it to a string variable first, and then
   output the variable, like this:

	$Assign S6 $FSubStr(S3,1,8)
        * $S6

   Here is a sample script which places the filenames of the files in the
   current directory minus their filetypes (the three characters after the
   period) in a file called TEST.TXT.  It then types the file.

	* DEL TEST.TXT
	$FirstFile S1 *.*
	$IfEqual EndLoop S1 FILE NOT FOUND
	$Loop:
	    $Write TEST.TXT $FBefore(S1,.)
	    $NextFile S1
	    $IfEqual EndLoop S1 FILE NOT FOUND
	    $Goto Loop
	$EndLoop:
	* Type TEST.TXT


  V2.9 adds the $Music directive.  $Music allows you to play melodies from
  a Phantom script.  $Music accepts a series of note/duration arguments,
  each of which specifies a musical note and the length of time for which
  is to be played. Four octaves supported with notes from C1 to B5.  The
  following notes are supported: A A# Bb C C# Dd D D# Eb F F# Gg G G# Ab R.
  R is a rest (no sound).  Each note is suffixed with the octave in which
  it is to be played, a forward slash, and the number of ticks for which
  the note is to be sounded.
  
  Here is how the first few notes of Mary Had A Little Lamb would be
  specified in a Phantom script (played in octave 3):

	$Music R/80
	$Music E3/60 D3/20 C3/40 D3/40 E3/15 R/25 E3/15 R/25 E3/60 R/20 
	$Music D3/15 R/25 D3/15 R/25 D3/40 R/40 E3/40 G3/15 R/25 G3/40
	$Music R/80 


  The $BeginMenu directive has a new parameter in V2.9.  The new parameter
  is not required, and the behavior of $BeginMenu defaults to what it was
  in previous versions.  The new parameter is either 0 or 1.  The default
  is 0.  If 1 is supplied, the auto-incrementing feature of DOS Phantom
  menus is disabled for that menu.  For example, the following $BeginMenu
  directive would begin the definition of a non-auto-incrementing menu at
  row 5, column 20, white on blue, saving existing Phantom pop-ups.

	$BeginMenu 5 20 1 S 1
		   | |  | | |
		   | |  | | +- disable auto incrementing
		   | |  | +--- save existing pop-ups
                   | |  +----- attribute code for white on blue
                   | +-------- column 20
                   +---------- row 5



  $ResumeKey and $IfKey

  The new $ResumeKey and $IfKey directives can be used in a variety of ways
  to enhance the functionality of your Phantom scripts.  $ResumeKey accepts
  a list of keys which will resume playback of the script from a $Pause or
  $Sleep state.  $ResumeKey with no arguments removes any previously assigned
  resume keys.  $ResumeKey Any makes any keystroke end a $Pause or $Sleep
  state.  The following example allows F12 or Alt-F12 to terminate a $Pause
  and then removes the resume key assignments:

	$ResumeKey <F12> <Alt-F12>
	$Pause
	$ResumeKey

  Resume key assignments, with the exception of Any, remain in effect until
  changes with another $ResumeKey directive.  The $ResumeKey Any assignment
  is automatically removed as soon as it is used to terminate a $Pause or
  $Sleep.  Note that the keys listed following $ResumeKey are separated
  with a single space.

  The $IfKey directive allows you to test the last keystroke entered by the
  user. This is especially useful after a $Pause which might have been
  terminated by a number of resume key assignments and after $EndDisplay
  to find out which key the user pressed to terminate the display. This
  in effect allows you to create a number of "hot keys" which are available
  as long as your script is in execution.

  The following example demonstrates the use of the $ResumeKey and $IfKey
  directives in a number of ways.

  !
  ! HOTMENU - An example using $ResumeKey and $IfKey
  !

  $Loop:
  $BeginDisplay 4 15 1 30 R
  $Title HotMenu
 
      Select one of the options below
      by typing the letter preceeding    
      the option name.
  
      A  Directory of .EXE files
      B  Directory of .COM files
      C  Directory of .BAT files
      X  Exit
  
  $EndDisplay
  
  !
  ! See if they pressed one of the special keys
  !
  $IfKey DIREXE A
  $IfKey DIREXE a
  
  $IfKey DIRCOM B
  $IfKey DIRCOM b
 
  $IfKey DIRBAT C
  $IfKey DIRBAT c
  
  $IfKey EXIT X
  $IfKey EXIT x
  
  !
  ! They didn't press a special key.  re-display the "menu"
  !
  $Goto Loop
  
  !
  ! Handle the "menu" options.  After executing the command, wait 10 seconds
  ! or for any keystroke before re-displaying the "menu".
  !
  $DIREXE:
  * CLS
  * DIR *.EXE
  $ResumeKey Any
  $Pause 10
  $Goto Loop
  
  $DIRCOM:
  * CLS
  * DIR *.COM
  $ResumeKey Any
  $Pause 10
  $Goto Loop
  
  $DIRBAT:
  * CLS
  * DIR *.BAT
  $ResumeKey Any
  $Pause 10
  $Goto Loop
  
  !
  ! Take them to DOS.  Wait for F12 to re-display the "menu", or Alt-F12
  ! to exit the playback.
  !
  $EXIT:
  * cls
  * Rem  **** Use F12 to return to the menu. ****
  $ResumeKey <F12> <Alt-F12>
  $Pause
  $IfKey END <Alt-F12>
  $Goto Loop

  $END:
  $Music C4/5 R/5 C4/5
  !
  ! End of HOTMENU
  !


THE SCRAPER UTILITY

  V2.9 includes the SCRAPER utility which allows you to copy text displayed
  by a program into Phantom's string variables and play the stored text back
  later as if it were keyboard input.  Scraper is activated with the hot key
  specified using DOS Phantom's /B command line switch.  The default Scraper
  activation hot key is ALT-S.

  Scraper is named as it is for the slang term "screen scraping" commonly
  used to describe Scraper's function.

  Install Scraper by typing SCRAPER/I at the DOS command line.  DOS Phantom
  must be installed before Scraper can be installed.  Activate Scraper using
  the hot key (default ALT-S).  A pop-up help window is displayed which
  tells you to move the cursor using the arrow keys to the upper left of
  the text you wish to select and press Enter.  As soon as you press an
  arrow key, the help window disappears.

  When you press Enter, a second pop-up help window appears, telling you to
  move the cursor to the lower right of the text you wish to select and
  then to press the number key where you want to begin storing the selected
  text.  The text will be stored in DOS Phantom string variables beginning
  with that number.  If only one line of text was selected, only the one string
  variable will be used. The contents of the string variables, if any, are
  overwritten.

  To play back the contents of a string variable, invoke Scraper using the
  hot key and press the number key of the string variable whose contents you
  wish to play.

  To disable the pop-up help windows, install Scraper with the /H switch
  like this: SCRAPER/H/I.  You may un-install scraper using the /U switch.
  When you un-install DOS Phantom, Scraper will be automatically uninstalled.

  If you record your use of Scraper with DOS Phantom, it will be played back
  correctly, allowing you to automate the movement of data from one program
  into another (or even back into the same program).

  Scraper uses about 6K bytes of memory with help enabled, and about 3K bytes
  with help disabled.