PHANTOM2 The Phantom of the Keyboard II P2 Enterprises P.O. Box 25 Ben Lomond, CA 95005 Phantom2 V1.1 Copyright (c) 1991 P2 Enterprises All Rights Reserved - 1 - PHANTOM V1.1 Page 2 14 January 91 CONTENTS CHAPTER 1 INTRODUCTION 1.1 WHAT IS THE PHANTOM OF THE KEYBOARD II? . . . . . 1-1 1.2 WHAT IS PHANTOM2 GOOD FOR? . . . . . . . . . . . . 1-1 CHAPTER 2 DIFFERENCES BETWEEN PHANTOM V1.0 AND PHANTOM2 CHAPTER 3 USING PHANTOM2 3.1 PHANTOM2'S COMMAND LINE . . . . . . . . . . . . . 3-1 3.2 RECORDING AND PLAYING BACK . . . . . . . . . . . . 3-2 3.3 PAUSING . . . . . . . . . . . . . . . . . . . . . 3-3 3.4 QUICK PLAYBACK . . . . . . . . . . . . . . . . . . 3-3 3.5 LOOPING PLAYBACK . . . . . . . . . . . . . . . . . 3-3 3.6 THE PHANTOM2 CONTROL PANEL . . . . . . . . . . . . 3-4 3.7 CHANGING THE HOT KEY . . . . . . . . . . . . . . . 3-5 3.8 MAKING PHANTOM2 MEMORY RESIDENT . . . . . . . . . 3-5 3.9 REMOVING PHANTOM2 FROM MEMORY . . . . . . . . . . 3-6 3.10 EDITING PHANTOM2 RECORDINGS . . . . . . . . . . . 3-6 3.10.1 PROGRAMMED PAUSES . . . . . . . . . . . . . . . 3-9 3.10.2 SUBSTITUTION PARAMETERS . . . . . . . . . . . . 3-9 3.10.3 COMPRESSED MODE . . . . . . . . . . . . . . . 3-10 3.10.4 POP-UP DISPLAYS . . . . . . . . . . . . . . . 3-10 3.10.5 LABELS AND THE $GOTO DIRECTIVE . . . . . . . . 3-12 3.10.6 POP-UP MENUS . . . . . . . . . . . . . . . . . 3-13 3.10.7 ELIMINATING HELP TEXT . . . . . . . . . . . . 3-15 3.11 PASSING PARAMETERS TO RECORDINGS ON THE COMMAND LINE . . . . . . . . . . . . . . . . . . . . . . 3-16 3.12 WHAT'S BAD ABOUT PHANTOM2? . . . . . . . . . . . 3-16 CHAPTER 4 PHANTOM2 TECHNICAL INFORMATION 4.1 DOS VERSION REQUIREMENTS . . . . . . . . . . . . . 4-1 4.2 CALLING PHANTOM2 FROM A USER PROGRAM . . . . . . . 4-1 - 2 - PHANTOM V1.1 Page 3 14 January 91 4.3 HOW DOES IT WORK? . . . . . . . . . . . . . . . . 4-2 - 3 - CHAPTER 1 INTRODUCTION 1.1 WHAT IS THE PHANTOM OF THE KEYBOARD II? Phantom2 is a shareware keystroke recorder for MS-DOS. In record mode, Phantom2 records every key pressed on your keyboard, whether you are at the DOS command prompt or running a program. Then, in playback mode, Phantom2 plays back the recorded keystrokes exactly as they were originally recorded, with exactly the same timing as when they were recorded. 1.2 WHAT IS PHANTOM2 GOOD FOR? o Recovery After System Crashes or Power Failures Because Phantom2 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. o A Batch Substitute Phantom2 can be used in place of simple batch files, eliminating the need to prepare the batch files with an editor -- You just show Phantom2 what you want done, and Phantom2 can do it for you after that. You can even edit your Phantom2 recordings if you make a mistake during the recording. You can also perform parameter substitution similar to that available with MS-DOS batch files. - 4 - INTRODUCTION Page 1-2 WHAT IS PHANTOM2 GOOD FOR? 14 January 91 o Program Startup Phantom2 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. o 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; Phantom2 can do it after that. Phantom2 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. All you need is a timer to turn on your PC early in the morning and an extra line in your AUTOEXEC.BAT file to run Phantom2. o Demos Phantom2 can be used create a quick demonstration of a program which can then be played back at will for prospective users or customers. Phantom2 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 feature allow Phantom2-based demos to run continuously and unattended and yet allow users to interact with the demonstration if they wish. o Software Testing Phantom2 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 still works after the revisions. - 5 - CHAPTER 2 DIFFERENCES BETWEEN PHANTOM V1.0 AND PHANTOM2 o Quick Playback Phantom2 allows you to play back recordings with no delays between the recorded keystrokes. This can speed execution of Phantom2 recordings when the programs being run do not require paced input. You select quick playback by using the /Q switch instead of the /P switch on the Phantom2 command line. o Pause and Resume Phantom2 allows you to pause and resume recording and playback. The period of time paused in not included in Phantom2's recording. While Phantom2 is paused, you may type at the keyboard just as if Phantom2 were not present. When recording or playback is resumed, Phantom2 picks up where it left off. You can introduce automatic pauses during playback by editing the recording file to insert pause requests wherever desired. o Looping Playback You can cause Phantom2 to restart a playback session automatically when the end of the recording file is reached. The looping continues until the hot key is pressed. This is especially useful for automated demonstrations of software products. o User-Selectable Hot Key You pause and resume Phantom2 by pressing the "hot key". When Phantom2 is in RECORD mode and you press the hot key, the recording is paused. A second pressing of the hot key resumes the recording. Playback mode works similarly. - 6 - DIFFERENCES BETWEEN PHANTOM V1.0 AND PHANTOM2 Page 2-2 14 January 91 You select the hot key by using the /K switch on the command line. For example, to set the hot key to ALT-K, you would include this on the Phantom2 command line: /K=ALT-K. The default hot key is ALT-P. o Sound and Lights Phantom2 signals transitions between modes (The four modes are RECORD, PLAY, PAUSE, and IDLE.) by sounding either a rising or a falling series of tones. A rising series of tones signals a change from IDLE or PAUSE to RECORD or PLAY, while a falling series of tones signals a change to IDLE or PAUSE mode. Keyclicks are heard while in record or playback mode. The current mode is displayed in a reverse-video box in the upper left corner of the screen. The mode display may contain "Record", "Play", "Pause", or "Phantom2". Phantom2 is displayed when Phantom2 is in IDLE mode. You can disable sounds by including the /S switch on the Phantom2 command line, and disable the mode display by including the /M switch. o Pop-Up Phantom2 Control Panel Pressing the hot key twice in rapid succession triggers the display of the Phantom2 control panel. From the control panel you can begin recording or playback, close a recording file, enable or disable sounds and the mode display, or change the recording file name. Pressing ESC erases the control panel. o Memory Residence (TSR) The /I command line switch installs Phantom2 as a TSR (Terminate and Stay Resident) program, eliminating the need to spawn a new command shell and reducing memory requirements. Once resident, Phantom2 is activated by pressing the hot key twice in succession to trigger Phantom2 control panel, or by issuing Phantom2 commands at the DOS prompt. When Phantom2 is resident in memory, you can begin a recording or playback while a program is in progress, rather than only at the DOS prompt. - 7 - DIFFERENCES BETWEEN PHANTOM V1.0 AND PHANTOM2 Page 2-3 14 January 91 Once Phantom2 is resident in memory, Phantom2 commands typed at the DOS prompt are passed to the memory-resident Phantom2 for execution, and do not spawn a new command shell. o Editing of Recording Files The pair of programs PTM2TXT and TXT2PTM extract data from Phantom2 recording files and place it into a text file for editing, and then re-create a Phantom2 recording file from the modified text file. This allows you to prepare recordings for playback without actually executing the commands and to correct errors or make changes to recordings you have made. o Parameter Substitution Special Phantom2 directives which you can add to your recording files allow you to pass parameters to your recording file at playback time, often making single recording do the work of several. This is similar to MS-DOS's batch parameter substitution. o Programmed Pauses You can add automatic pauses to your recordings to allow users to enter data or for discussion during a demonstration. Programmed pauses may have a timeout assigned to them. When the timeout period has passed with no input from the keyboard, the pause is automatically ended, and the playback continues. o Programmed Pop-up Displays You can add pop-up displays to your recordings to inform watchers of the playback what is happening. Text you supply is displayed in a pop-up window, and the playback is paused for a timeout period which you may specify or until a key is depressed on the keyboard. An unlimited number of pop-up displays may added to Phantom2 recordings. o Programmed Pop-up Menus Pop-up menus can be added to your recordings to allow users to direct the course of the playback. Menu text you supply is displayed to the user in a pop-up window. When the user selects a menu item, the playback is resumed at the point in the recording which you have associated with that menu item. - 8 - DIFFERENCES BETWEEN PHANTOM V1.0 AND PHANTOM2 Page 2-4 14 January 91 If the user does not respond within a timeout period you specify, the next menu item is chosen, and the playback resumes. Thus, if the user does nothing, each menu item is selected in turn automatically. An unlimited number of pop-up menus may added to Phantom2 recordings. - 9 - CHAPTER 3 USING PHANTOM2 3.1 PHANTOM2'S COMMAND LINE Phantom2 accepts the following command line switches: /P Playback /R Record /Q Quick Playback /L Looping Playback /K Hot Key Selection /S Disable Sounds /M Disable Mode Display /I Install as a Memory Resident Program /U Un-install Phantom2 from memory Here's an example of a Phantom2 command to begin recording and create the file RECORDNG.PTM: C> PHANTOM2 /R RECORDNG.PTM Here's the command to play back those keystrokes: C> PHANTOM2 /P RECORDNG.PTM - 10 - USING PHANTOM2 Page 3-2 RECORDING AND PLAYING BACK 14 January 91 3.2 RECORDING AND PLAYING BACK Phantom2 normally creates a new command shell when you start recording. Phantom2 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 Phantom2 V1.1 #123456 Copyright (c) 1991...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 Phantom2 terminated. Now play them back: C> PHANTOM2 /P RECORDING.PTM Phantom2 V1.1 #123456 Copyright (c) 1991...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 Phantom2 terminated. C> While Phantom2 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 ant the mode display, just include the /M switch on the command line, like this: - 11 - USING PHANTOM2 Page 3-3 RECORDING AND PLAYING BACK 14 January 91 C> PHANTOM2 /P /M RECORDNG.PTM 3.3 PAUSING If you press the hot key (ALT-P) during record or playback, after a brief delay, Phantom2 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. While in PAUSE mode, Phantom2 "steps aside" and lets all keystrokes (except the hot key) flow freely to the program running. 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 Phantom2 command line, like this: C> PHANTOM2 /R /S RECORDNG.PTM 3.4 QUICK PLAYBACK Phantom2 normally plays back recordings at the same speed at which they were recorded. The /Q switch forces Phantom2 to playback as fast as possible. Many programs have no problem with this. Some programs however, "eat" characters typed while they are busy, and will cause the recording to end prematurely. PRODIGY is an example of a program which does this. To automate a PRODIGY session, timed playback is a requirement. 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 below on editing Phantom2 recordings. 3.5 LOOPING PLAYBACK If you supply the /L switch on the command line, Phantom2 will rewind and play the same recording file over and over until you pause it by pressing the hot key. If Phantom2 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 Phantom2 is not memory-resident, then you must type EXIT at the DOS prompt. - 12 - USING PHANTOM2 Page 3-4 LOOPING PLAYBACK 14 January 91 Looping can be a valuable tool in continuously-running demonstrations or in stress-testing software systems. 3.6 THE PHANTOM2 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. Here is what the control panel looks like: +----------------------------------------------------+ | Phantom2 V1.1 | +----------------------------------------------------+ | | | +---------+ +---------+ +---------+ +--------+ | | | | | | | | | | | | | 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 Phantom2 begins executing your command. CLOSE closes an open recording file - This is the only to close a recording file when Phantom2 is memory-resident. 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. Pressing the hot key or the ESC key erases the menu without starting a recording or playback session. - 13 - USING PHANTOM2 Page 3-5 CHANGING THE HOT KEY 14 January 91 3.7 CHANGING THE HOT KEY The /K command line switch allows you to change the hot key from the default ALT-P. Here's how you would change the hot key to F10: C> PHANTOM2 /K=F10 /R RECORDNG.PTM Here is a list of all the acceptable hot keys which you can specify with /K: 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 PGDWN 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 3.8 MAKING PHANTOM2 MEMORY RESIDENT If you include the /I switch on the command line, Phantom2 installs itself as a TSR (Terminate and Stay resident) program in memory. This method of using Phantom2 has a number of benefits. Among them are lower memory utilization because no command shell is invoked, faster - 14 - USING PHANTOM2 Page 3-6 MAKING PHANTOM2 MEMORY RESIDENT 14 January 91 execution because no loading of the Phantom2 program is required, and beginning and ending of recording and playback sessions while another program is running. Once resident, you access Phantom2 by pressing the hot key twice in succession to trigger the pop-up menu, or by issuing Phantom2 commands at the DOS prompt. 3.9 REMOVING PHANTOM2 FROM MEMORY The /U switch un-installs Phantom2 from memory. When you execute the PHANTOM/U command, one of two responses will be displayed: 1. Phantom2 un-installed. This means that Phantom2 was successfully un-installed. 2. Phantom2 disabled. Memory not reclaimed. This means that Phantom2 was only disabled, and is dormant in memory. This is almost certainly because another TSR was loaded after Phantom2 which intercepts some of the same interrupts used by Phantom2. To remove Phantom2, first remove any TSR's loaded after Phantom2, and then re-issue the /U command. To re-enable Phantom2, simply issue another Phantom2 command other than /U. 3.10 EDITING PHANTOM2 RECORDINGS NOTE The programs TXT2PTM and PTM2TXT required to edit Phantom2 recordings are supplied with registered versions of Phantom2 only. The program PTM2TXT extracts information from a Phantom2 recording and places it in a text file for editing. Here is an example of PTM2TXT: C> PTM2TXT RECORDNG.PTM RECORDNG.TXT - 15 - USING PHANTOM2 Page 3-7 EDITING PHANTOM2 RECORDINGS 14 January 91 The output text file looks like this: !======================================================================== ! P2 PHANTOM V1.0 ! ! Text translation of recording file RECORDNG.PTM. ! Translated by PTM2TXT V1.1 #123456. ! ! 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) ! ! Comment lines (lines beginning with !) and empty lines are ignored ! by the TXT2PTM translator. ! ! Lines beginning with an asterisk (*) are processed by TXT2PTM ! without timing information. This allows you to place entire ! commands on one line rather than one character per line. A ! carriage return is automatically placed at the end of * lines ! by TXT2PTM unless the last character on the line is a dollar ! sign. Special character expressions (e.g., ) are ! delimited with angle brackets (<,>). ! ! Phantom2 directives begin with a dollar sign ($). ! Directives supported by Phantom2 V1.1 are: ! ! $Pause Causes an automatic switch to pause mode during ! playback. The user must press the hot key to ! resume playback. The $Pause directive must ! be placed on a line by itself. ! ! $n Where n is a single digit from 1 to 9 causes ! arguments from the command line to be substituted ! for the $n directive. $1 refers to the first ! command line argument after the filename, $2 the ! second, and so on. The $n directive may be ! within an asterisk line. ! ! $BeginDisplay See the Phantom2 documentation for ! $EndDisplay instructions on using these directives. ! $BeginMenu ! $EndMenu ! $Title - 16 - USING PHANTOM2 Page 3-8 EDITING PHANTOM2 RECORDINGS 14 January 91 ! $Goto