Collecting trace information

There are three ways to collect trace information. You can use:

The Profiling tab on the System Options dialog box
A window similar to the Profiling tab
Trace objects and functions

Use the Profiling tab if you want to trace an entire application run in the development environment. For more information, see “Tracing an entire application in PowerBuilder”.

Use a window or trace objects and functions if you want to create a trace file for selected parts of the application or the entire application, either in the development environment or when running an executable file. See “Using a window” and “Collecting trace information using PowerScript functions”.

Collection time The timer values in the trace file exclude the time taken to collect the trace data. Because an application can be idle (while displaying a MessageBox, for example), percentage metrics are most meaningful when you control tracing programmatically, which can help minimize idle time. Percentages are less meaningful when you create a trace file for a complete application.

Whichever method you use, you can specify:

The name and location of the trace file and optional labels for blocks of trace data
The kind of timer used in the trace file
The activities you want recorded in the trace file

Trace file names and labels

The default name of the trace file is the name of the application with the extension PBP. The trace file is saved in the directory where the PBL or executable file resides and overwrites any existing file of the same name. If you run several different tests on the same application, you should change the trace file name for each test.

You can also associate a label with the trace data. If you are tracing several different parts of an application in a single test run, you can associate a different label with the trace data (the trace block) for each part of the application.

Timer kinds

There are three kinds of timer: clock, process, and thread. If your analysis does not require timing information, you can omit timing information from the trace file to improve performance.

If you do not specify a timer kind, the time at which each activity begins and ends is recorded using the clock timer, which measures an absolute time with reference to an external activity, such as the machine's start-up time. The clock timer measures time in microseconds. Depending on the speed of your machine's central processing unit, the clock timer can offer a resolution of less than one microsecond. A timer's resolution is the smallest unit of time the timer can measure.

You can also use process or thread timers, which measure time in microseconds with reference to when the process or thread being executed started. You should always use the thread timer for distributed applications. Both process and thread timers exclude the time taken by any other running processes or threads so that they give you a more accurate measurement of how long the process or thread is taking to execute, but both have a lower resolution than the clock timer.

Trace activities

You can choose to record in the trace file the time at which any of the following activities occurs. If you are using the System Options dialog box or a window, you select the check boxes for the activities you want. If you are using PowerScript functions to collect trace information, you use the TraceActivity enumerated type to identify the activity.

**Table 33-1: Trace activities**
Trace Activities check box	What is recorded	TraceActivity value
Routine Entry/Exit	Routine entry or exit	ActRoutine!
Routine Line Hits	Execution of any line in any routine	ActLine!
Embedded SQL	Use of an embedded SQL verb	ActESQL!
Object Creation/ Destruction	Object creation or destruction	ActObjectCreate!, ActObjectDestroy!
User Defined Activities	A user-defined activity that records an informational message	ActUser!
System Errors	A system error or warning	ActError!
Garbage Collection	Garbage collection	ActGarbageCollect!
Not available	Routine entry and exit, embedded SQL verbs, object creation and destruction, and garbage collection	ActProfile!
Not available	All except ActLine!	ActTrace!

When you begin and end tracing, an activity of type ActBegin! is automatically recorded in the trace file. User-defined activities, which you use to log informational messages to the trace file, are the only trace activities enabled by default.