













                                    PHANTOM2

                         The Phantom of the Keyboard II



















                                 P2 Enterprises
                                  P.O. Box 25
                              Ben Lomond, CA 95005













                                 Phantom2 V1.1
            Copyright (c) 1991 P2 Enterprises   All Rights Reserved



                                    - 1 -
    PHANTOM V1.1                                                    Page 2
                                                             14 January 91












                                       CONTENTS



    CHAPTER 1       INTRODUCTION

            1.1     WHAT IS THE PHANTOM OF THE KEYBOARD II?  . . . . . 1-1
            1.2     WHAT IS PHANTOM2 GOOD FOR? . . . . . . . . . . . . 1-1


    CHAPTER 2       DIFFERENCES BETWEEN PHANTOM V1.0 AND PHANTOM2


    CHAPTER 3       USING PHANTOM2

            3.1     PHANTOM2'S COMMAND LINE  . . . . . . . . . . . . . 3-1
            3.2     RECORDING AND PLAYING BACK . . . . . . . . . . . . 3-2
            3.3     PAUSING  . . . . . . . . . . . . . . . . . . . . . 3-3
            3.4     QUICK PLAYBACK . . . . . . . . . . . . . . . . . . 3-3
            3.5     LOOPING PLAYBACK . . . . . . . . . . . . . . . . . 3-3
            3.6     THE PHANTOM2 CONTROL PANEL . . . . . . . . . . . . 3-4
            3.7     CHANGING THE HOT KEY . . . . . . . . . . . . . . . 3-5
            3.8     MAKING PHANTOM2 MEMORY RESIDENT  . . . . . . . . . 3-5
            3.9     REMOVING PHANTOM2 FROM MEMORY  . . . . . . . . . . 3-6
            3.10    EDITING PHANTOM2 RECORDINGS  . . . . . . . . . . . 3-6
            3.10.1    PROGRAMMED PAUSES  . . . . . . . . . . . . . . . 3-9
            3.10.2    SUBSTITUTION PARAMETERS  . . . . . . . . . . . . 3-9
            3.10.3    COMPRESSED MODE  . . . . . . . . . . . . . . .  3-10
            3.10.4    POP-UP DISPLAYS  . . . . . . . . . . . . . . .  3-10
            3.10.5    LABELS AND THE $GOTO DIRECTIVE . . . . . . . .  3-12
            3.10.6    POP-UP MENUS . . . . . . . . . . . . . . . . .  3-13
            3.10.7    ELIMINATING HELP TEXT  . . . . . . . . . . . .  3-15
            3.11    PASSING PARAMETERS TO RECORDINGS ON THE COMMAND 
                    LINE . . . . . . . . . . . . . . . . . . . . . .  3-16
            3.12    WHAT'S BAD ABOUT PHANTOM2? . . . . . . . . . . .  3-16


    CHAPTER 4       PHANTOM2 TECHNICAL INFORMATION

            4.1     DOS VERSION REQUIREMENTS . . . . . . . . . . . . . 4-1
            4.2     CALLING PHANTOM2 FROM A USER PROGRAM . . . . . . . 4-1


                                    - 2 -
    PHANTOM V1.1                                                    Page 3
                                                             14 January 91


            4.3     HOW DOES IT WORK?  . . . . . . . . . . . . . . . . 4-2




















































                                    - 3 -












                                  CHAPTER 1

                                 INTRODUCTION



    1.1  WHAT IS THE PHANTOM OF THE KEYBOARD II?

    Phantom2 is a shareware keystroke recorder for MS-DOS.

    In record mode, Phantom2 records every key pressed on  your  keyboard,
    whether you are at the DOS command prompt or running a program.  Then,
    in playback mode, Phantom2 plays back the recorded keystrokes  exactly
    as they were originally recorded, with exactly the same timing as when
    they were recorded.



    1.2  WHAT IS PHANTOM2 GOOD FOR?


          o  Recovery After System Crashes or Power Failures

             Because Phantom2 writes your recorded keystrokes to the  disk
             after  every  32  keystrokes, if you were recording when your
             system failed, you can  just  playback  the  recording  file,
             recovering  everything except perhaps the last 31 keystrokes.
             This can be tremendously useful during long editing sessions,
             eliminating  the need to periodically save your work to avoid
             losing it in a system crash.

          o  A Batch Substitute

             Phantom2  can  be  used  in  place  of  simple  batch  files,
             eliminating  the  need  to  prepare  the  batch files with an
             editor -- You just show Phantom2  what  you  want  done,  and
             Phantom2  can  do  it  for you after that.  You can even edit
             your Phantom2 recordings if you make  a  mistake  during  the
             recording.   You  can  also  perform  parameter  substitution
             similar to that available with MS-DOS batch files.





                                    - 4 -
    INTRODUCTION                                                  Page 1-2
    WHAT IS PHANTOM2 GOOD FOR?                               14 January 91


          o  Program Startup

             Phantom2  can  be  used  to  automatically  supply  input  to
             programs  which  expect  to  receive keyboard input (programs
             such as spreadsheets and others).  It can  thus  be  used  to
             perform  a  sequence  of  "startup"  commands which you would
             otherwise have to type each time you run the program.

          o  Automatic Execution

             You might record the keystrokes to run your spreadsheet, load
             current stock quotes, print a graph, and exit.  You only have
             to do it once; Phantom2 can do it after that.

             Phantom2 can be used to automate access to  systems  such  as
             Prodigy which normally require your presence at the keyboard.
             Record the keystrokes that you use to dial Prodigy and  print
             headline  news  and current stock quotations.  Then have your
             computer wake up early and call Prodigy.  You  can  have  the
             latest information printed and waiting for you to peruse with
             your morning coffee.  All you need is a timer to turn on your
             PC   early   in  the  morning  and  an  extra  line  in  your
             AUTOEXEC.BAT file to run Phantom2.

          o  Demos

             Phantom2 can be  used  create  a  quick  demonstration  of  a
             program which can then be played back at will for prospective
             users or customers.  Phantom2 can be paused automatically  or
             manually  during  playback  for discussion or manual entry of
             data to the program being demonstrated.  In addition,  pop-up
             windows  can be displayed to explain what is happening in the
             demo, and menus can be presented to allow the user  to  guide
             the course of the demo.

             Automatic timeouts when  user  response  is  required  and  a
             looping   feature   allow   Phantom2-based   demos   to   run
             continuously and unattended and yet allow users  to  interact
             with the demonstration if they wish.

          o  Software Testing

             Phantom2 can be used to record tests  of  software  which  is
             undergoing  revision.   Then,  the tests can be run after the
             revisions are complete to be  sure  what  worked  before  the
             revisions still works after the revisions.







                                    - 5 -












                                  CHAPTER 2

                DIFFERENCES BETWEEN PHANTOM V1.0 AND PHANTOM2




          o  Quick Playback

             Phantom2 allows you to play back recordings  with  no  delays
             between the recorded keystrokes.  This can speed execution of
             Phantom2 recordings  when  the  programs  being  run  do  not
             require paced input.

             You select quick playback by using the /Q switch  instead  of
             the /P switch on the Phantom2 command line.

          o  Pause and Resume

             Phantom2  allows  you  to  pause  and  resume  recording  and
             playback.   The  period  of  time  paused  in not included in
             Phantom2's recording.  While Phantom2 is paused, you may type
             at  the  keyboard just as if Phantom2 were not present.  When
             recording or playback is resumed, Phantom2 picks up where  it
             left off.

             You can introduce automatic pauses during playback by editing
             the recording file to insert pause requests wherever desired.

          o  Looping Playback

             You  can  cause  Phantom2  to  restart  a  playback   session
             automatically  when the end of the recording file is reached.
             The looping continues until the hot key is pressed.  This  is
             especially  useful  for  automated demonstrations of software
             products.

          o  User-Selectable Hot Key

             You pause and resume Phantom2  by  pressing  the  "hot  key".
             When  Phantom2  is  in RECORD mode and you press the hot key,
             the recording is paused.  A second pressing of  the  hot  key
             resumes the recording.  Playback mode works similarly.


                                    - 6 -
    DIFFERENCES BETWEEN PHANTOM V1.0 AND PHANTOM2                 Page 2-2
                                                             14 January 91


             You select the hot key by using the /K switch on the  command
             line.   For  example,  to set the hot key to ALT-K, you would
             include this on the Phantom2 command line:  /K=ALT-K.

             The default hot key is ALT-P.

          o  Sound and Lights

             Phantom2 signals transitions between modes  (The  four  modes
             are  RECORD,  PLAY,  PAUSE,  and  IDLE.) by sounding either a
             rising or a falling series of  tones.   A  rising  series  of
             tones  signals a change from IDLE or PAUSE to RECORD or PLAY,
             while a falling series of tones signals a change to  IDLE  or
             PAUSE mode.

             Keyclicks are heard while in record or playback mode.

             The current mode is displayed in a reverse-video box  in  the
             upper  left  corner  of  the  screen.   The  mode display may
             contain "Record", "Play", "Pause", or  "Phantom2".   Phantom2
             is displayed when Phantom2 is in IDLE mode.

             You can disable sounds by including  the  /S  switch  on  the
             Phantom2  command  line,  and  disable  the  mode  display by
             including the /M switch.

          o  Pop-Up Phantom2 Control Panel

             Pressing the hot key twice in rapid succession  triggers  the
             display  of  the  Phantom2  control  panel.  From the control
             panel you can begin recording or playback, close a  recording
             file,  enable  or  disable  sounds  and  the mode display, or
             change the recording file  name.   Pressing  ESC  erases  the
             control panel.

          o  Memory Residence (TSR)

             The /I  command  line  switch  installs  Phantom2  as  a  TSR
             (Terminate  and  Stay Resident) program, eliminating the need
             to  spawn  a  new   command   shell   and   reducing   memory
             requirements.    Once  resident,  Phantom2  is  activated  by
             pressing the hot key twice in succession to trigger  Phantom2
             control  panel,  or  by  issuing Phantom2 commands at the DOS
             prompt.

             When  Phantom2  is  resident  in  memory,  you  can  begin  a
             recording  or playback while a program is in progress, rather
             than only at the DOS prompt.





                                    - 7 -
    DIFFERENCES BETWEEN PHANTOM V1.0 AND PHANTOM2                 Page 2-3
                                                             14 January 91


             Once Phantom2 is resident in memory, Phantom2 commands  typed
             at  the DOS prompt are passed to the memory-resident Phantom2
             for execution, and do not spawn a new command shell.

          o  Editing of Recording Files

             The pair of programs PTM2TXT and TXT2PTM  extract  data  from
             Phantom2  recording  files  and place it into a text file for
             editing, and then re-create a Phantom2  recording  file  from
             the   modified   text  file.   This  allows  you  to  prepare
             recordings  for  playback  without  actually  executing   the
             commands  and to correct errors or make changes to recordings
             you have made.

          o  Parameter Substitution

             Special  Phantom2  directives  which  you  can  add  to  your
             recording   files  allow  you  to  pass  parameters  to  your
             recording  file  at  playback  time,  often   making   single
             recording  do  the  work  of  several.   This  is  similar to
             MS-DOS's batch parameter substitution.

          o  Programmed Pauses

             You can add automatic pauses  to  your  recordings  to  allow
             users to enter data or for discussion during a demonstration.
             Programmed pauses may have a timeout assigned to them.   When
             the  timeout  period  has  passed  with  no  input  from  the
             keyboard, the pause is automatically ended, and the  playback
             continues.

          o  Programmed Pop-up Displays

             You can add pop-up displays  to  your  recordings  to  inform
             watchers  of the playback what is happening.  Text you supply
             is displayed in a pop-up window, and the playback  is  paused
             for  a timeout period which you may specify or until a key is
             depressed on the keyboard.

             An unlimited number of pop-up displays may added to  Phantom2
             recordings.

          o  Programmed Pop-up Menus

             Pop-up menus can be added to your recordings to  allow  users
             to  direct  the course of the playback.  Menu text you supply
             is displayed to the user in a pop-up window.  When  the  user
             selects  a menu item, the playback is resumed at the point in
             the recording which you have associated with that menu item.




                                    - 8 -
    DIFFERENCES BETWEEN PHANTOM V1.0 AND PHANTOM2                 Page 2-4
                                                             14 January 91


             If the user does not respond  within  a  timeout  period  you
             specify,  the  next  menu  item  is  chosen, and the playback
             resumes.  Thus, if the user does nothing, each menu  item  is
             selected in turn automatically.

             An unlimited number of pop-up menus  may  added  to  Phantom2
             recordings.














































                                    - 9 -












                                  CHAPTER 3

                                USING PHANTOM2



    3.1  PHANTOM2'S COMMAND LINE

    Phantom2 accepts the following command line switches:

             /P Playback

             /R Record

             /Q Quick Playback

             /L Looping Playback

             /K Hot Key Selection

             /S Disable Sounds

             /M Disable Mode Display

             /I Install as a Memory Resident Program

             /U Un-install Phantom2 from memory


    Here's an example of a Phantom2 command to begin recording and  create
    the file RECORDNG.PTM:

                   C> PHANTOM2 /R RECORDNG.PTM


    Here's the command to play back those keystrokes:

                   C> PHANTOM2 /P RECORDNG.PTM







                                    - 10 -
    USING PHANTOM2                                                Page 3-2
    RECORDING AND PLAYING BACK                               14 January 91


    3.2  RECORDING AND PLAYING BACK

    Phantom2  normally  creates  a  new  command  shell  when  you   start
    recording.   Phantom2  will  record everything you type until you exit
    the shell by typing EXIT at the DOS command prompt.  Here's an example
    of recording a DIR command followed by a playback of the recording:

        Record the keystrokes:

            C> PHANTOM2 /R RECORDNG.PTM
            Phantom2 V1.1 #123456  Copyright (c) 1991...blah...blah...

            Press ALT-P to pause or resume recording.
            Press ALT-P twice in succession to activate the control panel.
            Type EXIT at the DOS prompt when done.


            C> DIR

            ...blah blah blah...

            C> EXIT
            Phantom2 terminated.



        Now play them back:

            C> PHANTOM2 /P RECORDING.PTM
            Phantom2 V1.1 #123456  Copyright (c) 1991...blah...blah...

            Press ALT-P to pause or resume playback.
            Press ALT-P twice in succession to activate the control panel.
            Type EXIT at the DOS prompt when done.


            C> DIR

            ...blah blah blah...

            C> EXIT
            Phantom2 terminated.

            C>


    While Phantom2 was running, it placed a small  display  in  the  upper
    right  corner of the screen showing what it was doing.  In the example
    above, the display showed either "Record" or "Play".  If you don't ant
    the mode display, just include the /M switch on the command line, like
    this:


                                    - 11 -
    USING PHANTOM2                                                Page 3-3
    RECORDING AND PLAYING BACK                               14 January 91


            C> PHANTOM2 /P /M RECORDNG.PTM




    3.3  PAUSING

    If you press the hot key (ALT-P) during record or  playback,  after  a
    brief  delay, Phantom2 will play a series of tones falling in pitch to
    indicate its transition to PAUSE mode.  The mode display, if  enabled,
    will  change  to  "Pause".  A second depression of the hot key resumes
    the recording or playback, accompanied by a  series  of  rising  tones
    indicating the transition out of PAUSE mode.

    While in PAUSE mode, Phantom2 "steps aside" and  lets  all  keystrokes
    (except  the  hot key) flow freely to the program running.  If you are
    recording, the keys you press while paused are not  recorded,  nor  is
    the time which passes while in PAUSE mode recorded.

    You can disable the sounds by including the /S switch on the  Phantom2
    command line, like this:

            C> PHANTOM2 /R /S RECORDNG.PTM




    3.4  QUICK PLAYBACK

    Phantom2 normally plays back recordings at the  same  speed  at  which
    they were recorded.  The /Q switch forces Phantom2 to playback as fast
    as possible.  Many programs have no problem with this.  Some  programs
    however,  "eat"  characters  typed while they are busy, and will cause
    the recording to end prematurely.  PRODIGY is an example of a  program
    which  does  this.  To automate a PRODIGY session, timed playback is a
    requirement.

    You can alter the intervals between individual keystrokes to speed  up
    some  sections  of  a  recording  and  slow down others by editing the
    recording file.  See the section below on editing Phantom2 recordings.



    3.5  LOOPING PLAYBACK

    If you supply the /L switch on the command line, Phantom2 will  rewind
    and  play  the same recording file over and over until you pause it by
    pressing the hot key.  If Phantom2 is memory-resident (see below), you
    must  close  the  recording  file to avoid the continuation of looping
    when you press the hot key again.  If Phantom2 is not memory-resident,
    then you must type EXIT at the DOS prompt.


                                    - 12 -
    USING PHANTOM2                                                Page 3-4
    LOOPING PLAYBACK                                         14 January 91


    Looping can be a valuable tool in continuously-running  demonstrations
    or in stress-testing software systems.



    3.6  THE PHANTOM2 CONTROL PANEL

    If you hit the hot key twice within about a half  second,  the  pop-up
    control panel is triggered, and is displayed over whatever was already
    on the screen.

    Here is what the control panel looks like:

            +----------------------------------------------------+
            |                      Phantom2                 V1.1 |
            +----------------------------------------------------+
            |                                                    |
            |   +---------+ +---------+ +---------+ +--------+   |
            |   |         | |         | |         | |        |   |
            |   | PLAY    | | QPLAY   | | RECORD  | | CLOSE  |   |
            |   |         | |         | |         | |        |   |
            |   +---------+ +---------+ +---------+ +--------+   |
            |                                                    |
            |    Sound On     Mode Display On   Loop Mode Off    |
            |                                                    |
            |    Filename: RECORDNG.PTM                          |
            |                                                    |
            +----------------------------------------------------+



    You can highlight the selection of your choice using the  arrow,  tab,
    or  spacebar  keys and press RETURN to execute it or you can press the
    key corresponding to the first letter of your selection.

    If you press R, P, or Q, the menu is immediately erased, and  Phantom2
    begins  executing your command.  CLOSE closes an open recording file -
    This  is  the  only  to  close  a  recording  file  when  Phantom2  is
    memory-resident.   The  Sound,  Mode Display, and Loop Mode selections
    toggle the sounds, mode display, and looping on and off.

    Selecting Filename allows you to change the recording filename.   When
    you have finished entering the filename, press RETURN.

    Pressing the hot key or the ESC key erases the menu without starting a
    recording or playback session.







                                    - 13 -
    USING PHANTOM2                                                Page 3-5
    CHANGING THE HOT KEY                                     14 January 91


    3.7  CHANGING THE HOT KEY

    The /K command line switch allows you to change the hot key  from  the
    default ALT-P.  Here's how you would change the hot key to F10:

            C> PHANTOM2 /K=F10 /R RECORDNG.PTM


    Here is a list of all the acceptable hot keys which  you  can  specify
    with /K:
            SHFT-TAB        ALT-Q           ALT-W           ALT-E
            ALT-R           ALT-T           ALT-Y           ALT-U
            ALT-I           ALT-O           ALT-P           ALT-A
            ALT-S           ALT-D           ALT-F           ALT-G
            ALT-H           ALT-J           ALT-K           ALT-L
            ALT-Z           ALT-X           ALT-C           ALT-V
            ALT-B           ALT-N           ALT-M           F1
            F2              F3              F4              F5
            F6              F7              F8              F9
            F10             HOME            UP              PGUP
            LEFT            RIGHT           END             DOWN
            PGDWN           INSERT          DELETE          SHFT-F1
            SHFT-F2         SHFT-F3         SHFT-F4         SHFT-F5
            SHFT-F6         SHFT-F7         SHFT-F8         SHFT-F9
            SHFT-F10        CTRL-F1         CTRL-F2         CTRL-F3
            CTRL-F4         CTRL-F5         CTRL-F6         CTRL-F7
            CTRL-F8         CTRL-F9         CTRL-F10        ALT-F1
            ALT-F2          ALT-F3          ALT-F4          ALT-F5
            ALT-F6          ALT-F7          ALT-F8          ALT-F9
            ALT-F10         CTRL-LEFT       CTRL-RIGHT      CTRL-END
            CTRL-PGDWN      CTRL-HOME       ALT-1           ALT-2
            ALT-3           ALT-4           ALT-5           ALT-6
            ALT-7           ALT-8           ALT-9           ALT-0
            ALT--           ALT-=           CTRL-PGUP       CTRL-A
            CTRL-B          CTRL-C          CTRL-D          CTRL-E
            CTRL-F          CTRL-G          CTRL-H          CTRL-I
            CTRL-J          CTRL-K          CTRL-L          CTRL-M
            CTRL-N          CTRL-O          CTRL-P          CTRL-Q
            CTRL-R          CTRL-S          CTRL-T          CTRL-U
            CTRL-V          CTRL-W          CTRL-X          CTRL-Y
            CTRL-Z          ESC




    3.8  MAKING PHANTOM2 MEMORY RESIDENT

    If you include the /I switch on the command  line,  Phantom2  installs
    itself as a TSR (Terminate and Stay resident) program in memory.  This
    method of using Phantom2 has a number of  benefits.   Among  them  are
    lower  memory  utilization because no command shell is invoked, faster


                                    - 14 -
    USING PHANTOM2                                                Page 3-6
    MAKING PHANTOM2 MEMORY RESIDENT                          14 January 91


    execution because no loading of the Phantom2 program is required,  and
    beginning  and ending of recording and playback sessions while another
    program is running.

    Once resident, you access Phantom2 by pressing the hot  key  twice  in
    succession to trigger the pop-up menu, or by issuing Phantom2 commands
    at the DOS prompt.



    3.9  REMOVING PHANTOM2 FROM MEMORY

    The /U switch un-installs Phantom2 from memory.  When you execute  the
    PHANTOM/U command, one of two responses will be displayed:

         1.  Phantom2 un-installed.

             This means that Phantom2 was successfully un-installed.

         2.  Phantom2 disabled.  Memory not reclaimed.

             This means that Phantom2 was only disabled, and is dormant in
             memory.   This  is  almost  certainly because another TSR was
             loaded after Phantom2  which  intercepts  some  of  the  same
             interrupts  used  by  Phantom2.   To  remove  Phantom2, first
             remove any TSR's loaded after Phantom2, and then re-issue the
             /U command.

             To re-enable Phantom2, simply issue another Phantom2  command
             other than /U.




    3.10  EDITING PHANTOM2 RECORDINGS


                                     NOTE

            The programs TXT2PTM  and  PTM2TXT  required  to  edit
            Phantom2   recordings  are  supplied  with  registered
            versions of Phantom2 only.


    The program PTM2TXT extracts information from a Phantom2 recording and
    places it in a text file for editing.  Here is an example of PTM2TXT:

            C> PTM2TXT RECORDNG.PTM RECORDNG.TXT





                                    - 15 -
    USING PHANTOM2                                                Page 3-7
    EDITING PHANTOM2 RECORDINGS                              14 January 91


    The output text file looks like this:

    !========================================================================
    ! P2 PHANTOM V1.0
    !
    ! Text translation of recording file RECORDNG.PTM.
    ! Translated by PTM2TXT V1.1 #123456.
    !
    ! Line format:
    !     mm:ss.ttt keystroke   eeaa ff
    !
    !     mm:ss:ttt = time interval between the previous keystroke and
    !                 this one.
    !         mm    = minutes
    !         ss    = seconds
    !         ttt   = thousandths of seconds
    !     ee        = extended keycode       (optional)
    !     aa        = ASCII code             (optional)
    !     ff        = keyboard status flags  (optional)
    !
    !     Comment lines (lines beginning with !) and empty lines are ignored
    !     by the TXT2PTM translator.
    !
    !     Lines beginning with an asterisk (*) are processed by TXT2PTM
    !     without timing information.  This allows you to place entire
    !     commands on one line rather than one character per line. A
    !     carriage return is automatically placed at the end of * lines
    !     by TXT2PTM unless the last character on the line is a dollar
    !     sign.  Special character expressions (e.g., <Ctrl-K>) are
    !     delimited with angle brackets (<,>).
    !
    !     Phantom2 directives begin with a dollar sign ($).
    !     Directives supported by Phantom2 V1.1 are:
    !
    !         $Pause      Causes an automatic switch to pause mode during
    !                     playback.  The user must press the hot key to
    !                     resume playback.  The $Pause directive must
    !                     be placed on a line by itself.
    !
    !         $n          Where n is a single digit from 1 to 9 causes
    !                     arguments from the command line to be substituted
    !                     for the $n directive.  $1 refers to the first
    !                     command line argument after the filename, $2 the
    !                     second, and so on.  The $n directive may be
    !                     within an asterisk line.
    !
    !         $BeginDisplay    See the Phantom2 documentation for
    !         $EndDisplay      instructions on using these directives.
    !         $BeginMenu
    !         $EndMenu
    !         $Title


                                    - 16 -
    USING PHANTOM2                                                Page 3-8
    EDITING PHANTOM2 RECORDINGS                              14 January 91


    !         $Goto <label>
    !         $<label>:
    !
    !     The special characters $, <, and > must be preceded by a
    !     dollar sign ($) when they are present in an asterisk line.
    !     Otherwise TXT2PTM will attempt to perform special processing
    !     erroneously.
    !
    ! The optional fields need not be entered when editing this file.
    ! Values appropriate for most circumstances will be provided for
    ! you by TXT2PTM.  If you include values for the optional fields,
    ! Your values will override those which TXT2PTM would provide.
    !
    !========================================================================

    00:01.430 D            2044 60
    00:00.165 I            1749 60
    00:00.165 R            1352 60
    00:00.605 /            352f 60
    00:00.220 W            1157 60
    $1
    00:00.605 <CR>         1c0d 20
    00:07.480 e            1265 20
    00:00.000 x            2d78 20
    00:00.000 i            1769 20
    00:00.000 t            1474 20
    00:00.000 <CR>         1c0d 20
    $Pause
    00:00.000 <CR>         1c0d 20


    The above file depicts a recording of the commands "DIR/W" and "EXIT".
    As you can see, the carriage return character is translated to <CR> in
    the file.  Spaces are translated as <SP>.   Non-printing  and  special
    characters  such  as CTRL-K are all translated in this manner.  If you
    are not sure what the translation of a character might be, it is  best
    to  make  a  recording containing the character and then translate the
    recording with PTM2TXT to find out what the correct translation is.

    The line format is as described in the output file  shown  above.   If
    you  change  a  line  in  the  file,  it  is  best, unless you clearly
    understand the BIOS extended keycodes and keyboard  status  flags,  to
    remove the eeaa and ff fields.  TXT2PTM will supply appropriate values
    when you leave them out.  An exception to this is  when  you  want  to
    create a programmed pause as described earlier.

    Some programs may require the actual  values  for  the  keyboard  scan
    codes  supplied  by the BIOS when an extended keycode is not required.
    In these cases, you must supply the correct values for the eeaa and ff
    fields.  We have not run across such a program to date.



                                    - 17 -
    USING PHANTOM2                                                Page 3-9
    EDITING PHANTOM2 RECORDINGS                              14 January 91


    Note that if you edit a translated Phantom2 recording files and insert
    comments  and labels, then translate the text file to a recording file
    and back into a text file, the  comments  and  labels  will  be  lost.
    PTM2TXT will create labels required by the menu and goto directives in
    the recording, but they will not be  the  labels  from  your  original
    edited text file.  Goto and menu directives are discussed below.



    3.10.1  PROGRAMMED PAUSES

    The example contains a programmed pause  directive  after  the  second
    <CR>.   Pauses  may be programmed into the recording file as described
    in the file header shown above.  Note that  programmed  pauses  (i.e.,
    pauses  which  occur  automatically  at  predetermined  points  during
    playback) may only be created by preparing an input file  for  TXT2PTM
    such as that shown above.  There is no way to create programmed pauses
    while recording.  The pause directive may be  followed  by  a  timeout
    value  expressed  in  seconds.  If the timeout period passes without a
    key being depressed, the pause is ended and playback resumes.



    3.10.2  SUBSTITUTION PARAMETERS

    The example also contains a  substitution  parameter  directive:   $1.
    This  directive  causes  the  first  parameter entered on the Phantom2
    command line after the filename to be substituted for  the  $1  during
    playback.   Up  to  nine substitution parameters ($1, $2, $3, ..., $9)
    may be used.   If  a  corresponding  command  line  parameter  is  not
    supplied  for  playback,  the  parameter  used on the last playback is
    used.  If no parameter was used on the last playback, or  if  this  is
    the  first  playback  of this Phantom2 session, nothing is substituted
    for the substitution parameter (i.e., it is as if it was not there).

    Multiple  substitution  parameter  directives  may  be  placed  in  an
    asterisk  line.   Otherwise,  only  a  single directive is allowed per
    line.















                                    - 18 -
    USING PHANTOM2                                               Page 3-10
    EDITING PHANTOM2 RECORDINGS                              14 January 91


    3.10.3  COMPRESSED MODE

    You may avoid typing in the time fields (mm:ss.ttt) by starting  lines
    with  an asterisk.  Lines starting with an asterisk are referred to as
    being in "compressed" mode.  When TXT2PTM  processes  lines  beginning
    with  an  asterisk,  it behaves as if each character was on a separate
    line and preceded with "00:00.000".  TXT2PTM automatically  inserts  a
    <CR>  at  the  end of each * line.  Here is the previous example above
    created using this technique:

    !
    ! Example of the use of * lines.
    !

    * DIR/W $1
    $Pause
    * EXIT
    *

    !
    ! End of example
    !


    You can mix compressed an non-compressed modes in the same text file.

    You can cause PTM2TXT to produce  compressed  mode  output  from  your
    recordings by including the /C switch on the command line like this:

            C> PTM2TXT /C RECORDNG.PTM RECORDNG.TXT


    Note that the switches to the PTM2TXT command must be  separated  from
    the PTM2TXT command and other switches by spaces.



    3.10.4  POP-UP DISPLAYS

    You can cause windows containing test you provide  to  pop  up  during
    playbacks  of  Phantom2 recordings.  These pop-up displays can contain
    text explaining what  the  user  is  seeing  in  a  demonstration,  or
    announce a that a certain operation is about to take place.

    When a pop-up display is displayed, playback is halted until the  user
    presses  any  key  or  until  a  timeout  period which you specify has
    elapsed.

    The text which you wish to  appear  in  a  pop-up  display  is  placed
    between  two  Phantom2 directives:  $BeginDisplay and $EndDisplay.  If
    you want a title to appear in the upper  left  border  of  the  pop-up


                                    - 19 -
    USING PHANTOM2                                               Page 3-11
    EDITING PHANTOM2 RECORDINGS                              14 January 91


    display,  you may include a $Title directive on the line following the
    $BeginDisplay directive.

    The $BeginDisplay directive takes the following form:

           $BeginDisplay row col attr timo sr


    The parameters following the directive are interpreted as follows:

             row - the screen row on which the top pop-up display is to be
             written.

             col - the screen column on which the left edge of the  pop-up
             display is to be written.

             attr - The display attributes to be used for display of  your
             text:
                            0 Normal
                            1 Bold
                            2 Reverse Video
                            3 Reverse Bold 

             timo - A timeout value in seconds.   If  the  timeout  period
             passes  without  keyboard  input,  the  display is erased and
             playback resumes.

             sr - The character S or R indicating whether you  wish  other
             Phantom2  displays  and  menus  which  may  be present on the
             screen to be erased  before  this  window  is  displayed.   R
             restores  the  screen  to  what  it  was  before any Phantom2
             displays or menus were popped-up.  S saves the screen  as  it
             is  and  causes  the  new display to be painted over anything
             currently shown on the screen.

             Phantom2  pop-up  displays  are  automatically  erased   when
             playback is resumed.


    The text you wish to appear in the pop-up display  is  placed  between
    the $BeginDisplay and $EndDisplay directives.

    Here is an example of the directives used to create a pop-up display:

            !
            ! Create a display at row 5, column 20, reverse video, 2-minute
            ! timeout and erase any currently displayed pop-ups.
            !
            $BeginDisplay 5 20 2 120 R
            $Title Sample Pop-Up Display



                                    - 20 -
    USING PHANTOM2                                               Page 3-12
    EDITING PHANTOM2 RECORDINGS                              14 January 91


            This is just a simple example of a
                 Phantom2 pop-up display.

               (Press any key to continue.)
            $EndDisplay


    Here's how the above pop-up display would appear on the screen (at row
    5, column 20):

            +--Sample Pop-Up Display---------------+
            |                                      |
            |  This is just a simple example of a  |
            |       Phantom2 pop-up display.       |
            |                                      |
            |     (Press any key to continue.      |
            +--------------------------------------+


    Note that when you specify the row and  column  for  the  display  you
    should  take  into  account  that Phantom2 will add 3 columns-worth of
    border to each line and an extra line at the top and  bottom  for  the
    border.



    3.10.5  LABELS AND THE $GOTO DIRECTIVE

    You can cause playback to transfer from one place in a recording  file
    to  another  by  using the $Goto directive.  The $Goto directive has a
    single parameter:  the label of the location from which playback is to
    continue.  Labels in Phantom2 recording files take the form

            $<text>:


    where <test> is any printable text string not starting  with  a  digit
    and not containing spaces or tabs.

    Here is an example of a recording which continually clears the  screen
    and the displays the current directory:

            !
            ! Endless loop directory
            !
            $Loop:
            * CLS
            * DIR /W
            $Goto Loop




                                    - 21 -
    USING PHANTOM2                                               Page 3-13
    EDITING PHANTOM2 RECORDINGS                              14 January 91


    The $Goto is most useful for returning to  a  pop-up  menu  after  the
    actions  requested  by  the user have been carried out.  (Pop-up menus
    are described in the next section.)



    3.10.6  POP-UP MENUS

    You can cause menus to pop up during playbacks of Phantom2 recordings.
    These  pop-up menus can contain text and items from which the user may
    choose.  Once an item is selected, playback resumes at  the  place  in
    the recording file which is associated with that menu selection.

    When a pop-up menu is displayed, playback is  halted  until  the  user
    selects  an  item  or  until  a  timeout  period which you specify has
    elapsed.

    The text and selection items which you wish to appear in a pop-up menu
    are  placed between two Phantom2 directives:  $BeginMenu and $EndMenu.
    If you want a title to appear in the upper left border of  the  pop-up
    menu,  you  may  include  a $Title directive on the line following the
    $BeginMenu directive.

    The $BeginMenu directive takes the following form:

           $BeginMenu row col attr timo sr


    The parameters following the directive are interpreted as follows:

             row - the screen row on which the top pop-up menu  is  to  be
             written.

             col - the screen column on which the left edge of the  pop-up
             menu is to be written.

             attr - The display attributes to be used for display of  your
             text:
                            0 Normal
                            1 Bold
                            2 Reverse Video
                            3 Reverse Bold 

             timo - A timeout value in seconds.   If  the  timeout  period
             passes  without  keyboard  input,  the  display is erased and
             playback resumes.

             sr - The character S or R indicating whether you  wish  other
             Phantom2  displays  and  menus  which  may  be present on the
             screen to be erased  before  this  window  is  displayed.   R
             restores  the  screen  to  what  it  was  before any Phantom2


                                    - 22 -
    USING PHANTOM2                                               Page 3-14
    EDITING PHANTOM2 RECORDINGS                              14 January 91


             displays or menus were popped-up.  S saves the screen  as  it
             is  and  causes  the  new display to be painted over anything
             currently shown on the screen.

             Phantom2 pop-up menus are automatically erased when  playback
             is resumed.


    Menu selection items are placed after the $BeginMenu and the  optional
    $Title  directives  and after any introductory text you wish to appear
    above the selection items in the menu window.   Menu  selection  items
    are  prefixed by $<label> where <label> is the label at which playback
    is to be resumed (or at which another display  or  menu  is  defined).
    Labels are described in the section on the $Goto directive.

    Here is an example of the directives used to create a pop-up menu:

            !
            ! Create a menu at row 5, column 20, reverse video, 10-second
            ! timeout and retain any currently displayed pop-ups.
            !
            $START:

            $BeginMenu 5 20 2 10 S
            $Title Sample Pop-Up Menu

            Choose one of the items below
            by moving the highlight bar
            with the arrow keys and pressing
            RETURN when the item you want
            is highlighted.

            $DIR    Directory
            $CLEAR  Clear Screen
            $QUIT   Quit
            $EndMenu

            $DIR:
            * dir/w
            $Goto start

            $CLEAR:
            * cls
            $Goto start

            $QUIT:
            * exit






                                    - 23 -
    USING PHANTOM2                                               Page 3-15
    EDITING PHANTOM2 RECORDINGS                              14 January 91


    Here's how the above pop-up menu would appear on the screen (at row 5,
    column 20):

            +--Sample Pop-Up Menu----------------+
            |                                    |
            |  Choose one of the items below     |
            |  by moving the highlight bar       |
            |  with the arrow keys and pressing  |
            |  RETURN when the item you want     |
            |  is highlighted.                   |
            |                                    |
            |  Directory                         |
            |  Clear Screen                      |
            |  Quit                              |
            +------------------------------------+


    Note that when you specify the row and column for the menu you  should
    take  into account that Phantom2 will add 3 columns-worth of border to
    each line and an extra line at the top and bottom for the border.



    3.10.7  ELIMINATING HELP TEXT

    If you don't want the detailed help header on the PTM2TXT output file,
    you  can specify the /H switch on the command line.  This will cause a
    brief header to  be  prefixed  to  the  translation  rather  than  the
    detailed  help text shown in the above example.  Including both /C and
    /H will result in the smallest possible output from PTM2TXT.  Here  is
    an example of both switches being used:

            C> PTM2TXT /C /H RECORDNG.PTM RECORDNG.TXT

    .literal

    Note that the switches to the PTM2TXT command must be separated from the
    PTM2TXT command and other switches by spaces.

    When you have finished editing, you can create a recording file using the
    TXT2PTM program like this:

    .literal

            C> TXT2PTM RECORDNG.TXT RECORDNG.PTM








                                    - 24 -
    USING PHANTOM2                                               Page 3-16
    PASSING PARAMETERS TO RECORDINGS ON THE COMMAND LINE     14 January 91


    3.11  PASSING PARAMETERS TO RECORDINGS ON THE COMMAND LINE


                                     NOTE

            The programs TXT2PTM and  PTM2TXT  required  to  enter
            substitution    parameter   directives   in   Phantom2
            recordings are supplied with  registered  versions  of
            Phantom2 only.


    If you have placed substitution parameter directives in your recording
    file  (see  the  previous  section),  you  may  pass  the values to be
    substituted for them on the command line after the filename.  Here  is
    an example passing the parameters A:, XYZ, and BOOBOO:

           C> PHANTOM2/Q/I/K=F1 RECORDNG.PTM A: XYZ BOOBOO


    A:  is substituted for $1, XYZ for $2, and BOOBOO for $3.



    3.12  WHAT'S BAD ABOUT PHANTOM2?

    Well, Phantom2 doesn't  have  the  capability  to  determine  if  what
    happened  when  you  recorded the keystrokes is the same thing that is
    happening when you play them back.  It's as if you had  to  type  with
    your monitor turned off.  If things go wrong, Phantom2 just goes right
    on playing back keystrokes.  As  the  saying  goes,  the  results  are
    unpredictable...

    To recover an aborted editing session with Phantom2, for example,  you
    should  make  sure  that  everything is as it was when you started the
    recording:  the same files with the same contents,  the  same  default
    disk and directory, and so on.

    Batch files, on the other hand, can check the exit status of  programs
    to  determine  if  things  are  going awry.  But, supplying input to a
    spreadsheet is not something you  do  with  batch  files.   Also,  for
    simple  repetitive  tasks,  recording  what  you  want done is usually
    easier than writing and debugging a batch file to do it.

    Phantom2 doesn't record mouse activity, so you have to  do  everything
    you want recorded on the keyboard.








                                    - 25 -












                                  CHAPTER 4

                        PHANTOM2 TECHNICAL INFORMATION



    4.1  DOS VERSION REQUIREMENTS

    PHANTOM uses features first made available in MS-DOS  V3.0,  and  will
    probably not execute properly on prior versions of MS-DOS.



    4.2  CALLING PHANTOM2 FROM A USER PROGRAM

    You can invoke  Phantom2  functions  from  a  program  using  Int  2fh
    function  e1h  (passed  in  register  AH).  The following subfunctions
    (passed in register AL) are supported:

          o  00 - Installation check.

              .  AX = 0001 on return if Phantom2 is resident in memory.

              .  DS:SI =  address  of  null  terminated  hot-key  name  in
                 resident Phantom2

              .  DS:DI = address of null terminated recording file name in
                 resident Phantom2


          o  01 - Function request

              .  Call with BX = function mask, CX  =  INT  16  function  0
                 return   code   for   the  hotkey,  DS:DX  =  address  of
                 null-terminated filespec.

              .  Function mask bit  definitions:   0  record,  1  play,  2
                 QuickPlay, 3 Loop, 4 Mode Display Toggle, 5 Sound Toggle,
                 6 Set Hotkey, 7 Set Filespec






                                    - 26 -
    PHANTOM2 TECHNICAL INFORMATION                                Page 4-2
    CALLING PHANTOM2 FROM A USER PROGRAM                     14 January 91


          o  02 - Uninstall request.

              .  AX  =  0001  on  return  if   the   de-installation   was
                 successful.

              .  AX = 0002 on return if Phantom2 is  not  installed  as  a
                 TSR, but has merely spawned a command shell

              .  AX = ffffh on return if Phantom2 was only  disabled,  and
                 is now dormant in memory.





    4.3  HOW DOES IT WORK?

    Phantom2 intercepts the BIOS keyboard interrupt  and  the  PC's  clock
    interrupt,  and  in  record  mode,  copies any keystrokes that it sees
    along with the number of  clock  ticks  that  have  accumulated  since
    startup.   On playback, Phantom2 substitutes its own interrupt handler
    for the BIOS keyboard interrupt routine and feeds  back  the  recorded
    keystrokes  at  the  appropriate  times.   If  Phantom2  runs  out  of
    keystrokes to play back, it passes any requests for keyboard input  on
    to the BIOS keyboard interrupt routine.




























                                    - 27 -
