Shareware Grab Bag

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

/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / crossref.arc / CROSSREF.DOC < prev next >

Wrap

Text File | 1984-06-16 | 22.7 KB | 722 lines

Computerenergy's CROSSREF Cross Reference Utility Version 1.02 Proprietary Notice CROSSREF is a proprietary product developed by Richard C. Bemis and distributed by Computerenergy Corporation, Denver, Colorado. Copyright 1982 by Richard C. Bemis and Computerenergy Corporation. All rights reserved except those expressly granted to the user within this document. Computerenergy Corporation, PO Box 6267, Denver, CO 80206 (303) 233-9118 Source: ST6070 - i - TABLE OF CONTENTS Section Page CHAPTER 1 CROSSREF DISTRIBUTION NOTICE ............................. 1 CHAPTER 2 INTRODUCTION ............................................. 2 CHAPTER 3 SYSTEM SETUP ............................................. 3 3.1 Copying CROSSREF ............................................ 3 3.2 Program Setup - Final Installation .......................... 3 CHAPTER 4 OPERATION ................................................ 4 4.1 Execution ................................................... 4 4.2 Entering Responses .......................................... 4 4.3 Maillist/Donation Assistance ................................ 4 4.4 Program Entry ............................................... 4 4.5 Statistics and Limitations .................................. 5 4.5.1 Limitations ............................................ 5 4.6 Programming Tip ............................................. 6 CHAPTER 5 OPTION DEFAULTS .......................................... 7 5.1 Program Name Extension ...................................... 7 5.2 Beginning Program Line Number ............................... 7 5.3 Ending Program Line Number .................................. 7 5.4 Changing Default Options .................................... 7 CHAPTER 6 OTHER INFORMATION ........................................ 9 6.1 Distribution Disk Contents .................................. 9 6.2 System Requirements ......................................... 9 6.3 Disclaimer .................................................. 9 CHAPTER 7 SUGGESTIONS, FEEDBACK, AND BUG REPORTS ................... 10 CROSSREF - ii - Computerenergy Corporation CHAPTER 1 CROSSREF DISTRIBUTION NOTICE CROSSREF is being distributed using the "Freeware"* approach. To those of you unfamiliar with this approach, it works like this. You may send either a preformatted single-sided disk (or a prepaid contribution for our disk and mailer) to us with a prepaid return mailer and we will send a complete copy of the product. If the product does not meet your needs, please pay nothing. If the product does meet your needs, and you can use it, then we would appreciate a contribution of whatever you feel is appropriate. Naturally, we have probably given you a clue in several places as to what is our "completely unprejudiced opinion" of an appropriate contribution amount. Contributions are completely voluntary and much encouraged. Even if you do not contribute, you are encouraged to copy and distribute the product freely subject to the following restrictions: 1. Do not distribute altered copies. Note: You may distribute a separate set of modifications to merge in if you wish but they must be clearly identified as not originating from Computerenergy. If you do make modifications, we would like to see what you've done, if possible, for future versions. 2. The product is to be distributed as a complete "distribution copy" produced by the copy utility provided with the product for this purpose. 3. No fee is to be charged for copying or distributing the program without an express written agreement with Computerenergy Corporation. 4. Commercial sale of this product in any manner is prohibited without Computerenergy's written permission. Some products will be released with this permission automatically given and expressly stated. User Groups/Clubs: Computerenergy's freeware products may be distributed by Clubs and User Groups subject to the same restrictions. We would ask only that contributions to our continuing efforts be encouraged by those performing such distribution. Computer Bulletin Boards: Computerenergy's freeware products may be distributed by BBS's subject to the same restrictions and contribution encouragement. However, as the products tend to be large and consist of several files, we have some concern as to the reliability of transmissions and length of connect time. Perhaps disks could be mailed or just the documentation placed on the board for browsers. * The Freeware concept was initially developed by Andrew Fluegelman and the term "FREEWARE" is a trademark of The Headlands Press, Inc. The Headlands Press provides a catalog of information about Freeware products available from multiple sources. They may be contacted at PO Box 862, Tiburon, CA 94920 or Source: TCP204 or Compuserve: 71435,1235. CROSSREF - 1 - Computerenergy Corporation CHAPTER 2 INTRODUCTION Computerenergy's Cross Reference was created to make programming and maintenance jobs easier. We feel that a computer should help as much as possible in its own development efforts. CROSSREF is a tool that produces a cross-reference for each reference to a variable or a line number within a program. Multiple occurances of a variable or a line number on a single line will be referenced for each occurance. After you have setup the system and read the Operation chapter, we recommend that you try CROSSREF on some of your own programs. If you are going to "wing-it" without reading further, then SAVE the Basic program to be cross-referenced in ASCII (true wingers understand this), type CROSSREF, and good luck! CROSSREF - 2 - Computerenergy Corporation CHAPTER 3 SYSTEM SETUP The Cross Reference distribution disk contains a version of the program in compiled format along with its Syntax file and Options file. Compiled versions are being distributed as they execute much faster. 3.1 Copying CROSSREF There is a batch file which copies the entire distribution disk for backup or distribution purposes. We highly recommend making a backup copy before proceeding as it is safer and the mails can be slow. Place the Cross Reference distribution disk in Drive A: and a formatted disk without DOS on it in Drive B:. While in DOS, type CRCOPY and follow any instructions. 3.2 Program Setup - Final Installation We recommend that a copy of CROSSREF, its control file CROSSWDS.DAT and its options file CROSSOPT, all be placed on a Basic Program Development DOS System disk if possible. If this is your first run-through, do not perform this step yet - use your copy of the distribution disk and proceed to the Operation Chapter. 1. Copy CROSSREF.EXE to the System disk. A Sample COPY command might be: COPY B:CROSSREF.EXE A: 2. Copy the CROSSWDS.DAT file to the same disk. This file must be available any time CROSSREF is used. A sample COPY command might be: COPY B:CROSSWDS.DAT A: 3. Copy the CROSSOPT file to the same disk. This file must also be available any time CROSSREF is used. A sample COPY command might be: COPY B:CROSSOPT A: CROSSREF - 3 - Computerenergy Corporation CHAPTER 4 OPERATION 4.1 Execution Starting Cross Reference is simply a matter of entering DOS and typing CROSSREF followed by the Enter key. 4.2 Entering Responses You will quickly notice that all input requested by Cross Reference is at the bottom of the screen, following a prompt, and contained within a "target". We have found that a relatively constant area for data entry is superior to the more typical design of "fill-in-the-blanks" as it minimizes eye travel and usually makes for a more consistant entry process. All responses are completed by pressing the Enter key. In several prompts, and on the keyboard, the Enter key is represented by a symbol roughly similar to this: (<-'). In addition to the normal editing functions provided for inner-field editing there are a couple of special functions available: Field Erase: Press the ESC key to erase an entry and start over or to change a field that has a pre-loaded value. Field Backup: Press the Up-Arrow to "backup" to the previous entry. The current entry will be erased as you "backup". Note: You can "backup" as far as you like until the very beginning of the program. 4.3 Maillist/Donation Assistance The first screen you see is a title, information, and copyright screen with a "Press Enter to continue or space for Maillist/Donation assistance" prompt. Normally, you will press the Enter key to start CROSSREF. If you press the space bar, a program will run which will help you print a letter that you can send to us to be sure you are placed on our maillist - particularly important if you did not receive your copy directly from us. Amazingly enough, the letter will even assist you in making a contribution but that is not required (nice though). Note: The assistance program - CRMAIL - is contained on the distribution disk and its copies but should not be copied to your DOS development disk as it is large, not required, and a waste of disk space. CRMAIL is chained from CROSSREF as it resides on the distribution disk or may be executed directly from the distribution disk by typing CRMAIL. 4.4 Program Entry The next question you will be asked is to specify the Drive address that contains the program(s) to be referenced. This is followed by the Program Entry screen. Up to 25 programs may be specified to be CROSSREF - 4 - Computerenergy Corporation CHAPTER 4: OPERATION listed in sequence at one time. NOTE: Each program must be previously saved in ASCII format using the ",A" option of the Save command in Basic. Example: SAVE "B:progname.S",A We use the .S extension for "Source" to differentiate between Basic encoded programs and those saved in ASCII. This approach also provides 2 copies of each program as it is developed - a sort of automatic backup. Any program extension may be used. If a program is read by CROSSREF that has accidentally not been saved in ASCII, CROSSREF will display an ERR=62 message and return to DOS. For each program to be listed, CROSSREF asks for 3 pieces of information - program name, beginning line number to start listing, ending line number to end listing. Each program name may be entered without an extension and CROSSREF will append the default Program Name Extension from the options file (originally = ".S"). If the program is entered with an extension, then the entered extension will be used. Each line number field is pre-loaded with a default value from the options file which may be changed most easily by pressing the ESC key and keying a new number or backspacing and re-keying the number. The default value is selected by pressing the Enter key. The beginning and ending lines specified will limit the lines checked for references but will still list all references found within the range even if they refer to lines beyond the range. 4.5 Statistics and Limitations After each program's references have been listed, a short statistical summary is printed. The summary includes the number of lines read/processed, symbols referenced, references, beginning line, and ending line. Both variable names and line numbers that are referenced are defined as symbols. 4.5.1 Limitations The critical number from CROSSREF's point of view is the number of symbols. CROSSREF's current architecture will handle 500 symbols. If a program contains more symbols than that, we recommend that the reference be done in 2 or more parts. If you are using a 64K system, the maximum number of references is around 1000. If you have a 96K or larger system, the maximum is much larger. It should also be mentioned that CROSSREF will only print the first 12 characters of a variable name. Each variable name's references are kept correctly by their full name though not fully reflected on the table. CROSSREF - 5 - Computerenergy Corporation CHAPTER 4: OPERATION 4.6 Programming Tip CROSSREF can be used to help compact programs by locating unused variables that may no longer be required for a program. Look for any variable names that are referenced only once - they may be candidates for deletion. CROSSREF - 6 - Computerenergy Corporation CHAPTER 5 OPTION DEFAULTS The CROSSREF Options file - CROSSOPT - contains three data items that are used by CROSSREF to preload entries for you. They are referred to as default options or defaults. 5.1 Program Name Extension The Program Name Extension option is used by CROSSREF to concatenate to any program name that is entered without an extension. We use .S for "Source" to differentiate from Basic encoded programs (.BAS) but any extension is acceptable. If a program name is entered with an extension, this option is ignored. 5.2 Beginning Program Line Number The Beginning Program Line Number default establishes a value that will be preloaded into the Beginning Line Number prompt request for each program to be referenced. The value may be changed at entry time if desired. We tend to place a significant number of routines (the MONITOR) at lines 10 - 9999 and therefore do not wish to list these routines over and over. The beginning value we use is 10000 but any valid line number is acceptable. 5.3 Ending Program Line Number The Ending Program Line Number default establishes a value that will be preloaded into the Ending Line Number prompt request for each program to be referenced. The value may be changed at entry time if desired. The value we use is 65529, which is the highest valid line number for a Basic program and therefore will list to the end of the program. Any valid line number is acceptable. 5.4 Changing Default Options The Option file - CROSSOPT - is a sequential file that contains a single record with 3 fields. The record, as distributed, contains the 3 default values in sequence: Program Name Extension, Beginning Program Line Number, Ending Program Line Number separated by commas. The record looks like: .S,10000,65529 The file may be accessed and modified with EDLIN or any other text editor or word processor that works with PC-DOS compatible sequential ASCII files. If you are using EDLIN, the easiest way to change the defaults is as follows: 1. Assuming that the CROSSOPT file is on the default drive, and while in DOS, enter "EDLIN CROSSOPT" (without quotes). CROSSREF - 7 - Computerenergy Corporation CHAPTER 5: OPTION DEFAULTS 2. When EDLIN prints "End of input file", key a 1. EDLIN will respond with a "1*". 3. Rekey the entire line with the defaults changed to the way you want them, separated by commas, and press Enter. 4. After EDLIN displays "2*", press CTRL-BREAK. 5. After EDLIN displays the "*", key "E" (w/o quotes) and press Enter. The new file will be saved. CROSSREF - 8 - Computerenergy Corporation CHAPTER 6 OTHER INFORMATION 6.1 Distribution Disk Contents File Name Description ------------ -------------------------------------- CROSSREF.EXE Compiled CROSSREF CROSSREF.DOC Documentation CROSSWDS.DAT Basic Syntax File CROSSOPT Cross Reference Options File CRMAIL.EXE Maillist/Donation Assistance CRCOPY.BAT Copies Distribution Disk - both CROSSREF and MONITOR 6.2 System Requirements CROSSREF requires an IBM PC with 64K, DOS 1.1, and at least 1 disk drive (2 disks highly recommended for development machines). 6.3 Disclaimer All Computerenergy computer programs are distributed on an "as is" basis without warranty. Computerenergy Corporation and/or any of its program authors shall have no liability or responsibility to customer or any other person or entity with respect to any liability, loss or damage caused or alleged to be caused directly or indirectly by programs distributed in any manner by Computerenergy Corporation, including but not limited to any interruption of service, loss of business or anticipatory profits or consequential damages resulting from the use or operation of such computer programs. Note: Good data processing procedure dictates that the user test the program, run and test sample sets of data, and run the system in parallel with the system previously in use for a period of time adequate to insure that results of operation of the computer program are satisfactory. CROSSREF - 9 - Computerenergy Corporation CHAPTER 7 SUGGESTIONS, FEEDBACK, AND BUG REPORTS If you can spare the time, we would appreciate your feedback and suggestions to help us to improve CROSSREF. As an added inducement, we will also send a free CROSSREF (corrected) to the first person reporting each bug. Immediate family members of Computerenergy employees are NOT eligible. If possible, each bug reported should include a short-as-possible printout of the reference situation with explanatory notes. Our unprejudiced judging panel will make "Bug Awards" when the spirit moves them and, of course, their decisions are final. We are also aware of some esthetic errors when operating with the color video interface. Those still remaining should be corrected soon, but we'd still like to hear about any you find. Please address correspondence to the address on the title page. (If you've lost your title page, just send us a note and we'll send you a new one.) CROSSREF - 10 - Computerenergy Corporation