A major obstacle to debugging code problems is that you cannot actually see what’s happening as the code runs. All of the variables, formulas and control flow are invisible inside the computer. Panorama’s Debug Instrumentation system is designed to reveal this hidden information. Once you can actually see what’s going on in your code, it becomes much easier to track down most problems.

Before instrumentation was available, a common debugging technique was to add message statements to the code to display variables and formulas. When the code was run, Panorama would stop at each message statement and display the value in an alert. This technique can be helpful, but it comes with some significant drawbacks.

For example, consider the blizzard of alerts that will appear if the message statement is used to debug this procedure with a loop:

Panorama’s Debug Instrumentation is designed to give you the advantages of making the operation of your code visible, but without the disadvantages listed above. It’s just as easy to use as message statements, but without the drawbacks.

The Zlog statement

The heart of the instrumentation system is the zlog statement. You use this statement just as you would use the message statement, and the structure of the zlog statement is identical to the message statement- it takes a single parameter, a formula. But there are two key differences between the zlog and message statements:

Here is a procedure similar to the procedure shown in the previous section, but using the zlog statement instead of message. This version of the code runs without stopping to show alerts, and generates the easily understandable log shown on the right.

Earlier I told you that the zlog statement is ignored if you’re not debugging. How does Panorama know you’re not debugging? All you have to do is close the procedure editor window. If you run this code with the editor window closed (for example, from the Action menu or triggered by a button), nothing will appear in the log. Only instrumentation information from procedures that are currently open for editing will appear in the log, so you’re not distracted by extraneous information from other procedures that you aren’t interested in at the moment. (I’m over simplifying a bit – it IS possible to see instrumentation information from specified procedures that aren’t currently open if you want. To learn how this is done, see Customizing Debug Instrumentation Coverage.)

The zlog statement is all you need, but Panorama does provide some additional statements and functions that can make it more convenient to output information to the log. For example, there is a special function for displaying variables with their names, and a special statement for displaying dictionaries. You don’t have to use these statements and functions, but they can make your instrumentation code easier to write. To learn more, see Coding with Debug Instrumentation.

Enabling Instrumentation

Out of the box, the Debug Instrumentation feature is turned off. To turn it on, start by opening the Preferences window (from the Panorama menu), then clicking on the Advanced tab, then clicking the Enable Instrumentation Panel checkbox. You’ll immediately see an additional panel option, Instrumentation.

Here’s what this panel typically looks like. The top portion of the panel controls where the instrumentation output is sent, either a file or the console, or both (see Debug Instrumentation Text File). The bottom portion of the panel controls which databases and procedures currently have enabled instrumentation coverage (see Customizing Debug Instrumentation Coverage).

When the Instrumentation panel is enabled, you’ll also see a new Instrumentation menu at the end of the menu bar. This menu is displayed with a microscope icon.

The top item in this menu provides quick access to the Instrumentation panel. The second item opens the dynamic log viewer. The other items provide quick, universal access to features in the Instrumentation panel without having to actually open that panel.

Viewing the Instrumentation Log

The easiest way to view the instrumentation output is to use the built in Instrumentation Log window. Simply choose Open Instrumentation Log from the Instrumentation menu whenever you want to see the instrumentation output. The new window will show recent Panorama instrumentation activity, and will automatically update as new activity occurs.

For example, this procedure contains two zlog statements that will output information to the log (the zlog statement is discussed in detail later on this page). If you run this procedure with the Instrumentation Log window open, the information will automatically appear in the log:

The top of the Instrumentation Log window contains a toolbar with common actions:

See Debug Instrumentation Log Window to learn the specifics of each of these tools.

Additional Debug Instrumentation Topics

As described above, it’s really simple to get started using Panorama’s Debug Instrumentation feature. Simply add one or more zlog statements to your code, open the Debug Instrumentation Log Window, then run your code and see what you get. When you’re done, simply close the Instrumentation Log window and your procedure window and use your code normally.

Beyond the basics described above, see these additional help pages to learn about additional Debug Instrumentation features.

See Also


10.2NewNew in this version.