FINDER - SUPERSTRUCTURE USER'S MANUAL Copyright 1994 G.A.Morris 16 Ferryfield Edinburgh EH2 4AN Scotland UK CompuServe ID 100275,1443 1 INTRODUCTION ................................. 1 2 OPERATION .................................... 2 2.1 Comments & Strings ..................... 3 2.2 Comments for Documentation ............. 4 2.3 Send Operator .......................... 4 2.4 #INCLUDE & .CLP Files .................. 4 2.5 Information Screen ..................... 5 2.6 Generated Files ........................ 5 3 GENERATING STRUCTURE FILES ................... 6 3.1 Top Menu ............................... 6 3.2 Create ................................. 6 3.2.1 Specifying Search Criteria ....... 7 3.3 Work .................................. 10 3.3.1 View ............................ 10 3.3.2 New Run ......................... 11 3.3.3 Update .......................... 11 3.4 Delete ................................ 11 3.5 Exit .................................. 12 4 REVIEWING STRUCTURE FILES ................... 13 4.1 Function Keys ......................... 14 4.2 Reporting Options ..................... 15 4.2.1 Reports-Listings ................ 16 4.2.2 Report-Redundancies ............. 17 4.2.3 Report-Settings ................. 18 5 APPENDIX .................................... 20 5.1 Installation .......................... 20 5.2 File Structures ....................... 21 1 INTRODUCTION SuperStructure is a programme designed to allow developers of Clipper software to maintain full details about their .PRG files, function/procedure declarations and list the calls made to them. SuperStructure also has the capability of maintaining a set of development notes which can be incorporated by the developer into the SuperStructure data base files or, alternatively, imported directly from the .PRG files by placing a + after the comment block start delimiter /*. Databases of individual application's structure files can be maintained for projects and the contents viewed in alphabetic .PRG file order, declared function/procedure order or called order. This allows the developer to track where functions have been declared, where a function is being called from and the .PRG files containing the original declaration. To assist in pin-pointing the location of individual declarations and calls in a programme file, the line number is also included. By typing the full drive\path name that is to be scanned, the developer can quickly produce a complete data base of all function declarations and calls and immediately view it in a browse style window. Facilities are available for printing the function declaration and calling hierarchy in a Clipper application along with, optionally, notes for each declared function. In the demonstration version the number of .PRG files which will be searched is limited to five. In the demonstration version of SuperStructure, the database files generated are 'zapped' when the run is completed. In the working version data base files are maintained for permanent reference. G.A.Morris SuperStructure 1 2 OPERATION SuperStructure works as a syntax checker to locate function and procedure declarations and calls for the Clipper language and, as such, some idiosyncrasies may arise depending on the syntax style adopted by the applications developer. From tests carried out during development all syntax styles 'appear' to be catered for, however, there may be some that are missed. If you find any, please fax a copy of the offending code fragment and the syntax style will be included in future releases of SuperStructure. (Fax No 031 220 0927) Given that the programme text files for an application are maintained on an application directory, SuperStructure will scan all .PRG (or other user defined file extension) files on the application's directory and generate a set of database structure files which show the declared functions and procedures, where they are called, which functions they call and related information. If #INCLUDE and .CLP files are incorporated into the search, and they contain references to other paths, the .PRG files on the specified paths will also be included in the search. A database of applications structure files is also maintained for reference when using SuperStructure. SuperStructure itself is written in Clipper and developers will be familiar with the input screens and mechanisms used for displaying data. It should be emphasised that SuperStructure does not make any alterations to the source .PRG files which it reads from the disc. The .PRG file is read directly into a variable and as such; the .PRG file should not exceed 64k in length. As a syntax checker, SuperStructure has been based on the current Clipper 5.1 version and will handle most styles of syntax. G.A.Morris SuperStructure 2 2.1 Comments & Strings The first operation to be carried out by SuperStructure is to remove all comments from the PRG file text. This is done to avoid conflicts when searches for commands such a FUNCTION are carried out. If the in line comment // this is a function to do something was included in the .PRG file, SuperStructure would report that the word 'to' was a function declaration. Hence, all free text, in comments or delimited as strings is excluded from the searching. All forms of comment delimiters are supported with the exception of ** for an inline comment. This is because ** can also represent the exponentiation operator in Clipper 5.1. The preferred form for in line comments of // is supported and should be used. ** inline comment delimiters may cause a problem if the comment contains Clipper command words such as FUNCTION, PROCEDURE or DO. If this problem is encountered, change the ** to // in your .PRG file. The '*' comment line syntax is supported. The second operation carried out by SuperStructure is to remove all free text strings contained in the file. The three delimiters ', ", and [] are supported although it should be noted that the [ must NOT be preceded by a letter, number or underscore, or the immediate preceding text will be treated as an array name. The old form of TEXT....ENDTEXT commands are also treated as free text and excluded from the search. G.A.Morris SuperStructure 3 2.2 Comments for Documentation As previously noted, comments can be incorporated into SuperStructure's data files. By placing a + immediately after the /* for a comment block, to give /*+, the complete comment block, started with /*+, will be saved in the structure database down to and including the end */ delimiter 2.3 Send Operator The send operator (:) is treated such that any messages are not included in the search. If the message includes parenthesis in its normal syntax and there is a function call made by the message, the function call will be detected by SuperStructure and reported accordingly. 2.4 #INCLUDE & .CLP Files If #INCLUDE statements are incorporated in a .PRG file and they make reference to a different drive\path, they can be, optionally, searched after the primary path specified at the time of starting SuperStructure. If .CLP files are used in an application's development system they can be, optionally, included in the search. As with the #INCLUDE statement, when reference is made to a .PRG file on a different drive\path the .PRG files are searched after the application's primary path. G.A.Morris SuperStructure 4 2.5 Information Screen After completing the search of the specified file or directory, the user is immediately placed in a browse type screen showing the declared function, its type, function calls made by it and the program file in which it is contained. The line number of the called function is also shown. By using the function keys F3, F4 or F5 the order in which the information is displayed can be changed. The key's functions are given in the lower portion of the screen. From the browse screen various facilities can be accessed with the function keys. They include, searching for a function, printing reports, listing redundant declarations, deleting records, updating documentation notes and displaying the .PRG file contents. Full details are given in section 4. 2.6 Generated Files If a directory listing is taken of the distribution disk it will be noted that there are no database files. SuperStructure generates these as required. The basic rules that SuperStructure follows for file generation are:- a) A database of application structure files is generated on the path where SuperStructure is located. b) The structure files for an application are generated on the user defined path at the time they are first defined. Details about these databases are given in the appendix. This is provided for users who wish to carryout further data file processing. G.A.Morris SuperStructure 5 3 GENERATING STRUCTURE FILES 3.1 Top Menu After the introduction screen, the first menu offers four options as follows:- Create - Creates new structure files for an application Work - Accesses existing structure files for viewing and updating Delete - Removes an application's structure files from disk. Exit Leaves the SuperStructure programme and returns to DOS. The menu is navigated with the cursor keys or selecting the first letter of the required item. The operation of each option is described in the following sections. 3.2 Create Selecting the Create option to generate structure files for an application presents an input screen for the data to define an application's structure files:- a) The name of the application. This is for the users own reference and can be up to fifteen characters long. b) The name of the structure files. This is a four character name which will be used as a prefix to the DOS name for structure files. c) Directory where the structure files are to be stored d) Drive for the structure files. This defaults to C: if none is given. G.A.Morris SuperStructure 6 SuperStructure will check if an application name is already allocated, if the directory exists and that the structure files' name is not already in use. If any of these conditions fail a warning is flagged and the user prompted to re-input the data. If no application name is given, or ESC is pressed, input is abandoned and the top menu redisplayed. After a structure file system has been successfully created the information is stored as a record on the database file SUPERSDB.DBF which is located on the directory where SuperStructure is run from. 3.2.1 Specifying Search Criteria The next data input screen is the FUNCTION AND PROCEDURE SEARCH ROUTINE's screen. This screen allows details to be given about which drive:\directory is to be searched and the scope of the search. The data items to be given are:- a) Drive and path to search This defaults to the drive:\directory specified for the structure files. This can be over written to give a different search path. If a specific file name is appended to the search path specification then only that file will be included in the search. This facility is designed to allow existing structure files to be updated. Note that the complete file name, including the extension, must be given in this case. If no file name is given all files with the specified file extension, found on the search path, are included in the search. G.A.Morris SuperStructure 7 b) Programme file extension By default this is set to .PRG for programme text files. This default can be overwritten to any valid file extension. c) Ignore Clipper functions The user can elect to include Clipper functions within the search or omit them. It is generally advised that calls to Clipper functions be omitted from the search as they can cause excessively large database files to be generated. The function list that SuperStructure will ignore is based on the Clipper functions in the version 5.0 documentation. On the distribution disk SuperStructure is supplied with an .OBJ file SUPERSTR.OBJ and a .PRG file, FINDTAIL.PRG. FINDTAIL.PRG is a function which allocates the function names to a public array. This file can be edited and complied. The SuperStructure .EXE file can then be re-linked. This facility has been provided to allow users to update the Clipper function list for new releases of Clipper and add their own or third party library functions that they may wish to exclude from the searches. Conversely, if users wish to check on a specific Clipper function it can be deleted from the FINDTAIL.PRG. d) Search #INCLUDE files If .PRG files contain the #INCLUDE pre-processor directive which calls for files on a different path to the one currently being searched, selecting Y to this option will cause such files to be incorporated into the search. If the #INCLUDE directive does not specify a path the file is assumed to be on the current search path. G.A.Morris SuperStructure 8 e) Search Compiler Script Files This allows .CLP files to be searched for files which are on a different path to the one being searched, in the same way as the #INCLUDE function works. f) Script File Extension The default extension is .CLP. This can be overwritten by any valid file extension. After the data input is completed the search process begins. The screen will display the time that the search started and the name of the file being searched. Also shown, to verify that the programme is running, is the name of the current function being scanned and the names of function calls found. The time taken for the search procedure will depend upon the size of the files being searched and the speed of the computer being used. As a rough guide to speed, searching some 250k of .PRG files, on a 20MHz 386SX machine with no disk cache, takes about 3 minutes. Once the search procedure is completed a message is displayed to say that data is being written to file. If an application is very large and contains more than 3000 user function calls, or Clipper functions have been included in the search, this message may appear several times before the search is completed. On completion of the search process the browse screen appear for the application. The browse screen is described in more detail in section 4. G.A.Morris SuperStructure 9 3.3 Work Selecting the Work option from the top menu allows previously generated applications structure files to be viewed and updated. Selecting Work causes a secondary menu to be displayed with the following options:- a) View b) New Run c) Update d) Quit Selecting any of the first three options causes a list to appear with the currently available applications structure files. This is a Clipper ACHOICE type list and the required application should be highlighted and ENTER pressed to select it. Selecting Quit returns control to the top menu. 3.3.1 View The View option displays the selected application structure files in the browse window. G.A.Morris SuperStructure 10 3.3.2 New Run The New Run option will 'Zap' the selected application's structure files and re-run the structure files generation routines for the currently selected application. After the files have been generated the browse window is displayed. NOTE:-If the New Run option is selected the documentation notes are also deleted. This does not cause a problem if the documentation is all generated from comment blocks starting /*+ in the programme files, the documentation will be regenerated. If, however, notes have been input manually from the browse window THEY WILL BE LOST. Be warned! If notes must be saved, before a new run, copy the ****NOTE.DBF and ****NOTE.NTX to a different file name. See the appendix for more details. 3.3.3 Update The Update option allows new programme files to be added to the selected application's structure files. The file name and extension must be explicitly specified when the search drive:\directory is given. 3.4 Delete The Delete option in the top menu allows all references to an application's structure files to be removed from the system and the structure files to be deleted from disk. A list of the currently available applications is displayed, as for the Work option, and the application to be deleted is highlighted, by using the cursor keys, and Enter pressed to select. The records and files are then deleted. This operation is final and files can not be retrieved. The recreation of an application's structure files can be done, obviously, with the Create option. G.A.Morris SuperStructure 11 3.5 Exit This terminates the programme and returns to the DOS prompt. G.A.Morris SuperStructure 12 4 REVIEWING STRUCTURE FILES After an application's structure files have been created, a New Run or Update option carried out or the Work-View option selected the structure files browse window is displayed. Initially this window is displayed in 'Declared Function' order. Once an application has been run with SuperStructure this window should be reviewed. When reviewing the window the following should be noted:- a) The name of the application is displayed at the top of the window, under its title. b) On the top left border line the current index key is displayed. Initially this is 'Declared'. c) The window is divided into five columns:- i The declared function ii The type of function or procedure. The first letter can be D to indicate a dynamic or public routine or S for a static routine. The second letter is F for a function or P for a procedure. iii Called. These are the functions or procedures called by the declared routine. iv Line number. The line number in the programme file where the call is made. v .PRG File. This is the programme file where the function or procedure is declared. d) At the bottom of the window the function key operations are noted. There functions are as detailed in the next section. G.A.Morris SuperStructure 13 4.1 Function Keys The operations that can be carried out by the function keys are as follows:- F1 - Context sensitive help. This is available through out the programme. F2 - Search and position the highlight at the result. Used to find a specific routine or programme file. The operation of the find facility depends on the currently selected index. The F2 function will find the first occurrence of a routine or programme file based on the current index. F3 - Displays in declared routine order F4 - Displays in called function order. This is helpful when locating all of the points where a routine is called. F5 - Display in programme file order. F6 - Displays the notes for a declared function. If the block delimiter /* is used, in the programme file with a trailing +, as /*+ the following text block is available and F6 will display it. If there is a number of different text blocks in a function they are all appended to the notes. Additions and deletions can be made to the text and saved with the Ctrl-W key. F7 - Displays a menu for printing reports. See section 4.2.3 for more details. F8 - Lists redundant functions and procedures. Redundant functions are those found on during the search of the application's directory and are not called by any other function or procedure. Note that the head function or procedure for the application will be included in this list as no other function will call it (unless there is a recursive programme structure) G.A.Morris SuperStructure 14 F9 - Displays the current .PRG file with the cursor positioned at the line number of the currently highlighted record. F10- Marks or unmarks the current highlighted record as deleted. The record is only marked at this time. The physical deletion does not occur until the browse window is exited. Records marked as deleted are not included in printed reports. This facility is useful for limiting the contents of printed reports and tidying up the structure file contents. 4.2 Reporting Options Using the F7 function key will display a menu for printing options. The printing options menu shows the top menu options and the name of the current declared function and .PRG file. The top menu options are Listings produce a standard listings report of the structure files. The contents of the report is determined by the currently selected index and user selected options. Redundancies produces a report of the redundant functions found in the application's directory Settings This option allows the settings for Esc codes to be sent to the printer and details about standard paper sizes to be given Quit Leaves the printing options menu G.A.Morris SuperStructure 15 4.2.1 Reports-Listings The Listings option is for producing a standard report of the structure files contents. The report is printed in a standard format as follows:- Application:-********** Report Date:-**/**/** Page # Report Type:-********** File|Declared Functions|Scope|Functions Called|Line No. **** ****************** ***** ************* ******* TABLE OF DATA **** ****************** ***** ************* ******* The report has been designed to print on A4 paper using 12 cpi type. The printer settings can be adjusted for other paper sizes. The report is generated based on the currently selected index in the browse window. Note that the required index should be set in the browse window before selecting the reports option. The three options are:- Declared Function Order - This will produce a report with declared functions in alpha order. Called function Order - This will produce a report in alpha order of called functions. Programme File Order - The report is in alpha order of the programme file names After selecting the Listings option from the Report Printing Options top menu the options for the report's content are given with drop down menus. G.A.Morris SuperStructure 16 The first option is to Include or Exclude the printing of notes. This allows development notes to be included in the report. The notes associated with each declared function are printed at the end of each section for that function. The second option allows the contents of the report to be selected. This can be:- All Functions Produces a report for all declared functions in the structure file Current PRG File Produces a report for all declared functions in the current PRG file Current Function Produces a report for the current declared function or procedure Finally the destination for the report can be selected as either the printer or a file. If a printer is selected the default output port is LPT1. Should the printer be on another port the DOS MODE command should be used to redirect output. If output to a file is selected the file name given should include the complete Drive:\Directory\Filename.Extension. Selecting Quit for the destination will exit the Report Printing Options window. 4.2.2 Report-Redundancies A Redundancies report will produce a report of the same style as the Standard Listings but will be restricted to the functions and procedures which are not called by any others in the application's directory. G.A.Morris SuperStructure 17 4.2.3 Report-Settings Selecting the settings option will display the printer settings screen. This screen allows paper sizes, control codes and report headings to be specified. The settings are saved and should not need to be changed unless you paper sizes or printer is changed. The facility to specify two sizes of paper is provided. This is not required by the current version of SuperStructure but is included at this time as further versions will make use of wide paper. Page sizes should be in inches. If you do not have a wide carriage printer specify the wide page size to be the same as the standard page. Note that reports are designed to fit on the largest paper size. Paper size can not be selected at the time of printing. If a wide page is required for a report, a message will be displayed warning that wide paper should be in the printer. If the printer does not accept wide paper, and this is required for the normal printing of a report, the report will automatically be printed in a smaller pitch size that will allow it to fit onto the smaller page. Top and Bottom margins are give as the number of lines. The Printer reset code and the pitch control codes are the Esc code sequences accepted by your printer. These are specified using the \ character followed by a three digit number corresponding to the ASCII value of the Esc code. eg. 'ESC A' would be given as \027\065 G.A.Morris SuperStructure 18 Note that all codes must be given. If the printer does not produce an particular printing pitch then the next SMALLER pitch size should be given. This may occur for the 15cpi codes. Some printers do not produce 15cpi and the next smallest size is 17.5 cpi (compressed). In this case the ESC code for 17.5 cpi should be given for the 15cpi entry. The printer reset code is the ESC sequence to reset the printer to its default conditions. NOTE:-If your printer has a default page length different from the current paper size the ESC code sequence to set the page length should be given at the start of EACH pitch control code. A heading, of up to three lines, to print at the top of each page of the report can be given. If no headings are given the report starts on the first line after the top margin. G.A.Morris SuperStructure 19 5 APPENDIX 5.1 Installation To install SuperStructure on a hard disk, make a directory where you wish to keep the programme, help and applications database files. Copy the entire contents of the distribution disk to the directory. If SuperStructure is to be relinked using a modified FINDTAIL.PRG file then the FINDTAIL.PRG and SUPERSTR.OBJ should be placed on paths which are available to the Clipper compiler and linker. To run SuperStructure go to the directory where it is stored and type SUPERSTR to start it. If you are running the demo version of SuperStructure type SSDEMO to start it. If the demonstration version is supplied on a 3.5" disk it can be run from the floppy. On copies supplied on two 360k 5.25" disks all files from each disk will need to be copied to the hard disk before running. The demonstration version is NOT supplied with the SUPERSTR.OBJ and FINDTAIL.PRG files. G.A.Morris SuperStructure 20 5.2 File Structures SuperStructure generates two groups of database files. The first is the database of applications. This is created on the path from which SuperStructure is run. The second group is the actual structure files associated with an application. The location of these files are specified by the user. Normally they would be maintained on the same directory as the application or a directory of applications structure files. The content of each file used by SuperStructure is detailed below for users who may wish to generate their own reports or other file manipulation operations. Database of Applications File name:-SUPERSTR.DBF Field name Type Length Description APPLIC C 15 Name of the application STRUCTNAME C 4 Prefix name for structure files DIR_LOC C 63 directory location of structure files DRV C 2 drive location of structure files Index file name:- SUPERSTR.NTX Index key- APPLIC (upper case) G.A.Morris SuperStructure 21 Structure Files Databases File name:- ****CALL.DBF Contains the function and procedure calls data **** is the prefix name in the Applications database field STRUTNAME Field name Type Length Description FUNC_PROC C 15 Name of the declared function or procedure TYPE C 2 Code for type of function or procedure. The first letter is D=public or S=static the second letter is F=function or P=procedure CALLING C 15 Name of the function or procedure called LINE_NO N 6 Line number where the call is made PRGFILE C 12 Name of the programme file containing the declared function or procedure G.A.Morris SuperStructure 22 Three index files are used with ****CALL.DBF. They are:- Index file Key expression (all uppercase) ****FUNC.NTX FUNC_PROC + PRGFILE ****CALL.NTX CALLING + FUNC_PROC + PRGFILE ****PRGS.NTX PRGFILE + FUNC_PROC + CALLING G.A.Morris SuperStructure 23 File name:-****NOTE.DBF Contains the notes associated with each declared function or procedure Field name Type Length Description FUNC_PROC C 15 Name of the declared function or procedure FUNC_NOTES M 10 Notes associated with FUNC_PROC The index file associated with this database is ****NOTE.DBF and the key expression is FUNC_PROC (upper case) SuperStructure has the facility to add notes to the memo field from the browse window as well as generate notes from the /*+ style comment block. If the Work-New Run option is selected then the notes file is 'zapped'. This may cause a problem if notes have been added from the browse window, they will be lost. In general it is recommended that the /*+ comment blocks be used in the programme files as these will be regenerated when SuperStructure is run and will provide a fully documented code section in the programme file listing. If notes input from the browse window must be preserved use the DOS COPY command (not the RENAME command) to create a copy of the notes file with a different name. This can be accessed later with the DBU utility or other database browser. Future releases of SuperStructure will contain facilities to update the Notes Database. G.A.Morris SuperStructure 24