TraceOpen
PowerScript function
Description
Opens a trace file with the specified name and enables logging of
application trace activities.
Syntax
|
1 |
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
|
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
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