******************************************************* * * * THIS SOFTWARE WAS DEVELOPED WITH SUPPORT * * FROM THE NATIONAL INSTITUTES OF HEALTH: * * NIH CA06927 * * NIH CA22780 * * * * DIRECT INQUIRIES TO: * * COMPUTER CENTER * * THE INSTITUTE FOR CANCER RESEARCH * * 7701 BURHOLME AVENUE * * PHILADELPHIA, PENNSYLVANIA 19111 * * * * NO WARRANTY OR REPRESENTATION, EXPRESS OR * * IMPLIED, IS MADE WITH RESPECT TO THE * * CORRECTNESS, COMPLETENESS, OR USEFULNESS * * OF THIS SOFTWARE, NOR THAT USE OF THIS * * SOFTWARE MIGHT NOT INFRINGE PRIVATELY * * OWNED RIGHTS. * * * * NO LIABILITY IS ASSUMED WITH RESPECT TO * * THE USE OF, OR FOR DAMAGES RESULTING FROM * * THE USE OF THIS SOFTWARE * * * ******************************************************* * * * THIS SOFTWARE WAS DESIGNED FOR USE ON A * * PDP-11/70 OPERATING UNDER IAS V3.0 USING * * THE FORTRAN-IV PLUS COMPILER. * * * ******************************************************* I A S F D T R e f e r e n c e S h e e t --------------------------------------------- Sample command file for including FDT. -------------------------------------- (Assumes there are three source modules: PROG, SUB1, and SUB2). FOR/F4P/LIST:PROG/SW:(/LI:3) PROG FOR/F4P/LIST:SUB1/SW:(/LI:3) SUB1 FOR/F4P/LIST:SUB2/SW:(/LI:3) SUB2 LINK/DEBUG:LB:[1,1]FDT/MAP:PROG PROG,SUB1,SUB2 FDT PROG,PROG=PROG,SUB1,SUB2/PROG (If overlayed, you must not have default core resident library SYSRES. Thus the link command must eliminate this). ie: LINK/OPT/DEBUG:LB:[1,1]FDT/MAP:PROG/OVER:PROG / (If virtual arrays must be examined or changed, use LB:[1,1]VFDT). FDT Commands. ------------- Execution control: ;B List all breakpoints. [module:]entry-name;B Set breakpoint. [module:]statement-number;B [module:]@line-number;B ;C Clear all breakpoints. [module:]entry-name;C Clear a breakpoint. [module:]statement-number;C [module:]@line-number;C ;G Return from a breakpoint. @line-number;G Jump to a location and resume statement-number;G execution. ;X Exit program. Variable examination: Variable format: [module:]variable-name Array format (only VFDT can access virtual arrays): [module:]array-name[(subscripts)] Display type terminators: / Display by type. ;A Display in ASCII. ;D Display in decimal (only affects logical and integer). ;O Display in octal (only affects logical and integer). Modification terminators: Close location. Open and display next array element. ^ Open and display last array element. F D T - - F O R T R A N D E B U G G I N G T O O L ========================================================= I. Introduction. FDT is a program designed to assist FORTRAN programmers in debugging their programs. There are three versions of FDT. The small FDT is designed to provide the necessary debugging tools in a minimum of space. This version of FDT features: -- Variable examination and modification, -- Execution control (breakpoint set and clear). VFDT, is somewhat larger. It is identical to FDT, but will correctly handle virtual arrays. XFDT (not yet complete), is larger still. In addition to all the features of VFDT, XFDT features: -- Program and variable tracing, -- Array scanning. -- Conditional breakpoints. FDT, VFDT, and XFDT are designed to work with FORTRAN IV Plus version 3.0 under IAS version 3.0. Because the list formats of the compiler and the task builder may be different, it is not known whether they will run under other versions. FDT should work with FORTRAN IV Plus V2.5. FDT, VFDT, and XFDT will probably not work with the RMS version of the compiler (though this has not been tested). Though FDT has not been tested under V3.1 of IAS, it does include support for the CONTINUE/DEBUG switch of that version. II. Including FDT in your program. Program modification. --------------------- In general, no changes need to be made in a program to use FDT, except for size considerations discussed below. FDT consists of two pieces. The program FDT is used to create the FORTRAN symbol table. The FDT subroutine is included in your program by the task builder. The program resident section of FDT (for the smaller version) is currently about 1800 words, and will not get substantially larger in the future. Since it references several I/O and formatting routines which your program may not use, the actual size increase will depend on what features your program does use. Under no circumstances should FDT add more than 7000 words to your program. If you already have some formatted I/O statements in your program, it will be closer to about 3000 words. VFDT will add about the same to programs which have virtual arrays. FDT requires exclusive use of an event flag. As FORTRAN programmers seldom use event flags, this is unlikely to cause conflicts. FDT normally uses event flag 23. This may be overridden at link time by the statement GBLDEF=.FDTFG:nn where nn is the octal event flag number. Program compilation. -------------------- You must get full, disk resident listings of each FORTRAN source file you wish to reference in your session. This is done by specifying a list file, and using the /LI:3 compiler switch of the FORTRAN-IV Plus compiler. If using the PDS FORTRAN command: FOR/LIST:PROG/SW:(/LI:3) PROG If using the ICR CPL command: CPL/LIST/LI:3 PROG If using the MCR command: MCR FOR PROG,PROG/-SP=PROG/LI:3 THE LISTINGS MUST BE CURRENT! Each time you recompile the file, you must get a new listing. Linking the program with FDT. ----------------------------- Several changes must be made to your standard link command. 1. You MUST get a disk resident map file. This is done using the /MAP:prog switch. 2. You must specify the FDT debugging aid. This is done by using the switch: /DEBUG:LB:[1,1]FDT or /DEBUG:LB:[1,1]VFDT 3. If your program is overlayed, you may not use any core resident libraries (ie. SYSRES or F4PRES). If you are already specifying link options, simply do not specify the libraries. If you are not specifying options, you must specify the /OPT switch and follow the command with a "/". See reference sheet for an example. AN OVERLAYED PROGRAM LINKED TO SYSRES WITH FDT WILL EXIT IMMEDIATELY WITH A SEGMENT FAULT TYPE ERROR. THE MAP FILE MUST BE CURRENT! A new map must be made each time the program is linked. Generating the FORTRAN symbol table file. ----------------------------------------- The program resident portion of FDT learns the locations of variables, source statements, array dimensions, etc. from the FORTRAN symbol table file. This file has the extension .FDT, and is produced -- along with an optional symbol table list (.STL) file -- by the FDT command. The FDT command uses a modified MCR command line for input. The general form of the command line is: FDT fdtfil[,stlfil]=lstfils/mapfil "fdtfil" is the symbol table file. The default extension (and the one which is required) is .FDT. The "stlfil" is a list file containing a listing of all symbols which can be referenced during the FDT session. The default extension is .STL. "lstfils" is a list of all the compiler list files (separated by commas). The default extension is .LST. "mapfil" is the map file generated by the task builder, and the default extension is .MAP. The FDT command line may span several lines, with the following restrictions: 1. The equals sign ("=") must immediately follow the .STL file (if present), or the .FDT file. 2. File names may not be continued on the next lines. 3. The slash must immediately follow the final .LST file. 4. If you are using an indirect command file, either the command must be in a single line, or the filenames must be in a separate command file, and invoked by: FDT @cmdfil where "cmdfil" is the name of the command file. THE FORTRAN SYMBOL TABLE FILE MUST BE CURRENT! A new one must be made each time the program is linked with FDT. III. Using FDT The terminal interface. ----------------------- The terminal interface to FDT is slightly different than that normally used by FORTRAN programmers. Input is processed character by character rather than a line at a time. As soon as a valid command line is detected by FDT, it will begin processing it. A command line consists of data followed by an FDT terminator. FDT terminators are any of the following: "/", , , "^", or a semicolon followed by any character. The terminator determines the function to be performed, while the data generally specifies variable or locations for the function to operate on. Control-U works as it normally does. Rubout performs deletion, but only echoes the character being deleted. Entering FDT. ------------- When you run your program, control is automatically transfered to FDT. Upon entry, FDT will type its revision number and prompt: PROGRAM NAME? Type the name of the FDT file (do NOT include the extension), followed by a carriage return. If you do not wish to use FDT for this run, simply type a carriage return, and the program will proceed. Assuming you have given the name of the FDT file, FDT will type the prompt "*". At this point you may type any valid FDT command. Execution control. ------------------ FDT allows the user to set and clear "breakpoints". Setting a breakpoint at a location will cause the program to be interrupted by FDT when the program gets to that location. This allows the user to examine and modify variables at critical stages in the program. Four commands are used to control execution of your program: ;B Set or list breakpoints. ;C Clear breakpoints. ;G Return from breakpoints. ;X Exit program. These commands are detailed below. Setting breakpoints: Breakpoints may be set at any entry point, line number, or statement number defined in the .STL file. The three formats are shown below. Statement and line numbers may not have lead- ing zeros. If the module name is unspecified, the current module is assumed. [module:]entry-name Specifies an entry point. [module:]statement-number Specifies a line of code identified by a FORTRAN statement number. [module:]@line-number Specifies a line of code with number shown in compiler listings. Setting breakpoints at entry points and at line-numbers may have unexpected results as described in section four. Statement numbers are safest, but most of your statement numbers will be inaccessible from FDT. READ SECTION IV CAREFULLY. To set breakpoints, specify the location and type ";B". ie: SUB1:@17;B would set a breakpoint at line 17 of subroutine SUB1. When the program reaches this statement, it will be interrupted and FDT will type: FDT BREAKPOINT FROM SUB1 AT @17 Any valid FDT commands may be typed at this point. Up to ten breakpoints may be set at once. Listing breakpoints: All currently active breakpoints may be listed by typing ";B" with no data before it. Clearing breakpoints: Breakpoints may be cleared individually by typing the location followed by ";C". Typing ";C" without a location will clear all breakpoints. For example: SUB1:@17;C would clear the breakpoint at line 17 of SUB1, while ;C would clear all active breakpoints. Returning from breakpoints: When you wish to resume execution of your program, you may type ";G". You may also have execution resume at some other location in the current routine. To transfer control to statement number ten in the current routine, type: 10;G Note that only statement numbers and line numbers may be used here. Modules names and entry points are not allowed. Abort program: To stop the current run, type ";X". The FORTRAN exit routine will be called to close files and terminate in an orderly fashion. Variable or array examination and modification. ----------------------------------------------- Variables are addressed in a fashion similar to location addressing. As in locations, the module may be absent to specify the current module. If the subscripts are absent, the first element of the array is addressed. Arguments of subroutines may only be addressed from within that module. PLEASE READ SECTION IV CAREFULLY! Variable specifications are: [module:]variable-name or [module:]array-name[(subscripts)] Variables may be displayed in four ways, determined by the command terminator: Terminator Display format ---------- -------------- / According to type. ie. logical will be displayed as "T" or "F", floating point will be displayed as real numbers, etc. Note that byte variables are logical *1. ;A Display in ASCII. ;D Display in decimal. Logical and integer only -- all others are displayed according to type. ;O Display in octal. Logical and integer only -- all others are displayed according to type. After the variable or array element has been displayed, the location is said to be "open". Typing a value (same format as display) followed by a carriage return will change the variable value and close the location. Typing a carriage return will "close" the location without modifying it. Typing any valid command will close the location and execute that command. When the variable being displayed is an array element, the carriage-return function may be replaced by a line-feed. This will cause FDT to change the value of that element (if a new value was supplied), close that location, and open the next element in that array. Similarly, an up-arrow ("^") will cause the last element of the array to be opened. Note that variables cannot be addressed through a module which is in a non-resident overlay (even if the variable is in a resident common area). VIRTUAL ARRAYS MAY ONLY BE ADDRESSED BY VFDT. They are invisible to FDT even though they appear in your symbol table listing. CONTINUE/DEBUG entry to FDT. ---------------------------- IAS V3.1 has a CONTINUE/DEBUG which may be typed after a control-C to PDS. This effectively sets the T-bit causing an immediate trap to FDT. Because the state of the program is unknown, FDT will only allow the user to type the B, C, and G commands at this time. In this fashion, a user may type control-C, and CONTINUE/DEBUG to enter FDT, set a breakpoint, and continue. Note that any T-bit trap will enter this mode. IV. Known anomolous behavior. There are many cases where FDT does not behave as you might guess. These cases fall into four categories: effects due to compiler optimization, effects due to inaccessable information, bugs -- known and unknown, and restrictions. These are described below. Effects due to compiler optimization. ------------------------------------- The FORTRAN IV-Plus compiler is an optimizing compiler. This means that the compiler translates your FORTRAN program into machine language in "blocks" rather than line by line. A block is generally more than one line. This makes your program run faster, but it also means that within blocks, the state of variables may not be determined from looking at your FORTRAN code. For example, suppose your program contains the following three lines: 0001 A = 1.0 . . . . . . . 0113 A = A + 1.0 0114 A = A * B If you place a breakpoint at line number 114, the value of A will probably be displayed as 1.0, and not as 2.0. Further, if you modify the value of A at that point, it will probably not take effect. The reason for this is apparent when you look at how an optimizing and a non-optimizing compiler translate this code: FORTRAN Non-optimizer Optimizer -------------- ---------------------- -------------------------- A = 1.0 Move 1.0 to A. Move 1.0 to A. A = A + 1.0 Move A to register. Move A to register. Add one to register. Add one to register. Move register to A. A = A * B Move A to register. Multiply register by B. Multiply register by B. Move register to A. . . . . . . . Move register to A. Since FDT has no way of knowing that A is not in its niche when the breakpoint occurs, FDT will read the old value (1.0) from A's location, and will put any requested modifications in A's location -- which is about to be overwritten. Therefore, if you set breakpoints by statement number, variables which have recently been modified may be in this limbo state. Where possible, therefore, it is preferable to assign breakpoints at the beginning of a compiler optimization block. Blocks always begin after an entry point, and will also generally begin at any statement number which can be referenced by FDT (see your .STL listing). Blocks will also generally begin following the return from a subroutine. If this is a major problem, you may try the undocumented /OP:0 switch, which limits program optimization by the compiler. This may or may not solve your problem. In certain rare instances (only, I believe, in modules with ENTRY statements), some arguments may be unavailable until the first executable statement following the entry point. Thus, examination of these arguments from a breakpoint at the entry point (or in the type declarations following the first entry point), will either cause an error, or cause the argument from the last call to be used. To be safe, if the module has any ENTRY statements, and you wish to examine the arguments after the entry point, place the breakpoint on the first executable statement. Effects of insufficient data. ----------------------------- All of FDT's information is extracted from your list files and the map file. Any information known to the compiler, but not listed is not available to FDT. This causes one major headache. When you use variable dimensions in a subroutine, FDT is aware of how many subscripts there are, but does not know their size. It therefore assumes the following for the lower and upper bound of a dimension when variables are used: Lower bound = 1. Upper bound = Lower bound. Arrays can still be stepped through beyond their upper boundary, but you must specify a legal value. This is also true when you use a dummy dimension of 1. Experiment with it, and this will become clearer. Virtual arrays which are arguments to a subroutine are inaccessible through the subroutine. This is because the list file provides insufficient information to properly address them. DEC has promised, in an SPR response, to remedy this fault in the list format, so later versions of FDT may have this corrected. Bugs. ----- There are no known bugs in FDT. If you find bugs, please report them to: Robert K. Stodola The Institute for Cancer Research 7701 Burholme Ave. Philadelphia, PA 19111 215 728-2760 Specifically, if the FDT program bombs or generates error messages, send me a copy of the listings and the map file. Barring variable modification and jumping using the G command, FDT should never cause your program to behave differently. Restrictions. ------------- You may not examine or modify values from a breakpoint in a function subprogram called from a write statement. If you use a PROGRAM statement, the program module have that name. When you first enter FDT (by running the program), it assumes it is in a module named .MAIN. (the default program module name). When referencing variables or locations in the main module, you must specify the module name. After the first breakpoint, it will, however, always have the correct default module name. Entry to FDT through the trace trap mechanism (ie. CONTINUE/DEBUG) will only allow you to set and clear breakpoints and to return (";G"). Virtual array access is restricted to VFDT.