
======================================================================
Welcome to the demo version of Valkyrie for Clipper 5. This demo is
almost identical to the full system. The primary limitation is that
this version will not save anything to disk. You can, however, preview
source code in a window on-screen, and perform most other functions.
======================================================================

Installing the Demo
======================================================================

The complete Valkyrie 5 Demo is contained in V5DEMO.ZIP. You should
unzip this file onto your hard disk, preferably in a directory in your
PATH. There are no other special environment settings required to run
the demo.

V5DEMO.ZIP contains the following files:

   V5DEMO.EXE
      The Valkyrie 5 Demo main program. Start the demo by running this
      program. You can run it from a different directory if it can be
      found in your PATH.

   VPP5.EXE
      The Valkyrie 5 Preprocessor. This is the program that identifies
      the linker used on Clipper applications. It writes this
      information and a list of the names and locations of all Clipper
      procedures in the application to a .RIP file. An ASCII version
      of this information is written to a .MOD file. VPP5 is run
      automatically by V5DEMO.EXE -- you do not have to run it
      yourself.

   VAU.EXE
      The Valkyrie Analysis Utility, which can be used to determine
      which Clipper compiler was used to create an .EXE file. Run it
      from the DOS command line followed by the name of the .EXE file
      to analyze, and it will report what it finds in the file. If it
      cannot identify the compiler used on the file, it will report
      "No Clipper signature located". If the file was compiled with
      Clipper Summer 87, the Valkyrie S87 demo may be used on it.

   CLIPPER.VLB
   EXTEND.VLB
   ERRORSYS.VLB
   BLINKER.VLB
   CT3.VLB
      The .VLB files contain ASCII lists of module and procedures
      names for various Clipper libraries. These are used by the
      "Assign from Libraries" command in V5.

Running the Demo
======================================================================

Start the demo by running "V5DEMO". You will see a sign-on screen from
the Phar Lap Dos-Extender (used to create V5DEMO.EXE), followed
shortly by the V5 main screen and menu bar.

A few of the commands on the menus are disabled in the demo. First,
the "Recover" command on the File menu is disabled. This prevents you
from saving recovered source code to disk, but you can preview any
procedure on-screen. "View Source File" is also disabled -- since the
demo does not write source files to disk, there will be no source
files to view. In the full system, the contents of any window can be
written to a disk file. In the demo, this feature is disabled. Lastly,
the Options|Video and Options|Color commands are disabled in the demo
version.

======================================================================
Valkyrie 5 Commands
======================================================================

Following is a brief description of each command in the Valkyrie 5
menu system.

File Menu
----------------------------------------------------------------------

The File Menu provides commands for opening and recovering Clipper 5
EXE files, and also a few miscellaneous system commands.

   Open
      Allows you to open a Clipper EXE file for recovery. Highlight
      the desired file in the list of EXE files and press enter or
      click OK. If this is the first time you have opened this file,
      Valkyrie will automatically run the Valkyrie 5 Preprocessor
      (VPP5) on it to create the .RIP and .MOD files. If you are
      unsure if a file was compiled with Clipper 5, choose "Analyze"
      to see if it was. When the file is opened successfully, you will
      see a Statistics box with various information about the EXE
      file. After closing this box, the Application Window will be
      opened, which shows you all of the Clipper procedures found in
      the EXE file, along with pertinent information about each
      procedure.

   Resolve Conflicts
      This command is used in the full system before a complete
      recovery is performed. It examines the list of procedures and
      source modules in the Application Window to ensure that all
      static procedures and variables are correctly located to avoid
      problems when recompiling the system. Conflicts occur when a
      static procedure or variable is referenced outside of the module
      it in which it is defined. Since Valkyrie 5 allows you complete
      control over the placement of the procedures in your
      application, it is always wise to run this command before the
      complete recovery. The demo version of this command works the
      same as in the full system.

   Change Directory
      This command allows you to change to a different working
      directory while running the system.

   DOS Shell
      Allows you to temporarily exit to DOS. Type 'EXIT' at the DOS
      prompt to return to the Valkyrie 5 demo.

   About
      Displays the sign-on screen containing the Valkyrie version and
      copyright information.

   Exit
      Exits the Valkyrie 5 Demo. In the full system, the current
      layout of the modules and procedures in an open EXE file is
      written to a .CFG file.

Module Menu
----------------------------------------------------------------------

Modules are the source files which will be created by Valkyrie 5 when
the application is recovered. A Module contains one or more
procedures. In the main Application Window, Modules are listed in the
left-most column. The second column contains procedure names belonging
to the modules in column one. This window is where you can organize
the application being recovered.

   Sort
      Allows you to sort the procedures in a module according to a
      certain criteria. If you sort a module, only the procedure in
      that module will be sorted. Normally, the Application Window
      lists procedures by module in the order in which they will be
      written to the disk file. This command allows you to quickly
      change the order of the procedures within a module.

   Rename
      Allows you to change the name of a module, which is listed in
      column one of the Application Window. This name is used to
      create the source file. Valkyrie 5 creates source files with an
      extension of .SRC to avoid accidentally overwriting existing
      .PRG files on your hard disk.

   Find
      Allows you to quickly locate a module in the Application Window
      by name. A listbox appears with the names of all source modules
      in the current application. Type the name, or first few letters,
      of the module you want to locate, then press enter or click OK.
      The Application Window will be positioned to the first line
      containing the desired module.

   Dependents
      Displays a dialog box containing the names of all dependents for
      the highlighted module in the Application Window. A dependent is
      a procedure which must accompany (i.e., be in the same source
      file as) the module in question. When you choose to display
      dependents for a module, the list box shows you all of the
      procedures that belong to the module, and also all dependents of
      these procedures. This gives you a complete list of all
      procedures which should be in the source file.

   Assign from Libraries
      This command allows you to quickly assign module names based on
      procedures found in common libraries such as CLIPPER.LIB and
      EXTEND.LIB. The list of names used by this command are found in
      .VLB files in your Valkyrie directory. The demo ships with five
      predefined files: CLIPPER.VLB, EXTEND.VLB, ERRORSYS.VLB,
      BLINKER.VLB, and CT3.VLB. When you choose this command, a dialog
      box shows you a list of these five libraries, and a second list
      box shows you the list of procedure names defined for each
      library. To assign the names for a library, highlight the
      library name and click on 'Assign'. Valkyrie 5 will go through
      your application and find any procedure names which match the
      names in the dialog box, and then assign those procedures the
      module name from the library, such as CLIPPER or EXTEND. This
      command helps in recovering Clipper 5 apps when there are many
      Clipper-written routines pulled into your .EXE file from
      CLIPPER.LIB, etc. To avoid having these routines recovered into
      your application, you can assign modules from the .VLB files
      with this command, and recover them (or not) into separate .SRC
      files, which you can then examine or disregard.

   Assign from Debug Info
      When a Clipper 5 application is compiled with debugging
      information (the /b switch), the names of the original source
      modules are encoded into the compiled code. Also available are
      the names of static and local variables. Choosing this command
      assigns to the application any module names available from debug
      info. The new module names appear in the Module column of the
      Application Window.

   Revert
      Allows you to revert to the original layout of the application,
      when it was created by VPP5. Use this only when you want to undo
      any and all changes you have made to the layout of the
      application.

   Tag All
      Tags all procedures for the selected module. This allows you to
      then go to the Procedure Menu and perform commands on the group
      of tagged procedures all at once. See the Procedure Menu for
      more information on commands that work with tagged procedures.

   Tag Dependents
      Similar to the Tag All command, but additionally tags all
      procedures which are dependents of any procedure contained in
      the module. The resulting group of tagged procedures can then be
      acted upon with one command from the Procedure Menu.

   Include All
      Marks all procedures in the module to be included for recovery
      when the Recover command is run. Initially, all procedures will
      be recovered unless disabled with the Exclude All command. This
      command basically undoes the effects of the Exclude command.

   Exclude All
      Marks all procedures in the module to NOT be recovered. This
      might be useful if you have assigned the library names from
      CLIPPER.VLB and then do not want to recover these procedures as
      part of your application.

Procedure Menu
----------------------------------------------------------------------

Procedures are the Clipper-coded parts of the application. "Procedure"
and "Function" are often used interchangably in Valkyrie, except when
source code is recovered. They are listed in the main Application
Window, in column two, after the module to which they belong.
Procedures can be moved from module to module, sorted, rearranged,
etc, through the commands on this menu. There are also several
commands for viewing and browsing procedures.

   Preview
      Allows you to quickly preview the recovered source code for a
      procedure in a scrolling window. Highlight the procedure you
      wish to view with the arrow keys, and then hit F7, or click on
      "Preview" on the status line. The source code is constructed and
      then displayed in a window. In the full Valkyrie 5 system, this
      window may be panned left and right to completely view longer
      lines of code. In the demo version, this feature is disabled.

   Browse
      Brings up a dialog box which displays usage information on the
      highlighted procedure in the Application Window. The information
      displayed includes: Dependents, Calls Made, Called By, Variables
      Used, Variables Changed, String Constants, and more.

   Dependents
      Shows a quick list of dependents for the highlighted procedure.
      A dependent is any other procedure which must accompany (reside
      in the same source file as) the highlighted procedure.
      Dependents in Clipper 5 occur when the application uses static
      procedures and/or variables. A static procedure may only be
      called by a procedure in the same source file, so each would be
      a dependent of the other. Likewise, file-wide static variables
      may only be referenced by a procedure in the same source file.

   Find
      Allows you to quickly locate a procedure in the Application
      Window by typing the first few letters of its name.

   Find Top
      Goes directly to the top (or sometimes called the "main")
      procedure of the application. This is the procedure which is
      first executed when the application is run, and thus it must be
      the first routine in its source module, and this module must be
      the first to be specified to the linker. The Top procedure is
      identified by VPP5 when it processes the application and creates
      the .RIP file.

   Move Top|Bottom|Up|Down
      Moves the highlighted procedure to the Top, the Bottom, Up one
      position, or Down one position, respectively, in its module.
      Procedures cannot be moved to other modules with these commands,
      they affect only the position of a procedure within its module.
      They allow you to specify the exact layout and ordering of
      procedures within a module.

   Relocate
      The relocate command moves one or more procedures to a
      different, or new, module. It is one of the more powerful
      commands on the Procedure Menu. It acts upon the currently
      highlighted procedure. If several procedures have been tagged
      through other commands, it affects the entire group of tagged
      procedures. The dialog box contains a check box labled "Move
      Dependents". When this option is checked, the highlighted or
      tagged procedures are moved along with ALL dependents of those
      procedures. This ensures that procedures can be moved to other
      modules without the danger of leaving behind a dependent in the
      old module. You may choose the name of an existing module, or
      type a new module name, and it will be created as a new module
      in the application. If you type the name of an existing module,
      the relocated procedures are merged into the existing module
      along with the procedures already there. A new module contains
      only the relocated procedures.

   Separate
      The separate command is similar to the Relocate command, except
      that it moves each highlighted or tagged procedure to a
      separate, individual module with the name of the procedure. This
      is useful when you want many small source modules, each
      containing a single routine. Tag the procedures to be separated,
      then then use this command to separate them out.

   Tag/Untag
      This command toggles the tagged status of the highlighted
      procedure in the Application Window. A tagged procedure will
      have arrow indicators in the left and right margins of the
      window. Multiple procedures can be tagged, one after the other,
      and then another command, such as Relocate, can be executed on
      them.

   Tag All
      This command tags all procedures in the entire application.

   Tag All Like
      This command allows you to tag procedures based on a wildcard
      pattern, such as "REPT*". You can view a list of matching
      procedures by clicking on the "Show Selected" button before
      clicking OK.

   Tag Dependents
      This commands tags all dependents of the highlighted procedure.

   Clear All Tags
      Clears all tags from all procedures.

   Include
      Marks a procedure for inclusion in the recovery process. Used to
      re-enable a procedure which may have been previously excluded
      with the Exclude or Exclude All commands.

   Exclude
      Marks a procedure to be excluded from the recovery process. The
      procedure will be dimmed in the Application Window. When the
      source code is recovered, the excluded procedures will not be
      written to disk. This option should be used only when it is
      certain that a procedure is not needed or desired in the
      recovery.

PCode Menu
----------------------------------------------------------------------

PCode (pseudo-code) is the internal format of compiled Clipper 5 code.
Note that pcode is not the same as assembly language, although they
share a few characteristics. Clipper pcode is unique to Clipper. It is
created by the Clipper compiler and written to the .OBJ files and then
linked into the final .EXE file. It is interpreted when the
application is executed by a run-time interpreter. Thus, although
Clipper 5 is not a true native-code compiler, it does compile Clipper
source code to an efficient internal format. The Valkyrie 5 PCode
Window displays a symbolic form of the pcode for the highlighted
procedure in the Application Window. While it is beyond the scope of
this Valkyrie demo to describe Clipper pcode and what each opcode
does, it is nonetheless a very interesting and educational window.

   Search for Text
      This command allows you to search the pcode window for specific
      text within the compiled code. "Text" in this case means string
      constants, such as prompts and messages, as coded in the
      original source code. These string constants are compiled with
      the PUSHC (Push Character) opcode.

   Search for Symbol
      This command allows you to search the pcode window for a
      reference to a particular symbol from the symbol table. A symbol
      is referenced in the pcode by various opcodes, which are
      generated by source code expressions that fetch or store the
      value of a variable, or when a function call is made.

   Search for Opcode
      This command presents a list of the available Clipper 5 opcodes,
      and lets you search for the use of such an opcode in the pcode
      window.

   Repeat Search
      Repeats the previous search for Text, Symbol, or Opcode.

   Goto Offset
      The offset of each line of pcode in the window is displayed in
      the left-most column in the window. The offsets start at 0 and
      advance based on the number of bytes in each opcode. For
      instance, a string constant opcode uses one opcode byte for the
      PUSHC opcode itself, another byte for the length of the string,
      followed finally by the characters of the string. A symbol table
      reference uses one byte for the opcode, followed by 2 bytes
      indicating the position of the symbol in the symbol table.

   Goto Line Number
      When source code is compiled with line numbers, each line of
      compiled code starts with a line number opcode, followed by all
      of the opcodes generated for the line of code. This command
      allows you to find a particular line number opcode, which
      corresponds to the physical line number in the original source
      code.

   Jump
      Certain pcode commands are "jump" commands, similar to the
      various jump commands in assembly langauge. There are several
      types of jumps in Clipper pcode, such as JMP (Jump) and JF (Jump
      If False). Each opcode is followed by the location to which the
      interpreter should jump when executing the code at run-time. The
      Jump command moves to the target of the highlighted jump opcode
      in the pcode window. It will be disabled if the window is not
      highlighting a jump opcode.

View Menu
----------------------------------------------------------------------

The View Menu presents the complete list of windows available in
Valkyrie 5, as well as a few other related commands.

   Display Order
      Allows you to specify the display order in the Application
      Window. "Module" is the default display order, and this is the
      order in which procedures and modules will be written to disk.
      Therefore, when you choose some other display order, some of the
      commands on the procedure menu become disabled (such Move Up or
      Move Down, which do not have meaning when you are displaying
      procedures sorted by size).

   Application
      Switches to the Application Window. Available only after an .EXE
      file has been opened.

   PCode
      Switches to or opens the PCode Window, which displays the
      compiled PCode in sync with the Application Window. Available
      only when an .EXE file is open.

   Externals
      Displays the names and addresses of all external procedures in
      the application. An External procedure is one which was written
      not in Clipper but in some other language, such as C or ASM.
      Valkyrie 5 cannot decompile external procedures.

   Symbol Table
      Displays the Symbol Table for the application. The Options
      command allows you to choose which types of symbols to display
      and the sort order of the symbols.

   Messages
      Opens the Message Window. Valkyrie 5 writes any warning or error
      messages to the Message Window.

   Statistics
      Displays the statistics box for the application. This is the
      same box displayed when you open an .EXE file for the first
      time.

   Source File
      Disabled in the demo.

Options Menu
----------------------------------------------------------------------

   Preferences
      Allows you to specify several interface preferences for use in
      Valkyrie 5, such as mouse characteristics and some display
      options.

   Video
      Disabled in the demo.

   Color
      Disabled in the demo.

   Symbol Table
      Allows you to specify options for the Symbol Table Window. This
      is the same dialog box as that produced by the Options command
      in the Symbol Table Window itself.

   Preprocessor Translations
      Toggles the capability for Valkyrie 5 to perform Clipper 5
      Preprocessor Translations in the recovered source. For more
      information on the Clipper 5 Preprocessor, see your Clipper
      manual and especially STD.CH in your Clipper INCLUDE directory.
      Valkyrie can reverse many of the translations defined in STD.CH,
      as well as several others from INKEY.CH, SET.CH, and COMMON.CH.
      When this option is turned on, Valkyrie 5 will "un-preprocess"
      the source code before it is displayed in the Preview Window.
      Many times this is actually how the source code was originally
      written, and it looks more like "xBase" code. When it is off,
      you will see the raw Clipper code that was actually processed by
      the Clipper compiler when the application was created.

   Animate PCode
      This option moves the highlight bar through the PCode Window
      when the code is being parsed for the Preview command.

   Save
      Saves the current options to the VALKYRIE.INI file. Disabled in
      the demo.

Window Menu
----------------------------------------------------------------------

   Close
      Closes the active window. If the Application Window is active,
      the Clipper EXE file is also closed, and all associated windows
      (PCode, Externals, Symbol Table) are also closed.

   Next
      Selects the next window on the desktop.

   Move
      Allows the active window to be moved on the desktop. Use the
      arrow keys to move the window, and press enter when the window
      is positioned. Windows may also be moved by dragging their title
      bar with the mouse.

   Size
      Allows the active window to be resized with the arrow keys.
      Windows may also be sized by dragging the lower right corner of
      the frame.

   Zoom/UnZoom
      Enlarges the active window to full-screen size, or toggles back
      to its previous size. Windows may also be zoomed by double-
      clicking on the title bar with the mouse.

   Tile
      Arranges the active windows on the desktop in a tiled pattern.

   Cascade
      Arranges the active windows in a cascaded pattern.

   Write to Disk
      Write the contents of the active window to an ASCII text file.
      Disabled in the demo.
