BuildModel

Description

Builds either a performance analysis or trace tree model based on the trace file you have specified with the SetTraceFileName function. Optional arguments let you monitor the progress of the build or interrupt it.

You must specify the trace file to be modeled using the SetTraceFileName function before calling BuildModel.

Applies to

Profiling and TraceTree objects

Syntax

instancename.BuildModel ( { progressobject, eventname, triggerpercent } )

Argument

Description

instancename

Instance name of the Profiling or TraceTree object

progressobject (optional)

A PowerObject that represents the number of activities that have been processed

eventname (optional)

A string specifying the name of an event you define

triggerpercent (optional)

A long identifying the number of activities the BuildModel function should process before triggering the eventname event

Returns

ErrorReturn. Returns one of the following values:

Usage

The BuildModel function extracts raw data from a trace file and maps it to objects that can be acted upon by PowerScript functions. If you want to build a model of your trace file without recording the progress of the build, call BuildModel without any of its optional arguments. If you want to receive progress information while the model is being created or if you want to be able to interrupt a BuildModel that is taking too long to complete, call BuildModel with its optional arguments.

The event eventname on the passed progressobject is triggered when the number of activities indicated by the triggerpercent argument are processed. If the value of triggerpercent is 0, eventname is triggered for every activity. If the value of triggerpercent is greater than 100, eventname is never triggered. You define this event using this syntax:

eventname ( currentactivity, totalnumberofactivities )

Argument

Description

eventname

Name of the event

currentactivity

A long identifying the number of the current activity

totalnumberofactivities

A long identifying the total number of activities in the trace file

Eventname returns a boolean value. If it returns false, the processing initiated by the BuildModel function is canceled and any temporary storage is cleaned up. If you need to stop BuildModel processing that is taking too long, you can return a false value from eventname. The script you write for eventname determines how progress is monitored. For example, you might display progress or simply check whether the processing must be canceled.

Examples

Example 1

This example creates a performance analysis model of a trace file:

Profiling lpro_model

String ls_filename


lpro_model = CREATE Profiling

lpro_model.SetTraceFileName(ls_filename)

lpro_model.BuildModel()

Example 2

This example creates a trace tree model of a trace file:

TraceTree ltct_model

String ls_filename


ltct_model = CREATE TraceTree

ltct_model.SetTraceFileName(ls_filename)

ltct_model.BuildModel()

Example 3

This example creates a performance analysis model that provides progress information as the model is built. The eventname argument to BuildModel is called ue_progress and is triggered each time five percent of the activities have been processed. The progress of the build is shown in a window called w_progress that includes a Cancel button:

Profiling lpro_model

String ls_filename

Boolean lb_cancel


lpro_model = CREATE Profiling

lb_cancel = false

lpro_model.SetTraceFileName(ls_filename)


Open(w_progress)

// Call the of_init window function to initialize

// the w_progress window

w_progress.of_init(lpro_model.NumberOfActivities, &

    'Building Model', This, 'ue_cancel')


lpro_model.BuildModel(This, 'ue_progress', 5)


// Clicking the cancel button in w_progress

// sets lb_cancel to true and returns

// false to ue_progress

IF lb_cancel THEN &

    Close(w_progress)

    RETURN -1

END IF

See also