You use the PowerScript functions and PowerBuilder objects listed in The following table to analyze the performance of an application.
|
Use this function |
With this object |
To do this |
|---|---|---|
|
SetTraceFileName |
Profiling |
Set the name of the trace file to be analyzed. |
|
BuildModel |
Profiling |
Build a call graph model based on the trace file. You can pass optional parameters that let you track the progress of the build. |
|
RoutineList |
Profiling and ProfileClass |
Get a list of routines in the model or in a class. |
|
ClassList |
Profiling |
Get a list of classes in the model. |
|
SystemRoutine |
Profiling |
Get the name of the routine node that represents the root of the model. |
|
IncomingCallList |
ProfileRoutine |
Get a list of routines that called a specific routine. |
|
OutgoingCallList |
ProfileRoutine and ProfileLine |
Get a list of routines called by a specific routine or from a specific line. |
|
LineList |
ProfileRoutine |
Get a list of lines in the routine in line order. |
|
DestroyModel |
Profiling |
Destroy the current performance analysis model and all the objects associated with it. |
Each of these functions returns a value of the enumerated datatype ErrorReturn. The objects contain information such as the number of times a line or routine was executed, and the amount of time spent in a line or routine and in any routines called from that line or routine.
The call graph model that you create with the BuildModel function contains all the routines in the trace file and can take a long time to build. If you want to monitor the progress of the build or you want to be able to interrupt it while the model is being built, you can pass optional arguments to BuildModel.
BuildModel arguments
BuildModel takes three arguments: the name of an object of type PowerObject, the name of a user event, and a long value representing how often the user event should be triggered as a percentage of the build completed.
The user event returns a boolean value and has two arguments: the number of the current activity, and the total number of activities in the trace file.
Destroying existing models
Before you call BuildModel, you can call DestroyModel to clean up any objects remaining from an existing model.
Example: building a call graph model
In the following example, the user event 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 has a cancel button.
Profiling lpro_model lpro_model = CREATE Profiling ib_cancel = FALSE lpro_model.SetTraceFileName(is_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') // Build the call graph model lpro_model.BuildModel(this, 'ue_progress', 5) // clicking the cancel button in w_progress // sets ib_cancel to TRUE and // returns FALSE to ue_progress IF ib_cancel THEN & close(w_progress) RETURN -1 END IF
After you have built a call graph model of the application, you can extract detailed information from it.
For routines and lines, you can extract the timing information shown in the following table from the ProfileRoutine and ProfileLine objects.
|
Property |
What it means |
|---|---|
|
AbsoluteSelfTime |
The time spent in the routine or line itself. If the routine or line was executed more than once, this is the total time spent in the routine or line itself. |
|
MinSelfTime |
The shortest time spent in the routine or line itself. If the routine or line was executed only once, this is the same as AbsoluteSelfTime. |
|
MaxSelfTime |
The longest time spent in the routine or line itself. If the routine or line was executed only once, this is the same as AbsoluteSelfTime. |
|
AbsoluteTotalTime |
The time spent in the routine or line and in routines or lines called from the routine or line. If the routine or line was executed more than once, this is the total time spent in the routine or line and in called routines or lines. |
|
MinTotalTime |
The shortest time spent in the routine or line and in called routines or lines. If the routine or line was executed only once, this is the same as AbsoluteTotalTime. |
|
MaxTotalTime |
The longest time spent in the routine or line and in called routines or lines. If the routine or line was executed only once, this is the same as AbsoluteTotalTime. |
|
PercentSelfTime |
AbsoluteSelfTime as a percentage of the total time tracing was active. |
|
PercentTotalTime |
AbsoluteTotalTime as a percentage of the total time tracing was active. |
Example: extracting information from a call graph model
The following function extracts information from a call graph model about the routines called from a specific routine. You would use similar functions to extract information about the routines that called the given routine and about the routine itself.
The function takes a ProfileCall object and an index as arguments and returns a structure containing the number of times the called routine was executed and execution times for the called routine.
str_func_detail lstr_result ProfileClass lproclass_class ProfileRoutine lprort_routine // get the name of the called routine // from the calledroutine property of // the ProfileCall object passed to the function lprort_routine = a_pcall.Calledroutine lstr_result.Name = "" lproclass_class = a_pcall.Class IF isValid(lproclass_class) THEN & lstr_result.Name += lproclass_class.Name + "." lstr_result.name += a_pcall.Name lstr_result.hits = a_pcall.HitCount lstr_result.selfTime = a_pcall. & AbsoluteSelfTime * timeScale lstr_result.totalTime = a_pcall. & AbsoluteTotalTime * timeScale lstr_result.percentSelf = a_pcall.PercentSelfTime lstr_result.percentTotal= a_pcall.PercentTotalTime lstr_result.index = al_index RETURN lstr_result
