Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / TLDR20.ZIP / FILXRF.DOC < prev next >

Wrap

Text File | 1992-10-01 | 21.8 KB | 571 lines

F i l e X r e f Version 2.0 ──────────────────────── User's Guide ┌───────┐ ┌───────┐ │ (R) ──│ │ │─────────────────── │ ┌───────┐ │ Association of ConVal Software, Inc. │ │ │─┘ Shareware └──│ o │ Professionals ─────│ | │───────────────────── └───┴───┘ MEMBER F i l e X r e f Version 2.0 ──────────────────────── User's Guide ┌───────┐ ┌───────┐ │ (R) ──│ │ │─────────────────── │ ┌───────┐ │ Association of ConVal Software, Inc. │ │ │─┘ Shareware └──│ o │ Professionals ─────│ | │───────────────────── └───┴───┘ MEMBER Copyright 1990-1992 ConVal Software, Inc. All rights reserved. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Features of FileXref . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Specifying the Files to be Examined. . . . . . . . . . . . . . . . . . . 9 Specifying Words to Search for . . . . . . . . . . . . . . . . . . . . . 10 Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Notes and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 13 Data File Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Page 6 Introduction ────────────────────────────────────── ConVal Software supports software developers. It provides tools and services to assist throughout the life cycle of a software project. FileXref was the first of these tools, and I think you'll find it can give you a competitive edge for your software 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 files are unused and obsolete? These questions can't be answered without some groundwork on your part, however. (Isn't that always the case?) FileXref examines text file representations of the components of your application. This can include source code as well as your documentation files, program specs, etc. It 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. It doesn't really matter what the extension is, as long as all files with the same extension are the same type of file. Although it is not a requirement for FileXref, you will reduce your own analysis efforts if you: ■ never let variable names match any of your filenames, language keywords or words you may use in messages to the user, ■ make your filenames unique across all the file types you use, and ■ group files of the same file type under a common subdirectory To state this differently, when you want to find something you want only to find what you're looking for. So if you name a variable "help", and have files with the name "help" and use the word help in messages, you will complicate your life. Why? Well when you are having a problem with the variable named "help" not being properly initialized, the first thing you'll probably do is a global search for the word "help". What comes back from the search will be far more than you need to solve the immediate problem. So you'll have to waste your time looking at files having nothing to do with the problem you're solving. Wouldn't it be easier if your search returned just references to the variable? To see how FileXref works independently of ToolDriver, type FILEXREF at the DOS command line. This will cross reference the files in FILEXREF.FSL and the words in FILEXREF.WSL. Page 7 A Condensed File Cross Reference report, showing the relationships of the files will be produced. A Condensed Word Usage Report will also be created if the text file FILEXREF.WSL exists. An Unreferenced Files will be produced if there were any files which were not referenced by any others in the list. View the output report FILEXREF.RPT and the run statistics FILEXREF.MSG. 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 logic for supporting the syntax of the following file types: FILE EXTENSION CATEGORY ─────────────────────────────────────────────── .BAS BASIC .BAT Batch Files .C .CPP C and .H .HPP C++ source .CBL COBOL .COB COBOL .FOR FORTRAN .ASM Macro Assembler .MAK Make files .PAS Pascal .PLI PL/I .REX REXX .SQL .INP Oracle .TXT .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 10), to create a list of all files on a disk drive which match one of the file types in the table just above. You'll optionally prepare a list of words and/or word prefixes you'd also like cross referenced. Page 8 FileXref can run out of memory when processing very large numbers of files and words. If this happens, you may unload other programs (like TSR's), and/or 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. Later you'll see how to break a large job into smaller pieces. FileXref will generate report files containing cross reference information for the list of files and words provided. Three report files may be produced: 1) The file cross reference report presents "up" and "down" references in one integrated report. It lists a file name in the center column with its "next assembly" information on the left and its "component" information on the right. The cross reference report may be selected in two styles: Use "condensed" reporting style when knowing a file's file type is enough to know the directory where it may be found. Use "extended" reporting when filenames are not enough to uniquely determine a full file specification. E.G If C:\APP01\HIST.PRG and C:\APP01\HIST.C both exist, then a reference to HIST alone is ambiguous. 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. 2) The Word Usage Report is optional. It shows the usage of names, symbols, and variables throughout your source and documentation files. 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. 3) 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! Page 9 By using the following guidelines, the Word Usage Report can be a valuable aid to problem solving. ■ use meaningful names for variables ■ use the same name for the same variable in all places ■ avoid the use of names which are the same as keywords in any of the languages you're using So if you are working on 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 (or export) 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. 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 and may be created with any text editor. Each file spec must start in column one of a line and only one file spec may exist on each line. 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. Page 10 To ease the effort in preparing this file, a utility called FileList is provided for you. Given a starting directory, it will read all file names in that directory, writing each filename matching a file type in the table on page 7. FileList processes subdirectories as well so the file selection process examines a directory tree, not just a single directory. Example 1: This causes FileList to create an input file for FileXref of files on C:\SOURCE and its subdirectories, writing it to file FILEXREF.FSL. FILELIST C:\SOURCE FILEXREF.FSL Example 2: This causes FileList to create an input file for FileXref of files on the C disk. FILELIST C: FILEXREF.FSL Example 3: This causes FileList to create an input file for FileXref of files on the C, D, and E disks. FILELIST C: C.LST FILELIST D: D.LST FILELIST E: E.LST COPY C.LST+D.LST+E.LST FILEXREF.FSL 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. It may also contain words 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 line. The code must be "I" for Include or "X" for eXclude. Terminate word prefixes with an "*". Example 1: Cross reference all uses of "malloc", "extern" and words that start with the letters "str". Exclude "strcopy". I malloc I extern I str* X strcopy Page 11 Example 2: Cross reference all words. 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 3: Cross reference a portion of the alphabet on one pass of the files. Use multiple passes to cover the whole alphabet. You may use this technique if you get an "out of memory" type of error message. I A* I B* I C* I D* . . . 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). The program requires that CONFIG.SYS contain FILES=20, or greater. 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. /RPTC Tells FileXref to create condensed reports. (This is the default) /RPTE Instructs FileXref to create extended reports. /RPTX Specifies that no reports are to be generated - produce export files instead. fsl is a file specification for the input file containing file specifications of each text file 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. Page 12 fei is a file specification for the output data file to contain a list of unreferenced files (File End Items). 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 a file specification for the input file containing the words and word prefixes to be cross referenced. If omitted, this defaults to FILEXREF.WSL. If this parameter is not overridden and the file FILEXREF.WSL exists, then a Word Usage Report will be generated. rpt is a file specification for the output file containing the reports. If omitted, FILEXREF.RPT. Example 1: Take all the defaults. FILEXREF This will read file specifications from FILEXREF.FSL and look for the file FILEXREF.WSL. If found, it will read its contents for words to be cross referenced. Messages will be written to FILEXREF.MSG. Since the default processing is /RPTC, condensed reports will be written to FILEXREF.RPT. Files FILEXREF.XRF and FILEXREF.FEI will be empty - they are only used with the /RPTX option. Example 2: Create data files instead of report files. FILEXREF /RPTX This invocation will cause cross reference data (in quote and comma delimited format) to be written to FILEXREF.XRF and unreferenced words to be written to FILEXREF.FEI. The report file FILEXREF.RPT will be empty. 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 two separate lines, you would type it all in at the DOS prompt and press enter once. NOTE: All parameters 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. Page 13 Notes and Restrictions ────────────────────────────────────── 1. The input files must be text files with each line terminated by a line feed alone or a carriage return and line feed. 2. The FileXref utility distinguishes the comment syntax of each file extension, i.e. REM in .BAT files and /* */ in C files. Words found within comments are not cross referenced. 3. Words found in quotes or apostrophes are cross referenced. 4. 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 11 for a multiple pass solution. 5. Only the first 31 characters of a word are retained. 6. Cross reference entries will be created only for filenames and words 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 c or d below, even though these are valid DOS file names. This is because the names are not valid C symbols. a. avg_value = get_avg ( list ); OK b. fp = fopen ( "C:\\TEST.dat", "r" ); OK c. fp = fopen ( "87tax.dat", "w" ); starts with a digit d. strcpy ( fspec, "A:$budget.trn" ); starts with $ Data File Formats ────────────────────────────────────── FILEXREF.XRF Columns are quote and comma delimited. Every line in FILEXREF.XRF consists of three columns. COL COL COL 1 2 3 ------ -------- --- SYMBOL FILENAME Flags Table 1: Export file flags ──────────────────────────────────────────────────── Column 123456 ------ The symbol in the first column is: 1..... a filename. .1.... a whole word. ..1... a word prefix. ...1.. an expansion of a word prefix. ....1. The symbol was referenced. .....1 The symbol was marked for inclusion. ──────────────────────────────────────────────────── Page 14 Examples: ───────────────────────────────────────────────────────────────── "SUB1","DRIVER","100011" Filename DRIVER contains a reference to symbol SUB1, which is a filename. "READ","DRIVER","010011" Filename DRIVER references the symbol READ, which was specified as a word in the word specification list. "Testing","DOC1","001011" Filename DOC1 references the symbol Testing, which is a word prefix in the word specification list. "Testing5","DOC1","000111" Filename DOC1 references the symbol Testing5, which matches a word prefix in the word specification list. ───────────────────────────────────────────────────────────────── FILEXREF.FEI Columns are quote and comma delimited. Every line in FILEXREF.FEI consists of two columns. COLUMN COLUMN 1 2 -------- ----- FILENAME Flags Flags is as described on the prior page. Examples: ─────────────────────────────────────────────────────────────────────── "SUB2","100001" Filename SUB2 was not referenced by any other file. "EXEC","100001" Filename EXEC was not referenced by any other file. ─────────────────────────────────────────────────────────────────────── End of FileXref Documentation.