************************************************** ************************************************** ** ** ** F O D T ** ** ** ** FORTRAN-IV ON-LINE DEBUGGING TOOL ** ** ** ** OPERATING INTRUCTIONS ** ** ** ************************************************** ************************************************** THIS DEBUGGING AID ALLOWS THE USER OF RT-11 FORTRAN IV TO MONITOR THE OPERATION OF HIS PROGRAM USING COMMANDS SIMILAR TO ODT. FODT PROVIDES A SUBSET OF THE COMMANDS AVAILABLE WITH ODT WITH CERTAIN DIFFERENCES TO ACCOMODATE THE ENVIRONMENT IN WHICH A FORTRAN PROGRAM RUNS. 1) RUNNING A PROGRAM WITH FODT. NO EDITING OF THE FORTRAN SOURCE CODE OR RECOMPILATION IS NECESSARY TO RUN A PROGRAM WITH FODT. THE EXISTING OBJECT MODULES MUST ONLY BE BUILT INTO A NEW LOAD MODULE WHICH INCLUDES THE FODT MODULE. THE COMPILER LISTINGS FOR THE FORTRAN MODULES ARE REQUIRED SO THAT THE EXECUTION OF THE PROGRAM MAY BE FOLLOWED AND THE VALUES OF FORTRAN VARIABLES DISPLAYED. A LINKER LOAD MAP WILL BE REQUIRED IF ANY VARIABLES STORED IN A FORTRAN COMMON AREA WILL NEED TO BE EXAMINED. FODT CONTAINS ROUTINES WHICH REPLACE SEVERAL THAT MAY ORDINARILY BE OBTAINED FROM THE FORTRAN LIBRARY, THE LINKER WILL FETCH ALL NEEDED FORTRAN OTS ROUTINES FROM "FORLIB.OBJ" AUTOMATICALLY. IN SUMMARY, THE ONLY CHANGE REQUIRED TO INCLUDE FODT IN A FORTRAN TASK ARE: A) INCLUDE FODT AS AN INPUT MODULE IN THE LINK COMMAND STRING. SAMPLE LINKER COMMAND STRING: TEST,TEST=TEST,FODT/F IF THE TASK TO BE DEBUGGED IS AN OVERLAYED TASK, THE FODT MODULE SHOULD BE PLACED IN THE ROOT SEGMENT. FODT WILL OPERATE CORRECTLY IN FORTRAN TASKS WHICH INCLUDE ASSEMBLY LANGUAGE SUBROUTINES. HOWEVER, FODT CANNOT GAIN CONTROL IN THOSE SUBROUTINES. IF IT IS NECESSARY TO DEBUG ASSEMBLY CODE, YOU MUST ALSO INCLUDE THE NORMAL ODT DEBUGGER. THERE IS NO CONFLICT BETWEEN THE TWO DEBUGGING TOOLS. 2) OPERATION OF FODT. FODT GAINS CONTROL BEFORE THE FIRST EXECUTABLE FORTRAN STATEMENT, AND PRINTS "FODT DEBUGGER" TO SIGNIFY THAT IT IS ACTIVE. IT THEN PRINTS THE NAME OF THE "CURRENT" ROUTINE AND THE FORTRAN SEQUENCE NUMBER OF THE FIRST STATEMENT THAT WILL BE EXECUTED. AT THIS POINT FODT IS READY TO ACCEPT ANY OF THE COMMANDS DESCRIBED LATER. ALL REFERENCES TO THE "CURRENT" ROUTINE MEAN THE SUBROUTINE, FUNCTION OR MAIN PROGRAM IN WHICH THE NEXT FORTRAN STATEMENT WILL BE EXECUTED. WHEN IT REGAINS CONTROL, FODT ALWAYS PRINTS THE NAME OF THE "CURRENT" ROUTINE AND THE SEQUENCE NUMBER OF THE NEXT STATEMENT TO BE EXECUTED. THE SEQUENCE NUMBER IS THE NUMBER AT THE EXTREME LEFT SIDE OF THE COMPILER LISTING OF THE PROGRAM. AFTER FODT HAS IDENTIFIED ITS LOCATION, IT PRINTS AN UNDERLINE CHARACTER IN COLUMN 1 AS A PROMPT TO INDICATE IT IS READY TO ACCEPT COMMANDS. 3) COMMAND SYNTAX ALL FODT COMMANDS CONSIST OF A SINGLE LETTER COMMAND CODE PRECEDED BY UP TO THREE PARAMETERS. THE PARAMETERS ARE ALWAYS NUMERIC, AND SOMETIMES THEY ARE OPTIONAL. MULTIPLE PARAMETERS ARE SEPARATED BY EITHER COMMAS OR SEMICOLONS. THE PARAMETERS ARE ASSUMED TO BE DECIMAL NUMBERS UNLESS PRECEDED BY A COLON, IN WHICH CASE THEY ARE INTERPRETED AS OCTAL NUMBERS AND MUST NOT CONTAIN THE DIGITS 8 OR 9. FODT DEFAULTS TO THE DECIMAL RADIX EACH TIME A NON- DIGIT, SUCH AS A COMMA SEPARATING TWO PARAMETERS, IS ENCOUNTERED. BLANKS ARE COMPLETELY IGNORED IN COMMAND STRINGS AND DO NOT CHANGE THE RADIX. FODT INTERPRETS THE CHARACTERS ONE AT A TIME AS THEY ARE TYPED, SO THE RUBOUT AND CTRL/U KEYS DO NOT ALLOW CORRECTION OF MISTAKES. IF A TYPING ERROR IS DISCOVERED BEFORE THE COMMAND LETTER HAS BEEN TYPED, JUST TYPE A CARRIAGE RETURN AND RE-ENTER THE COMMAND. ANY TIME AN INVALID COMMAND LETTER OR UNRECOG- NIZABLE CHARACTER IS ENTERED, FODT WILL IMMED- IATELY PRINT "???" AND RE-PROMPT ON THE NEXT LINE. 4) EXECUTION CONTROL COMMANDS A) **** B **** SET BREAKPOINT THIS COMMAND ALLOWS SPECIFICATION OF A ROUTINE NAME AND SEQUENCE NUMBER OF A FORTRAN STATEMENT WHERE EXECUTION IS TO BE STOPPED AND CONTROL RETURNED TO FODT FOR EXAMINATION OF VARIABLES. THE FORM OF THE COMMAND IS: 48B THIS INDICATES EXECUTION IS TO BE STOPPED BEFORE EXECUTION OF STATMENT NUMBER 48. NEXT FODT ASKS FOR THE NAME OF THE ROUTINE. THE NAME OF THE ROUTINE IS SPECIFIED IN A "SUBROUTINE" OR "FUNCTION" STATEMENT. IF THE BREAKPOINT IS TO BE PLACED IN THE MAIN PROGRAM, SIMPLY TYPE A CARRIAGE RETURN. HERE ARE SOME EXAMPLES: 48B SUBROUTINE:(CR) (PUT IT IN ".MAIN.") 56B SUBROUTINE:SUB1(CR) (PUT IT IN "SUB1") 23B SUBROUTINE:-(CR) (SAME AS LAST SPECIFIED) REGARDLESS OF THE ANSWER, IT MUST BE TERMINATED WITH A CARRIAGE RETURN (CR). A MINUS SIGN (-) IS USED TO SIGNIFY THAT THAT THE ROUTINE IS TO BE THE SAME AS THE LAST ONE SPECIFIED IN A BREAKPOINT COMMAND. WHEN FODT IS STARTED THE DEFAULT IS ".MAIN.". ONCE SET, THE BREAKPOINT REMAINS SET UNTIL IT IS EXPLICITLY CHANGED OR REMOVED BY ANOTHER BREAKPOINT COMMAND. IT CAN BE REMOVED BY ENTERING A BREAK- POINT COMMAND WITH A NULL OR ZERO PARAMETER. B OR 0B BREAKPOINTS MAY BE SET ONLY AT EXECUTABLE FORTRAN STATEMENTS. SEVERAL TYPES OF STATEMENTS SUCH AS "FORMAT" AND "DIMENSION" STATEMENTS ARE NOT EXECUTABLE AND A BREAKPOINT SET AT SUCH A STATEMENT WILL NEVER OCCUR. ! ! ! CAUTION ! ! ! BE CAREFUL WHEN TYPING THE NAME OF THE SUBROUTINE IN WHICH THE BREAKPOINT IS TO BE PLACED. FODT HAS NO WAY OF CHECKING ITS VALIDITY. IF THE NAME OR SEQUENCE NUMBER IS NONEXISTENT THE BREAKPOINT WILL NEVER OCCUR AND FODT CAN NOT REGAIN CONTROL. B) **** P **** PROCEED WITH EXECUTION THIS COMMAND ALLOWS RESUMPTION OF EXECUTION OF THE FORTRAN PROGRAM FROM THE POINT WHERE FODT IS CURRENTLY STOPPED. EXECUTION WILL PROCEED NORMALLY UNTIL A BREAKPOINT IS ENCOUNTERED. AN OPTIONAL PARAMETER (N) CAN BE SPECIFIED TO IGNORE N-1 BREAKPOINTS AND STOP ON THE NTH ENCOUNTER. THIS IS USEFUL FOR EXECUTING A LOOP SEVERAL TIMES BEFORE STOPPING AGAIN. HERE ARE SOME EXAMPLES: P (STOP AT NEXT BREAKPOINT) 20P (IGNORE THE NEXT 19 BREAKPOINTS) C) **** S **** STEP THROUGH FORTRAN STATEMENTS THIS COMMAND ALLOWS ONE TO STEP THROUGH A PROGRAM ONE STATEMENT AT A TIME OR SEVERAL STATEMENTS AT A TIME. AN OPTIONAL PARAMETER (N) CAN BE SPECIFIED TO EXECUTE N STATEMENTS BEFORE STOPPING. FODT IDENTIFIES THE NEXT STATEMENT TO BE EXECUTED EACH TIME IT STOPS. HERE IS AN EXAMPLE: FODT DEBUGGER (.MAIN. 3) _S (.MAIN. 4) _4S (.MAIN. 8) ONLY EXECUTABLE STATEMENTS ARE COUNTED. IF YOU SPECIFY "6S", FODT WILL STOP ON THE SIXTH EXECUTABLE STATEMENT. FODT WILL FOLLOW THE NORMAL FLOW OF EXECUTION OF THE PROGRAM. D) **** X **** EXIT FROM FORTRAN TASK THIS COMMAND ALLOWS THE FORTRAN PROGRAM TO BE ABORTED AT ANY POINT IF IT IS NOT DESIRABLE TO CONTINUE. THIS IS USEFUL IF A FATAL ERROR HAS BEEN EXECUTED AND FURTHER EXECUTION IS EITHER FRUITLESS OR DANGEROUS TO DATA FILES, ETC. THE COMMAND IS SIMPLY... X A NORMAL FORTRAN EXIT IS TAKEN WHICH CLOSES ANY OPEN FILES. 5) VARIABLE EXAMINATION COMMANDS THESE COMMANDS ALLOW EXAMINATION OF THE CURRENT CONTENTS OF THE FOLLOWING TYPES OF VARIABLES: COMMAND TYPE BYTES OUTPUT AS ------------------------------------------ R REAL*4 4 G14.7 I INTEGER*2 2 I10 O OCTAL INTEGER 2 O10 A ASCII 2 A2 THE COMMANDS ALL HAVE THE SAME SYNTAX. THREE PARAMETERS MAY BE SPECIFIED IN THE FORM: ,, - COMMAND TO DISPLAY A VARIABLE (R,I,O,A) - THE STORAGE ADDRESS OF THE VARIABLE OBTAINED FROM THE COMPILER STORAGE MAP FOLLOWING THE PROGRAM LISTING. THE NUMBERS GIVEN IN THE STORAGE MAP ARE OCTAL NUMBERS AND MUST BE PRECEEDED BY A COLON (:) TO SIGNIFY THIS TO FODT. - OPTIONAL PARAMETER TO SPECIFY THE ELEMENT NUMBER IF THE VARIABLE OF INTEREST IS AN ELEMENT OF AN ARRAY. IF THIS IS NOT SPECIFIED, THE FIRST ELEMENT WILL BE DISPLAYED. IF THE ARRAY IS N-DIMEN- TIONAL, THE USER MUST CALCULATE THE ELEMENT NUMBER AS IF IT WERE A ONE- DIMENSIONAL ARRAY (SEE SECTION ON HOW N-DIMENSIONAL ARRAYS ARE STORED). - OPTIONAL PARAMETER TO SPECIFY AN ABSOLUTE BASE ADDRESS FOR THE VARIABLE OR ARRAY. THIS PARAMETER IS NOT USED (NULL) FOR VARIABLES WHICH ARE LOCAL TO THE "CURRENT" ROUTINE OR ARE CALL PARAMETERS. HOWEVER, VARIABLES STORED IN COMMON MUST HAVE THIS PARAMETER SPECIFIED. THIS PARAMETER IS OBTAINED FROM THE LINKER LOAD MAP. THE NAME OF THE COMMON AREA WILL APPEAR IN THE LOAD MAP FOLLOWED BY TWO OCTAL NUMBERS. THE FIRST OF THE TWO IS THE ABSOLUTE BASE ADDRESS OF THE COMMON AREA AND IS USED (PRECEDED BY A ":") AS THE PARAMETER. UNNAMED (BLANK) COMMON WILL BE SHOWN AS .$$$$. . ONLY VARIABLES LOCAL TO THE "CURRENT" ROUTINE, CALL PARAMETERS, AND VARIABLES IN COMMON AREAS CAN BE EXAMINED. VARIABLES LOCAL TO ANOTHER ROUTINE CANNOT BE EXAMINED UNTIL FODT REGAINS CONTROL IN THAT ROUTINE. WHEN EXAMINING VARIABLES IN A SUBROUTINE FODT KNOWS WHICH VARIABLES ARE LOCAL TO THE SUBROUTINE AND WHICH ARE CALLING PARAMETERS FROM THE ADDRESSES IN THE STORAGE MAP. CALLING PARAMETERS ARE EXAMINED EXACTLY AS LOCAL VARIABLES, BUT FODT PERFORMS AN EXTRA STEP TO ACCESS THEM. THE STORAGE MAP FOR THE "CURRENT" ROUTINE MUST ALWAYS BE USED TO DETERMINE THE ADDRESSES. HERE ARE SOME EXAMPLES: :46R (EXAMINE A REAL) :32,6R (ELEMENT 6 OF A REAL ARRAY) :60O (EXAMINE OCTAL INTEGER VALUE) :20A (DISPLAY TWO ASCII CHARACTERS) :20,2A (DISPLAY CHARACTERS 3 & 4) :20,9A (DISPLAY CHARACTERS 17 & 18) :24,0,:10044I (INTEGER VARIABLE IN COMMON AREA) :200,9,:10044R (9TH ELEMENT OF REAL ARRAY IN COMMON) AFTER THE VALUE OF A VARIABLE IS DISPLAYED, FODT PROMPTS FOR ANOTHER COMMAND ON THE NEXT LINE. IT IS OFTEN USEFUL TO BE ABLE TO DISPLAY SEVERAL CONSECUTIVE ELEMENTS IN AN ARRAY. EACH TIME THE LINE FEED KEY IS TYPED THE NEXT HIGHER ELEMENT OF AN ARRAY IS DISPLAYED. TYPING THE UP ARROW (^) KEY DISPLAYS THE NEXT LOWER ELEMENT OF THE ARRAY. EACH VARIABLE DISPLAYED IN THIS MANNER IS ASSUMED TO BE OF THE SAME TYPE AS THE PREVIOUS VARIABLE DISPLAYED. TYPING THE SLASH (/) KEY WILL RE-DISPLAY THE CONTENTS OF THE LAST VARIABLE DISPLAYED EVEN IF EXECUTION OF THE PROGRAM HAS BEEN RESUMED AND STOPPED IN THE MEAN TIME.