TopWare Tools

home *** CD-ROM | disk | FTP | other *** search

/ TopWare Tools / TOOLS.iso / tools / top1137 / readme.1st < prev next >

Wrap

Text File | 1994-01-21 | 23.0 KB | 601 lines

DOS PHANTOM V2.9c 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. V2.9a of PTM2TXT fixes bugs which sometimes acused PTM2TXT to terminate without producing an output file or produce garbled output. V2.9a of P2FLUSH fixes a bug which caused it not to recognize installed instances of registered versions of PHANTOM2. V2.9a of PHANTOM2 fixes a problem where recordings initiated with the PHANTOM2 /R command when PHANTOM2 was already installed as a TSR terminated with an erroneous disk full message after 32 keystrokes. Also, playback can now more reliably be paused with the attention hot key. V2.9b of PHANTOM2 fixes a problem where if a recording was made following a playback in a single PHANTOM2 session, PTM2TXT would report that a later version of PTM2TXT was needed to translate the recording. V2.9c of PHANTOM2 fixes a problem wherein certain of the new v2.9 directives could, under certain circumstances, cause PHANTOM2 to lose its place in a playback file.