💾 Archived View for gemini.spam.works › mirrors › textfiles › computers › DOCUMENTATION › phantom2.t… captured on 2022-07-16 at 23:40:44.
⬅️ Previous capture (2022-06-12)
-=-=-=-=-=-=-
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>
! {body}lt;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
{body}lt;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 {body}lt;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 -