Collecting trace information using PowerScript
functions
You use the PowerScript system functions listed in the following
table to collect information in a trace file. Each of these functions
returns a value of type ErrorReturn, an enumerated datatype.
|
Use this PowerScript function |
To do this |
|---|---|
|
TraceOpen |
Open a named trace file and set the timer |
|
TraceEnableActivity |
Enable logging of the specified |
|
TraceBegin |
Start logging all enabled activities. You can |
|
TraceError |
Log a severity level and error message to the |
|
TraceUser |
Log a reference number and informational message |
|
TraceEnd |
Stop logging all enabled |
|
TraceDisableActivity |
Disable logging of the specified |
|
TraceClose |
Close the open trace file. |
In general, you call the functions in the order shown in the
table. That is, you must call TraceOpen before you call any other
trace functions. You call TraceClose when you have finished
tracing.
TraceEnableActivity and TraceDisableActivity can be called only
when a trace file is open but tracing has not begun or has
stopped—that is, before you call TraceBegin or after you call
TraceEnd.
TraceUser and TraceError can be called only when the trace file
is open and tracing is active—that is, after you call TraceBegin and
before you call TraceEnd.
About TraceUser and
TraceError
You can use TraceUser to record specific events in the trace
file, such as the beginning and end of a body of code. You can also
record the execution of a statement you never expected to reach, such
as the DEFAULT statement in a CHOOSE CASE block. TraceError works just
like TraceUser, but you can use it to signal more severe
problems.
Both TraceUser and TraceError take a number and text string as
arguments. You can use a simple text string that states what activity
occurred, or you can build a string that provides more diagnostic
information by including some context, such as the current values of
variables. Run the application with only ActUser! or ActError! tracing
turned on and then use the Profiling Trace View to pinpoint problems
quickly.
Example: trace data
collection
In this example, the user selects a timer kind from a drop-down
list and enters a name for the trace file in a single-line edit box.
Typically you would use the ErrorReturn return value from every trace
call to return an error message if the call fails. For brevity, the
example shows this only for the TraceOpen call.
Several trace activities are disabled for a second trace block.
The activities that are not specifically disabled remain enabled until
TraceClose is called.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
ErrorReturn le_err integer li_key TimerKind ltk_kind CHOOSE CASE ddlb_timerkind.Text CASE "None" ltk_kind = TimerNone! CASE "Clock" ltk_kind = Clock! CASE "Process" ltk_kind = Process! CASE "Thread" ltk_kind = Thread! END CHOOSE // Open the trace file and return an error message // if the open fails le_err = TraceOpen( sle_fileName.Text, ltk_kind ) IF le_err <> Success! THEN & of_errmsg(le_err, 'TraceOpen failed') RETURN END IF // Enable trace activities. Enabling ActLine! // enables ActRoutine! implicitly TraceEnableActivity(ActESQL!) TraceEnableActivity(ActUser!) TraceEnableActivity(ActError!) TraceEnableActivity(ActLine!) TraceEnableActivity(ActObjectCreate!) TraceEnableActivity(ActObjectDestroy!) TraceEnableActivity(ActGarbageCollect!) TraceBegin("Trace_block_1") // first block of code to be traced // this block has the label Trace_block_1 … TraceEnd() // disable trace activities not needed for // second block TraceDisableActivity(ActLine! ) TraceDisableActivity(ActObjectCreate!) TraceDisableActivity(ActObjectDestroy!) TraceDisableActivity(ActGarbageCollect!) TraceBegin("Trace_block_2") // second block of code to be traced … TraceEnd() TraceClose() |