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 |
Return value
ErrorReturn. Returns one of the following values:
-
Success! -- The function succeeded
-
FileNotSetError! -- TraceFileName has not been set
-
ModelExistsError! -- A model has already been built
-
EnterpriseOnlyFeature! -- (Obsolete) This function is supported only in the Enterprise edition of PowerBuilder 12.6 and earlier versions.
-
EventNotFoundError! -- The event cannot be found on the passed progressobject, so the model cannot be built
-
EventWrongPrototypeError! -- The event was found but does not have the proper prototype, so the model cannot be built
-
SourcePBLError! -- The source libraries cannot be found, so the model cannot be built
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
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()
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()
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 IFSee also
