ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

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

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / UTILITY / KEYBOARD / PHANTOM2.ZIP / PHANTOM2.DOC < prev next >

Wrap

Text File | 1991-05-19 | 51.4 KB | 1,567 lines

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., <Ctrl-K>) 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 <label> ! $<label>: ! ! The special characters $, <, and > must be preceded by a ! dollar sign ($) when they are present in an asterisk line. ! Otherwise TXT2PTM will attempt to perform special processing ! erroneously. ! ! 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. ! !======================================================================== 00:01.430 D 2044 60 00:00.165 I 1749 60 00:00.165 R 1352 60 00:00.605 / 352f 60 00:00.220 W 1157 60 $1 00:00.605 <CR> 1c0d 20 00:07.480 e 1265 20 00:00.000 x 2d78 20 00:00.000 i 1769 20 00:00.000 t 1474 20 00:00.000 <CR> 1c0d 20 $Pause 00:00.000 <CR> 1c0d 20 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. 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. An exception to this is when you want to create a programmed pause as described earlier. Some programs may require the actual values for the keyboard scan codes supplied by the BIOS when an extended keycode is not required. In these cases, you must supply the correct values for the eeaa and ff fields. We have not run across such a program to date. - 17 - USING PHANTOM2 Page 3-9 EDITING PHANTOM2 RECORDINGS 14 January 91 Note that if you edit a translated Phantom2 recording files 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. 3.10.1 PROGRAMMED PAUSES The example contains a programmed pause directive after the second <CR>. Pauses may be programmed into the recording file as described in the file header shown above. 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. If the timeout period passes without a key being depressed, the pause is ended and playback resumes. 3.10.2 SUBSTITUTION PARAMETERS The example also contains a substitution parameter directive: $1. This directive causes the first parameter entered on the Phantom2 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 last playback is used. If no parameter was used on the last playback, or if this is the first playback of this Phantom2 session, nothing is substituted for the substitution parameter (i.e., it is as if it was not there). Multiple substitution parameter directives may be placed in an asterisk line. Otherwise, only a single directive is allowed per line. - 18 - USING PHANTOM2 Page 3-10 EDITING PHANTOM2 RECORDINGS 14 January 91 3.10.3 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. Here is the previous example above created using this technique: ! ! Example of the use of * lines. ! * DIR/W $1 $Pause * EXIT * ! ! End of example ! You can mix compressed an 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. 3.10.4 POP-UP DISPLAYS You can cause windows containing test you provide to pop up during playbacks of Phantom2 recordings. These pop-up displays can contain text explaining what the user is seeing in a demonstration, or announce a that a certain operation is about to take place. 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 Phantom2 directives: $BeginDisplay and $EndDisplay. If you want a title to appear in the upper left border of the pop-up - 19 - USING PHANTOM2 Page 3-11 EDITING PHANTOM2 RECORDINGS 14 January 91 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: row - the screen row on which the top pop-up display is to be written. col - the screen column on which the left edge of the pop-up display is to be written. attr - The display attributes to be used for display of your text: 0 Normal 1 Bold 2 Reverse Video 3 Reverse Bold timo - A timeout value in seconds. If the timeout period passes without keyboard input, the display is erased and playback resumes. sr - The character S or R indicating whether you wish other Phantom2 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 Phantom2 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. Phantom2 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 - 20 - USING PHANTOM2 Page 3-12 EDITING PHANTOM2 RECORDINGS 14 January 91 This is just a simple example of a Phantom2 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 | | Phantom2 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 Phantom2 will add 3 columns-worth of border to each line and an extra line at the top and bottom for the border. 3.10.5 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 Phantom2 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 - 21 - USING PHANTOM2 Page 3-13 EDITING PHANTOM2 RECORDINGS 14 January 91 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.) 3.10.6 POP-UP MENUS You can cause menus to pop up during playbacks of Phantom2 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. 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 Phantom2 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 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: 0 Normal 1 Bold 2 Reverse Video 3 Reverse Bold timo - A timeout value in seconds. If the timeout period passes without keyboard input, the display is erased and playback resumes. sr - The character S or R indicating whether you wish other Phantom2 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 Phantom2 - 22 - USING PHANTOM2 Page 3-14 EDITING PHANTOM2 RECORDINGS 14 January 91 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. Phantom2 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). 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 $QUIT Quit $EndMenu $DIR: * dir/w $Goto start $CLEAR: * cls $Goto start $QUIT: * exit - 23 - USING PHANTOM2 Page 3-15 EDITING PHANTOM2 RECORDINGS 14 January 91 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 Phantom2 will add 3 columns-worth of border to each line and an extra line at the top and bottom for the border. 3.10.7 ELIMINATING HELP TEXT If you don't want the detailed help header on 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. Including both /C and /H will result in the smallest possible output from PTM2TXT. Here is an example of both switches being used: C> PTM2TXT /C /H RECORDNG.PTM RECORDNG.TXT .literal Note that the switches to the PTM2TXT command must be separated from the PTM2TXT command and other switches by spaces. When you have finished editing, you can create a recording file using the TXT2PTM program like this: .literal C> TXT2PTM RECORDNG.TXT RECORDNG.PTM - 24 - USING PHANTOM2 Page 3-16 PASSING PARAMETERS TO RECORDINGS ON THE COMMAND LINE 14 January 91 3.11 PASSING PARAMETERS TO RECORDINGS ON THE COMMAND LINE NOTE The programs TXT2PTM and PTM2TXT required to enter substitution parameter directives in Phantom2 recordings are supplied with registered versions of Phantom2 only. If you have placed substitution parameter directives in your recording file (see the previous section), 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. 3.12 WHAT'S BAD ABOUT PHANTOM2? Well, Phantom2 doesn't have the capability to determine if what happened when you recorded the keystrokes is the same thing that is happening when you play them back. It's as if you had to type with your monitor turned off. If things go wrong, Phantom2 just goes right on playing back keystrokes. As the saying goes, the results are unpredictable... To recover an aborted editing session with Phantom2, 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. Batch files, on the other hand, can check the exit status of programs to determine if things are going awry. But, supplying input to a spreadsheet is not something you do with batch files. Also, for simple repetitive tasks, recording what you want done is usually easier than writing and debugging a batch file to do it. Phantom2 doesn't record mouse activity, so you have to do everything you want recorded on the keyboard. - 25 - CHAPTER 4 PHANTOM2 TECHNICAL INFORMATION 4.1 DOS VERSION REQUIREMENTS PHANTOM uses features first made available in MS-DOS V3.0, and will probably not execute properly on prior versions of MS-DOS. 4.2 CALLING PHANTOM2 FROM A USER PROGRAM You can invoke Phantom2 functions from a program using Int 2fh function e1h (passed in register AH). The following subfunctions (passed in register AL) are supported: o 00 - Installation check. . AX = 0001 on return if Phantom2 is resident in memory. . DS:SI = address of null terminated hot-key name in resident Phantom2 . DS:DI = address of null terminated recording file name in resident Phantom2 o 01 - Function request . Call with BX = function mask, CX = INT 16 function 0 return code for the hotkey, DS:DX = address of null-terminated filespec. . Function mask bit definitions: 0 record, 1 play, 2 QuickPlay, 3 Loop, 4 Mode Display Toggle, 5 Sound Toggle, 6 Set Hotkey, 7 Set Filespec - 26 - PHANTOM2 TECHNICAL INFORMATION Page 4-2 CALLING PHANTOM2 FROM A USER PROGRAM 14 January 91 o 02 - Uninstall request. . AX = 0001 on return if the de-installation was successful. . AX = 0002 on return if Phantom2 is not installed as a TSR, but has merely spawned a command shell . AX = ffffh on return if Phantom2 was only disabled, and is now dormant in memory. 4.3 HOW DOES IT WORK? Phantom2 intercepts the BIOS keyboard interrupt and the PC's clock interrupt, and in record mode, copies any keystrokes that it sees along with the number of clock ticks that have accumulated since startup. On playback, Phantom2 substitutes its own interrupt handler for the BIOS keyboard interrupt routine and feeds back the recorded keystrokes at the appropriate times. If Phantom2 runs out of keystrokes to play back, it passes any requests for keyboard input on to the BIOS keyboard interrupt routine. - 27 -