Collecting trace information

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

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”.

NoteCollection 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:

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.