Simtel MSDOS 1992 September

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

/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / dbase / dscar1.arc / DSCAR.DOC < prev next >

Wrap

Text File | 1986-07-02 | 37KB | 1,201 lines

d S C A R dBASE Source Code Analyzer & Reporter by Ryan Katri Version 1.0 July 1, 1986 Ryan Katri 2575 Drake Hill Road Fortuna, CA 95540 Voice: (707) 725-5559 Modem: (707) 725-9612 (7pm-3pm) Copyright (c) 1986 by Ryan Katri All Right Reserved. dSCAR User's Guide Table of Contents Purpose . . . . . . . . . . . . . . . . . . . .3 System Requirements . . . . . . . . . . . . . .3 Read This! . . . . . . . . . . . . . . . . . .3 Installation . . . . . . . . . . . . . . . . .5 Invoking dSCAR . . . . . . . . . . . . . . . .6 The Menu . . . . . . . . . . . . . . . . . . .7 Quitting dSCAR. . . . . . . . . . . . . . . . .8 Diagram Program Flow . . . . . . . . . . . . .8 Control Only . . . . . . . . . . . . . . . . .9 Errors Only . . . . . . . . . . . . . . . . . .9 Line Numbering . . . . . . . . . . . . . . . .9 Modules . . . . . . . . . . . . . . . . . . . .10 Variables Cross-Reference . . . . . . . . . . .10 Output . . . . . . . . . . . . . . . . . . . .11 GO! . . . . . . . . . . . . . . . . . . . . . .12 Additional Modules . . . . . . . . . . . . . .12 Batch Mode . . . . . . . . . . . . . . . . . .13 Limitations . . . . . . . . . . . . . . . . . .14 Appendix A: Reporting Problems . . . . . . . .15 Appendix B: Error Messages . . . . . . . . . .16 Appendix C: Future Enhancements . . . . . . . .17 Appendix D: About Me & My Program & My Help . .18 Appendix E: Disclaimer. . . . . . . . . . . . .19 Page 3 -Purpose- --------- To put it bluntly, dSCAR is a tool for dBASE III and dBASE III Plus that performs the following functions: -- Structured formatting of dBASE code (indentation). -- Flow diagrams to highlight control statements. -- Cross-referencing of variables and field names. -- Display structural errors in code. -- Line numbering of source code. -- Selectable options to get the report you want. -- Ability to send any reports to screen, printer or disk. -- Menu-driven or command-driven. -System Requirements- --------------------- dSCAR should work on any IBM PC/XT or compatible machine that meets the requirements of running dBASE III or dBASE III Plus. It was developed under PC-Dos 3.1, but should work on most lower versions of Dos. dSCAR can also process dBASE II source code. The only drawback is if you use a dBASE III reserved word for a variable or field name. If this is done, the variable or field name is NOT included in the variables cross-reference. You may also experience this problem using dBASE III if you have used any dBASE III Plus reserved words as variables. -READ THIS!- ------------ This is a full-fledged version of dSCAR. The only drawback to it is that it displays a title page every time it is brought up. This screen can by by-passed by pressing <return>. If <return> is not pressed, dSCAR will continue execution after a 30-second wait, thus allowing dSCAR to be run in batch files with un-attended operation. Optionally, you can press the letter key 'I' to bring up an invoice for dSCAR that can be printed by hitting Shift+PrtScr. Page 4 You can register your copy of dSCAR by sending $20 - $100,000 (or more if you have it!) to this name and address: Ryan Katri 2575 Drake Hill Road Fortuna, CA 95540 If you do register you will receive the latest version of dSCAR (are there going to be any more versions?) without the title page garbage. In this form, dSCAR can be instantly fired up and ready to go to work on your dBASE code! When you register, be sure to include your mailing address and phone number. I would also appreciate any comments about dSCAR: suggestions for improvements, how you are using it, where you got it, etc. The registered version will be sent to you through the mail or you can elect to download it from my Bulletin Board System: M.I.T. Colossus (707) 725-9612 7pm-3pm, 7 days a week. 300/1200/2400 Baud The latest demo version can also be found on my BBS. Page 5 -Installation- -------------- To configure dSCAR for your particular system setup, run dSCAR using 'C' as an argument on the command line, like this: DSCAR C dSCAR immediately comes up with the installation questions to customize it for both your needs and your hardware (especially your printer). Each question is detailed below under its appropriate heading. Note that defaults are displayed except for certain questions. All yes/no questions default to 'no'. Your basic cursor editing keys are in effect. <Insert>, <Delete>, and arrow keys all work like you would expect. NUMBER OF SPACES FOR INDENTATION: This is the indentation increment you want to use below control statements, such as IF, DO WHILE, DO CASE, etc. Shown below are two pieces of the same code, the first with an indentation of 3 and the second with an indentation of 5. store 1 to count This is code produced do while count < 100 with an indentation if count = 50 then of three (3). ? 'Halfway there!' endif x = x + 1 enddo store 1 to count This is with indentation do while count < 100 five (5). if count = 50 then ? 'Halfway there!' endif x = x + 1 enddo STRIP DRIVE/PATH FROM FILENAMES: This options defaults to 'no', use the drive and path specified. Regardless of what this option is set to, dSCAR always recognizes and uses any path appended to the main file you enter at start-up. This option is especially important when the option Modules (detailed later) is turned on. See the Modules section for more information. PRINTER LENGTH: The printer length tells dSCAR how many lines are on the paper so that it can issue a formfeed at the proper time to skip over the perforation. The default should work Page 6 for paper that is the standard 11 inches long. PRINTER WIDTH: Some of you probably use wide carriage printers, so this option will keep dSCAR from printing on only half the page. If you set your printer for condensed mode you will probably also want to reset this. PRINTER SETUP SEQUENCE: Up to 10 characters may be sent to your printer. This may be used to set condensed mode, emphasized print, or a variety of other options you may want to use when printing out your source code with dSCAR. To send an escape, press the ESCape key. To send other non- printable ascii characters, hold down the ALT key and enter the ascii code using the numeric keypad. Keyboard characters can be easily entered by typing the character. When you are done entering codes, enter a blank line by hitting the <Return> key. PRINTER RESET SEQUENCE: When you are done using dSCAR, these printer codes will be sent (if defined). Follow the same method detailed above in the Setup Sequence for entering your printer codes. The last question asked is if you want to save your configuration. If you made a mistake and want to start over (by re-running dSCAR), answer no. If saving the configuration is confirmed, dSCAR will ask for a filename to clone itself to. Do not include an extension with the filename, as dSCAR automatically adds the .COM extension that is needed. Upon entering the filename, dSCAR will write a new copy of itself to your file. This file may be run just like the original dSCAR was!! There is no need for any external configuration files. Consider the new copy your custom version! -Invoking dSCAR- ---------------- Running dSCAR in the menu-driven mode is as easy as typing 'DSCAR' (without the quotes) at the Dos prompt. If you cloned your configuration to a different filename than 'dSCAR', enter that filename instead. You will then be prompted for the dBASE file that you wish to process. When entering the filename, an extension of .PRG is assumed. If your file has a different extension than this, specify it. If there is no extension, place a dot after the filename anyway so that dSCAR will not add the default .PRG. Path names are supported. Up to 80 characters may be entered for Page 7 the filename so that you can specify the directory it is in. If a valid filename is entered and the file exists, a menu bar will appear across the top line of the display. -The Menu- ---------- NOTE: The menu colors will appear different depending on whether you are using a color or monochrome screen. dSCAR automatically determines which type of display you are using and adjusts the colors accordingly. If you experience problems with this adjustment, let me know and I'll work something out for you. First, we'll define the different parts of the screen. On the top line we have the menu bar, which contains the options available to select and de-select. Next, we have the status line towards the bottom of the screen. This line displays the name of the program (dSCAR), the copy- right notice, and the dBASE file to be processed. Below the status line is the help line. This will contain a one- line description of the option currently selected on the menu bar. The menu of options is almost completely self-explanatory, but some explanation may still be needed. Here is a quick review of what the options do: Go! - Begin processing of file using set options Controls - Displays control lines only Diagram - Diagram program flow Errors - Display errors only -- no source listing Output - Toggles the output device: screen, printer, or disk Modules - Processes modules called by current module Numbering - Adds line numbers to source output X-Ref - Variables cross-reference To toggle any of these options, highlight it using the cursor keys or by pressing the first letter of the option (such as 'X' for X-Ref), then hit the <return> key. The Output option is selected a little bit differently, as is Page 8 explained below in the Output section. MONOCHROME MONITOR USERS: Selected options appear as bright video. If the cursor is on a selected option, the cursor will blink. COLOR MONITOR USERS: Selected options appear as yellow on blue text. If the cursor is on a selected option, it is yellow on gray text (as opposed to the normal cursor of white on grey). -Quitting dSCAR- ---------------- Quitting dSCAR is accomplished by pressing Q or <Esc> (the Escape key). At this point you are again asked for a filename to process. If you are completely done with dSCAR and have no more files to process, hit <return> to exit to Dos (or the calling program). -Diagram Program Flow- ---------------------- One of the most useful features of dSCAR is its ability to line up all your control statements to make sure they are structurally sound. This makes it easy, for example, to see where you might have an open CASE or a missing IF. The resulting output with Diagramming on would look something like this: store .t. to okay do while okay W accept 'What is your name?' to myname W if upper(myname) <> 'JOE' W T ? 'Only Joe is allowed access!' W T cancel W else W F ? 'Hello Joe' W F do case W F case myname = 'JOE' W F 1 ? 'JOE' W F 1 ? 'Welcome' W F case myname = 'joe' W F 2 ? 'joe' W F 2 ? 'Not Welcome!' W F otherwise W F O ? W F O cancel W F endcase W endif enddo Page 9 Notice that each control statement has a corresponding character to represent it. For example, a WHILE structure is lined up with a W. Below is what each characters represents: W - DO WHILE; terminates with ENDDO T - IF is true; terminates with ENDIF or ELSE F - ELSE is false; terminates with ENDIF C - DO CASE; terminates with first CASE, OTHERWISE, or ENDCASE # - Number of the case statement; terminates with next CASE, OTHERWISE, or ENDCASE O - OTHERWISE; terminates with ENDCASE If you don't quite understand these, try running some of your dBASE code through dSCAR with Diagramming on and I think you'll get the picture. -Control Only- -------------- This option tells dSCAR to only include the control lines in the output. These control lines would be commands like DO CASE, IF, OTHERWISE, ENDIF, etc. This option is especially useful in conjunction with the Diagram function. The purpose of this is to quickly see if your program flow is correct without having to look at all the other extraneous code. -Errors Only- ------------- With Errors Only on, only errors that are found in the dBASE code are displayed. These errors can be of many types. See Appendix B for a listing of error messages. When selected, Line Numbering, Control Only, and Diagramming are automatically turned off. -Line Numbering- ---------------- Line Numbering on will add line numbers to your source code. If Variable Cross-Reference is on, then I suggest to have Line Numbering on, as the variables are referenced with the corresponding line numbers. Page 10 -Modules- --------- Modules will instruct dSCAR to process all modules that may call each other in a complete dBASE system. Anytime dSCAR comes across a DO <filename>, it will add the filename to a list of modules to be processed. Thus, if you had several modules to process, and they are all eventually called somewhere in the system, you could start with the main module and dSCAR will work from there. To illustrate this: You have the module called MAIN.PRG, which calls ACCOUNTS.PRG and INVENT.PRG. ACCOUNTS.PRG in turn calls EDIT.PRG, and INVENT.PRG also calls EDIT.PRG. If you turn Modules on and start with the file MAIN.PRG, then all of these would get processed: MAIN.PRG, ACCOUNTS.PRG, INVENT.PRG, and EDIT.PRG. A module will NOT be processed twice! The current module being processed is written on the command line where the main file was. Thus, it is easy to see what modules have errors in them with a glance at the status line. Depending on what you specified in the configuration, drive designators and path names will or will not be stripped from filenames. If a file cannot be found, no matter where it is looking, it is merely skipped. No error message is displayed. dSCAR will also look for SET PROC TO <filename> and process procedure files, too. -Variables Cross-Reference- --------------------------- Variables Cross-Reference is a cross-reference of variables in a file. If this is used, Line Numbering should be turned on also. The resulting listing of the variables contains the variable name and the line numbers it occurs in. Simple as that! Each procedure gets its own cross-reference. If Modules is on, also, then a global cross-reference of variables will also be made. The global cross-reference quickly shows which variables occur in which files. If it occurs in a procedure, then the procedure name is displayed, and the module name is in parenthesis next to it. Page 11 -Output- -------- When <return> is pressed with Output highlighted, an output device name in parenthesis next to the word 'Output' is toggled between three devices. These are screen, printer, and disk, with screen being the default. Each of these is explained in further detail: SCREEN: Everything goes to the screen. When the screen is full you can press <return> to see the next page, or hit the Q key to exit back to the main menu. DISK: Output to a file is good for formatting your code to make it easier to read. To get an output readable by dBASE, turn OFF Line Numbering, Diagramming, Errors Only, and Controls Only. When output to a file is selected, the resulting output file is filename.FLO. The original file is left unchanged. If Variables Cross-Reference is on, then the cross-reference goes to a file named filename.XRF. And if Variables Cross-Reference and Modules is on, then the global cross-reference goes to a file called GLOBAL (with no extension). IF ANY OF THESE FILES ALREADY EXIST ON THE DISK, THEY WILL BE OVERWRITTEN WITH NO WARNINGS! Example: Original file : MAIN.PRG Processed file : MAIN.FLO X-Reference file : MAIN.XRF Global X-Ref file : GLOBAL PRINTER: The printer option is excellent for printing up documentation when your dBASE system is all done. I suggest turning on Diagramming, Line Numbering, Variables Cross- Reference, and Modules to print out the whole system with complete documentation, including variables cross-reference and global cross-reference. All pages will be numbered when output goes to the printer. A table of contents is printed if Modules is on. If a printer is not hooked up to the computer, or is off-line, then Output only toggles between Screen and Disk, making the printer inaccessible. As soon as the printer is ready, you are able to select it as the output device. Page 12 -GO!- ----- To begin processing with the desired options, just press the 'G' key, or highlight 'GO!' and hit <return>. If output is to printer, be sure the printer is hooked up and on- line. If output is to a file, make sure there is enough free space on the current drive to handle the new files. -Additional Modules- -------------------- If you have modules to process that are not called by other modules, there is a way to process these in a batch-type method. Or, you might have a section of dBASE code that looks like this: DO FILE&X The filename to be processed depends on the X variable. dSCAR would try to process the file called FILE&X and, as you can see, fail to find the file! To process this file you could create a text file called MODULES and put in it all the files you want to be processed that wouldn't normally be processed. dSCAR will look for this file IF Modules is on. The stucture of the file MODULES should be one filename per line, with each line separated by a carriage return. This file could be created with your word processor or text editor in the non- document mode. Or you could create the file using the Dos command COPY CON MODULES. Enter each filename and when done press your F6 key (or Ctrl-Z) and then the <return> key. The file MODULES (no extension) should come out looking something like this: FILE1.PRG FILE2 FILE10.XYZ Get the idea? Even if dSCAR does come across a DO <filename> and the filename is in the MODULES file list, it will NOT be processed twice. NOTE: Remember to delete your MODULES file when you are done with it. dSCAR does not delete it for you. Page 13 -Batch Mode- ------------ There is another way to invoke dSCAR besides just by typing DSCAR from Dos. You can also tag on a filename to the command line, and some options if wanted. If a filename is included then dSCAR will skip asking for a filename when it starts up. Example: DSCAR MAIN.PRG The extension did not have to be included, as .PRG is assumed. dSCAR would start up and automatically use MAIN.PRG as the file to process. You can also specify options to use from the command line. If this is done then dSCAR returns to Dos when processing is complete, and does not pause when a screen is full. Thus, dSCAR works smoothly in Dos batch files. To specify the options, include them after the filename (and a space between the filename and the options). The options are just as you would specify from the menu. To demonstrate: DSCAR MAIN FVMD | |||| | ||| \__Diagramming ON | || \___Module Processing ON | | \ ___Variables Cross-Reference ON | \_____Ouput to File \_________File to process Notice that the D in the options turned Diagramming on. This is due to the fact that during batch operation with dSCAR, diagramming is NOT turned on as a default! If you wish to run dSCAR in auto mode but have NO options turned on, specify an invalid option, like this: DLONE MAIN A 'A' is not a valid option, so dSCAR will ignore it but still put you in auto mode. I like to use 'A' because it is easy to relate to the mode: Auto. Even though dSCAR does not stop after each page when screen output is selected, you can still abort this operation by pressing your 'Q' key. You may have to hold it down, as dSCAR is not very sensitive to keypresses while it is processing files. This is another feature that needs to be experimented with to get full understanding. Page 14 -Limitations- ------------- There are only a few limitations on dSCAR. The biggest one is probably that it can handle only so many variables for a cross- reference. If you find major garbage in your listing of variables, then you have probably reached the limit on allowable variables. If this occurs, call me and I might be able to help. Another limitation is that all commands should be separated by a space, or you may end up with some wierd variables in the cross- reference. Let's say you have a line of code that reads something like this: If Name = Your_Name.or.Name = His_Name Your_Name.or.Name will be treated as one variable. It can not interpret the .OR. statement between the two variables. This, on the other hand, is okay: If Name=Your_Name .or. Name = His_Name dSCAR will separate Name and Your_Name, no problem. You may have to do a little experimenting to determine what dSCAR can and cannot handle. I think you'll find that it will work fine on most code you have written. Page 15 -Appendix A: Reporting Problems- -------------------------------- The steps to be taken before reporting an error are as follows: 1) Read all documentation to make sure it is not YOUR problem. 2) Try re-configuring dSCAR. 3) Get rid of all other programs that are in memory or were loaded at boot-time and see if the problem still persists. 4) Call me or my BBS system or write (these numbers and the address are listed above!) and tell me of the error, where it occurs, and under what circumstances. I will be more than happy to help and appreciative of your efforts in tracking down the bugs in my program! Page 16 -Appendix B: Error Messages- ---------------------------- dSCAR traps many errors that may occur in dBASE code. The below summarizes the various error messages and explains the meanings, if needed: DO CASE not followed by CASE DO with no program name ELSE without IF Empty DO CASE ENDCASE without DO CASE ENDDO without DO WHILE ENDIF without IF or ELSE Follows LOOP - never executed -> Statement following LOOP is never processed by dBASE Follows RETURN never executed -> Statement following RETURN is never processed by dBASE Missing DO CASE statement -> CASE with no DO CASE Open DO CASE from line x Open DO WHILE from line x Open IF from line x Open TEXT from line x Redundant LOOP statement -> LOOP occurs just before an ENDDO, so would be processed many times SET PROC not followed by TO Unexpected ENDTEXT -> No TEXT to match the ENDTEXT Warning: At most 1 iteration -> A RETURN occurs within a loop, so loop would only last for 1 iteration WITH expected, but not found -> Words following DO <filename> are ignored unless it is WITH <variables> Page 17 -Appendix C: Future Enhancements- --------------------------------- These are the many features I'd still like to add to dSCAR: o Maybe re-write in Modula. I understand it is a great language (especially when coming from a Pascal background) and I currently have Interface Technologies Modula-2 (SDS), but waiting for an update. Would rather do it in Logitech's, as I hear it is SSSOOO much better! o Number of cross-referenced variables only dependent on memory. I'm hoping Modula will make it easier to do than it is in Pascal. o Faster! Again, I'm partly relying on Modula to cure this problem. I do know of some code changes that would help speed-up dSCAR, but that would require a total re-write in the current language I am using! o User-specified colors. Adding color options is hard for me to do, as I only have a Hercules display card with monochrome monitor. Maybe someday, though... o Smaller. Probably another re-write... o Code stripper. Give dSCAR the ability to strip out un- necessary spaces, tabs, comments, and break all commands down to their 4-letter equivalents (i.e. APPEND becomes APPE). This could be added fairly easily, but would probably have to go to overlays (which I don't want to do). o Anything anyone suggests!! Throw your ideas & comments at my way. Page 18 -Appendix D: About Me & My Program & My Help- --------------------------------------------- I, Ryan Katri, am a student on a LOW budget. You wouldn't believe how low my budget is!! That is why I am asking you (the user of my program) to support the User-Supported concept of software distribution; it will increase my time available in designing and writing quality programs like dSCAR, as I will not have to do other work! dSCAR started out as a project to test my just-learned skills as a Pascal programmer. The resulting program turned out much bigger than I originally anticipated. One feature I had planned for dSCAR had to be left out because I could not figure out how to do this certain thing in Turbo Pascal. It was not Turbo that kept me from putting the feature in, but was my lack of sufficient knowledge. Sorry! I have not separated dSCAR into overlays, as you will notice. I almost refuse to do it, also! My reasoning behind this decision is that if you run dSCAR from a different directory than what it is in, it would not be able to find the overlays in most cases! A little more inside information behind the economics of dSCAR: I was thinking about selling dSCAR for $20, but decided against this, as I cannot afford the advertising needed. Therefore, I distributed dSCAR using the User-Supported concept. This way I get free distribution and maybe a handful of people will be generous enough (and honest enough) to send me some reimbursement for my efforts. There you got it. A history of dSCAR--sort of. Now a few words of thanks to: Gene Head for beta-testing and actually reporting problems! Not only that, Gene is responible for getting me 'hooked' on computers, and therefore takes the blame for screwing up my life! Michael Bosen for donating to me a copy of Turbo Pascal (no, not pirated!) and also recognizing the importance of a screen-install program! Dan Hankison and Bruce Bott for going beyond their duties as beta testers by providing advice and suggestions in the overall look, feel, and function of dSCAR. And the many others who have contributed to the success(?) or failure(?) of dSCAR. Page 19 -Appendix E: Disclaimer- ------------------------ RYAN KATRI AND ANYONE INVOLVED IN THE CREATION AND TESTING OF dSCAR SHALL NOT BE HELD RESPONSIBLE FOR ANY DAMAGE INCURRED BY THE USER TO HARDWARE, SOFTWARE, OR PERIPHERAL DEVICES WHILE RUNNING dSCAR. ALL RESPONSIBILITY LIES WITH THE USER OF THE SOFTWARE. Page 20