Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / FLXREF13.ZIP / FILEXREF.DOC < prev next >

Wrap

Text File | 1991-10-01 | 25.9 KB | 896 lines

FileXref A New Type of Cross Reference Tool Version 1.3 October, 1991 Release ConVal Software, Inc. _______ ____|__ | (R) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER Copyright 1990, 1991 ConVal Software, Inc. All rights reserved. ConVal Software, Inc. 11607 E. Butter Creek Road Moorpark, CA 93021 Sales and technical support: Monday - Friday (805) 529-6847 9 AM - 6 PM Pacific Time Leave a message and I'll contact you the same or next business day. 7 PM - 10 PM Pacific Time To speak to me directly. CompuServe 72330,1621 This program is produced by a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at: ASP Ombudsman 545 Grover Road Muskegon, MI 49442-9427 U.S.A. or send a CompuServe message via CompuServe MAIL to ASP Ombudsman 70007,3536. The ombudsman may be contacted by FAX by sending to the ASP FAX number: (616) 788-2765. In communication with the ombudsman please include a telephone number and/or FAX if available. TABLE OF CONTENTS INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . 4 FEATURES OF FILEXREF . . . . . . . . . . . . . . . . . . . . 5 INSTALLATION . . . . . . . . . . . . . . . . . . . . . . . . 8 SPECIFYING THE FILES TO BE EXAMINED . . . . . . . . . . . . . 9 SPECIFYING WORDS TO SEARCH FOR . . . . . . . . . . . . . . . 10 GETTING STARTED . . . . . . . . . . . . . . . . . . . . . . . 11 NOTES AND RESTRICTIONS . . . . . . . . . . . . . . . . . . . 13 DATA FILE FORMATS . . . . . . . . . . . . . . . . . . . . . . 14 FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 3 INTRODUCTION Having now been a software developer for more years than I care to admit, I've built a number of support tools for myself. I am now generalizing and formalizing those tools, making them available for other developers like you. FileXref is the first of these and I think you'll find it can give you a competitive edge for your development projects. There are three questions that FileXref directly answers. What is the potential application-wide impact of changing a particular source file? When I'm fixing a bug, how can I be sure that I've addressed the whole class of the underlying problem and not just one instance? What components are unused and obsolete? These questions can't be answered without some groundwork on your part, however. (Isn't that always the case?) FileXref needs access to text file representations of ALL components of your application. This includes your source code as well as documentation files, program specs, etc. It also needs your files to follow minimum naming conventions. For example file extensions must indicate the type of data held in the file. So .C files imply C source code, while .BAT files imply batch files, and .TXT or .DOC implies a printable text file. Although it is not a requirement for FileXref, you will reduce your own analysis problems if you : never let variable names match any of your filenames, make your filenames unique across all the file types you use, and group related files in a minimum of subdirectories. Running the demonstration provided will give you a series of reports to assist you in being able to answer the three questions above for the application you are developing or maintaining. (See the README.DOC file for instructions for running the DEMO.) FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 4 FEATURES OF FILEXREF FileXref analyzes a list of text files, extracting cross reference information which it stores in memory. It can process all text files and this version has special processing locic for supporting the syntax of the following file types: FILE EXTENSION CATEGORY ---- -------------------- .BAS BASIC .BAT Batch Files .C .H C source .CPP .HPP C++ source .COB COBOL .FOR FORTRAN .ASM Macro Assembler .MAK Make files .PAS Pascal .PLI PL/I .REX REXX .SQL .INP Oracle .TXT Text (ASCII) .DOC Text (ASCII) .PRG xBASE All other types are scanned as if they were ASCII text files with no regard to whether a reference was found in a "comment". You will prepare the list of files to be examined and insure that it represents all files related to your application. Or, you may use a utility, FileList (see Page 9), to create a list of all files on a disk drive which match one of the file types currently supported by FileXref. You'll optionally prepare a list of words and/or word prefixes you'd like cross referenced. Note that if you have a very large disk with much more source code than your application, this may cause FileXref to run "out of memory". If this happens, use your text editor to pare down the list generated by FileList to just those files needed by your application. You may also need to reduce the list of words and word prefixes you supplied. The FileXref utility will generate report files containing cross reference information for the list of files and words provided. FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 5 Three report files may be produced: A List of Unreferenced Files, A File Usage Report, and A Word Usage Report. The List of Unreferenced Files lists every file which was referenced by no other file examined. So this list contains your application's top level components. You would expect to see top level overview specs and/or batch files in this list. It also will contain components not yet documented. This will assist you in keeping documentation up to date with the product. And it may contain obsolete components. Now you have a tool to keep obsolete components from confusing the development and maintenance effort! The File Usage Report shows, for every file examined, each file which references it. This report may be selected in two styles. A condensed version is available for applications with source code localized to a small number of subdirectories. An extended style is available for others. This report will tell you the global impact of changing a file. By examining the list of impacted files repeatedly, you can construct a completely exploded tree representing the "ripple effect" of changing the one file. The Word Usage Report is optional. If you supply a list of words or word prefixes to FileXref, it will cross reference the words and word prefixes to the files referencing them. This report also is available in condensed and extended styles. By following the following conventions the Word Usage Report can be a valuable aid to problem solving. o use meaningful names for variables o use the same name for the same variable in all modules o don't use variable names which are the same as keywords in any of the languages you're using The Word Usage Report will show everywhere in your application each variable (word) is used. FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 6 So if you are working a bug having to do with the value of a counter, the report will show you every reference to the counter variable in the system - including documentation and support files! You will be able to address the counter's integrity throughout the system instead of just in the particular instance where it was incorrectly set. Here then is a tool for solving problems, not just addressing individual symptoms! As an alternative to producing report files, FileXref can instead generate cross reference data files. These files are in a "quote and comma delimited" format. You may load these files into your spreadsheet or database program and work with the data that way. FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 7 INSTALLATION FileXref requires an IBM PC, XT, AT, PS/2 or compatible computer with 256K of RAM. Your CONFIG.SYS file must specify FILES=10 or more for the program to run. In addition, version 2.0 or greater of PC-DOS or MS-DOS is required. FileXref requires approximately 100K of computer memory to contain the program's executable code. Additional memory is allocated as required to contain the list of files and words being processed and cross reference information about them. This data is allocated in conventional memory. FileXref will acquire as much conventional memory as is available to handle large applications and/or large numbers of words to be cross referenced. FileXref is not a Terminate and Stay Resident program, so the memory it uses is only required when you are actually running the program. Installing FileXref is very simple. There is only one file required to run the program. This is FILEXREF.EXE (the program itself). Copy this file to one of the directories identified in your PATH command. In order to run the DEMO, copy three additional files - FILELIST.EXE (a support utility), FILEXREF.WSL (an input file for the DEMO), and DEMO.BAT (a batch file to run the DEMO). When FileXref is started with no command-line arguments, it assumes its input control files (FSL and WSL) are in the current directory and it creates its output files (RPT, XRF, FEI and MSG) in the current directory. For other options, see page 11. FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 8 SPECIFYING THE FILES TO BE EXAMINED A File Specification List (FSL) file identifies to FileXref the files to be scanned and cross referenced. It is a text file which may be created with any text editor. Each file spec must start in column one of the record and only one file spec may exist on each record. Example: C:\SOURCE\MAINPGM.C C:\SOURCE\SUBPGM1.C C:\SOURCE\SUBPGM2.C C:\SOURCE\INCLUDE\INFILE.H C:\SOURCE\INCLUDE\OUTFILE.H A:\SAMPLES\DEMO01.TXT By naming all files in your application for FileXref, you insure that you will get a complete cross referencing. To ease the effort in preparing this file, a utility called FileList is provided for you. Given a starting directory, it will READ all files in that directory, writing each filename matching a file type that FileXref knows how to scan. It recursively processes subdirectories so that all files in the tree starting with the specified directory are extracted. It produces its output to the DOS standard output, so it can be redirected. Example 1: This causes FileList to create an input file for FileXref of all files on C:\SOURCE and its subdirectories. FILELIST C:\SOURCE > FILEXREF.FSL Example 2: This causes FileList to create an input file for FileXref of all files on the C disk. FILELIST C: > FILEXREF.FSL Example 3: This causes FileList to create an input file for FileXref of all files on the C, D, and E disks. FILELIST C: > FILEXREF.FSL FILELIST D: >> FILEXREF.FSL FILELIST E: >> FILEXREF.FSL FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 9 SPECIFYING WORDS TO SEARCH FOR An optional input to FileXref is a Word Specification List (WSL) file. This contains words and word prefixes you wish to see cross referenced to the files that reference them as well as those to be excluded from the resulting list (for example language keywords). Use a text editor to create this file. Start each entry in column one and place a code and a word or word prefix on each record. The code must be "I" for Include or "X" for eXclude. Terminate word prefixes with an "*". All entries will be raised to upper case by FileXref when output. Example 01: Cross reference all uses of the whole word "malloc", the whole word "extern" all symbols that start with the letters "str", and exclude the words "if" and "else". I malloc I extern I str* X if X else Example 02: Cross reference all symbols I * NOTE: This option will use up memory very quickly, since ALL words will be cross referenced (even words like "the", "and", "a"). If you use this option you may need to limit the number of files to examine, or use the technique in the next example. Example 03: Cross reference a portion of the alphabet on one pass of the files. Use multiple passes to cover the whole alphabet. Use this technique if you get an "out of memory" type of error message. I A* I B* I C* I D* I E* I F* . . . FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 10 GETTING STARTED Prior to running FileXref, create the list of files to be examined (see page 9) and, optionally, the list of words and word prefixes to be cross referenced (see page 10). Remember that the program won't run unless CONFIG.SYS contains FILES=10. The usual way to start up FileXref is to type FileXref and press Enter at the DOS prompt. However, the following parameters can be specified on the command line to modify FileXref's behavior during a particular run. The general command line syntax for running FileXref is: FILEXREF [opt fsl xrf fei msg wsl rpt] where opt is: ? Causes FileXref to display help information. /RPTS Instructs FileXref to create only extended reports. /RPTC Tells FileXref to create only condensed reports. (This is the default.) /RPTB Directs FileXref to create both extended and condensed reports (the DEMO uses this). /RPTN Specifies that no reports are to be generated - produce data files instead. fsl is a file specification for the input file containing file specifications for each source to be examined. If omitted, this defaults to FILEXREF.FSL. xrf is a file specification for the output cross reference data file. If omitted, this defaults to FILEXREF.XRF. fei is a file specification for the output data file to contain a list of unreferenced files. If omitted, this defaults to FILEXREF.FEI. msg is a file specification for the output file of run statistics. If omitted, this defaults to FILEXREF.MSG. wsl is an optional file specification for the input file containing the words and word prefixes to be cross referenced. If omitted, this defaults to FILEXREF.WSL. rpt is an optional file specification for the output file containing the reports. If omitted, FILEXREF.RPT. FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 11 Example 1: Take all the defaults. FILEXREF The two control files (FSL and WSL) must be in the current directory. This will read file specifications from FILEXREF.FSL and will look for optional word specifications in FILEXREF.WSL. Messages will be output to FILEXREF.MSG. Since the default processing is /RPTC, condensed reports will be written to FILEXREF.RPT, while files FILEXREF.XRF and FILEXREF.FEI will be empty. Example 2: Create data files instead of report files. FILEXREF /RPTN This invocation will cause cross reference data (in quote and comma delimited format) to be written to FILEXREF.XRF and unreferenced symbols to be written to FILEXREF.FEI. No report file will be generated. Example 3: Override the location and naming of the report file. FILEXREF /RPTC FILEXREF.FSL FILEXREF.XRF FILEXREF.FEI FILEXREF.MSG FILEXREF.WSL C:\DATA\MYREPORT.FIL NOTE: Although the above is shown as three separate lines, you would type it all in at the DOS prompt and press enter once. NOTE: All pameters are positional. So, to override the last one, we supplied the defaults for all others. That is, none may be omitted prior to the one you wish to override. FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 12 NOTES AND RESTRICTIONS 1. The FileXref utility distinguishes the comment syntax of each file extension, i.e. REM in .BAT files and /* */ in C files. Symbols found within comments are not cross referenced. 2. Symbols found in quotes or apostrophes are cross referenced. 3. If you get the message "Insufficient memory", try reducing the scope of the processing. This may mean limiting the file specification list (FSL) entries to only those files used by your application and/or eliminating / limiting the word specification list (WSL) entries to just those you need to see. Or see example 3 on page 10 for a multiple pass solution. 4. Only the first 31 chacters of a symbol are retained. 5. Symbols are all converted to upper-case in the report and data files. 6. Cross reference entries will be created only for filenames and symbols that are consistent with the symbol naming convention for each source file type. So the restriction means that if the following is a fragment from a .C file, a cross reference entry would not be created for lines 3 or 4 below, even though these are valid DOS file names. This is because the names are not valid C symbols. 1. avg_value = get_avg ( list ); OK 2. fp = fopen ( "C:\\TEST.dat", "r" ); OK 3. fp = fopen ( "87tax.dat", "w" ); starts with a digit 4. strcpy ( fspec, "A:$budget.trn" ); starts with $ FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 13 DATA FILE FORMATS FILEXREF.XRF Columns are quote and comma delimited. ====> FILENAME2 IS REFERENCED BY FILENAME1 COLUMN COLUMN COLUMN 1 2 3 ------------------------------------ FILENAME2 FILENAME1 F ====> WORD MATCHING A WORD PREFIX IS REFERENCED BY FILENAME1 NOTE: THE WHOLE WORD, NOT JUST THE PREFIX IS IN COLUMN ONE. COLUMN COLUMN COLUMN 1 2 3 ------------------------------------ WORD FILENAME1 E ====> WORD IS REFERENCED BY FILENAME1 COLUMN COLUMN COLUMN 1 2 3 ------------------------------------ WORD FILENAME1 W ====> WORD PREFIX IS REFERENCED BY FILENAME1 COLUMN COLUMN COLUMN 1 2 3 ------------------------------------ WORD FILENAME1 P FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 14 FILEXREF.FEI Columns are quote and comma delimited. ====> UNREFERENCED FILENAME: COLUMN COLUMN 1 2 ------------------------ FILENAME F ====> UNREFERENCED WORD PREFIX: COLUMN COLUMN 1 2 ------------------------ WORD PREFIX P ====> UNREFERENCED WORD: COLUMN COLUMN 1 2 ------------------------ WORD W FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 15 End of FileXref Documentation.