====================================================================== 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.