Opens a trace file with the specified name and enables logging of application trace activities.
TraceOpen ( filename, timer )
Argument |
Description |
|---|---|
filename |
A read-only string used to identify the trace file |
timer |
A value of the enumerated datatype TimerKind that identifies the timer. Values are:
Clock timers and thread timers are the only kinds of timers supported on handheld devices. If you select the process timer for an application running on a device, the thread timer is used instead. |
ErrorReturn. Returns one of the following values:
Success!—The function succeeded
FileAlreadyOpenError!—TraceOpen has been called again without an intervening TraceClose
FileOpenError!—The file could not be opened for writing
EnterpriseOnlyFeature!—This function is only supported in the Enterprise edition of PowerBuilder.
If filename is null, TraceOpen returns null.
TraceOpen opens the specified trace file and enables logging of application trace activities. When it opens the trace file, TraceOpen logs the current application and library list to the trace file. It also enables logging of the default activity type, a user-defined activity type identified by the value ActUser!.
After calling TraceOpen, you can select any additional activities to be logged in the trace file using the TraceEnableActivity function. Once you have called TraceOpen and TraceEnableActivity, you must then call TraceBegin for logging to begin.
To stop logging of application trace activity, you must call the TraceEnd function followed by TraceClose to close the trace file. Each call to TraceOpen resets the logging of activity types to the default ActUser!
You typically include the TraceOpen function in your application’s Open script.
Caution
If the trace file runs out of disk space, no error is generated,
but logging is stopped, and the trace file cannot be used for analysis.
By default, 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 startup 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 in a desktop application. These timers measure time in microseconds with reference to when the process or thread being executed started. You can use only the clock or thread timers for applications running on handheld devices. Both process and thread timers 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.
If your analysis does not require timing information, you can omit timing information from the trace file.
Collection time The timestamps in the trace file exclude the time taken to collect the trace data.
This example opens a trace file with the name you entered in a single line edit box and a timer kind selected from a drop-down list. Then it begins logging the enabled activities for the first block of code to be traced:
TimerKindltk_kind
CHOOSE CASE ddlb_timestamp.text
CASE "None"
ltk_kind = TimerNone!
CASE "Clock"
ltk_kind = Clock!
CASE "Process"
ltk_kind = Process!
CASE "Thread"
ltk_kind = Thread!
END CHOOSE
TraceOpen(sle_filename.text,ltk_kind)
