A Caché of Tips: Studio debugging

[Rich Taylor]

Last week we covered Command Line Debugging.  Today’s tip will extend the debugging discussion to our Studio Debugger.  We will have several screen captures embedded in this tip.  If your email client has a problem displaying this you can view this tip in PDF format.  That PDF file is attached.   Studio is Caché’s Integrated Development Environment (IDE).   From within Studio you can do all the normal debugging actions on programs, triggers, Class methods, and Zen pages.   These functions include

·         Setting break points

·         Watching variables

·         Changing variable values

·         Setting conditions on both break points and watch points

·         Stepping through execution of a process

 

You can also easily ATTACH to a running process and begin debugging that process.  This will be discussed below.

 

There are several advantages to using the Studio debugger over the command line and a few disadvantages.

 

Advantages

Disadvantages

·         You debug your source code not the intermediate code.  Note that if you share one code library among several MV Accounts there will be some additional setup.  This is to handle the indexing of source code lines to intermediate code since the debugger still deals with Caché routines under the covers. ·         The ability to easily attach to another running process ·         Your program source is always visible.  There is no need to ask for a display of code lines. ·         Watch variables are always visible ·         Working in an environment more familiar to new programmers

·         The Command line Debugger has a Trace functionality (not covered in last week’s tip) that is very useful ·         Studio is not “aware” of the Namespace/MV Account context when running the program.   This can lead to difficulty in debugging the program when the source lives and is compiled in an account other than where it is run.  This can be dealt with using Caché mapping capabilities.  See your Sales Engineer for more details on this. ·

 

STUDIO ENVIRONMENT

When you debug in Studio you will have three main windows you will deal with. 

·         The Program window which is typically located in the left upper.  This where your source is displayed.  Here you can set break points, step through programs and examine variables. 

·         The Output window.  Here you typically see messages from Studio regarding things such as compiling a program.  When debugging there is much more you can do here.  First it is possible to run programs completely within the Studio with no terminal session.  Normally this is for simple programs and/or programs that have little screen output.    In this case the output window becomes your terminal session.  You can run a MV Basic or Caché Object Script command  as you would from the command line debugger.  When you want to try a calculation or display a value in a format not held in variable.  This window is typically in the lower left portion of the Studio environment.

·         The Watch Window.  This window actually has several tabs; 4 variable watch tabs and one that provides a view of the call stack.

 

Any of these windows can be resized and moved so the position on your system may vary.

 

Now let’s run through a debugging session as we did with the command line debugger.  We will cover the common debugging tasks as we go.

 

SETTING A BREAK POINT

Setting a break point can be done is several ways.  The most common is to place your cursor in the program on the line where you want to establish a break and press the F9 key.  You could also right click the program line where you want the break point and select the “toggle Breakpoint” option.  To remove a breakpoint repeat the action.    Finally, you can go to the Debug Menu and select the Breakpoints sub-menu where you will choose the View Breakpoints dialog box.  We will examine this dialog more closely when we set conditions on watches and breaks.   There are also some rules you need to be aware of:

·         You cannot set a breakpoint if you have uncompiled changes.  The mapping of source lines to intermediate code and object code could be changing so you must compile the change first.  Any existing breaks will remain intact.

·         Once you have attached to a separate process you will not be able to set breakpoints until the process enters the debugger.  This will happen once a breakpoint has been reached or you interrupt the process

·         The process is at a terminal input statement.  You cannot gain control of a running process or interrupt the process to set a break if the process is sitting waiting on terminal input.

 

If the process is running, but you have not reached a break point you can gain control by selecting the Break or Interrupt option from the Debug menu.  Break will pause the execution and interrupt will stop a command that is running to give you debugging control.  In practice interrupt seems to work better.

 

In this example I have set a breakpoint on the line where SPLIT is calculated meaning I will drop gain control of the debugger when this line is reached and before it is executed.  Note my breakpoint is indicated with a red circle on the left margin of the program.  This is on line 32 in this example.

 

 

Executing the program being debugged

When I want to run this program to debug its process I have two ways to do this.  First I can attach to a terminal, either Caché terminal or some third party telnet connection, session then run this program in there.  Attaching to a process is one of the best features of the Studio Debugger and will be discussed further below.  The other way is to run this program directly from Studio.   To accomplish this do the following:

·         Indicate the program you wish to execute in studio. 

o   This can be accomplished from the Debug menu where you choose “Debug Target”.  This will display the following dialog.  You will note that you can debug programs, class methods, or   Web pages written in Caché here.  Enter the routine name prefixed by a caret (^).

o   The easier way however is to right-click anywhere in the program edit window on the program you wish to debug.  From the Context menu that pops up choose “set {program name} as debug target”.

·         Once you have set the target for debugging you can execute this target from within Studio by pressing Crtl-F5 or selecting Go from the Debug menu.  Your program will now execute and any output or prompting will appear in the output window.  For our sample program I have started the execution and entered ‘3’ for the prompt.  The program should now be at the first break point which is normally indicated in Yellow by default.

   

 

 

STEPPING THROUGH THE CODE

As with the command line debugger you can execute your program one line at a thime, single stepping.  This is done through the Debug menu, tool bar icons, or function keys.

·         STEP INTO – Execute one line of the program.  or F11    If  this line is a subroutine call or GOSUB then bring that routine up in the debugger.  Single step execution will continue

·         STEP OVER – Execute one line of the program.  or F10   If this line calls to a subroutine (CALL or GOSUB)  do not step into that code.  Run the entire subroutine and stop on the next command following the call.

·         STEP OUT – Continue the execution of a call or gosub until control returns to the controlling program.   or Shift-F11    The debugger will stop on the next executable line following the call or GOSUB.

·         RUN TO CURSOR – Run the program to the line where the cursor is currently located in the program window.   or Shift-F10.   This is useful when you have started to debug a loop or some other block of code and wish to skip the remainder.  Simply place the cursor on the line following the end of the loop or code block and click the icon.

 

When single stepping you will likely encounter times when you press the single step command (F10 or F11) but the current line indicator does not move to the next line.  This is due to the fact that some commands actually compile down to multiple low level commands.   Single stepping is actually stepping through this logic so the source instruction may take several steps to complete

 

CHECKING AND CHANGING VARIABLE VALUES

There are a couple of ways to check the value of a variable. 

·         Hover Over – if you place the mouse pointer over most variables you will be able to see the value in a floating box.  Some variable references do have trouble determining what you want to see exactly.  If you are trying to view the value that is not displaying you can use the mouse to highlight the entire reference then hover over that. 

·         Watch Window – You can also reference a variable in the watch window.   You can either type the variable name into the name column on a watch window tab or highlight and drag the variable there.  In the screens above you will see that we are watching the FACTOR and DONE variable.  The advantage here is that as you step through the program you will constantly be aware of the values contained in the variables being watched.  Any recently changed values are highlighted in RED.    Finally the values will be referenced as strings by default.  However the references could, in fact, be objects or arrays.  If you want to get a better view of these types of variables you can right-click the Name in the watch window.  You from the displayed menu select “View As” where you will be able to select a type.  For example if the variable contained an object handle you would be able to see the properties of the object rather than just the string representation of the handle its self.

·         Watch Point – putting a variable in the Watch window only monitors its value.  It does not stop execution when the value changes.  That functionality is called a watch point.  This is setup from the Debug menu.  Select the “Breakpoints” submenu then “View Breakpoints”.  A dialog will be displayed as shown below.   Type the variable you wish to set the watch point on in the Variable Field of the Set Watch point section of this dialog box then click Set.  Now each time the variable Rate changes during program execution the process will pause on the line that caused the change.

 

To CHANGE  the value of a variable you need to have it referenced in the Watch window.  You can then double click the Value column for the variable in question and change the value to whatever you need.

 

 

PUTTING CONDITIONS ON BREAK AND  WATCH POINTS

As in the tip last week we can assume that by some means we have determined that the problem in the example program is that the RATE is getting set to a value that is beyond the normal range.  We will assume for this example that all RATEs need to be lower than 1000.00.   We can put a condition on the break point that was set earlier so that we only stop when the RATE is outside this normal range.  From the Debug menu select the “Breakpoints” submenu then “View Breakpoints”.  A dialog will be displayed as shown below.  Click on the breakpoint to bring the values up to the edit boxes above the breakpoint list.   We will then add the Condition “RATE > 1000.00” then click the Set button.  The results is shown below.

                                     

You can set a similar condition on a Watchpoints.

 

 

ATTACHNING TO AN EXISTING PROCESS

To this point all debugging we have shown was done solely in Studio.  One of the great features of the Studio debugger is the ability to easily attach to another process that may already be running.  There are a few reasons you may wish to do this rather than just execute within Studio.

·         Your program may have more complex interaction with the terminal window than is possible in the studio Output window.  You will note in our examples above that the prompt for Split Factor is preceded and followed by numeric codes.  These are actually terminal control strings that this window is not capable of interpreting correcting.  To debug a more complex display in the manner a user will work with it requires a full terminal emulator.

·         Any testing should be done the way that a user will perform the actions.  Therefore, as in the first point, attaching to a terminal session rather than just using the Studio Output window is a good idea for many processes.

·         A user may already be in the process and having a problem.  Using Studio we can attach to the process which will immediately bring up the program currently running and perform a break at the current line being executed.  There is one exception to this.  If the process is waiting on user input then the break will not happen until the user presses enter on whatever the expected input is.  One way to check for this is to open the System Management Portal.  Under System Operations choose the Processes function.  Locate the process being debugged.  If the State is READ then the process is waiting on input.  Once you or the user has press a carriage return the code will resume and break at the next execution line.

 

To attach to a running process go to the Debug menu and pick the Attach option.  You will be presented with a list of currently running processes.  You can click on any column header to resort by that column.  If you know the process number you can also enter it manually in the input box below the process list. 

Select the process you wish to attach to and click OK

 

You would now be in the program that was running on that processes with the currently executed line being highlighted and with execution paused at that point.   Note that when you do this to a running process you may be left at a point where the Debugger cannot be utilized, such as in Caché internal code.  If you get an error related to not finding source for a routine that is not the one you expected try pressing Ctrl-F11 to step out of that code and back to the calling routine.  This would probably be your program.  You may have to do this a couple of times to get back to your own code.

 

Hopefully this will get you started with using Studio to debug your system.   You can read up more on this topic in the documentation for “Using Studio Debugger”.  This can be found in your documentation or at http://docs.intersystems.com/cache20121/csp/docbook/DocBook.UI.Page.cls?KEY=GSTD_Debugger