TraceOpen PowerScript function
Description
Opens a trace file with the specified name and enables logging
of application trace activities.
Syntax
|
1 |
<span>TraceOpen </span><span></span>( <span>filename</span>, <span>timer</span> ) |
|
Argument |
Description |
|---|---|
|
filename |
A read-only string used to identify the |
|
timer |
A value of the enumerated datatype TimerKind
|
Return Values
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.
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 |
TimerKindltk_kind |
|
1 |
|
1 |
CHOOSE CASE ddlb_timestamp.text |
|
1 |
CASE "None" |
|
1 |
ltk_kind = TimerNone! |
|
1 |
CASE "Clock" |
|
1 |
ltk_kind = Clock! |
|
1 |
CASE "Process" |
|
1 |
ltk_kind = Process! |
|
1 |
CASE "Thread" |
|
1 |
ltk_kind = Thread! |
|
1 |
END CHOOSE |
|
1 |
|
1 |
<span>TraceOpen</span>(sle_filename.text,ltk_kind) |