Best Objectech Shareware Selections

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

/ Best Objectech Shareware Selections / UNTITLED.iso / boss / util / dos / 005 / phantom.doc < prev next >

Wrap

Text File | 1992-11-16 | 97.0 KB | 3,481 lines

DOS PHANTOM V2.6 _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER P2 Enterprises P.O. Box 25 Ben Lomond, CA 95005-0025 VoiceMail (408) 336-8080 mailbox 9090 DOS Phantom V2.6 Copyright (c) 1992 P2 Enterprises All Rights Reserved - 1 - DOS PHANTOM V2.6 Page 2 20 September 92 CONTENTS CHAPTER 1 INTRODUCTION 1.1 WHAT IS DOS PHANTOM? . . . . . . . . . . . . . . . 1-1 1.2 WHAT IS DOS PHANTOM GOOD FOR? . . . . . . . . . . 1-3 CHAPTER 2 NEW FEATURES ADDED IN VERSION 2.3, 2.4, 2.5, AND 2.6 CHAPTER 3 WHAT IS SHAREWARE? CHAPTER 4 LICENSE, WARRANTY, REGISTRATION, AND SUPPORT 4.1 LICENSE . . . . . . . . . . . . . . . . . . . . . 4-1 4.2 REGISTRATION . . . . . . . . . . . . . . . . . . . 4-3 4.3 SUPPORT . . . . . . . . . . . . . . . . . . . . . 4-4 CHAPTER 5 USING DOS PHANTOM 5.1 BEFORE YOU BEGIN . . . . . . . . . . . . . . . . . 5-1 5.2 DOS PHANTOM'S COMMAND LINE . . . . . . . . . . . . 5-2 5.3 RECORDING AND PLAYING BACK . . . . . . . . . . . . 5-4 5.4 PAUSING . . . . . . . . . . . . . . . . . . . . . 5-6 5.5 QUICK PLAYBACK . . . . . . . . . . . . . . . . . . 5-7 5.6 LOOPING PLAYBACK . . . . . . . . . . . . . . . . . 5-8 5.7 THE DOS PHANTOM CONTROL PANEL . . . . . . . . . . 5-9 5.8 CHANGING THE HOT KEYS . . . . . . . . . . . . . 5-10 5.9 MAKING DOS PHANTOM MEMORY RESIDENT . . . . . . . 5-12 5.10 REMOVING DOS PHANTOM FROM MEMORY . . . . . . . . 5-13 5.11 USING THE /O SWITCH . . . . . . . . . . . . . . 5-14 CHAPTER 6 USING HOT KEYS TO START PLAYBACKS - 2 - DOS PHANTOM V2.6 Page 3 20 September 92 CHAPTER 7 SCHEDULING RECORDINGS FOR LATER PLAYBACK CHAPTER 8 CONVERTING ASCII TEXT FILES FOR PLAYBACK CHAPTER 9 EDITING DOS PHANTOM RECORDINGS 9.1 ELIMINATING HELP TEXT . . . . . . . . . . . . . . 9-4 9.2 DOS PHANTOM DIRECTIVES . . . . . . . . . . . . . . 9-5 9.3 $PAUSE AND $WAIT - PROGRAMMED PAUSES . . . . . . . 9-5 9.4 $1 - $9 - SUBSTITUTION PARAMETERS . . . . . . . . 9-7 9.5 COMPRESSED MODE . . . . . . . . . . . . . . . . . 9-8 9.6 POP-UP DISPLAYS . . . . . . . . . . . . . . . . . 9-9 9.7 LABELS AND THE $GOTO DIRECTIVE . . . . . . . . . 9-11 9.8 POP-UP MENUS . . . . . . . . . . . . . . . . . . 9-12 9.9 PROGRAMMED SCREEN CAPTURE . . . . . . . . . . . 9-15 9.10 PROGRAMMED PRINT CAPTURE . . . . . . . . . . . . 9-16 9.11 PACING . . . . . . . . . . . . . . . . . . . . . 9-17 9.12 MATCHING SCREEN TEXT . . . . . . . . . . . . . . 9-18 9.13 WAITING FOR PROGRAM EXIT . . . . . . . . . . . . 9-20 9.14 DETECTING EXIT STATUS . . . . . . . . . . . . . 9-21 9.15 USING THE $SETMODE DIRECTIVES . . . . . . . . . 9-22 9.16 HINTS AND TIPS . . . . . . . . . . . . . . . . . 9-23 9.16.1 RECOVERING EDITING SESSIONS . . . . . . . . . 9-23 9.16.2 USING DOS PHANTOM IN BATCH FILES . . . . . . . 9-23 9.16.3 PLAYBACK CHAINING . . . . . . . . . . . . . . 9-23 9.16.4 DON'T USE THE MOUSE . . . . . . . . . . . . . 9-23 CHAPTER 10 DOS PHANTOM TECHNICAL INFORMATION 10.1 DOS VERSION REQUIREMENTS . . . . . . . . . . . . 10-1 10.2 MEMORY USAGE . . . . . . . . . . . . . . . . . . 10-1 CHAPTER 11 DIFFERENCES BETWEEN DOS PHANTOM V1.4 AND V2.0 - 3 - CHAPTER 1 INTRODUCTION 1.1 WHAT IS DOS PHANTOM? DOS Phantom is a full-featured task automator which can perform a large number of functions to make life with your computer easier and more efficient. 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. o Provides the ability to edit recordings, o Provides the ability to add pop-up displays and pop-up menus to recordings, 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, - 4 - INTRODUCTION Page 1-2 WHAT IS DOS PHANTOM? 20 September 92 o Captures output destined for the printer and writes it to a file (can be turned on and off from within a recording file), - 5 - INTRODUCTION Page 1-3 WHAT IS DOS PHANTOM GOOD FOR? 20 September 92 1.2 WHAT IS DOS PHANTOM GOOD FOR? o Recovery After System Crashes or 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. o 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. o 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. o 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. 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; DOS Phantom can do it after that. And you can start it all with a single keystroke! 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 - 6 - INTRODUCTION Page 1-4 WHAT IS DOS PHANTOM GOOD FOR? 20 September 92 latest information printed and waiting for you to peruse with your morning coffee. o Demos DOS Phantom can be used 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 feature allow DOS Phantom-based demos to run continuously and unattended and yet allow users to interact with the demonstration if they wish. o 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 still works after the revisions. Screens 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. o 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 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. - 7 - CHAPTER 2 NEW FEATURES ADDED IN VERSION 2.3, 2.4, 2.5, AND 2.6 Version 2.3 of DOS Phantom added support for the PHANTOMDIR environment variable, hot files, and playback scheduling: o Use of PHANTOMDIR Environment Variable Starting with V2.3, if the DOS environment variable PHANTOMDIR is set to define a disk and directory path, DOS Phantom and the TXT2PTM and PTM2TXT translators will store recording files in the PHANTOMDIR directory. You no longer need to remember where a particular recording file is and you no longer need to type in long pathnames when your default is not the same as the location of the recording file. If PHANTOMDIR is not set, DOS Phantom behaves as it did before, searching the default directory for recording files unless otherwise instructed. To define PHANTOMDIR as C:\PHANTOM, you would place the following line in your AUTOEXEC.BAT file: SET PHANTOMDIR=C:\PHANTOM Should you wish to remove the environment variable, use the following command: SET PHANTOMDIR= o Hot Files Hot files are recording files whose playback is initiated by the touch of a hot key. This eliminates the need to bring up the DOS Phantom Control Panel and type in the filename or type in the PHANTOM2 play command at the DOS prompt. - 8 - NEW FEATURES ADDED IN VERSION 2.3, 2.4, 2.5, AND 2.6 Page 2-2 20 September 92 The HOTFILE program, included in the DOS Phantom V2.4 kit, allows you to define 16 hot files and associated hot keys. HOTFILE also allows you to list the defined hot files and hot keys, delete hot key assignments, and display a list of the valid hot keys. HOTFILE requires that the PHANTOMDIR environment variable be defined. o Playback Scheduling Version 2.3 introduced the SCHEDULE program. SCHEDULE allows you to schedule playback of up to 16 Phantom recordings. Playback can be scheduled to occur on a daily basis, on a weekly basis, or one time only. SCHEDULE also allows you to list the current schedule and delete scheduled playbacks. Only files placed in the directory defined by the PHANTOMDIR environment variable may be scheduled. Version 2.4 addressed the following bugs which were present in V2.2 but which were reported after V2.3 was released: o Characters with keyboard scan codes under 10h were erroneously given timings of zero by PTM2TXT. o Characters were lost in some recordings when typematic repeat rates of over 15 characters per second were used. Version 2.4 also includes the MAKEPTM program which automatically converts a text file so that it can be played back through DOS Phantom as if it were being typed at the keyboard. MAKEPTM allows you to specify delay between characters and delay between lines. Version 2.5 corrects a problem with MAKEPTM which caused errors when line delays of zero were specified and corrects a bug which caused system hangs under certain circumstances when invalid file specifications were entered for playback. Version 2.5 also incorporates the capability to invoke Phantom from within a playback to "chain" to another file. Note that invoking Phantom to begin recording from within a playback session is not supported. Version 2.6 added support for the F11, F12, SHFT-F11, SHFT-F12, CTRL-F11, CTRL-F12, ALT-F11, and ALT-F12 keys and fixed a bug which caused corruption of the schedule file when recordings were made using the default file RECORDNG.PTM. - 9 - CHAPTER 3 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. - 10 - CHAPTER 4 LICENSE, WARRANTY, REGISTRATION, AND SUPPORT 4.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 not 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 others, subject to the above limitations, and also the following: 1. DOS PHANTOM must be copied in unmodified form, complete with the provided license and registration information. 2. The full machine-readable DOS PHANTOM documentation must be included with each copy. 3. DOS PHANTOM may not be distributed in conjunction with any other product with out a specific license to do so from P2 Enterprises. - 11 - LICENSE, WARRANTY, REGISTRATION, AND SUPPORT Page 4-2 LICENSE 20 September 92 4. 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. 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 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. U.S. 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. - 12 - LICENSE, WARRANTY, REGISTRATION, AND SUPPORT Page 4-3 REGISTRATION 20 September 92 4.2 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 by sending US$25.00 by check or postal money order to DOS Phantom P2 Enterprises P.O. Box 25 Ben Lomond, CA 95005-0025 In response, P2 Enterprises will send you a personalized Product Registration Key (PRK) which you can use with the P2 REGISTER program to effect registration of this program. 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 at no additional cost. Licenses for unlimited use on a single LAN and licenses for commercial distribution of this product as part of another product are also available. Contact P2 Enterprises for details. - 13 - LICENSE, WARRANTY, REGISTRATION, AND SUPPORT Page 4-4 SUPPORT 20 September 92 4.3 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, or by US Mail at PO Box 25, Ben Lomond CA 95005-0025 USA. The VoiceMail system is in operation between the hours of 5AM and 5PM Pacific Time. 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. - 14 - CHAPTER 5 USING DOS PHANTOM 5.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 PHANTOMDIR gets set each time you boot your computer. You may wish to place the DOS Phantom executable files (PHANTOM2.EXE, TXT2PTM.EXE, PTM2TXT.PTM, HOTFILE.EXE, and SCHEDULE.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 the names of other products or just to make them easier to type.) 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 recordings. - 15 - USING DOS PHANTOM Page 5-2 DOS PHANTOM'S COMMAND LINE 20 September 92 5.2 DOS PHANTOM'S COMMAND LINE 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 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 /F Screen Capture File Selection /Z Suppresses all DOS Phantom-generated output (copyright notices, etc.) Here's an example of a DOS Phantom command to begin recording and create the file RECORDNG.PTM: C> PHANTOM2 /R RECORDNG.PTM - 16 - USING DOS PHANTOM Page 5-3 DOS PHANTOM'S COMMAND LINE 20 September 92 Here's the command to play back those keystrokes: C> PHANTOM2 /P RECORDNG.PTM - 17 - USING DOS PHANTOM Page 5-4 RECORDING AND PLAYING BACK 20 September 92 5.3 RECORDING AND PLAYING BACK DOS Phantom normally creates a new command shell when you start recording. 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.6 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.6 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. C> 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: - 18 - USING DOS PHANTOM Page 5-5 RECORDING AND PLAYING BACK 20 September 92 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. - 19 - USING DOS PHANTOM Page 5-6 PAUSING 20 September 92 5.4 PAUSING If you press the hot key (ALT-P unless you change it with /K) 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. - 20 - USING DOS PHANTOM Page 5-7 QUICK PLAYBACK 20 September 92 5.5 QUICK PLAYBACK 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, notable 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 want to use quick playback. 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 DOS Phantom recordings. - 21 - USING DOS PHANTOM Page 5-8 LOOPING PLAYBACK 20 September 92 5.6 LOOPING PLAYBACK If you supply the /L switch on the command line, DOS Phantom will rewind and play the same recording file over and over until you pause it by pressing the 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 directive in the recording file. See the section on editing recording files for more information. - 22 - USING DOS PHANTOM Page 5-9 THE DOS PHANTOM CONTROL PANEL 20 September 92 5.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. 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.6 | +----------------------------------------------------+ | | | +---------+ +---------+ +---------+ +--------+ | | | | | | | | | | | | | 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 when DOS Phantom 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 ESC key erases the menu without starting a recording or playback session. - 23 - USING DOS PHANTOM Page 5-10 CHANGING THE HOT KEYS 20 September 92 5.8 CHANGING THE HOT KEYS There are three hot keys used by DOS Phantom. By default, two of them are disabled (set to the key NONE). The three 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 enabled 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 enabled 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. Here's how you would change the attention hot key to F10: C> PHANTOM2 /K=F10 /R RECORDNG.PTM - 24 - USING DOS PHANTOM Page 5-11 CHANGING THE HOT KEYS 20 September 92 Here is a list of all the acceptable hot keys which you can specify with /K, /D, and /A: 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 F11 F12 SHFT-F11 SHFT-F12 CTRL-F11 CTRL-F12 ALT-F11 ALT-F12 NONE - 25 - USING DOS PHANTOM Page 5-12 MAKING DOS PHANTOM MEMORY RESIDENT 20 September 92 5.9 MAKING DOS PHANTOM MEMORY RESIDENT 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. You can install DOS Phantom in your AUTOEXEC.BAT file by including this command: PHANTOM2 /I - 26 - USING DOS PHANTOM Page 5-13 REMOVING DOS PHANTOM FROM MEMORY 20 September 92 5.10 REMOVING DOS PHANTOM FROM MEMORY The /U switch un-installs DOS Phantom from memory. When you execute the PHANTOM2/U command, one of two responses will be displayed: 1. DOS Phantom un-installed. This means that DOS Phantom was successfully un-installed. 2. 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. - 27 - USING DOS PHANTOM Page 5-14 USING THE /O SWITCH 20 September 92 5.11 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. - 28 - CHAPTER 6 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 before you press the hot key. HOTFILE 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 Here's an example of the LIST command: C:\> HOTFILE LIST HOTFILE V2.6 123456 Copyright (c) blah, blah, blah... No Hotkey Playback file -------------------------------- 1 ALT-F10 MAIL.PTM 1 CTRL-B BACKUP.PTM 1 ALT-D DIAL.PTM You can delete a hot key assignment with the DELETE command like this: C:\> HOTFILE DELETE CTRL-B HOTFILE V2.6 123456 Copyright (c) blah, blah, blah... Delete assignment of CTRL-B to file BACKUP.PTM (Y)? y C:\> - 29 - USING HOT KEYS TO START PLAYBACKS Page 6-2 20 September 92 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. 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. - 30 - CHAPTER 7 SCHEDULING RECORDINGS FOR LATER PLAYBACK The SCHEDULE program allows you to maintain a schedule of playbacks. Up to 16 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 recording file. (The recording 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:00pm on September 20, 1993: C:\> SCHEDULE ASSIGN 9/20/93-15:00 GETMAIL.PTM 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 - 31 - SCHEDULING RECORDINGS FOR LATER PLAYBACK Page 7-2 20 September 92 Here is an example of the LIST command: C:\> SCHEDULE LIST SCHEDULE V2.6 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 when SCHEDULE is run, SCHEDULE communicates the changes to DOS Phantom. 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. - 32 - CHAPTER 8 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: 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 - 33 - CONVERTING ASCII TEXT FILES FOR PLAYBACK Page 8-2 20 September 92 The output file can be played back like any DOS Phantom recording. Note that when a character delay has been specified, it is not possible to interrupt the recording with the attention hot key. MAKEPTM places its output file in the directory designated by the DOS environment variable PHANTOMDIR if it is defined. - 34 - CHAPTER 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 looks like this: !======================================================================== ! DOS Phantom V1.0 ! ! Text translation of recording file SAMPLE.KEY. ! Translated by PTM2TXT V2.6 999999. ! ! 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) ! ! 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 - 35 - EDITING DOS PHANTOM RECORDINGS Page 9-2 20 September 92 ! 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.6 are: ! ! $n Input parameters (n=1-9) ! $Pause [n] n=secs, default is no auto resume ! $Wait mm:ss.ttt mm=min, ss=secs, ttt=ms ! ! $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 ! $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 ! $IfError Go to <label> if exit status <> 0 ! $MatchWait n text Wait n secs for text to appear on screen ! $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 ! ! See the DOS Phantom Users Guide for details on using these directives. ! ! 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. ! !======================================================================== 00:01.430 D 2044 60 00:00.165 I 1749 60 00:00.165 R 1352 60 - 36 - EDITING DOS PHANTOM RECORDINGS Page 9-3 20 September 92 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. Note that if you edit a translated DOS Phantom 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. When you have finished editing, you can create a recording file using the TXT2PTM program like this: C> TXT2PTM RECORDNG.TXT RECORDNG.PTM - 37 - EDITING DOS PHANTOM RECORDINGS Page 9-4 ELIMINATING HELP TEXT 20 September 92 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. - 38 - EDITING DOS PHANTOM RECORDINGS Page 9-5 DOS PHANTOM DIRECTIVES 20 September 92 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 directives, all directives must begin at the first character position on a line. Each directive is discussed in detail below. 9.3 $PAUSE AND $WAIT - 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. 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 $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 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> - 39 - EDITING DOS PHANTOM RECORDINGS Page 9-6 $PAUSE AND $WAIT - PROGRAMMED PAUSES 20 September 92 In general, you use $Pause to pause for keyboard input, and $Wait in compressed recordings to stall without keyboard input. - 40 - EDITING DOS PHANTOM RECORDINGS Page 9-7 $1 - $9 - SUBSTITUTION PARAMETERS 20 September 92 9.4 $1 - $9 - 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). 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. - 41 - EDITING DOS PHANTOM RECORDINGS Page 9-8 COMPRESSED MODE 20 September 92 9.5 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 ! You can place substitution parameter directives anywhere in a asterisk line. The characters "<", ">", and "$" must be preceded with a $ if you don't want 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. - 42 - EDITING DOS PHANTOM RECORDINGS Page 9-9 POP-UP DISPLAYS 20 September 92 9.6 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 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: 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: Attribute Monochrome 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). - 43 - EDITING DOS PHANTOM RECORDINGS Page 9-10 POP-UP DISPLAYS 20 September 92 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. 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 line at the top and bottom for the border. - 44 - EDITING DOS PHANTOM RECORDINGS Page 9-11 LABELS AND THE $GOTO DIRECTIVE 20 September 92 9.7 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.) - 45 - EDITING DOS PHANTOM RECORDINGS Page 9-12 POP-UP MENUS 20 September 92 9.8 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. 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 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 Monochrome 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). - 46 - EDITING DOS PHANTOM RECORDINGS Page 9-13 POP-UP MENUS 20 September 92 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. 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 $QUIT Quit $EndMenu $DIR: * dir/w $Goto start $CLEAR: * cls $Goto start $QUIT: - 47 - EDITING DOS PHANTOM RECORDINGS Page 9-14 POP-UP MENUS 20 September 92 * 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 line at the top and bottom for the border. - 48 - EDITING DOS PHANTOM RECORDINGS Page 9-15 PROGRAMMED SCREEN CAPTURE 20 September 92 9.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 default 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. - 49 - EDITING DOS PHANTOM RECORDINGS Page 9-16 PROGRAMMED PRINT CAPTURE 20 September 92 9.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. Note that print capture can also be enabled with the /V command line switch. - 50 - EDITING DOS PHANTOM RECORDINGS Page 9-17 PACING 20 September 92 9.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 programs capability of accepting input. The $SetPace directive takes the following form: $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 Playback of recordings using the $SetPace directive can not be interrupted using the attention hot key. Once started, they must play to completion. - 51 - EDITING DOS PHANTOM RECORDINGS Page 9-18 MATCHING SCREEN TEXT 20 September 92 9.12 MATCHING SCREEN TEXT The directive $MatchWait is 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 directive takes the following form: $MatchWait timo text Where timo is the timeout period in seconds and text is the text string to look for on the screen. The text string may contain spaces, and the special characters <, >, and $ need not be prefixed with a $ as is the case elsewhere in recording files. 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: * BILLSMITH $MatchWait 5 "Password:" $IfTimeout RETRY - 52 - EDITING DOS PHANTOM RECORDINGS Page 9-19 MATCHING SCREEN TEXT 20 September 92 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 $MatchWait is case-sensitive. That is, $MatchWait does 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 $MatchWait directive. /O causes recent screen output to be included in recording files as comments. You can edit these comments into $MatchWait 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 $MatchWaits. 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. - 53 - EDITING DOS PHANTOM RECORDINGS Page 9-20 WAITING FOR PROGRAM EXIT 20 September 92 9.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: $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 - 54 - EDITING DOS PHANTOM RECORDINGS Page 9-21 DETECTING EXIT STATUS 20 September 92 9.14 DETECTING EXIT STATUS Many, if not most, 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: $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. - 55 - EDITING DOS PHANTOM RECORDINGS Page 9-22 USING THE $SETMODE DIRECTIVES 20 September 92 9.15 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 ! * <Shft-Tab><Shft-Tab> * E $SetMode Normal - 56 - EDITING DOS PHANTOM RECORDINGS Page 9-23 HINTS AND TIPS 20 September 92 9.16 HINTS AND TIPS 9.16.1 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.16.2 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. 9.16.3 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.16.4 DON'T USE THE MOUSE DOS Phantom doesn't record mouse activity, so you have to do everything you want recorded on the keyboard. - 57 - CHAPTER 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.6, when installed as a TSR, uses approximately 32K of memory. - 58 - CHAPTER 11 DIFFERENCES BETWEEN DOS PHANTOM V1.4 AND V2.0 o Program Termination Awareness The new $ExitWait directive allows you to pause DOS Phantom's playback until the currently executing program exits. You may optionally provide a timeout value after which playback will continue event if the program hasn't exited yet. The new $IfSuccess, $IfError, and $IfTimeout directives allow you to branch to a label in your recording file based on the termination status of the program or on an $ExitWait timeout. o Screen Awareness The new $MatchWait directive allows you to pause your DOS Phantom playback until a text string you specify appears on the screen. An optional timeout value causes playback to continue if the text string doesn't appear on the screen within the timeout period. The new $IfMatch and $IfTimeout directives allow you to direct playback based on whether the text string was matched or not. The new /O command line switch causes DOS Phantom to write text from the screen to the recording file during recording. When the recording file is processed with PTM2TXT, the screen text is placed within comments. This feature is intended to aid you in developing $MatchWait directives. o Special High Speed Playback Mode The new $SetMode directive allows the highest possible playback speed into programs such as Prodigy which use DOS function 6 for input. $SetMode Func6 allows playback into Prodigy at high speed with no loss of characters due to prodigy's "eating" of input. $SetMode Normal sets the - 59 - DIFFERENCES BETWEEN DOS PHANTOM V1.4 AND V2.0 Page 11-2 20 September 92 playback mode back to normal. This is the required setting for most programs. The new $SetPace directive allows you to set a constant delay between keystrokes as they are played back. o Special Abort Hotkey A second hotkey for aborting playback sequences may now be specified on the command line using the /A switch. The abort key defaults to none. The abort key, when pressed, is passed on to the program executing after aborting DOS Phantom's playback. Ctrl-C is the most commonly used abort key. o Disabling of Hotkey Using the command line switch /K=NONE results is disabling the hotkey used for pauses and displaying the DOS Phantom control panel. This allows DOS Phantom recordings to be used by users unfamiliar with DOS Phantom without the danger of their inadvertently pausing the playback. o Changes to /S and /M In addition to the pre-V2.0 toggle functions of the /S and /M command line switches, prefixing them with a minus sign disables the sound or mode display regardless of its current setting. Thus, /-S turns sound off, and /-M turns the mode display off whether or not they were already off. o Major Change to Record/Playback Functions DOS Phantom V2.0 uses an entirely new method of obtaining keystrokes during record and providing keystrokes during playback. The new method will work with a greater number of programs than the older method, and actually resulted in a savings in memory utilization. o Screen Capture The /F command line option and the $Screen directive allow a snapshot of the screen to be written to a file. This is useful when testing software and when creating complex recording files which depend on the screen contents to determine different paths of execution. o Print Capture The /V command and $Printer directives allow output which would normally go to the printer to be re-directed to a file. - 60 -