Description
Opens a trace file with the specified name and enables logging of application trace activities.
Syntax
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:
|
Return value
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! -- (Obsolete) This function is only supported in the Enterprise edition of PowerBuilder 12.6 and earlier versions.
If filename is null, TraceOpen returns null.
Usage
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, which measure time in microseconds with reference to when the process or thread being executed started. Use the thread timer for distributed applications. 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.
Examples
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:
TimerKind ltk_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)
See also
