DOS Phantom Users Guide DOS Phantom V2.9 Users Guide PUBLISHED BY P2 Systems Incorporated P.O. Box 25 Ben Lomond CA 95005-0025 Copyright (c) 1995 by P1 Systems Inc. All Rights Reserved. _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER ii DOS Phantom V2.9 Users Guide Contents 1. What Is DOS Phantom?..................................1 1.1. What is DOS Phantom Good For?.......................2 1.1.1. Recovery from Power Failures......................2 1.1.2. A Batch Substitute................................3 1.1.3. Keystroke Macros..................................3 1.1.4. Program Startup...................................3 1.1.5. Automatic Execution...............................3 1.1.6. Demos.............................................4 1.1.7. Software Testing..................................4 1.1.8. Applications Integration..........................4 2. What is Shareware?....................................6 3. Using DOS Phantom.....................................7 3.1. Before You Begin....................................7 3.2. The DOS Phantom Command Line........................8 3.2.1. Basic Command Switches............................8 3.2.2. Other Command Switches............................9 3.3. Recording and Playing Back.........................10 3.4. Pausing............................................11 3.5. Quick Playback - The /Q Switch.....................12 3.6. Looping Playback - The /L Switch...................12 3.7. The DOS Phantom Control Panel......................12 3.8. Changing The Hot Keys..............................14 3.9. Increasing Shell Environment Space - The /E Switch.16 3.10. Making DOS Phantom Memory Resident - The /I Switch16 3.11. Removing DOS Phantom From Memory - The /U Switch..16 3.12. Using The /O Switch...............................17 3.13. The Disk Write Trigger Value - The /T Switch......17 3.14. Autonomous Mode - the /N Switch...................18 4. Using Hot Keys To Start Playbacks....................19 5. Scheduling Recordings for Later Playback.............21 iii DOS Phantom V2.9 Users Guide 6. Converting ASCII Text Files for Playback.............24 7. The P2FLUSH Program..................................26 8. Scraper..............................................27 9. Editing DOS Phantom Recordings.......................30 9.1. Eliminating Help Text..............................34 9.2. DOS Phantom Directives.............................34 9.2.1. $PAUSE, $WAIT, and $SLEEP - Programmed Pauses....34 9.2.2. Ending Pauses - $ResumeKey.......................36 9.2.3. Substitution Parameters..........................36 9.2.4. Compressed Mode..................................37 9.2.5. Pop-Up Displays..................................38 9.2.6. Labels and the $GOTO Directive...................41 9.2.7. Pop-Up Menus.....................................41 9.2.8. The $IfKey Directive.............................45 9.2.9. Programmed Screen Capture........................47 9.2.10. Programmed Print Capture........................48 9.2.11. Pacing..........................................48 9.2.12. Matching Screen Text............................49 9.2.13. Waiting for Program Exit........................51 9.2.14. Detecting Exit Status...........................52 9.2.15. Disabling Keyboard Input - $DisableKybd.........53 9.2.16. Flushing the Typeahead Buffer - $FlushTypAhd....54 9.2.17. Disabling Ctl-Alt-Del...........................54 9.2.18. Programmed Reboots - $Reboot....................54 9.2.19. Retaining Keyboard Flags - $RetainKybdFlags.....54 9.2.20. Using the $SETMODE Directives...................55 9.2.21. String Variables................................56 9.2.22. Working with Files..............................57 9.2.23. Substrings - The $F Directives..................59 9.2.24. Iterated Looping - the $On Directive............61 9.2.25. Playing Music - The $Music Directive............62 9.3. Hints and Tips.....................................62 9.3.1. Interrupting Directive Execution.................62 9.3.2. Recovering Editing Sessions......................63 9.3.3. Using DOS Phantom in Batch Files.................63 9.3.4. Playback Chaining................................63 9.3.5. Don't Use the Mouse..............................63 10. DOS Phantom Technical Information...................64 10.1. DOS Version Requirements..........................64 10.2. Memory Usage......................................64 11. License, Warranty, Registration, and Support........65 iv DOS Phantom V2.9 Users Guide 11.1. License...........................................65 11.2. Limited Warranty..................................66 11.2.1. Government Restricted Rights....................67 11.3. Registration......................................67 11.4. Support...........................................68 11.4.1. P2 Technical Support............................68 11.4.2. The P1 Systems Customer Service BBS.............68 11.4.3. The ASP Ombudsman...............................69 v DOS Phantom V2.9 Users Guide 1. What Is DOS Phantom? DOS Phantom is a full-featured task automator and application integration tool which can perform a large number of functions to make life with your computer easier and more efficient. DOS Phantom can be used to make a group of separate application programs work together to perform a task automatically. DOS Phantom does the following: o Records and plays back keystrokes either with the original delays between keystrokes or at high speed. o Provides unlimited recording length (actually limited by the amount of available disk space). o Allows the definition of up to 16 hot keys to start playback of specific recordings with a single keystroke. o Allows scheduling of playback on a daily, weekly, or once-only basis. Up to 32 different scheduled events may be defined. o Provides the ability to edit recordings, o Provides the ability to add pop-up displays and pop- up menus to recordings, 1 DOS Phantom V2.9 Users Guide o Provides the ability to wait during playback for a certain character sequence to appear on the screen, o Provides the ability to wait during playback for a program to exit and detect whether a success or error status was returned, o Captures the screen contents and writes it to a file at the press of a hot key or as directed by the contents of a recording file, o Captures output destined for the printer and writes it to a file (can be turned on and off from within a recording file), o Can read and write files from within a playback, o Can copy screen text and write it to a file, o Can copy screen text from one application and use it as keyboard input to another, and o Play music. 1.1. What is DOS Phantom Good For? 1.1.1. Recovery from Power Failures Because DOS Phantom writes your recorded keystrokes to the disk after every 32 keystrokes, if you were recording when your system failed, you can just playback the recording file, recovering everything except perhaps the last 31 keystrokes. This can be tremendously useful during long editing sessions, eliminating the need to periodically save your work to avoid losing it in a system crash. 2 DOS Phantom V2.9 Users Guide You can even change the number of keystrokes which triggers the write to the disk and set it as low as one keystroke, although this can generate a inordinate amount of disk activity. 1.1.2. A Batch Substitute DOS Phantom can be used in place of simple batch files, eliminating the need to prepare the batch files with an editor -- You just show DOS Phantom what you want done, and DOS Phantom can do it for you after that. You can even edit your DOS Phantom recordings if you make a mistake during the recording. You can also perform parameter substitution similar to that available with MS-DOS batch files. 1.1.3. Keystroke Macros Using the HOTFILE program (included with DOS Phantom), recording files can be assigned to hot keys, allowing the entire recording to be played back with a single keystroke. Up to 16 hotkeys can be defined. The hotkeys work even when you're running a program. 1.1.4. Program Startup DOS Phantom can be used to automatically supply input to programs which expect to receive keyboard input (programs such as spreadsheets and others). It can thus be used to perform a sequence of "startup" commands which you would otherwise have to type each time you run the program. 1.1.5. Automatic Execution You might record the keystrokes to run your spreadsheet, load current stock quotes, print a graph, and exit. You only have to do it once; DOS Phantom can do it after that. And you can start it all with a single keystroke! 3 DOS Phantom V2.9 Users Guide DOS Phantom can be used to automate access to systems such as Prodigy which normally require your presence at the keyboard. Record the keystrokes that you use to dial Prodigy and print headline news and current stock quotations. Then have your computer wake up early and call Prodigy. You can have the latest information printed and waiting for you to peruse with your morning coffee. 1.1.6. Demos DOS Phantom can be used to create a quick demonstration of a program which can then be played back at will for prospective users or customers. DOS Phantom can be paused automatically or manually during playback for discussion or manual entry of data to the program being demonstrated. In addition, pop-up windows can be displayed to explain what is happening in the demo, and menus can be presented to allow the user to guide the course of the demo. Automatic timeouts when user response is required and a looping playback feature allow DOS Phantom-based demos to run continuously and unattended and yet allow users to interact with the demonstration if they wish. 1.1.7. Software Testing DOS Phantom can be used to record tests of software which is undergoing revision. Then, the tests can be run after the revisions are complete to be sure what worked before the revisions were done still works after the revisions. Screen contents can be written to a file at strategic points during the execution of the program and printer output can be captured as well. This allows the output of the program to compared with earlier test runs to detect differences. 1.1.8. Applications Integration DOS Phantom can be used as the "glue" to marry a collection of disparate programs into a complete package to solve a problem. For example, the shareware product QuickPro Retriever uses DOS Phantom to automatically update investment prices in Quicken (a finance management program from Intuit) with information from 4 DOS Phantom V2.9 Users Guide Prodigy's on-line stock market quote facility. DOS Phantom's ability to search out text on the screen and verify termination status of programs gives it a significant advantage over "blind playback" utilities which blithely continue delivering keystrokes even when the programs they are running have gone awry. The Scraper TSR (supplied with DOS Phantom) works with DOS Phantom to allow copying text displayed on the screen by one program and supplying it later as input to another program. Up to nine text strings can be be copied from the screen and stored for later playback. Scraper allows you to select the text and play it back while DOS Phantom is recording. Then, when you play the Phantom recording back, Scraper goes through the same motions. This eliminates the necessity of specifying screen coordinates and lengths for the copy operation as is required in some other packages. The strings copied from the screen by Scraper are also available from within the Phantom playback file, so you can write them to a file, compare them with other strings, extract substrings from them and perform other programmatic operations using DOS phantom's powerful script language. 5 DOS Phantom V2.9 Users Guide 2. What is Shareware? Shareware distribution gives users a chance to try software before buying it. If you try a shareware program and continue using it, you are expected to register. Individual programs differ on details -- some request registration while others require it, some specify a maximum trial period. With registration, you get anything from the simple right to continue using the software to an updated program with printed manual. Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware. Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee -- if you don't use the product, you don't pay for it. 6 DOS Phantom V2.9 Users Guide 3. Using DOS Phantom 3.1. Before You Begin Before using DOS Phantom, we recommend that you create a directory for your recording files and set the PHANTOMDIR environment variable to point to it. Assuming that you want to store your recording files in C:\PHANTOM, here is the command to create the directory and set the PHANTOMDIR environment variable appropriately: C:\> MKDIR PHANTOM C:\> SET PHANTOMDIR=C:\PHANTOM You should place the second command above in your AUTOEXEC.BAT file so that the PHANTOMDIR environment variable gets set each time you boot your computer. The environment variable PHANTOMDIR is used by DOS Phantom to determine where to place playback files and by the HOTFILE and SCHEDULE programs to determine where to store their data files and where to find playback files. Once PHANTOMDIR is defined, DOS Phantom expects to place all recording files there. You should not include disk or directory information in the filenames you supply DOS Phantom for recording or playback. 7 DOS Phantom V2.9 Users Guide You may wish to place the DOS Phantom executable files (PHANTOM2.EXE, TXT2PTM.EXE, PTM2TXT.PTM, HOTFILE.EXE, SCHEDULE.EXE, P2FLUSH.EXE, and SCRAPER.EXE in the same directory. If you do this, add the PHANTOMDIR directory to the PATH definition in your AUTOEXEC.BAT file. (You may change the names of the .EXE files with the DOS REN command to eliminate conflicts with names of other products' programs or just to make them easier to type.) Here's how your PATH definition might appear before you add the PHANTOM directory to it: PATH=C:\DOS;C:\WINDOWS;C:\ The path consists of a list of DOS directories separated by semicolons. When you type the name of a program at the DOS prompt, if it can't find a file by that name in the current directory, DOS searches the directories in the path in the order they are listed. Here's how the example PATH statement above might be changed to incorporate the PHANTOM directory: PATH=C:\DOS;C:\WINDOWS;C:\PHANTOM;C:\ 3.2. The DOS Phantom Command Line 3.2.1. Basic Command Switches DOS Phantom accepts the following basic command line switches: /P Playback /R Record /Q Quick Playback /L Looping Playback /I Install as a Memory Resident Program /U Un-install DOS Phantom from memory 8 DOS Phantom V2.9 Users Guide 3.2.2. Other Command Switches In addition, the following command line switches are also available: /K Attention Hot Key Selection /A Abort Hot Key Selection /D Screen Capture Hot Key /S Toggle Sounds /-S Disable Sounds /M Toggle Mode Display /-M Disable Mode Display /C Disable use of Color /O Include Screen Output Records in Recordings /V Print Capture File Specification /F Screen Capture File Selection /E Sets environment space in shells spawned by Phantom /Z Suppresses all DOS Phantom-generated output (copyright notices, etc.) /T Set trigger count for disk writes when recording /B Set Scraper hot key /N Enable Autonomous Mode Here's an example of a DOS Phantom command to begin recording and create the file RECORDNG.PTM: PHANTOM2 /R RECORDNG.PTM 9 DOS Phantom V2.9 Users Guide Here's the command to play back those keystrokes: PHANTOM2 /P RECORDNG.PTM 3.3. Recording and Playing Back DOS Phantom normally creates a new command shell when you start recording. (The /I switch can be used to make DOS Phantom install itself as a TSR instead.) DOS Phantom will record everything you type until you exit the shell by typing EXIT at the DOS command prompt. Here's an example of recording a DIR command followed by a playback of the recording: Record the keystrokes: C:\> PHANTOM2 /R RECORDNG.PTM DOS Phantom V2.9 123456 Copyright (c) 1992...blah...blah... Press ALT-P to pause or resume recording. Press ALT-P twice in succession to activate the control panel. Type EXIT at the DOS prompt when done. C:\> DIR ...blah blah blah... C:\> EXIT DOS Phantom terminated. Now play them back: C:\> PHANTOM2 /P RECORDING.PTM DOS Phantom V2.9 123456 Copyright (c) 1992...blah...blah... Press ALT-P to pause or resume playback. Press ALT-P twice in succession to activate the control panel. Type EXIT at the DOS prompt when done. C:\> DIR ...blah blah blah... C:\> EXIT DOS Phantom terminated. 10 DOS Phantom V2.9 Users Guide While DOS Phantom was running, it placed a small display in the upper right corner of the screen showing what it was doing. In the example above, the display showed either "Record" or "Play". If you don't want the mode display, just include the /M switch on the command line, like this: C:\> PHANTOM2 /P /M RECORDNG.PTM Note that the /M switch is a "toggle", meaning that if the feature is on it is turned off, and if it is off it is turned on. To unconditionally set the mode display off, use /-M. 3.4. Pausing If you press the hot key (ALT-P unless you change it with /K on the command line) during record or playback, after a brief delay, DOS Phantom will play a series of tones falling in pitch to indicate its transition to PAUSE mode. The mode display, if enabled, will change to "Pause". A second depression of the hot key resumes the recording or playback, accompanied by a series of rising tones indicating the transition out of PAUSE mode. If you are playing back, playback stops while you are in PAUSE mode. If you are recording, the keys you press while paused are not recorded, nor is the time which passes while in PAUSE mode recorded. You can disable the sounds by including the /S switch on the DOS Phantom command line, like this: C:\> PHANTOM2 /R /S RECORDNG.PTM Note that the /S switch is a "toggle", meaning that if the feature is on it is turned off, and if it is off it is turned on. To unconditionally set the sounds off, use /-S. 11 DOS Phantom V2.9 Users Guide 3.5. Quick Playback - The /Q Switch DOS Phantom normally plays back recordings at the same speed at which they were recorded. The /Q switch forces DOS Phantom to playback as quickly as possible. Note that some programs "eat" characters if they are delivered too fast. DOS Phantom's "demand playback" feature, introduced in V1.3, eliminates most problems in this area, but some programs, notably Prodigy, may still eat characters occasionally. For Prodigy and other programs which still appear to eat characters, edit your recording to use the $SetMode Func6 and $SetMode Normal directives as described later in the section on editing DOS Phantom recordings if you wish to use quick playback with those programs. You can alter the intervals between individual keystrokes to speed up some sections of a recording and slow down others by editing the recording file. See the section later in this document on editing DOS Phantom recordings for details. 3.6. Looping Playback - The /L Switch If you supply the /L switch on the command line, DOS Phantom will rewind when it reaches the end of the recording and play the same recording file over and over until you pause it by pressing the attention hot key. If DOS Phantom is memory- resident (see below), you must close the recording file to avoid the continuation of looping when you press the hot key again. If DOS Phantom is not memory-resident, then you must type EXIT at the DOS prompt. Looping can be a valuable tool in continuously-running demonstrations or in stress-testing software systems. Not that looping playback may also be accomplished using the $Goto and $On directives in the recording file. See the section on editing recording files for more information. 3.7. The DOS Phantom Control Panel If you hit the hot key twice within about a half second, the pop-up control panel is triggered, and is displayed over whatever was already on the screen. 12 DOS Phantom V2.9 Users Guide To remove the control panel without taking any action, press the Esc key. Note that if your screen is in graphics mode, the screen may not be restored to its original condition when you leave the control panel, or the control panel may not appear at all. Here is what the control panel looks like: +----------------------------------------------------+ | DOS Phantom V2.9| +----------------------------------------------------+ | | | +---------+ +---------+ +---------+ +--------+ | | | | | | | | | | | | | PLAY | | QPLAY | | RECORD | | CLOSE | | | | | | | | | | | | | +---------+ +---------+ +---------+ +--------+ | | | | Sound On Mode Display On Loop Mode Off | | | | Filename: RECORDNG.PTM | | | +----------------------------------------------------+ You can highlight the selection of your choice using the arrow, tab, or spacebar keys and press RETURN to execute it or you can press the key corresponding to the first letter of your selection. If you press R, P, or Q, the menu is immediately erased, and DOS Phantom begins executing your command. CLOSE closes an open recording file. This is the only way to close a recording file during recording or playback when DOS Phantom is memory- resident (i.e., installed with the /I command line switch). The Sound, Mode Display, and Loop Mode selections toggle the sounds, mode display, and looping on and off. Selecting Filename allows you to change the recording filename. When you have finished entering the filename, press RETURN. To change an existing filename, just type over it and overwrite any unwanted characters with the space bar. 13 DOS Phantom V2.9 Users Guide Pressing the ESC key erases the menu without starting a recording or playback session. 3.8. Changing The Hot Keys There are four hot keys used by DOS Phantom. By default, two of them are disabled (set to the key NONE). The four hot keys are: o The attention hot key - This is by default set to Alt-P and is used to pause and resume recordings, and to cause display of the DOS Phantom control panel as described earlier. The /K command line switch is used to change the attention hot key to another key or to disable it. o The screen capture hot key - This key is by default disabled. When it is defined with the /D command, pressing it at any time causes DOS Phantom to write a copy of the screen to the file specified with the /F command line switch. If no file was specified with /F, the default file SCREEN.TXT is used. o The abort hot key - The abort hot key, when defined with the /A command line switch, causes immediate termination of playback. In addition, the abort key is passed on to the program which is running (or the DOS command processor if no program is running). This is not true of the other hot keys -- they are "eaten" by DOS Phantom. The most common abort hot key is Ctrl-C. This allows a single keystroke to both terminate playback and the program running. o The Scraper hot key - The Scraper hot key (by default Alt-S) activates the Scraper program. See the section on Scraper for information about the Scraper program. The Scraper hot key is automatically disabled whenever Scraper is not installed. The Scraper hot key is set with the /B command line switch. Here's how you would change the attention hot key to F10: C:\> PHANTOM2 /K=F10 /R RECORDNG.PTM 14 DOS Phantom V2.9 Users Guide Here is a list of all the acceptable hot keys which you can specify with /K, /D, /A, and /B: SHFT-TAB ALT-Q ALT-W ALT-E ALT-R ALT-T ALT-Y ALT-U ALT-I ALT-O ALT-P ALT-A ALT-S ALT-D ALT-F ALT-G ALT-H ALT-J ALT-K ALT-L ALT-Z ALT-X ALT-C ALT-V ALT-B ALT-N ALT-M F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 HOME UP PGUP LEFT RIGHT END DOWN GDWN INSERT DELETE SHFT-F1 SHFT-F2 SHFT-F3 SHFT-F4 SHFT-F5 SHFT-F6 SHFT-F7 SHFT-F8 SHFT-F9 SHFT-F10 CTRL-F1 CTRL-F2 CTRL-F3 CTRL-F4 CTRL-F5 CTRL-F6 CTRL-F7 CTRL-F8 CTRL-F9 CTRL-F10 ALT-F1 ALT-F2 ALT-F3 ALT-F4 ALT-F5 ALT-F6 ALT-F7 ALT-F8 ALT-F9 ALT-F10 CTRL-LEFT CTRL-RIGHT CTRL-END CTRL-PGDWN CTRL-HOME ALT-1 ALT-2 ALT-3 ALT-4 ALT-5 ALT-6 ALT-7 ALT-8 ALT-9 ALT-0 ALT-- ALT-= CTRL-PGUP CTRL-A CTRL-B CTRL-C CTRL-D CTRL-E CTRL-F CTRL-G CTRL-H CTRL-I CTRL-J CTRL-K CTRL-L CTRL-M CTRL-N CTRL-O CTRL-P CTRL-Q CTRL-R CTRL-S CTRL-T CTRL-U CTRL-V CTRL-W CTRL-X CTRL-Y CTRL-Z ESC F11 F12 SHFT-F11 SHFT-F12 CTRL-F11 CTRL-F12 ALT-F11 ALT-F12 NONE 15 DOS Phantom V2.9 Users Guide 3.9. Increasing Shell Environment Space - The /E Switch The /E command line switch is used to increase the environment space for the command shell spawned when DOS Phantom is not executed as a TSR. For example, to set the environment space to 4096 bytes for playback of the file RECORDNG.PTM, you would use the following command: PHANTOM2 /E=4096 /P RECORDNG.PTM 3.10. Making DOS Phantom Memory Resident - The /I Switch If you include the /I switch on the command line, DOS Phantom installs itself as a TSR (Terminate and Stay Resident) program in memory. This method of using DOS Phantom has a number of benefits. Among them are lower memory utilization because no command shell is invoked, faster execution because no loading of the DOS Phantom program is required, and the ability to begin and end recording and playback sessions while executing another program. Once resident, you access DOS Phantom by pressing the hot key twice in succession to trigger the pop-up menu, or by issuing DOS Phantom commands at the DOS prompt. If DOS Phantom is resident, executing Phantom commands at the DOS prompt does not load another copy of Phantom, even if you include the /I switch on the command line. You can install DOS Phantom in your AUTOEXEC.BAT file by including this command (assuming the directory containing PHANTOM2.EXE is in your PATH): C:\> PHANTOM2 /I 3.11. Removing DOS Phantom From Memory - The /U Switch The /U switch un-installs DOS Phantom from memory. When you execute the PHANTOM2/U command, one of two responses will be displayed: 16 DOS Phantom V2.9 Users Guide o DOS Phantom un-installed. - This means that DOS Phantom was successfully un-installed and no trace of its presence remains. o DOS Phantom disabled. Memory not reclaimed. - This means that DOS Phantom was only disabled, and is dormant in memory. This is almost certainly because another TSR was loaded after DOS Phantom which intercepts some of the same interrupts used by DOS Phantom. To remove DOS Phantom, first remove any TSR's loaded after DOS Phantom, and then re-issue the /U command. In some cases, a reboot of your computer may be required to remove a dormant DOS Phantom. 3.12. Using The /O Switch The /O command line switch causes DOS Phantom to include snippets of screen output in the recording file as comments. This is provided to aid users of the $MatchWait directive in creating "interactive" recordings. The use of /O significantly increases the size of the recording file and causes many more disk writes to occur during recording. Its use is discouraged except when you are creating a recording which you intend to edit to include $MatchWait directives. The only way to disable /O is to uninstall DOS Phantom with the /U switch if it was installed as a TSR or the DOS EXIT command if it wasn't. See the chapter on editing DOS Phantom recordings for information on the $MatchWait and related directives. 3.13. The Disk Write Trigger Value - The /T Switch The command line switch /T 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. 17 DOS Phantom V2.9 Users Guide 3.14. Autonomous Mode - the /N Switch The command line switch /N 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 installs DOS Phantom in memory, disables the attention hot key, the mode display, and sounds, begins recording into the 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. In addition, there is no visible or audible indication that DOS Phantom is resident and active. C:\> PHANTOM2 /R/N/S/M/K=NONE/I KEYSTROK.LOG 18 DOS Phantom V2.9 Users Guide 4. Using Hot Keys To Start Playbacks You can assign hot keys to recording files using the HOTFILE program. Once a hot key is assigned to a recording file, pressing the hot key starts playback of the file, even if you are running another program at the time. Of course, DOS Phantom must be installed at the time you press the hot key. The HOTFILE program accepts four commands: ASSIGN, LIST, DELETE, and KEYS. The ASSIGN command lets you assign a hot key to a file. The file must reside in the directory defined by the environment variable PHANTOMDIR. Here's an example assigning the hot key CTRL-B to the recording file BACKUP.PTM: C:\> HOTFILE ASSIGN CTRL-B BACKUP.PTM The LIST command displays a list of the currently defined hot keys and their associated playback files. Here's an example of the LIST command: C:\> HOTFILE LIST HOTFILE V2.9 123456 Copyright (c) blah, blah, blah... No Hotkey Playback file -------------------------------- 1 ALT-F10 MAIL.PTM 2 CTRL-B BACKUP.PTM 19 DOS Phantom V2.9 Users Guide You can delete a hot key assignment with the DELETE command like this: C:\> HOTFILE DELETE CTRL-B HOTFILE V2.9 123456 Copyright (c) blah, blah, blah... Delete assignment of CTRL-B to file BACKUP.PTM (Y)? y C:\> The KEYS command displays a list of the hot keys you can use with HOTFILE. If you type HOTFILE without a command, a help screen is displayed. After you make changes to the hot key assignments, you do not need to unload and reload DOS Phantom in order for the hot keys to become usable. If DOS Phantom is already installed in memory when HOTFILE is run, HOTFILE communicates the changes to DOS Phantom automatically. A maximum of 16 hot key assignments may be made. All of the commands may be abbreviated to a single character. The hot key assignments are stored in a file called HOTKEYS.DAT in the PHANTOMDIR directory. You should not attempt to modify this file using any program other than HOTFILE. If you delete this file, all your hot key assignments will be lost. 20 DOS Phantom V2.9 Users Guide 5. Scheduling Recordings for Later Playback The SCHEDULE program allows you to maintain a schedule of playbacks. Up to 32 schedule items may be created. Playbacks may be scheduled on a daily, weekly, or once-only basis. The SCHEDULE program accepts commands similar to those of the HOTFILE program: ASSIGN, LIST, and DELETE. The ASSIGN command assigns a playback time to a playback file. (The file must be present in the directory defined by the environment variable PHANTOMDIR.) Here are some examples of the ASSIGN command: Play REMINDER.PTM every day at 11:30 am: C:\> SCHEDULE ASSIGN 11:30 REMINDER.PTM Play WKLYBKUP.PTM every Friday at 10:00 pm: C:\> SCHEDULE ASSIGN Fri-22:00 WKLYBKUP.PTM Play GETMAIL.PTM at 3:00 pm on September 20, 1993: C:\> SCHEDULE ASSIGN 9/20/93-15:00 GETMAIL.PTM 21 DOS Phantom V2.9 Users Guide Note that the times use a 24-hour clock and that the dash is required between the day of the week or the date and the time. Here are the abbreviations for the days of the week which SCHEDULE recognizes: Sun Mon Tue Wed Thu Fri Sat Here are the pm hours of the 24-hour clock: noon 12 3pm 15 6pm 18 9pm 21 midnight 00 1pm 13 4pm 16 7pm 19 10pm 22 1am 1 2pm 14 5pm 17 8pm 20 11pm 23 2am 2 The LIST command displays a list of the current schedule. Here is an example of the LIST command: C:\> SCHEDULE LIST SCHEDULE V2.9 922300 Copyright (c) 1992 blah, blah, blah... No When Playback file ------------------------------------ 1 11:30 REMINDER.PTM 2 Fri-22:00 WKLYBKUP.PTM 3 9/20/93-15:00 GETMAIL.PTM To remove an item from the schedule, use SCHEDULE's DELETE command, specifying the date and time of the item to remove, like this: C:\> SCHEDULE DELETE Fri-22:00 After you make changes to the schedule, you do not need to unload and reload DOS Phantom in order for the changes to become effective. If DOS Phantom is already installed in memory 22 DOS Phantom V2.9 Users Guide when SCHEDULE is run, SCHEDULE communicates the changes to DOS Phantom automatically. All of the commands may be abbreviated to a single character. The schedule information is stored in a file called SCHEDULE.DAT in the PHANTOMDIR directory. You should not attempt to modify this file using any program other than SCHEDULE. If you delete this file, the entire schedule will be lost. 23 DOS Phantom V2.9 Users Guide 6. Converting ASCII Text Files for Playback The program MAKEPTM accepts as input any ASCII text file and produces as output a DOS Phantom recording file which, when played back, makes it appear as if the contents of the ASCII text file were being typed in at the keyboard. MAKEPTM allows you to specify the delay in milliseconds between successive characters and the delay in seconds between successive lines of text. If you leave off the delay times, delays of zero are used. Here are some examples of MAKEPTM: Convert LETTER.TXT to LETTER.PTM: C:\> MAKEPTM LETTER.TXT LETTER.PTM Convert LETTER.TXT to LETTER.PTM with 100 ms delay between characters: C:\>MAKEPTM LETTER.TXT LETTER.PTM 100 Convert LETTER.TXT to LETTER.PTM with 100 ms delay between characters and 2 seconds between lines: 24 DOS Phantom V2.9 Users Guide C:\>MAKEPTM LETTER.TXT LETTER.PTM 100 2 Convert LETTER.TXT to LETTER.PTM with no delay between characters, but a 2 second delay between lines: C:\>MAKEPTM LETTER.TXT LETTER.PTM 0 2 The output file can be played back like any DOS Phantom recording. NOTE: When a character delay has been specified, it is not possible to interrupt playback with the attention hot key. MAKEPTM places its output file in the directory designated by the DOS environment variable PHANTOMDIR if it has been defined. 25 DOS Phantom V2.9 Users Guide 7. The P2FLUSH Program The P2FLUSH program, when executed, causes DOS Phantom to flush the record buffer to disk, even if the number of characters which would normally trigger a disk write has not yet been accumulated. P2FLUSH is effective even when DOS Phantom is operating in autonomous mode. 26 DOS Phantom V2.9 Users Guide 8. Scraper 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 actions can be recorded with DOS Phantom and played back later for automatic movement of data from one program into another. This capability dramatically increases DOS Phantom's usefulness for application integration. 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. Here is the command to install DOS Phantom and set the Scraper hot key to F12: C:\> PHANTOM2 /I /B=F12 Scraper is named as it is for the slang term "screen scraping" commonly used to describe Scraper's function of "scraping" the text from the screen for later use. Install Scraper by typing SCRAPER /I at the DOS command line. DOS Phantom must be installed before Scraper can be installed. 27 DOS Phantom V2.9 Users Guide 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 corner of the text you wish to select and then to press Enter. As soon as you press an arrow key, the help window disappears. When you press Enter after moving the cursor to the desired location, 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 (1-9) where you want to begin storing the selected text. The text will be stored in the DOS Phantom string variables beginning with that number. If only one line of text was selected, only the one string variable will be used. If, for example, you selected three lines of text and pressed the number 4, the string variables 4, 5, and 6 would receive the first, second, and third lines of selected text, respectively. The contents of the string variables, if any, are overwritten. (There are a total of nine Phantom string variables numbered 1-9.) To play back the contents of a string variable, invoke Scraper using the hot key and press the number key (1-9) of the string variable whose contents you wish to play. You can play back the contents of string variables which received their contents in ways other than via Scraper as well. For example, a playback file might load the string variables with data for later insertion into a program through the manual use of Scraper. Also, you can use the contents of string variables loaded with Scraper in your Phantom scripts. (See the section on string variables in the chapter on editing Phantom recordings for more information.) To disable the pop-up help windows, install Scraper with the /H switch like this: C:\> SCRAPER/H/I You may un-install scraper using the /U switch. Also, when you un-install DOS Phantom, Scraper will be automatically uninstalled. The /Z switch will cause Scraper to install and uninstall "quietly" without displaying its copyright notice. 28 DOS Phantom V2.9 Users Guide 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. 29 DOS Phantom V2.9 Users Guide 9. Editing DOS Phantom Recordings The program PTM2TXT extracts information from a DOS Phantom recording and places it in a text file for editing. Here is an example of PTM2TXT: C:\>PTM2TXT RECORDNG.PTM RECORDNG.TXT The output text file contains a header with a summary of DOS Phantom script language syntax and directives. It looks like this: !============================================================================ ! DOS Phantom V2.9 ! ! Text translation of recording file hotmenu. ! Translated by PTM2TXT V2.9 #EVAL00. ! ! Line format: ! mm:ss.ttt keystroke eeaa ff ! ! mm:ss:ttt = time interval between the previous keystroke and ! this one. ! mm = minutes ! ss = seconds ! ttt = thousandths of seconds ! ee = extended keycode (optional) ! aa = ASCII code (optional) ! ff = keyboard status flags (optional) 30 DOS Phantom V2.9 Users Guide ! ! The optional fields need not be entered when editing this file. ! Values appropriate for most circumstances will be provided for ! you by TXT2PTM. If you include values for the optional fields, ! Your values will override those which TXT2PTM would provide. ! You should delete the optional fields when changing the keystroke. ! ! Comment lines (lines beginning with !) and empty lines are ignored ! by the TXT2PTM translator. ! ! Lines beginning with an asterisk (*) are processed by TXT2PTM ! without timing information. This allows you to place entire ! commands on one line rather than one character per line. A ! carriage return is automatically placed at the end of * lines ! by TXT2PTM unless the last character on the line is a dollar ! sign. Special character expressions (e.g., ) are ! delimited with angle brackets (<,>). ! ! DOS Phantom directives begin with a dollar sign ($). ! Directives supported by DOS Phantom V2.9 are: ! ! $n Input parameters (n=1-9) ! $Sn String varaibles (n=1-9) ! $Pause [n] n=secs, default is no auto resume ! $Wait mm:ss.ttt mm=min, ss=secs, ttt=ms ! $Sleep [n] n=secs, default is no auto resume ! $ResumeKey [key]... Key to resume Paused condition ! $IfKey