************************************************** ************************************************** ** ** ** F P O D T ** ** ** ** FORTRAN-IV PLUS ON-LINE DEBUGGING TOOL ** ** ** ** OPERATING INTRUCTIONS ** ** ** ************************************************** ************************************************** THIS DEBUGGING AID ALLOWS THE USER OF RSX-11M FORTRAN IV TO MONITOR THE OPERATION OF HIS PROGRAM USING COMMANDS SIMILAR TO ODT. FPODT 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 FPODT. THE FIRST EXECUTABLE STATEMENT MUST BE "CALL FPODT". THIS WILL INITALIZE FPODT. THE PROGRAM MUST BE COMPILED WITH THE /TR:ALL SWITCH THE TASK MUST BE BUILT WITH [1,1]FPODT AS AN INPUT MODULE. THE COMPILER LISTINGS FOR THE FORTRAN MODULES ARE REQUIRED SO THAT THE EXECUTION OF THE PROGRAM MAY BE FOLLOWED. A TASK BUILDER ALLOCATION MAP WILL BE REQUIRED TO DISPLAY VARIABLES OUTSIDE THE MAIN PROGRAM'S $VARS PROGRAM SEGMENT. (SHORT MAP IS SUFFICIENT) ALSO, THE POST-PROCESSOR IS DEPENDENT ON THE ALLOCATION MAP FILE. THE RESULTANT TASK IMAGE MUST BE POSTPROCESSED BY TASK PREPRC.TSK WHICH IS INSTALLED AS ...PDB IN SUMMARY, THE ONLY CHANGES REQUIRED TO INCLUDE FPODT IN A FORTRAN TASK ARE: A)MAKE "CALL FPODT" THE FIRST EXECUTABE STATEMENT IN THE PROGRAM B) COMPILE WITH /TR:ALL SWITCH C) INCLUDE DR0:[1,1]FPODT AS AN INPUT MODULE FOR THE TASK BUILD SAMPLE TASK BUILDER COMMAND STRING: TKB>TEST,TEST/-SP=TEST,[1,1]FPODT D) POSTPROCESS THE TASK IMAGE WITH >PDB TEST IN ORDER TO SIMPLIFY OPERATIONS, SEVERAL INDIRECT COMMAND FILES HAVE BEEN GENERATED. SEE CAC DEBUG MANUAL FOR SPECIFICS. IF THE TASK TO BE DEBUGGED IS AN OVERLAYED TASK, THE FPODT MODULE SHOULD BE PLACED IN THE ROOT SEGMENT. FPODT WILL OPERATE CORRECTLY IN FORTRAN TASKS WHICH INCLUDE ASSEMBLY LANGUAGE SUBROUTINES. HOWEVER, FPODT 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. FPODT IS SETUP TO USE LUN 5 FOR ITS I/O BY DEFAULT. THE LUN CAN BE CHANGED BY THE "L" COMMAND DESCRIBED LATER AFTER FPODT GAINS CONTROL. HOWEVER, IT MAY BE DESIRABLE TO HAVE FPODT USE ANOTHER LUN AS ITS DEFAULT. THIS CAN BE ACCOMPLISHED BY EDITING THE SOURCE FILE TO CHANGE THE ASSIGNED VALUE OF THE SYMBOL "IOLUN" FROM 5 TO ANOTHER VALUE. THE USE OF EVENT FLAG 30. MAY ALSO BE CHANGED BY EDITING THE ASSIGNED VALUE OF "IOEFN" TO ANOTHER VALUE. 2) OPERATION OF FPODT. FPODT GAINS CONTROL BEFORE THE FIRST EXECUTABLE FORTRAN STATEMENT, AND PRINTS "FPODT 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 FPODT 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, FPODT 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 FPODT 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 FPODT 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. FPODT 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. FPODT 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, FPODT 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 FPODT 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 FPODT 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 FPODT 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. FPODT HAS NO WAY OF CHECKING ITS VALIDITY. IF THE NAME OR SEQUENCE NUMBER IS NONEXISTENT THE BREAKPOINT WILL NEVER OCCUR AND FPODT CAN NOT REGAIN CONTROL. B) **** P **** PROCEED WITH EXECUTION THIS COMMAND ALLOWS RESUMPTION OF EXECUTION OF THE FORTRAN PROGRAM FROM THE POINT WHERE FPODT 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. FPODT IDENTIFIES THE NEXT STATEMENT TO BE EXECUTED EACH TIME IT STOPS. HERE IS AN EXAMPLE: FPODT DEBUGGER (.MAIN. 3) _S (.MAIN. 4) _4S (.MAIN. 8) ONLY EXECUTABLE STATEMENTS ARE COUNTED. IF YOU SPECIFY "6S", FPODT WILL STOP ON THE SIXTH EXECUTABLE STATEMENT. FPODT 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 F INTEGER*4 4 I14 Y BYTE 1 I4 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 FPODT. - 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 TASK BUILDER LOAD MAP IN THE "PROGRAM SECTION ALLOCATION SYNOPSIS". THE NAME OF THE COMMON AREA WILL APPEAR IN ANGLE BRACKETS FOLLOWED BY THREE OCTAL NUMBERS. THE FIRST OF THE THREE 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 <.$$$$.>. A SEGMENT FAULT (OR TRAP 4 IN UNMAPPED RSX-11M) WILL OCCUR IF AN ATTEMPT IS MADE TO EXAMINE A LOCATION WHICH DOES NOT EXIST IN THE TASK. THIS WILL CAUSE THE TASK TO BE ABORTED AND OPEN FILES WILL BE LEFT IN A LOCKED CONDITION. IF AN ODD ADDRESS ERROR IS DISPLAYED WHILE TRYING TO DISPLAY A VARIBLE,REDISPLAY USING ADDRESS-1 AS THE VARIBLE ADDRESS. 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, FPODT 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. 6) VARIABLE BASE COMMAND A) **** V **** CHANG VARIABLE BASE IT IS POSSIBLE TO EXAMINE ANY LOCATION IN THE TASK. THIS IS ACCOMPLISHED BY CHANGING THE VARIABLE BASE. INITIALY IT IS SET AT $VARS. THE FORMAT TO CHANGE THIS THIS IS: :V WHERE IS THE DESIRED BASE ADDRESS. 7) MISCELLANEOUS COMMANDS A) **** L **** CHANGE FPODT LUN USAGE IF IT IS DESIRABLE FOR FPODT TO USE A LOGICAL UNIT (LUN) OTHER THAN UNIT 5 (DEFAULT) FOR ITS I/O, THIS COMMAND WILL ALLOW THE USER TO SPECIFY THE LUN TO BE USED. ONE PARAMETER, THE LUN NUMBER, IS REQUIRED. THE FORMAT IS: 4L (USE LUN 4 FOR FPODT I/O) FPODT WILL ATTEMPT TO PRINT "FODT I/O TERMINAL" ON THE DEVICE ASSIGNED TO THE NEW LUN. IF IT IS UNABLE TO PRINT THE MESSAGE FOR ANY REASON IT WILL SWITCH BACK TO THE ORIGINAL LUN AND PRINT "???". THE I/O DEVICE MUST BE A TERMINAL. IT MUST BE ASSIGNED TO THE LUN BY THE TASK BUILDER OR WITH THE MCR REASSIGN COMMAND BEFORE THE TASK IS STARTED.