TopWare Tools

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

/ TopWare Tools / TOOLS.iso / tools / top1137 / phantom.doc < prev next >

Wrap

Text File | 1994-01-21 | 130.9 KB | 4,463 lines

DOS Phantom Users Guide DOS Phantom V2.9 Users Guide PUBLISHED BY P2 Enterprises P.O. Box 25 Ben Lomond CA 95005-0025 Copyright (c) 1994 by P2 Enterprises. 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 P2 Enterprises 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., <Ctrl-K>) 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 <label> <key> If last key was <key>, branch to <label> ! ! $BeginDisplay row col attr timo S|R ! $Title text Display title (optional) ! <text> Text for pop-up display ! <text> More text lines... ! $EndDisplay Display text between Begin and EndDisplay ! ! $BeginMenu row col attr timo S|R incr ! $Title text Menu title (optional) ! <lines of text> Static (non-selectable) menu text ! $<label> itemtext Go to <label> when item is selected. ! $<label> itemtext More menu items... ! $EndMenu Ends a menu definition ! ! $Goto <label> Continue execution at <label> ! $<label>: Goto, Menu, or If target ! $ExitWait [n] Wait n secs for program exit ! $IfSuccess <label> Go to <label> if exit status = 0 31 DOS Phantom V2.9 Users Guide ! $IfError Go to <label> if exit status <> 0 ! $IfExitCode n <label> Go to <label> if exit status = n ! $MatchWait n text Wait n secs for text to appear on screen ! $MatchAt r,c n text Wait n secs for text at position r,c ! $MatchFrom r,c n text Wait n secs for text after position r,c ! $MatchTo r,c n text Wait n secs for text before position r,c ! $IfMatch <label> Go to <label> if match found ! $IfTimeout <label> Go to <label> if no match found ! $Screen "text" [file] Write screen to file prefixed with text ! $Printer C [file] Capture printer output in file ! $Printer N Return to normal printer output ! $RetainKybdFlags Restore Insert, NumLock, ScrollLock, CapsLock ! $DisableCtrlAltDel Ignore reboot requests from the keyboard ! $EnableCtrlAltDel Honor reboot requests from the keyboard ! $Reboot Reboot the computer ! $DisableKybd Ignore keyboard input ! $EnableKybd Stop ignoring keyboard input ! $FlushTypAhd Clear keyboard typeahead buffer ! $Assign Sn text Assign text to variable ! $Get Sn r,c len Read text from screen into variable ! $IfEqual label Sn text Branch if Sn equal to text ! $IfEmpty label Sn Branch if variable Sn is empty ! $Clear Sn Clear variable Sn ! $FirstFile Sn text Find first file matching text ! $NextFile Sn Find next file matching FirstFile text ! $On count label Branch to label the count'th time ! $Read file Sn Read one line from file into Sn ! $Write file text[$] Write text to file, $=no newline ! $Close Close file open for reading ! $IfClosed label Branch if read file is closed ! $FSubStr(Sn,start,end) Return substring ! $FBefore(Sn,char) Return substring before char ! $FAfter(Sn,char) Return substring after char ! $Music note/dur... Play note for duration dur ! $Scraper Invoke Scraper ! ! See the DOS Phantom Users Guide for details on using these directives. ! ! The special characters $, <, and > must be preceeded by a ! dollar sign ($) when they are present in an asterisk line. ! Otherwise TXT2PTM will attempt to perform special processing ! erroneously. ! !============================================================================ 00:06.050 D 2044 60 32 DOS Phantom V2.9 Users Guide 00:00.165 I 1749 60 00:00.220 R 1352 60 00:00.770 / 352f 60 00:00.330 W 1157 60 00:00.440 <SP> 3920 60 $1 00:01.210 <CR> 1c0d 60 00:01.210 <CR> 1c0d 60 $Pause 00:01.760 E 1245 60 00:00.275 X 2d58 60 00:00.440 I 1749 60 00:00.330 T 1454 60 00:00.330 <CR> 1c0d 60 The above file depicts a recording of the commands "DIR/W" and "EXIT". As you can see, the carriage return character is translated to <CR> in the file. Spaces are translated as <SP>. Non-printing and special characters such as CTRL-K are all translated in this manner. If you are not sure what the translation of a character might be, it is best to make a recording containing the character and then translate the recording with PTM2TXT to find out what the correct translation is. The line format is as described in the output file shown above. IMPORTANT: If you change a line in the file, it is best, unless you clearly understand the BIOS extended keycodes and keyboard status flags, to remove the eeaa and ff fields. TXT2PTM will supply appropriate values when you leave them out. Note that if you edit a translated DOS Phantom recording file and insert comments and labels, then translate the text file to a recording file and back into a text file, the comments and labels will be lost. PTM2TXT will create labels required by the menu and goto directives in the recording, but they will not be the labels from your original edited text file. Goto and menu directives are discussed below. When you have finished editing, you can create a recording file using the TXT2PTM program like this: C:\> TXT2PTM RECORDNG.TXT RECORDNG.PTM 33 DOS Phantom V2.9 Users Guide 9.1. Eliminating Help Text If you don't want the detailed help header in the PTM2TXT output file, you can specify the /H switch on the command line. This will cause a brief header to be prefixed to the translation rather than the detailed help text shown in the above example. For example: C:\>PTM2TXT /H RECORDNG.PTM RECORDNG.TXT Note that the switches to the PTM2TXT command must be separated from the PTM2TXT command and other switches by spaces. 9.2. DOS Phantom Directives DOS Phantom directives are directions to DOS Phantom that you insert into a recording to have DOS Phantom perform some action during playback. All directives begin with a $. With the exception of the $1-$9, $S1-$S9, and the $F directives, all directives must be the first non-blank word on a line. Each directive is discussed in detail below. 9.2.1. $PAUSE, $WAIT, and $SLEEP - Programmed Pauses The example above contains a programmed pause directive after the second <CR>. Note that programmed pauses (i.e., pauses which occur automatically at predetermined points during playback) may only be created by preparing an input file for TXT2PTM such as that shown above. There is no way to create programmed pauses while recording. The pause directive may be followed by a timeout value expressed in seconds (up to 3600 seconds). If the timeout period passes without a key being depressed, the pause is ended and playback resumes. Each time a key is pressed during the pause, the pause timer is restarted. The $Sleep directive behaves much as the $Pause directive in that playback is suspended for the period of seconds supplied as a parameter to $Sleep. The difference is that the timer used by $Sleep is not reset on each keystroke, so when the 34 DOS Phantom V2.9 Users Guide timeout period has elapsed, playback continues regardless of whether a key has been pressed in the meantime. The number of seconds to pause is a required parameter of $Sleep and it must be in the range of 1 to 3600 (1 hour). If you wish to pause indefinitely, you must use $Pause. As is the case with $Pause, if you need a $Sleep timeout of greater then 3600 seconds, you can place a series of $Sleep statements in your Phantom script which add up to the total time required. The $Wait directive is also available. $Wait accepts the time to wait in mm:ss.ttt format instead of in seconds like $Pause. $Wait cannot be terminated by pressing a key as can $Pause, and unlike $Pause the playback clock continues to run during a $Wait. This can cause the characters following a $Wait to be played back as fast as possible until the playback catches up (makes up for the time lost in the $Wait). $Wait directives are most useful in recordings which are meant to be played back at high speed (e.g., files prepared in compressed mode, described later), but where pauses without allowing keyboard input are required. To create the effect of a $Wait in a file with timed keystrokes without losing time during the wait, just add time to the keystroke which follows the wait. Here is a $Wait which will cause a wait of 3 minutes and 10 seconds (this will cause timed keystrokes following to be played back at high speed until the 3 minutes and 10 seconds are made up for): $Wait 03:10.000 Here is a keystroke which will not be played back until 3 minutes and 10 seconds have passed (no speedup of succeeding keystrokes occurs): 03:10.000 <CR> 35 DOS Phantom V2.9 Users Guide In general, you use $Pause to pause for keyboard input, and $Wait in compressed recordings to stall without keyboard input. 9.2.2. Ending Pauses - $ResumeKey Normally, $Pause and $Sleep are terminated only when the timeout period has expired or when you use the attention key. The $ResumeKey directive allows you to specify other keys which can be used to end the pause and resume playback. Here is an example of $ResumeKey being used to allow the F12, Alt-F12, or Ctrl-F12 keys to end the pause: $ResumeKey <F12> <Alt-F12> <Ctrl-F12> $Pause The key list contains the names of keys separated with a single space. These "resume keys" remain in effect until you change them with another $ResumeKey directive or until you cancel them using a $ResumeKey directive with no arguments. The special "$ResumeKey Any" directive can be used to allow any keystroke to end the pause. Unlike other resume key assignments, the $ResumeKey Any is cancelled automatically as soon as it is used to terminate a $Pause or $Sleep. See the description of the $IfKey directive for information on how to determine which resume key was used to end a pause. 9.2.3. Substitution Parameters The example also contains a substitution parameter directive: $1. This directive causes the first parameter entered on the DOS Phantom command line after the filename to be substituted for the $1 during playback. Up to nine substitution parameters ($1, $2, $3, ..., $9) may be used. If a corresponding command line parameter is not supplied for playback, the parameter used on the previous playback is used. If no parameter was used on the previous playback, or if this is the first playback of this DOS Phantom session, nothing is substituted for the substitution parameter (i.e., it is as if it was not there). 36 DOS Phantom V2.9 Users Guide Multiple substitution parameter directives may be placed in an asterisk line. Otherwise, only a single directive is allowed per line. Asterisk lines and compressed mode are discussed in the next section. If you have placed substitution parameter directives in your recording file you may pass the values to be substituted for them on the command line after the filename. Here is an example passing the parameters A:, XYZ, and BOOBOO: C:\>PHANTOM2/Q/I/K=F1 RECORDNG.PTM A: XYZ BOOBOO A: is substituted for $1, XYZ for $2, and BOOBOO for $3. 9.2.4. Compressed Mode You may avoid typing in the time fields (mm:ss.ttt) by starting lines with an asterisk. Lines starting with an asterisk are referred to as being in "compressed" mode. When TXT2PTM processes lines beginning with an asterisk, it behaves as if each character was on a separate line and preceded with "00:00.000". TXT2PTM automatically inserts a <CR> at the end of each * line. You can suppress the automatically added <CR> by ending the asterisk line with a $. Here is the previous example created using this technique: ! ! Example of the use of * lines. ! * DIR/W $1 * $Pause * EXIT ! ! End of example ! 37 DOS Phantom V2.9 Users Guide You can place substitution parameter directives anywhere in a asterisk line. The characters "<", ">", and "$" must be preceded with a $ if you don't want DOS Phantom to handle them specially. For example, if I wanted DOS Phantom to play "Hello, World" followed by an Alt-F5 and then "The amount <is> $2.00." without a carriage return at the end, I would use the following asterisk line: * Hello, World<Alt-F5>The amount $<is$> $$2.00.$ You can mix compressed and non-compressed modes in the same text file. You can cause PTM2TXT to produce compressed mode output from your recordings by including the /C switch on the command line like this: C:\> PTM2TXT /C RECORDNG.PTM RECORDNG.TXT Note that the switches to the PTM2TXT command must be separated from the PTM2TXT command and other switches by spaces. 9.2.5. Pop-Up Displays You can cause windows containing text you provide to pop up during playbacks of DOS Phantom recordings. These pop-up displays can contain text explaining what the user is seeing in a demonstration, announce a that a certain operation is about to take place, or instruct the user to perform some action. When a pop-up display is displayed, playback is halted until the user presses any key or until a timeout period which you specify has elapsed. The text which you wish to appear in a pop-up display is placed between two DOS Phantom directives: $BeginDisplay and $EndDisplay. If you want a title to appear in the upper left 38 DOS Phantom V2.9 Users Guide border of the pop-up display, you may include a $Title directive on the line following the $BeginDisplay directive. The $BeginDisplay directive takes the following form: $BeginDisplay row col attr timo sr The parameters following the directive are interpreted as follows: o row - the screen row on which the top pop-up display is to be written. o col - the screen column on which the left edge of the pop- up display is to be written. o attr - The display attributes to be used for display of your text: Attribute Mono Display Color Display --------- -------------- ----------------------- 0 Normal Gray on Blue 1 Bold White on Blue 2 Reverse Video Dark Gray on Light Gray 3 Reverse Bold Black on Light Gray 8 Normal Normal 9 Bold Bold o timo - A timeout value in seconds. If the timeout period passes without keyboard input, the display is erased and playback resumes. The maximum timeout value is 3600 seconds (1 hour). o sr - The character S or R indicating whether you wish other DOS Phantom displays and menus which may be present on the screen to be erased before this window is displayed. R restores the screen to what it was before any DOS Phantom displays or menus were popped-up. S saves the screen as it is and causes the new display to be painted over anything currently shown on the screen. 39 DOS Phantom V2.9 Users Guide DOS Phantom pop-up displays are automatically erased when playback is resumed. The text you wish to appear in the pop-up display is placed between the $BeginDisplay and $EndDisplay directives.Here is an example of the directives used to create a pop-up display: ! ! Create a display at row 5, column 20, reverse video, ! 2-minute timeout and erase any currently displayed pop-ups. ! $BeginDisplay 5 20 2 120 R $Title Sample Pop-Up Display This is just a simple example of a DOS Phantom pop-up display. (Press any key to continue.) $EndDisplay Here's how the above pop-up display would appear on the screen (at row 5, column 20): +--Sample Pop-Up Display---------------+ | | | This is just a simple example of a | | DOS Phantom pop-up display. | | | | (Press any key to continue. | +--------------------------------------+ Note that when you specify the row and column for the display you should take into account that DOS Phantom will add 3 columns-worth of border to each line and an extra row at the top and bottom for the border. 40 DOS Phantom V2.9 Users Guide 9.2.6. Labels and the $GOTO Directive You can cause playback to transfer from one place in a recording file to another by using the $Goto directive. The $Goto directive has a single parameter: the label of the location from which playback is to continue. Labels in DOS Phantom recording files take the form $<text>: where <test> is any printable text string not starting with a digit and not containing spaces or tabs. Here is an example of a recording which continually clears the screen and the displays the current directory: ! ! Endless loop directory ! $Loop: * CLS * DIR /W $Goto Loop Note that the colon following the label is not included when the label is the parameter of the $Goto directive. The $Goto is most useful for returning to a pop-up menu after the actions requested by the user have been carried out. (Pop- up menus are described in the next section.) 9.2.7. Pop-Up Menus You can cause menus to pop up during playbacks of DOS Phantom recordings. These pop-up menus can contain text and items from which the user may choose. Once an item is selected, playback resumes at the place in the recording file which is associated with that menu selection. 41 DOS Phantom V2.9 Users Guide When a pop-up menu is displayed, playback is halted until the user selects an item or until a timeout period which you specify has elapsed. The text and selection items which you wish to appear in a pop- up menu are placed between two DOS Phantom directives: $BeginMenu and $EndMenu. If you want a title to appear in the upper left border of the pop-up menu, you may include a $Title directive on the line following the $BeginMenu directive. The $BeginMenu directive takes the following form: $BeginMenu row col attr timo sr incr The parameters following the directive are interpreted as follows: row - the screen row on which the top pop-up menu is to be written. col - the screen column on which the left edge of the pop-up menu is to be written. attr - The display attributes to be used for display of your text: Attribute Mono Display Color Display --------- -------------- ----------------------- 0 Normal Gray on Blue 1 Bold White on Blue 2 Reverse Video Dark Gray on Light Gray 3 Reverse Bold Black on Light Gray 8 Normal Normal 9 Bold Bold timo - A timeout value in seconds. If the timeout period passes without keyboard input, the display is erased and playback resumes. The maximum timeout value is 3600 seconds (1 hour). sr - The character S or R indicating whether you wish other DOS Phantom displays and menus which may be present on the 42 DOS Phantom V2.9 Users Guide screen to be erased before this window is displayed. R restores the screen to what it was before any DOS Phantom displays or menus were popped-up. S saves the screen as it is and causes the new display to be painted over anything currently shown on the screen. incr - if specified as 1, the auto-incrementing feature of the menu is disabled, and each time the menu is encountered, the first item will be highlighted. If left off, or specified as zero, each time the menu is encountered, the selected item is incremented. The auto-incrementng feature makes possible unattended demos which cycle through all the menu selections. DOS Phantom pop-up menus are automatically erased when playback is resumed. Menu selection items are placed after the $BeginMenu and the optional $Title directives and after any introductory text you wish to appear above the selection items in the menu window. Menu selection items are prefixed by $<label> where <label> is the label at which playback is to be resumed (or at which another display or menu is defined) if that menu item is chosen. Labels are described in the section on the $Goto directive. Here is an example of the directives used to create a pop-up menu: ! ! Create a menu at row 5, column 20, reverse video, 10-second ! timeout and retain any currently displayed pop-ups. ! $START: $BeginMenu 5 20 2 10 S $Title Sample Pop-Up Menu Choose one of the items below by moving the highlight bar with the arrow keys and pressing RETURN when the item you want is highlighted. $DIR Directory $CLEAR Clear Screen 43 DOS Phantom V2.9 Users Guide $QUIT Quit $EndMenu $DIR: * dir/w $Goto start $CLEAR: * cls $Goto start $QUIT: * exit Here's how the above pop-up menu would appear on the screen (at row 5, column 20): +--Sample Pop-Up Menu----------------+ | | | Choose one of the items below | | by moving the highlight bar | | with the arrow keys and pressing | | RETURN when the item you want | | is highlighted. | | | | Directory | | Clear Screen | | Quit | +------------------------------------+ Note that when you specify the row and column for the menu you should take into account that DOS Phantom will add 3 columns- worth of border to each line and an extra row at the top and bottom for the border. 44 DOS Phantom V2.9 Users Guide 9.2.8. The $IfKey Directive The $IfKey directive can be used to determine what key was used to terminate a $Begin/EndDisplay, a $Pause, or a $Sleep condition. The $IfKey directive takes to following form: $IfKey <label> <key> A branch is taken to the label specified if the key specified was the last key entered at the keyboard. $IfKey is most useful immediately following a pop-up display or $Pause. A series of $IfKey directives can be used to dispatch to another part of the playback script based on which key was pressed. $IfKey can be used in conjunction with $ResumeKey to create the effect of "hot keys" during a Phantom playback. You set up a number of keys to end a $Pause with $ResumeKey and then, when the playback is resumed after the pause, use $IfKey to determine which key was used to resume playback. Here is a phantom playback script containing several uses of $IfKey along with $ResumeKey, $Begin/EndDisplay, and $Pause: ! ! HOTMENU - An example of the use of $ResumeKey and $IfKey ! to implement pop-up display-based menus and playback hot keys. ! ! $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 45 DOS Phantom V2.9 Users Guide ! ! 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 46 DOS Phantom V2.9 Users Guide ! ! 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 9.2.9. Programmed Screen Capture The $Screen directive can be included in a recording file to cause the contents of the screen to be written to a file. You may specify a line of text to appear before each screen in the file, and the name of the file. The $Screen directive takes the following form: $Screen "text" file The text must be placed between quotation marks. It is used to separate a series of screens written to the same file. The file parameter is optional. If it is not present, the file SCREEN.TXT in the current directory is used. If the file, whether specified or defaulted, is not present, it is created. If it is present, the current contents of the screen are appended to the file prefixed by the specified text line. Note that screen capture can also be controlled using the /D and /F command line switches described earlier. 47 DOS Phantom V2.9 Users Guide 9.2.10. Programmed Print Capture The $Printer directive allows you to direct output which would normally go to a printer to a file. You can turn the print capture on and off and specify the file to which printer output is to be directed. The $Printer directive takes the following form: $Printer C file or $Printer N The $Printer C (for Capture) directive enables print capture. If a file is specified, printer output is directed to that file. If no file is specified, the default is PRINTER.TXT. The $Printer N (for Normal) command disables print capture and printer output once again is sent to the printer. Print capture can also be enabled with the /V command line switch. Note: Be sure not to return the printer to normal too soon. The MS- DOS PRINT program (as well as other print spooling TSR's) goes on sending characters to the printer even after control has returned to the command line. If you issue a $Printer N command before PRINT has finished, the remainder of your output may be sent to the printer. 9.2.11. Pacing The $SetPace directive allows you to specify the number of milliseconds which are to elapse between successive keystrokes during playback. This can be useful if you find a compressed or /Q-invoked playback is overrunning a program's capability of accepting input. The $SetPace directive takes the following form: 48 DOS Phantom V2.9 Users Guide $SetPace ms Where ms is the number of milliseconds between keystrokes. The actual delay is rounded to the nearest 55-millisecond boundary as that is the default resolution of the PC's clock. You can disable pacing with $SetPace 0. Note: A playback can not be interrupted using the attention hot key when a $SetPace directive is in effect. Once started, the paced section must play to completion. 9.2.12. Matching Screen Text The directives $MatchWait, $MatchAt, $MatchTo, and $MatchFrom are used to cause a playback to pause until a text string you specify appears on the screen or until a timeout period you specify has passed. The $IfMatch and $IfTimeout directives allow you to determine whether a preceding $MatchWait directive ended with a timeout or a match and goto a label in your recording file depending on which occurred. The $MatchWait directives takes the following forms: $MatchWait timo text $MatchAt r,c timo text $MatchTo r,c timo text $MatchFrom r,c timo text Where timo is the timeout period in seconds, r,c is the screen row and column (1,1 is the upper left corner of the screen) and text is the text string to look for on the screen. The text string may contain spaces, and the special characters <, >, and 49 DOS Phantom V2.9 Users Guide $ need not be prefixed with a $ as is the case elsewhere in recording files. $MatchWait searches for a match anywhere on the screen. $MatchAt searches for a match at the row and column specified only. $MatchTo searches for a match in the portion of the screen before the row and column specified, and $MatchFrom searches for a match in the portion of the screen after the row and column specified. A timeout value of zero disables the timeout, and the $Match directive will wait forever for the text to appear on the screen. $MatchAt can accept a special timeout value: -1. This results in a single test of the screen contents (effectively a timeout of zero). -1 may not be used with the other $Match directives. The $IfMatch and $IfTimeout take a single parameter: the label to go to if a match or timeout occurred, respectively. Here is an example of a recording file segment which executes a DOS DIR command and then waits 10 seconds for the DOS prompt to appear before continuing and issuing an EXIT command. * DIR $MatchWait 10 C:\> * EXIT Here is a more complex example using $IfTimeout. This example issues <CR> characters until the word "Username:" appears on the screen. It then issues the name BILLSMITH and waits for the word "Password:" to appear. If "Password:" does not appear within 5 seconds, it goes back to sending <CR>'s and waiting for "Username:" $LOOP: * <CR>$ $MatchWait 3 Username: $IfMatch CONTINUE $Goto LOOP $CONTINUE: 50 DOS Phantom V2.9 Users Guide * BILLSMITH $MatchWait 5 Password: $IfTimeout LOOP The above is overly complex -- in particular, the $IfMatch followed by the $Goto and the CONTINUE label could all be replaced with just $IfTimeout LOOP. It is shown the way it is so that all the directives described in this section could be used. Note that $MatchWait searches the entire screen for a match, not just what was output since the last keystroke. You need to make sure that the text string you are waiting for isn't already on the screen, or your $MatchWait will appear to terminate prematurely. Also note that the $Match directives are case-sensitive. That is, they do not treat "Username" and "username" as a match. The letters must the same case (upper or lower) for a match to occur. The /O switch is provided to assist you in creating recording files using the $Match directives. /O causes recent screen output to be included in recording files as comments. You can edit these comments into $Match directives without having to remember what was on the screen when you recorded the session. The /O-captured output is far from perfect, and frequently may not be what is really needed in the $Match diectives. Alternatively, you can use the /D command line switch to enable a screen capture hot key and capture the important screens during recording and then refer to them when inserting your $MatchWait directives. Remember that the /O switch creates significant overhead and should only be used when needed. 9.2.13. Waiting for Program Exit The $ExitWait directive causes a playback to pause until the next DOS program exits. This allows you to run a program, turn control over to the keyboard, and resume playback as soon as the program ends. An optional timeout value allows you to resume playback after a number of seconds without keystrokes has passed. The form of the $ExitWait directive is as follows: 51 DOS Phantom V2.9 Users Guide $ExitWait n Where n is the number of seconds to wait before continuing with playback if no keystrokes are detected. You can use the $IfTimeout directive to determine whether a $ExitWait directive terminated because it timed out or because of program exit. Here is an example of running a program called TROJAN and waiting for program exit or 1 minute without keystrokes. If a timeout occurs, a CTRL-C character is delivered to the program to terminate it before continuing. * TROJAN $ExitWait 60 $IfTimeout TERMINATE $CONTINUE: . . . $TERMINATE: * <Ctrl-C>$ $Goto CONTINUE 9.2.14. Detecting Exit Status Many DOS programs return an "exit status" when they terminate indicating whether they were successful in performing whatever function they were supposed to perform. The $IfError and $IfSuccess directives enable you to go to a label depending on the exit status of the last program you ran. Here is the example from the previous section re-coded to take advantage of these directives: 52 DOS Phantom V2.9 Users Guide $LOOP: * TROJAN $ExitWait 60 $IfTimeout TERMINATE $IfSuccess CONTINUE $IfError LOOP $CONTINUE: . . . $TERMINATE: * <Ctrl-C>$ $Goto CONTINUE Note that the $IfSuccess CONTINUE is actually superfluous, since execution would continue at the CONTINUE label anyway. It was included to demonstrate the use of the directive. The $IfSuccess and $IfError simply check for an exit code of zero or anything else (zero indicating success). The $IfExitCode directive allows you to branch to a label depending on whether a specific exit code was returned. The format of the $IfExitCode directive is $IfExitCode n label where n is the exitcode to test for, and label is the label to branch to if the exit code is indeed n. 9.2.15. Disabling Keyboard Input - $DisableKybd The $DisableKybd causes DOS Phantom to ignore keyboard input until the $EnableKybd directive is encountered. This allows you to use $Pause, $MatchWait, and $ExitWait directives without interference. The $DisableKyd directive accepts a single optional parameter: a letter or number designating a key which when depressed will re-enable the keyboard. If no parameter is provided, the only way the keyboard can be re-enabled is with the $EnableKybd directive. Only letters and numbers may be specified in the 53 DOS Phantom V2.9 Users Guide $DisableKybd directive; no Alt or Ctrl key combinations are allowed, and letters are not case-sensitive. 9.2.16. Flushing the Typeahead Buffer - $FlushTypAhd The $FlushTypAhd directive removes any characters which have accumulated in the typeahead buffer and have not been read by a program. 9.2.17. Disabling Ctl-Alt-Del The $DisableCtrlAltDel directive prohibits the rebooting of the computer using the Ctrl-Alt-Del key combination until the $EnableCtrlAltDel directive is encountered. This can be useful to protect critical sections of a playback from accidental rebooting from the keyboard. Of course, the power could still be turned off, or the reset button pressed. 9.2.18. Programmed Reboots - $Reboot The $Reboot directive allows you to reboot your computer from within a DOS Phantom playback file. This can be useful for re- configuring a system at preset times (installing different CONFIG.SYS and AUTOEXEC.BAT files) from a scheduled Phantom playback. 9.2.19. Retaining Keyboard Flags - $RetainKybdFlags Normally, when a playback is complete, DOS Phantom returns the state of the toggle keys Insert, NumLock, ScrollLk and CapsLock to the state they were in before the playback was started. If you wish the keys to remain in the state they were in when the playback ended, use the $RetainKybdFlags directive anywhere in your playback file. 54 DOS Phantom V2.9 Users Guide 9.2.20. Using the $SETMODE Directives The $SetMode directives could have been called the "Prodigy directives" since their usefulness appears to be limited to fast playback into the Prodigy on-line service. Prodigy uses what may be a unique method of obtaining characters from the keyboard which can cause loss of characters during high-speed playback. To ensure against this, the $SetMode Func6 directive should be placed after the command which invokes Prodigy, and the $SetMode Normal command placed just after the command terminating Prodigy. You may not experience difficulties playing back into Prodigy without these directives. If that is the case, ignore this section. If you do experience character loss playing into Prodigy, these directives should solve the problem. Here is an example of the use of the $SetMode directives where Prodigy is invoked, the stock price for IBM is displayed, and Prodigy is terminated. * Prodigy $SetMode Func6 ! ! Prodigy user ID and password ! * HDCK21B<Tab>PASSWORD ! ! Jump to quote check ! * <F6>Quote Check ! ! Display IBM's current price ! * IBM ! ! Give us a chance to read it ! $Wait 00:30.000 ! ! Leave prodigy 55 DOS Phantom V2.9 Users Guide ! * <Shft-Tab><Shft-Tab> * E $SetMode Normal 9.2.21. String Variables V2.9 of DOS Phantom 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. For example, here is an output statement which includes a command line parameter as well as a string variable: * REM The value of $$1 is $1. The value of S3 is $S3. A number of directives are available for dealing with string variables: $Assign Sn <text> Assigns <text> to string variable Sn. <Text> may contain string and command line variables. The contents of Sn, if any, are overwritten. $GetScreen r,c len Sn Reads len characters from the screen at row r column c into string variable Sn. The contents of Sn, if any, are overwritten. $Read <file> Sn Reads a line from file <file> into string variable Sn. The contents of Sn, if any, are overwritten. 56 DOS Phantom V2.9 Users Guide $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.) $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. String variables retain their contents between successive Phantom playbacks if DOS Phantom is not unloaded from memory in between. 9.2.22. Working with Files A number of directives are available for working with files. They are listed here. 57 DOS Phantom V2.9 Users Guide $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. If no more files exist which match the <filename> specified in the last $FirstFile, the string FILE NOT FOUND is returned. $Read <file> Sn Reads a line from file <file> into string variable Sn. The file is opened if this is the first $Read from it. The line must not exceed 80 characters in length. The CR and LF characters are ommitted. When the end of file is reached, $Read automatically closes the file. (The $IfClosed directive can be used to detect this condition.) Subsequent $Reads of the file will begin at the start of the file. $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.) A CR-LF combination (a newline) is suffixed to the text unless the text string is terminated with a $. $Close Closes the file currently open for read, if any. Subsequent reads of the file will begin at the start of the file. 58 DOS Phantom V2.9 Users Guide $IfClosed <label> Branches to <label> if no $Read file is currently open. This directive can be used to detect the end of file when using $Read. The $FirstFile and $NextFile directives which allow you to perform directory searches from within Phantom scripts. 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 called 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: Only one file may be open for read at a time. If a second filename is encountered in a $Read directive, 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. 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. The result of the last $Read is invalid if the file was closed by the $Read. Thus, $IfClosed should be used before making use of lines returned by $Read. 9.2.23. Substrings - The $F Directives V2.9 of DOS Phantom introduces a new type of directive: the $F directive. $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 59 DOS Phantom V2.9 Users Guide directive in the string. $F directives take their arguments in parenthesis immediately following the directive name. No spaces are allowed between the directive name and the leading parenthesis, nor are any spaces allowed between the comma- separated arguments within the parentheses. 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 extract the substring, <start> is the character at which to start extracting (1-based), and <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: 60 DOS Phantom V2.9 Users Guide $Assign S6 $FSubStr(S3,1,8) * rem THE SUBSTRING IS $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 9.2.24. Iterated Looping - the $On Directive V2.9 adds support for looping using the $On directive. The format of the $On directive is: $On <count> <label> When the $On directive has been 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: 61 DOS Phantom V2.9 Users Guide A maximum of 256 $On directives may be used in a single Phantom script. The maximum count value is 32767. 9.2.25. Playing Music - The $Music Directive The $Music directive 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#, Gb, 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" might 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 /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 For those less musically inclined, numbers from 1 to 69 may be used in place of the musical notes. 9.3. Hints and Tips 9.3.1. Interrupting Directive Execution When a series of directives is executed without any intervening keystrokes, the attention hot key may be ignored for an extended period, making it difficult to interrupt the playback. 62 DOS Phantom V2.9 Users Guide 9.3.2. Recovering Editing Sessions To recover an aborted editing session with DOS Phantom, for example, you should make sure that everything is as it was when you started the recording: the same files with the same contents, the same default disk and directory, and so on. 9.3.3. Using DOS Phantom in Batch Files To use DOS Phantom from a batch file, don't use the /I command line switch and end your recordings with the DOS EXIT command. To use scraper from a batch-initiated playback, invoke Scraper from within the playback without the /I switch. When you are done with Scraper, remove it with the DOS EXIT command. Note that there will be two exit commands required to terminate the playback if Scraper is used. 9.3.4. Playback Chaining Beginning with version 2.5, during playback you can chain to another file by invoking Phantom at the DOS command line from within the first file. Note that invoking Phantom for recording from within a playback file is *not* supported. 9.3.5. Don't Use the Mouse DOS Phantom doesn't record mouse activity, so you have to do everything you want recorded on the keyboard. 63 DOS Phantom V2.9 Users Guide 10. DOS Phantom Technical Information 10.1. DOS Version Requirements DOS Phantom uses features first made available in MS-DOS V3.0, and will probably not execute properly on prior versions of MS- DOS. 10.2. Memory Usage DOS Phantom V2.9, when installed as a TSR, uses approximately 40K of memory. 64 DOS Phantom V2.9 Users Guide 11. License, Warranty, Registration, and Support 11.1. License DOS PHANTOM is not and has never been public domain software, nor is it free software. Non-licensed users are granted a limited license to use DOS PHANTOM on a 21-day trial basis for the purpose of determining whether DOS PHANTOM is suitable for their needs. The use of DOS PHANTOM, except for the initial 21-day trial, requires registration. The use of unlicensed copies of DOS PHANTOM by any person, business, corporation, government agency or any other entity is strictly prohibited. A single user license permits a user to use DOS PHANTOM only on a single computer. Licensed users may use the program on different computers, but may not use the program on more than one computer at the same time. No one may modify or patch the DOS PHANTOM executable files in any way, including but limited to decompiling, disassembling, or otherwise reverse engineering the program. A limited license is granted to copy and distribute DOS PHANTOM only for the trial use of customers, subject to the above limitations, and also the following: o DOS PHANTOM must be copied in unmodified form, complete with the provided license and registration information. 65 DOS Phantom V2.9 Users Guide o The full machine-readable DOS PHANTOM documentation must be included with each copy. o DOS PHANTOM may not be distributed in conjunction with any other product without a specific license to do so from P2 Enterprises. o No fee, charge, or other compensation may be requested or accepted, except as authorized below: o Operators of electronic bulletin board systems (sysops) may make DOS PHANTOM available for downloading only as long as the above conditions are met. An overall or time-dependent charge for the use of the bulletin board system is permitted as long as there is not a specific charge for the download of DOS PHANTOM. o Vendors of user-supported or shareware software approved by the ASP may distribute DOS PHANTOM, subject to the above conditions, without specific permission. Non-approved vendors may distribute DOS PHANTOM only after obtaining written permission from P2 Enterprises. Such permission is usually granted. Please write for details (enclose your catalog). Vendors may charge a disk duplication and handling fee, which, when pro-rated to the DOS PHANTOM product, may not exceed eight dollars. 11.2. Limited Warranty THIS PRODUCT IS LICENSED "AS IS" WITHOUT ANY WARRANTY OF ANY KIND INCLUDING, BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ALL OF WHICH ARE EXPRESSLY DISCLAIMED. SHOULD THE PROGRAM PROVE DEFECTIVE, THE PURCHASER ASSUMES THE RISK OF PAYING THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION AND ANY INCIDENTAL OR CONSEQUENTIAL DAMAGES. IN NO EVENT WILL P2 ENTERPRISES BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING 66 DOS Phantom V2.9 Users Guide WITHOUT LIMITATION DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION AND THE LIKE) ARISING OUT OF THE USE OR THE INABILITY TO USE THIS PRODUCT EVEN IF P2 ENTERPRISES HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Use of this product for any period of time constitutes your acceptance of this agreement and subjects you to its contents. 11.2.1. Government Restricted Rights Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subdivision (b)(3)(ii) of the Rights in Technical Data and Computer Software clause at 252.227-7013. Contractor/manufacturer is P2 Enterprises, P.O. Box 25, Ben Lomond, CA 95005-0025. The information in this document is subject to change without notice and does not represent a commitment on the part of P2 Enterprises. 11.3. Registration This program is shareware. It is not free. If, after an evaluation period of 21 days, you wish to continue using this program, you must register and pay the registration fee. The order form at the end of this document may be used to register. In response to your registration, P2 Enterprises will send you a personalized Product Registration Key (PRK) which you can use with the REGISTER program to effect registration of this program. 67 DOS Phantom V2.9 Users Guide Registration suppresses the display of the statements requesting that you register. Registration entitles you to three months of support from P2 Enterprises as described in the following section. Your Product Registration Key can be used to register future versions of this program released within one year at no additional cost. Licenses for unlimited use on a single LAN, licenses for commercial distribution of this product as part of another product and a Programmer's Kit are also available. See the order form at the end of this document for details. 11.4. Support 11.4.1. P2 Technical Support Registered users receive three months of support from P2 Enterprises. P2 Enterprises will answer questions and fix serious bugs during the three month support period. P2 Enterprises may choose not to attempt a fix to a problem involving a specific hardware or software environment or feature. If this is the case, a full refund of the registration fee will be made upon your request. P2 Enterprises may be reached via a VoiceMail system at (408) 336-8080 mailbox 9090, or via CompuServe ID 70621,2475, by Internet mail at p2p2p2@cruzio.santa-cruz.ca.us, or by US Mail at PO Box 25, Ben Lomond CA 95005-0025 USA. The VoiceMail system is in operation between the hours of 6AM and 6PM Pacific Time. 11.4.2. The P2 Enterprises Customer Service BBS P2 Enterprises maintains a dial-in Customer Service BBS. The latest versions of all P2 shareware products are always 68 DOS Phantom V2.9 Users Guide available on the P2 BBS. In addition, lists of frequently asked questions are available for perusal or download. Also, you can upload file to P2 Tech Support if you wish. The BBS is on-line weeknights between 6PM and 6AM and 24 hrs on weekends. (The BBS shares the phone line with our voicemail system.) The number for the P2 Enterprises Customer Service BBS is (408) 336-8080. 11.4.3. The ASP Ombudsman P2 Enterprises is a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442 or send a CompuServe message via CompuServe Mail to ASP Ombudsman 70007,3536. 69 REGISTRATION INFORMATION ====================================================================== P2 Enterprises, P.O. Box 25, Ben Lomond, CA 95005-0025 ====================================================================== PRODUCT REGISTRATION KEYS (PRK) Upon receiving payment for registration, P2 Enterprises will send you by mail a personalized Product Registration Key (PRK) which, used with the Register Main Menu option, will allow you to register your current copy of the software as well as future versions for a period of one year, without additional charge or paperwork. A separate Product Registration Key is required for each copy of the software. (A single copy may be moved from computer to computer, but if it is executed at the same time on different computers, it is regarded as constituting multiple copies requiring multiple registrations.) DISKETTES If you wish, we will mail you diskettes containing the latest version of the product(s) along with your Product Registration Key(s). There is an additional charge of US$4.00 per product for diskettes. Be sure to specify whether you prefer 3-1/2 or 5-1/4 inch diskettes. QUANTITY PURCHASES The order form on the following may be used to purchase multiple copies with discounts as follows: 1 - 5 copies no discount 6 and up 33% discount The name on the order form is the person whose name wil be associated with the Product Registration Key(s). PAYMENT Payment may be by cash, check, postal money order, or credit card. VISA and Mastercard are accepted. Checks denominated in US Dollars must be drawn on a US bank. You may pay with a check denominated in other than US Dollars if you first add 5% to the registration fee before conversion to US Dollars at the prevailing exchange rate. REGISTRATION INFORMATION (continued) REGISTRATION BY PHONE If you are paying by credit card, you may register using our voicemail system weekdays at (408) 336-8080 mailbox 9090. Leave your credit card information and we will call you back with your registration key, usually the same day. You may also register via the P2 Enterprises Customer Service BBS. The BBS is available weeknights between 6PM and 6AM Pacific Time and 24 hours on weekends at (408) 336-8080. (Our voicemail and BBS share the phone line and computer hardware.) AVAILABILITY All orders are shipped within 10 working days after receipt of the registration fee. Most orders are shipped within 48 hours. DOS PHANTOM REGISTRATION AND ORDER FORM ------------------------------------------------------------------- Remit to: P2 Enterprises, P.O. Box 25, Ben Lomond, CA 95005-0025 ------------------------------------------------------------------- Qty Item Price =================================================================== ___ DOS Phantom Single User PRK @ US$40.00 US$_______ ___ DOS Phantom Single User PRK + diskette @ US$44.00 US$_______ ___ DOS Phantom Laser-printed Users Guide @ US$12.00 US$_______ ___ DOS Phantom Quick Reference Booklet @ US$1.00 US$_______ (One FREE with each registration.) ___ DOS Phantom Multi-User LAN License @US$120.00 US$_______ Allows unlimited use on a single LAN. A separate license is required for each LAN installation. ___ DOS Phantom Commercial Distribution @ US$240.00 US$_______ License Allows unlimited distribution of the PHANTOM2.EXE file with another product. Other programs may not be distributed. ___ Borland C Phantom Programmer's Kit @ US$180.00 US$_______ C source code module which performs TXT2PTM translation for use in application programs and a play-only version of PHANTOM2.EXE. No restriction on use for commercial purposes. ___ Microsoft C Phantom Programmer's Kit @ US$180.00 US$_______ Volume Discount US$(______) Outside North America add $3 per diskette or users guide ordered US$_______ California residents add state and county taxes (at least 6.5%) US$_______ Diskette size: ___ 3.5 ___ 5.25 TOTAL US$_______ __Visa __Mastercard __Amex __Discover __DinersClub Account Number____________________________ Expir.Date____________ Name__________________________________________________________ Company__________________________________________________________ Address__________________________________________________________ ________________________________ Phone____________________ Where did you obtain your copy of DOS Phantom?___________________