You use the PowerScript system functions listed in Table 33-2 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 kind. |
TraceEnableActivity |
Enable logging of the specified activity. |
TraceBegin |
Start logging all enabled activities. You can pass an optional label for the trace block. |
TraceError |
Log a severity level and error message to the trace file. |
TraceUser |
Log a reference number and informational message to the trace file. |
TraceEnd |
Stop logging all enabled activities. |
TraceDisableActivity |
Disable logging of the specified activity. |
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.
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.
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.
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()
