PRODUCT:  R:BASE             VERSION :  4.0
     AREA   :  TRACE              CATEGORY:  DEBUGGING      DOCUMENT#: 657
     The TRACE command in R:BASE 4.0 makes debugging any RBASE ASCII code 
     easier and less time consuming for both beginners and experts. Anyone 
     can use TRACE. It steps you through application code line by line, 
     checking for errors; it displays variable values as they change; and 
     it also has many other features to make debugging your code easy. 
     Starting TRACE
     Start the debugger either by using the Debugger option on the 
     Applications menu or by entering the TRACE command at the R> prompt. 
     When you use the Debugger option on the Applications menu, a menu 
     appears with a list of applications (.apx files) from which to choose. 
     Also on the menu is the Other... option, which prompts you for the 
     drive, directory, and name of the file to debug. 
     When using TRACE from the R> prompt the syntax is as follows:
        TRACE filename.ext
     If an application is involved, use this syntax:
        TRACE application IN application.apx
     Using TRACE
     Once you're in the debugger, the program code appears on the screen. 
     Near the top is a reverse video bar showing the line of code to be 
     executed next. At the bottom of the screen on the right side is the 
     name of the file you are currently debugging, the line number of the 
     current cursor position, and the total number of lines in the file. 
     Two important features of the debugger are the F10 key and the F6 key. 
     The F10 key steps through the code line by line, executing each line as 
     if you were running the commands normally. The F6 key allows you to 
     view variables and see their values change as you step through the code. 
     The debugger executes your code just as if you were running the 
     application. Menus appear, reports are printed, screen messages appear, 
     and forms display for data entry and editing. The debugger pauses for 
     user input where necessary; respond as if the application were running 
     An Example
     Below is a sample ASCII file to demonstrate the use of the F10 and F6 
     keys in the debugger. The file includes some errors so it demonstrates 
     what happens in the debugger when an error is encountered. 
     *(* TEST.CMD - an experimental test file that has no real use *)
     SET QUOTE = "SET VAR v1 = 'this is a test'
     SET VAR v2 = (SLEN(. v1))
     SET VAR v3 = 1
     WHILE v3  v2 THEN
       SET VAR v3 = (. v3 + 1)
       SET QUOTE= '
     Running this file at the R> prompt with MESSAGES and ERROR MESSAGES ON 
     produces a "Syntax is incorrect for the command" error message and a 
     "Missing ENDWHILE, ENDIF or ENDSW" error message. Use the debugger to 
     find the commands or section of code that is generating the errors. 
     At the R> prompt, enter TRACE TEST.CMD. The code displays on the screen 
     and the reverse video bar is on line 3, SET QUOTES=". Note that the 
     initial comment line is ignored.
     Press F10 to step through the code. The reverse video bar moves from 
     line 3 to line 4 with no errors. Press F10 again to move from line 4 
     to line 5, and you get an error. 
     The message indicates that the error occurred on line 4. The reverse 
     video bar is on line 5, but line 5 has not yet been executed. Press a 
     key to continue. Line 5 is still highlighted; it does not execute until 
     you press F10. 
     The error has occurred because of the incorrect use of quotation marks. 
     You can correct the error with either the R:BASE editor or another ASCII 
     text editor; you cannot edit the command file code directly in TRACE.
     Because one error can cause others, always exit the debugger and fix an 
     error, then restart the debugger and continue. That way you'll know the 
     errors you're getting aren't due to an earlier problem in the program. 
     When you have corrected the first problem, restart the debugger and step 
     down to line 5 with the F10 key. Now press F6 to examine the variables. 
     Check off the variables to view (v2 and v3), and then press F2. The 
     checked variables and their current values are now displayed at the top 
     of the debugger screen. It's easy to see whether they have the correct 
     value and change correctly as you step through the program.
     Press F10 and continue down through the sample program to line 7, where 
     the debugger tries to execute the WHILE statement. The debugger returns 
     you to the R> prompt or the menus with the "No ENDWHILE, ENDIF or ENDSW" 
     error message. The last line the debugger was able to execute was the 
     WHILE statement that is missing the ENDWHILE. The debugger checks for 
     an ENDWHILE statement before moving to the next line of code. Note that 
     you got an R:BASE error message, not a debugger error message. In some 
     cases the debugger is unable to continue and exits with a normal R:BASE 
     error message.
     Add an ENDWHILE command after the SET VAR v3=(.v3+1) command. Restart 
     the debugger and using F10 and F6, step through the WHILE loop with the 
     F10 and F6 keys. You can see the control variable (v3) change at the top 
     of the debugger screen.
     Continuous Execution
     The F10 key is useful for stepping through program code line by line, 
     but debugging hundreds of lines of code with it can become cumbersome. 
     The F5 key continuously executes code rather than stepping through line 
     by line. Pressing F5 on the first line of code causes the debugger to 
     execute the code until it comes to an error or a break point or runs 
     another file.
     A break point is a line of code in which you designate that the debugger 
     is to stop executing. To set a break point, use the mouse or cursor keys 
     to move the cursor to the line of code on which to stop. Press F9 to set 
     the break point, then press F5. The debugger begins executing from the 
     highlighted line of code, not the current cursor position. You don't 
     have to move back to the top of the file once you have set a break point. 
     Just press F5 - the debugger remembers the last line of code it executed. 
     The debugger executes code until it reaches the break point, finds an 
     error, or encounters a RUN command. Respond normally to menus and provide 
     other user input as necessary. Keep pressing F5 until the debugger stops 
     at your break point. Then use F10 to single step through to the error and 
     use F6 to view variables. 
     TRACE Options
     The TRACE command includes many other options. The ones described above 
     can quickly get you started debugging your custom program code.
     You can see a brief description of each function key by pressing Shift-F1 
     while in the debugger. For more detailed information on the debugger, 
     refer to the Command Dictionary and the Guide to Software Installation 
     and New Features.