Performance Profiling
Progress 4GL Applications
Date: January 27, 1999
Last updated: April 26, 2001

1.	Overview
This document describes what you need to know in order to profile a Progress 4GL 
application. Before we begin, it is important to make one thing very clear: This is an 
Unsupported Free Software package. The package consists of the 4GL Application Tool 
that came with this document, the "hidden" feature of the Progress 4GL Client described 
in this document, and this document itself. What do we mean by Unsupported Free 
Software? Simply this:
Do not call Progress Software Technical 
Support concerning anything described in this 
document.

Wait, you say. Isn't that FreeWare? Progress Software doesn't normally supply software 
in this way. I pay for technical support. I expect technical support. What is this?

We have not adequately tested, reviewed, polished, documented, and run through a Beta 
cycle. In other words, it is not ready for us to support. At the same time, however, we 
realize that a decent performance profiler can make a world of difference in ironing out 
problems in complex applications. We reasoned that a number of you would be willing to 
put up with the relatively rudimentary Core Profiling Capabilities that made it into the 
4GL Client and AppServer . Those rudimentary core capabilities are reasonably stable 
and should take you a long way. At the end of this document, we will discuss in what 
ways we are thinking we may further develop these capabilities.

If you need help:
Contact your Regional Professional Services Manager 
(i.e., Progress Consulting) and employ their services.

For all versions of the product, the profiler tool is unsupported software.
1.1	What is Profiling?
A performance profiler is a common and useful tool for a software developer. In brief, a 
profiler provides a "profile" of a particular execution. A profiler generally provides 
timing information and call-tree information; with that, an engineer can analyze where 
their program is spending most of its time and what part of the application is calling what 
other part of the application.
Functionally, the profiling software comes in two parts. Part 1 is the profiling capability 
itself -- this is the part built in to the 4GL Client that generates and outputs the necessary 
timing data from a run of a Progress client session. Part 2 is the tool to import, interpret, 
and view that timing data. Part 1 was first shipped as an undocumented (and 
unsupported) feature in version 8.2A; in version 9.0B, the Part 1 feature was documented 
and is supported. We will describe the features below.

Part 2 is the 4GL Application Tool that came with this document. We will describe how 
to use that tool later.
1.2	Profiling Your 4GL Application
To profile a 4GL application, you run the 4GL application with profiling enabled. As the 
4GL Client exits and returns to the operating system, it produces an output file containing 
a summary of what code was executed and timing data for each line that was executed. 
We often refer to the data in that output file as representing a "profiling session". Then 
you use the Profiling Tool to import that summary data (the format is described below) 
into a Progress database; the Profiling Tool does an analysis of the data as part of the 
import process, and then the profiling session is available for view.

Starting with version 9.0A, there is a PROFILER system handle that may be used to start 
and stop the profiling, to write the data, to specify the output file, and to control a host of 
other things associated with profiling.
2.	Generating Profiling Data for a 4GL Application
2.1	For Versions 9.0A and higher
There are two ways to generate profiling data for an application run: generically using the 
profile startup parameter, or specifically using the PROFILER system handle. You 
should find the details for the PROFILER system handle documented starting in 9.0B in 
the Language Reference manual. You will also find those details in this document in the 
Technical Details section. If you don't care about the technical details, but want to be 
able to turn profiling on and off during an application run, you can add _profile.p (found 
in this directory) as a ProTool. _Profile.p is simply a GUI front-end for the PROFILER 
system handle. Using this is probably the simplest way to control the generation of 
profiling data for your application.

If you cannot use or do not want to use the _Profile.p ProTool, you can control the 
profiler using the profile startup parameter. It is invoked as follows:
-profile profile-configuration-file
where profile-configuration-file is the name of a configuration file. When -profile is 
specified, PROFILER:ENABLED will be initialized to True. The configuration file may 
contain any or none of the following options. A '#' is the comment marker. Everything to 
the end of the line after a '#' is disregarded. Note that all of the options here are described 
in terms of the PROFILER system handle, which is documented in the Technical Details 
section below.
-COVERAGE # Initialize PROFILER:COVERAGE to True
-DESCRIPTION description # Initializes PROFILER:DESCRIPTION to description 
(if more than one token, it should be a quoted string).
-FILENAME filename # Initialize PROFILER:FILE-NAME to filename 
-LISTINGS [directory] # Initialize PROFILER:LISTINGS to True; if directory is 
specified, initialize PROFILER:DIRECTORY to directory.
-PROFILING [yes | no] # Initialize the PROFILER:PROFILING to yes or no. If yes 
or no is not specified, the default is yes. If PROFILING is not specified, the 
default is also yes.
-TRACE-FILTER  patterns # Initialize PROFILER:TRACE-FILTER to patterns (if 
more than one token, it should be a quoted string).
-TRACING entries # Initialize PROFILER:TRACING to entries. This should be a 
quoted string.
Any error in the profile-configuration-file will result in Profiling being not enabled.
2.2 	For Version 8.X
To generate profiling data for an application run, start the Progress 4GL Client (or 
AppServer) with the command line startup -zprofile as follows:
-zprofile profile-configuration-file
where profile-configuration-file is the name of a configuration file. The configuration file 
may contain any (or none) of the following options:
-OUTFILE Filename
-LISTINGS [Directory] 
-DESCRIBE Description
A '#' is the comment marker. Everything to the end of the line after a '#' is ignored. 

Filename specifies the name of the file where you want Progress to put the profiling 
output data (the timings, etc.). If OUTFILE is not specified, the default is "prof.out".

If -LISTINGS is specified, then Progress will attempt to automatically generate debug 
listing files for the 4GL code that is profiled. The profiler only generates a debug listing 
file the first time that procedure is executed. Note that the profiler can only attempt to 
generate debug listing files; it cannot guarantee the generation of debug listing files. The 
source files that comprise a procedure need to be on the PROPATH in order for the 
profiler to actually generate a debug listing file. If the profiler cannot generate a debug 
listing file for a given procedure, it will simply look as though -LISTINGS was not 
specified for that procedure. Directory specifies the directory where you want Progress to 
put the generated listing files. If Directory is not specified, Progress will put the listing 
files in the current working directory.

If -DESCRIBE is specified, then Description will be the description of the profiling 
session that will be included as part of the data in the profile output file (see the section 
below, Profiler Output File Format). If your Description is more than one token, it 
should be enclosed in a quoted string.


3.	Using the Profiling Tool
First of all, we've given you source code for this tool and placed it in the public domain. 
Therefore, if there is anything about the tool that you do not like, or any problem with the 
tool you discover, you are free to change it. A "C" developer using the UIB did the 
original development, so no-one's feelings will be hurt if you modify it!

The Profiling Tool, as it is, runs on the Win95 or WinNT platforms (sorry, no character 
mode version). To use the tool, you will need to first create a database to hold the data 
from your profiling sessions. Use the .df file that came with this document to create the 
schema for the database. Then start Progress as follows:
prowin32.exe -1 profdb -ld prof -p sessions.w
The window that comes up displays a browse of all the profiling session descriptions that 
have been read into the database (the first time you run it, this will be an empty browse). 
Click on the "Add Session" button to import the data from your profiling session. 
Importing the data can take a while, especially if you import the debug listing files (it's 
worth the wait to import the debug listing files). You might run this database with -i (no-
integrity mode) to improve the performance.

Click on the "View Session" button to bring up the "Session Summary" window which 
details the total time for the profiling session and presents in a browse each procedure 
executed during the session, sorting the procedures in descending order by execution 
time.

Double clicking on any of the procedure descriptions in the Session Summary will bring 
up a "Profile of .p/.w" window with a focus on the procedure you selected. This is a busy 
window that gives:
1)	Summary Data for the procedure (or user-defined function) selected.
2)	A browse of other internal procedures or user-defined functions that are a part 
of this external procedure and that were executed during this profiling session.
3)	Caller information detailing what procedures called this procedure.
4)	Calling information detailing what procedures this procedure calls.
5)	Procedure listing data, if you generated and imported the debug listing file for 
this procedure. This is positioned at the first executable line of the procedure 
in focus. It also details how many times a line was executed and the average 
execution time.
6)	Finally, a browse of the executable lines for the procedure in focus, sorted in 
descending order by the amount of time spent at each line.

ToolTips give you direction on the things you can do. In general, you can double click on 
any of the browsers displayed and it will adjust the focus accordingly. For example, 
double clicking on the Caller browse will bring up a window detailing the calling 
procedure; or double clicking on the Executable line browse will reposition the listing 
browse to the corresponding executable line.

If you have a small monitor, you can click on the "ReUse Window" check-box, which 
tells the tool to not create separate windows for separate procedure profiles.
4.	Technical Details
This section describes how the Core Profiling Capabilities work so that you'll have a 
slightly better understanding of the data you are looking at, and it describes the format of 
the data output by the 4GL Client in case you need to know. The information in this 
section of the document will not be interesting to most of you.
4.1	Behavior

The 4GL application being profiled should perceive no functional difference in behavior. 
The only difference a user may ever see when their application session is being profiled 
is an occasional slow-down in the application while the 4GL Client is either:
1)	Generating debug listing files (this can be turned off);
2)	Writing raw timing data to a temporary file (this should be imperceptible); or
3)	Analyzing and writing summary data to the profiler output file -- this only 
happens when the session ends or the PROFILER:WRITE-DATA() method is 
called.

While profiling is enabled, the 4GL runtime engine records 4GL statement begin and end 
times with microsecond precision. This raw data is written to a temporary file . Along 
with the start or end time, Progress records the statement line number and a module 
identifier. Each distinct external procedure, internal procedure, user-defined function, 
session database trigger, or user interface trigger that is executed is considered a module  
and is assigned a unique identifier.

All profiling times are in terms of Progress debugger listing line numbers; these are what 
are stored in the r-code and so these are what it uses . Note that time attributed to line 0 is 
the time spent to initialize or uninitialize the procedure.

Time spent in user interface blocking statements, such as a WAIT-FOR, PAUSE, or 
MESSAGEALERT-BOX statement, are factored out. Time spent in the Progress 
debugger is factored out as well. However, time spent waiting for a response from a 
database server, an AppServer, the file system, or waiting for a record-lock are not 
factored out; they are considered a part of the application's profile.

While profiling is enabled, Progress generates debug listing files automatically, if 
directed to do so (see LISTINGS option described above in section 2). The time spent 
generating these listing files is factored out of the profiling time.

Progress also factors out any time spent in an ADE tool (Procedure Editor, AB/UIB, etc.). 
A procedure is considered part of an ADE tool if it is file-name begins with an 
underscore, '_'; e.g., _edit.p. 

Finally, Progress factors out the time that its profiling code spends writing raw timing 
data out to its temporary file. The overhead of taking the measurements themselves is 
pretty minimal and the 4GL Client makes no attempt to factor it out.

At the end of the session (or when PROFILER:WRITE-DATA() is invoked), Progress re-
reads the raw timing data and analyzes it in order to produce the profiler output file. 
4.2	PROFILER System Handle
Control of profiling can be managed from the 4GL by way of the new PROFILER system 
handle (introduced in version 9.0A). Here are the attributes and methods.

COVERAGE  Read/Write attribute of type Logical. Initial value is No, unless set 
otherwise by way of the command line startup option (see above). When set to 
True, the Profiler will begin maintaining executable line and internal procedure 
information on each external .p procedure that executes. When the analysis data is 
written to the Profiler output file, the Profiler will output this information (see the 
section below, Profile Output File Format). This information identifies what 
lines of code could have been executed for any given procedure; that, together 
with the Profiler timing data which tells us what lines of code were executed, can 
be used to do 4GL application code coverage analysis. For example, the profiling 
session only exercised 30% of the code in a given procedure.

Note that the profiler only reads the information necessary for coverage analysis 
the first time an external .p procedure executes. Therefore, if 
PROFILER:COVERAGE is False the first time a procedure executes, setting it to 
True at a later time will not cause the Profiler to register the coverage analysis 
information for that procedure. 

DESCRIPTION - Read/Write attribute of type Character. Initial value is 
"Unspecified" unless set otherwise by way of the command line startup option 
(see above). This attribute holds the description of the profiling session, which 
will be included as part of the data in the profile output file (see the section below, 
Profile Output File Format). 

DIRECTORY - Read/Write attribute of type Character. Unless set otherwise by way 
of the command line startup option (see above), the initial value is the -T 
directory or the current working directory if -T was not specified. This attribute 
specifies the directory in which automatically generated profiler debug listing 
files should be created. This attribute may not be set to the Unknown value, and 
will not permit itself to be set to an invalid directory.
 
ENABLED  Read/Write attribute of type Logical. Initial value is False, unless 
profile  command line startup option is specified (see above). This initiates the 
profiling capabilities.

When Profiling is first enabled, Progress will register all active procedures, 
assigning them a module identifier; an active procedure is any persistent 
procedure or procedure on the Progress procedure call stack. For each active 
procedure , it will also generate listing files (if PROFILER:LISTINGS is True) 
and register coverage analysis information (if PROFILER:COVERAGE is True). 
Thus, if you want listing files generated (or coverage analysis information 
registered), it is a good idea to set PROFILER:LISTINGS (or 
PROFILER:COVERAGE) to True before setting PROFILER:ENABLED to 
True.

As long as Profiling is enabled, Progress will maintain a registry of what 
procedures have executed, regardless of whether profiling is turned on or off. 
When Profiling is disabled by setting PROFILER:ENABLED to False, Progress 
will write accumulated profiling data to the profiler output file and then de-
allocate the registry of what procedures have executed.

FILE-NAME - Read/Write attribute of type Character. Initial value is "profile.out" 
unless set otherwise by way of the command line startup option (see above). This 
attribute specifies the name of the output file where the profiling data should be 
written. This attribute cannot be set to the Unknown value.

LISTINGS - Read/Write attribute of type Logical. Initial value is False, unless set 
otherwise by way of the command line startup option (see above). Setting this 
attribute True or False tells the profiler whether or not to attempt to automatically 
generate debug listing files for the 4GL code that is profiled.

Note that the profiler only generates a debug listing file the first time that 
procedure is executed. Therefore, if PROFILER:LISTINGS is False the first time 
a procedure is executed, setting it to True at a later time will not cause the profiler 
to try to generate the listing file for that procedure. In other words, the profiler 
only registers a module (assigns it a unique identifier) the first time it is executed 
and the profiler only generates debug listing files for modules that are external 
procedures. If PROFILER:LISTINGS is False when a procedure is first executed, 
the profiler will never try to generate a debug listing file for that procedure.

The profiler can only attempt to generate debug listing files; it cannot guarantee 
the generation of debug listing files. The source files that comprise a procedure 
need to be on the PROPATH in order for the profiler to actually generate a debug 
listing file. If the profiler cannot generate a debug listing file for a given 
procedure, it will simply look as though PROFILER:LISTINGS was False when 
that procedure was first executed.

The only way to get a Progress session to re-attempt generating the debug listing 
for a procedure is to disable and then re-enable the profiler by setting 
PROFILER:ENABLED to False (which causes Progress to de-allocate its profiler 
registry of procedures) and then to True.

PROFILING - Read/Write attribute of type Logical. Initial value is False, unless set 
otherwise by way of the command line startup option (see above). Setting this 
attribute turns profiling on or off. If PROFILER:ENABLED is false, this is a no-
op.
 
TRACE-FILTER  Read/Write attribute of type Character. Initial value is "", unless 
set otherwise by way of the command line startup option (see above). The value 
of PROFILER:TRACE-FILTER will be treated as a comma separated list of 
expression patterns that are interpreted in the same way as the 4GL built-in 
MATCHES() function. If a procedure name matches one of the patterns in the list, 
then the Profiler will generate detailed timing information for every executable 
line in that procedure. In addition to outputting the summary timing data for each 
executable line, it will output timing detail for each time an executable line is 
executed. See the Profiler Output File Format section for how the data will be 
represented. With this detailed information, an application's execution trace can 
be established.

If the value of TRACE-FILTER is "", then it matches no procedures; in this case 
the only tracing generated will be that generated via the PROFILER:TRACING 
attribute (see below). If the value is "*", then it matches all procedures. A couple 
of examples: To get tracing information for all enable_UI procedures, you could 
set TRACE-FILTER to "enable_UI *". To get tracing information for all 
enable_UI procedures and all executable lines in the procedure hello.p, you could 
set TRACE-FILTER to
"enable_UI *,*hello.p".

The pattern matching for TRACE-FILTER is case insensitive. 

The TRACE-FILTER patterns are utilized by the Profiler only while the Profiler 
is analyzing its raw data in preparation for writing data to the output file (usually 
during PROFILER:WRITE-DATA()). Thus, in most cases TRACE-FILTER need 
only be established sometime before the Profiler writes the data for the session to 
its output file. However, the Profiler may need to do partial analysis on the fly (in 
the event that the raw data temporary file gets too large); therefore, it is best to 
ensure that a TRACE-FILTER pattern is established before any procedure 
intended to match the pattern is run.

Redundant entries in the PROFILER:TRACE-FILTER list will be removed 
automatically.

TRACING  Read/Write attribute of type Character. Initial value is "". Like the 
value of TRACE-FILTER, the value of this attribute is treated as a comma 
separated list. The difference is that the elements in this list identify specific 
executable lines that are to have detailed timing information generated for them. 
Each comma separated element in the list should have the format: procedure-
name|line-number where procedure-name is the name of a main .p procedure (not 
an internal procedure, etc.) and line-number is the debug listing line number of 
the statement to be traced.

If TRACING is set to "", then the only tracing information that will be generated 
will be that generated via the PROFILER:TRACE-FILTER attribute.

As with the TRACE-FILTER patterns, the TRACING entries are utilized by the 
Profiler only while the Profiler is analyzing its raw data in preparation for writing 
data to the output file (usually during PROFILER:WRITE-DATA()). Thus, in 
most cases TRACING entries need only be established sometime before the 
Profiler writes the data for the session to its output file. However, the Profiler may 
need to do partial analysis on the fly (in the event that the raw data temporary file 
gets too large); therefore, it is best to ensure that a TRACING entries are 
established before the procedure-name|line-number is executed. 

Note that if an entry's procedure-name matches one of the patterns already 
specified in TRACE-FILTER, then that TRACING entry is redundant and will 
not be used during the write of the output data.

Redundant entries in the PROFILER:TRACING list will be removed 
automatically.

USER-DATA(val AS Char) - Method taking a single character parameter and 
returning a value of type Logical. This method instructs the profiler to write the 
character val data out to the profile output file. It returns False if it fails to write 
the data (this can only fail if the profiler is unable to open a temporary file); 
otherwise it returns True. If val is Unknown, then ? will be written. Otherwise, val 
will be enclosed in quotes (with any embedded quotes, quoted). This is all 
standard operating procedure for Progress exported data format. In addition to 
each val written, the Profiler will output an integer value representing the number 
of microseconds since the start of the profiler (these will correspond to values 
written due to tracing). See the Profiler Output File Format section for details.

The purpose of this method is to allow application developers collect their own 
profiler information (such as database statistics) and write it to the profiler output 
file. Any user data will be written as the last section of the profiler output file.

WRITE-DATA() - Method returning a value of type Logical. This method instructs 
the profiler to analyze the timing data collected so far and write the profiling data 
out to the profile output file. It returns False if it fails to write the data (this could 
be either because there was no new data or because it could not open the output 
file specified); otherwise it returns True.

Time spent analyzing and writing the profiling data is factored out of any further 
profiling.
4.3	Profiler Output File Format (Version 1  Progress version 9.0A 
and above)
This section is included so that you can create your own Profiling Tool, and so that you 
understand what the given version of the Profiling Tool is reading. Most of you won't 
care much about the information in this section.

The profiler output file has six sections. Each section is terminated with a line with a 
single dot '.', just like most data read by the 4GL into a Progress database. Depending on 
the profiling session, some sections may be empty; in that case, they will have at least the 
line with the single dot '.' terminating the input. I will detail the each of the sections 
below. The sections are:
1)	A section describing the profiling session;
2)	A section describing the modules (e.g., procedures, functions, triggers) 
involved in the session;
3)	A section providing procedure call-tree information;
4)	A section detailing timing summaries for each executable line that was a part 
of the profiling session;
5)	A section describing detailed tracing information; and
6)	A section detailing information necessary for coverage analysis.
7)	A section containing data written using the USER-DATA() method. 
4.3.1	Description Data Section
Format:
	IntegerVersion Date "Description" SystemTime "Userid"
where IntegerVersion is a version number for the profiling output (in case we choose 
to change the format at a later date) and identifies the format for the output file; Date 
is the date in format "mm/dd/yyyy" when the Profiler was enabled; Description will 
be the value of PROFILER:DESCRIPTION when the file was written; SystemTime is 
the wall-clock time in HH:MM:SS format; and Userid will be the userid of the 
current (at the time of the WRITE-DATA() call) DICTDB database or, if there is no 
database connected, the user's operating system login id. There is only one line of 
data for this section.
4.3.2	Module Data Section 
Format:
	IntegerModuleID "ModuleName" "DebugListingFile" IntegerCRCVal
where ModuleName may be the name of an external procedure, an user interface or 
session database trigger, an internal procedure, or an user-defined function. It looks 
roughly like the output of PROGRAM-NAME function in Progress. The 
DebugListingFile will be nil if PROFILER:LISTINGS was False when the module 
was first registered and it will be nil if the module is not an external procedure name 
(since they are the only ones that have debug listing files generated for them). The 
IntegerCRCVal will be 0 for modules that are not external procedures; for modules 
that are external procedures, this will be the RCODE-INFO:CRC value for the main 
procedure . The IntegerModuleID is an unique identifier for the module for this 
profiling session. All following data will be in terms of these identifiers. Here is an 
example of the first three lines from a profiling session that ran our internal SCC 
system:
44 "set-ndinfo editdesc.p" "" 0
28 "USER-INTERFACE-TRIGGER chgbug.p" "" 0
1 "/usr/rdl/devdbs6/scc-bug.p" "sccbugrun/00a06814.dbg" 42913
  4.3.3	Call-tree Data Section
Format:
	CallerID CallerLineno CalleeID CallCount
where module CallerID called Module CalleeID CallCount times from line 
CallerLineno. All data for this section are Integers. CallerID 0 is used to identify the 
Session. The "Session" module calls the top-level procedure.
4.3.4	Line Summary Section
Format:
	ModuleID LineNo ExecCount ActualTime CumulativeTime
where executable line LineNo of module ModuleID was executed ExecCount times 
and spent ActualTime seconds carrying out the actual execution of the statement and 
CumulativeTime seconds passed while this statement ran. ActualTime and 
CumulativeTime are both decimal data with precision 6 (microsecond precision) and 
all other elements are Integer data. ActualTime and CumulativeTime will be the same 
for simple statements that don't cause other statements to run. Statements such as the 
RUN statement or any statement that causes a trigger to fire, will have different 
values for the ActualTime and CumulativeTime. Note that ActualTime and 
CumulativeTime are the totals for this statement. If the statement ExecCount is 1, then 
they are the real times; otherwise, you need to divide ActualTime and 
CumulativeTime by the ExecCount to get the average time it took to execute the 
statement. The ActualTime and CumulativeTime are given in seconds and the profiler 
tries to get microsecond precision.

Here's some example output:
26 291 1 0.001915 0.022753
8 306 66 1.357740 1.387024
50 270 1 0.000473 0.000473

Where LineNo is 0, that refers to the time used to initialize and then later to tear down 
the procedure or trigger. This is the overhead of running the 
procedure/function/trigger.

Where ModuleID is 0, that is referring to time associated with the profiling session. 
There should only be one Line Summary record that references ModuleID 0 and that 
record should have a LineNo of 0, an ExecCount of 1, an ActualTime of 0, and the 
CumulativeTime should reflect the total time for the profiling session. The 
CumulativeTime can be used to compute session percentages; e.g., what percentage of 
the session did Module X use.
4.3.5	Tracing Data Section
Format:
	ModuleID LineNo ActualTime StartTime
where executable line LineNo of module ModuleID spent ActualTime seconds 
carrying out the actual execution of the statement, starting at StartTime. StartTime is 
relative to the SystemTime (see the Description Data Section above); that is, it is the 
number of seconds since SystemTime. StartTime has the same (microsecond) 
precision as the other timing data. For example,
50 270 0.000160 123.000954
53 116 0.000170 1432.789112
2 14 0.000143 0.132210

4.3.6	Coverage Data Section
Format:
	ModuleID "EntryName" LineCount
where ModuleID identifies the main .p procedure module identified in the Module 
Data Section. EntryName is the name of an internal procedure, user-defined function, 
or trigger. And LineCount is the number of executable lines in EntryName. If 
EntryName is nil, then this is identifying the executable line numbers for the main 
procedure of ModuleID. Each line in this section is followed by LineCount lines of 
data identifying the executable lines in EntryName. For example, if ModuleID 10 had 
an internal procedure defined as follows:
323	PROCEDURE foobar:
324
325	REPEAT I = 1 to 10:
326	   DISPLAY I.
327	END.
328	MESSAGE "All Done.".
329
330	RETURN.
331	END PROCEDURE.
Then the output in the Coverage Data Section would look like:
10 "foobar" 5
325
326
327
328
330
.	? Note the "." data terminator at the end of the executable line data.

A coverage analysis tool may be interested in only the fact that there are 5 executable 
lines in foobar, or it may want to know what the actual executable lines are. It can 
choose whether it throws the data out.
4.3.7	User Data Section
Format:
	WriteTime "UserData"
where WriteTime is the time at which the USER-DATA() method was executed and 
UserData is the val passed to the USER-DATA() method. WriteTime is relative to the 
SystemTime (see the Description Data Section above); that is, it is the number of 
seconds since SystemTime. WriteTime has the same (microsecond) precision as the 
other timing data.

4.4	Profiler Output File Format (Version 0  Progress version 8.x)
Progress Version 8.X outputs the profiler output file in four sections:
1)	A section describing the profiling session;
2)	A section describing the modules (e.g., procedures, user-defined functions, 
triggers) involved in the session;
3)	A section providing procedure call-tree information; and 
4)	A section detailing timing summaries for each executable line that was a part 
of the profiling session. 
 
Each section is terminated with a line with a single dot '.', just like most data read into a 
Progress database.
4.4.1	Description Data Section
Format:
	IntegerVersion Date "Description"
where IntegerVersion is a version number for the profiling output (in case we choose 
to change the format at a later date) and identifies the format for the output file; Date 
is the date in exported format for when the profiling session began; and Description 
will be the value specified by the -DESCRIBE option of profile configuration file. 
There is only one line of data for this section.
4.4.2	Module Data Section 
Format:
	IntegerModuleID "ModuleName" "DebugListingFile"
where ModuleName may be the name of an external procedure, an user interface or 
session database trigger, an internal procedure, or an user-defined function. It looks 
roughly like the output of PROGRAM-NAME function in Progress. The 
DebugListingFile will be nil if -LISTINGS was not specified in the profile 
configuration file. The IntegerModuleID is an unique identifier for the module for 
this profiling session. All following data will be in terms of these identifiers. Here is 
an example of the first three lines from a profiling session that ran our internal source 
code control system:
44 "set-ndinfo editdesc.p" ""
28 "USER-INTERFACE-TRIGGER chgbug.p" ""
1 "/usr/rdl/devdbs6/scc-bug.p" "sccbugrun/00a06814.dbg"
4.4.3	Call-tree Data Section
Format:
	CallerID CallerLineno CalleeID CallCount
where module CallerID called Module CalleeID CallCount times from line 
CallerLineno. All data for this section are Integers. CallerID 0 is used to identify the 
Session. The "Session" module calls the top level procedure.
4.4.4	Line Summary Section
Format:
	ModuleID LineNo ExecCount ActualTime CumulativeTime
where executable line LineNo of module ModuleID was executed ExecCount times 
and spent ActualTime seconds carrying out the actual execution of the statement and 
CumulativeTime seconds passed while this statement ran. ActualTime and 
CumulativeTime are both decimal data with precision 6 (microsecond precision) and 
all other elements are Integer data. ActualTime and CumulativeTime will be the same 
for simple statements that don't cause other statements to run. Statements such as the 
RUN statement or any statement that causes a trigger to execute, will have different 
values for the ActualTime and CumulativeTime. Note that ActualTime and 
CumulativeTime are the totals for this statement. If the statement ExecCount is 1, then 
they are the real times; otherwise, you need to divide ActualTime and 
CumulativeTime by the ExecCount to get the average time it took to execute the 
statement. The ActualTime and CumulativeTime are given in seconds and the profiler 
takes its measurements with microsecond precision.

Here's some example output:
26 291 1 0.001915 0.022753
8 306 66 1.357740 1.387024
50 270 1 0.000473 0.000473

Where LineNo is 0, that refers to the time used to initialize and then later to tear down 
the procedure or trigger. This is the overhead of running the procedure, user-defined 
function, or trigger.

Where ModuleID is 0, that is referring to time associated with the profiling session. 
There should be only one Line Summary record that references ModuleID 0 and that 
record should have a LineNo of 0, an ExecCount of 1, an ActualTime of 0, and the 
CumulativeTime should reflect the total time for the profiling session. The 
CumulativeTime can be used to compute session percentages; e.g., what percentage of 
the session did Module X use.


5.	Issues
Procedure Editor and AB/UIB Temporary Files
The Procedure Editor and the AB/UIB both re-use the name of the temporary file they 
write code to in order to COMPILE and/or RUN code you are developing. Profiling 
measurements are all taken relative to the procedure name. Since the procedure name is 
re-used, if you launch your application from the Procedure Editor more than one time 
during the session, your timing data will be confusing (since you may have changed the 
code between launches of your application from the Procedure Editor).

To get around this issue, simply run your application using the p startup parameter. 
Alternatively, for the Procedure Editor, you can modify its code to use a new temporary 
file name for each launch.
Pentium Floating Point Division
Because the Win32 API supplies only an indirect way of getting elapsed time with near 
microsecond precision, we have to carry out floating point arithmetic to convert the time 
to microseconds (don't worry, this is only done during the analysis of the raw data, so it's 
not happening at runtime). If you are running on a Pentium that has the famous floating-
point division problem, your timing data may not be reliable.

To resolve this issue, set up your machine to use the software floating-point division 
instead.
6.	Known Bugs
Open Query Statement (versions 8.X only)
The number of times that the Open Query statement is executed is not accurate. 
Generally, you'll find that the number of times the Open Query statement is actually 
executed is the same number of times the statement directly above or below the Open 
Query statement. The consequence of this bug is that average executable time for these 
lines will be off.
SYSTEM-DIALOG Statement (versions 8.2A only)
The 4GL Client is supposed to turn the profiling clock off when it goes into an input 
blocking mode (WAIT-FOR, UPDATE, PAUSE, etc.), while waiting for the user to enter 
something. As soon as it begins executing 4GL code again, the 4GL Client turns the 
profiling clock back on. It uses this data to factor out time spent waiting for user input. 
However, the 4GL Client does not turn off the profiling clock when you enter a 
SYSTEM-DIALOG statement (e.g., File Open Dialog).

To work around this bug, locate what executable lines have SYSTEM-DIALOG 
statements (they'll be easy to find using the Profiling Tool because it looks like they take 
a really long time to execute). Then modify the profiler output data by setting the 
ActualTime and CumulativeTime (see section 4.4.4 above) for those lines to something 
very small (zero should work). Then re-read your profiler output data file into the 
database.

7.	Reporting Problems
If you encounter technical problems with the Core Profiling Capabilities, i.e., problems 
like those described in the Known Bugs section above, please report them by way of 
email to Profiler@Progress.com. As this is unsupported software, do not expect patches 
to the commercial product.

If you discover bugs with the Profiling Tool, you may report them to the same email 
alias, but do not expect us to fix them and re-distribute the software. We may do that, but 
there is no guarantee. You have the source for the tool. 
8.	If you need Help
If you need help, do not call Progress Technical Support! For help, please contact your 
Regional Professional Services Manager (i.e., Progress Consulting) and employ their 
services. For version 8.X of the product, this is all unsupported software. From version 
9.0B of the product, the core capabilities are supported (i.e., the PROFILER system 
handle), but the Profiler tool is unsupported software.
9.	Future Plans
We are interested in your ideas for commercializing this capability. You can send us your 
suggestions by email to Profiler@Progress.com. So that we do not get the same 
suggestions 1000 times, we thought that we should share with you what we have in mind 
so far. Some of these may be available in some future release of the product.
 
For the Core Profiling Capabilities, it would be nice to:
1)	Track and output information available from the database's Virtual System 
Tables, such as: Number of Locks per Module, Network Traffic per Module, Disk 
I/O per Module, Lock-Wait time per Module.

For the Profiling Tool itself, it would be nice to:
1)	Be able to compare profiling sessions.
2)	Configure how you want to view the data. Presently, it's mostly as a percentage of 
the session.
3)	Re-use debugger listing files (so that they don't have to be repeatedly imported).
4)	Generate a printable summary report for a given session or portion of a session.

  In this document, except when referring to running the Profiler Tool, references to 4GL Client include the 
Progress AppServer.
  A hidden file whose name is rpfXXXXXX and which resides in the T specified temporary file directory.
  In the database schema supplied, these are referred to as Sources.
  The listing file generated by the Progress debugger is an "expanded" file, that is, the include files are 
expanded. This is because include files do not usually make up an independent executable Progress 
procedure but they often have executable code.
  Excluding those procedures that are part of the ADE, as appropriate.
  This value is computed over all the sources that comprise this .r procedure. If any source changes, then 
this value is very likely to change. With this, a profiler tool can avoid reading debug listing files into its 
database in the event that the debug listing file has already been read in for another profiling session by 
comparing this value.
	Unsupported (Free) Software
4GL Performance Profiler	16	Unsupported (Free) Software
	Progress Software Corporation
4GL Performance Profiler	1	Unsupported (Free) Software
