Performance Profiling

Progress 4GL Applications

Last updated: January 14, 2009

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?

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.

4GL Performance Profiler

Unsupported (Free) Software

Unsupported (Free) Software

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.

2.1.1 Using 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.1.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

4GL Performance Profiler

2
Unsupported (Free) Software
Progress Software Corporation

Unsupported (Free) Software

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
procedure1, 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 deallocate 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

Excluding those procedures that are part of the ADE, as appropriate.

4GL Performance Profiler

3
Unsupported (Free) Software
Progress Software Corporation

Unsupported (Free) Software

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 applications execution trace can be established.

If the value of TRACE-FILTER is , then it matches no procedures; in this case

4GL Performance Profiler

4
Unsupported (Free) Software
Progress Software Corporation

Unsupported (Free) Software

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 entrys 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.
4GL Performance Profiler

5
Unsupported (Free) Software
Progress Software Corporation

Unsupported (Free) Software

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.

3. Using the Profiling Viewer tool

The Profiling Tool, as it is, runs on the Windows only. To use the tool simply
run the following scripts on command line:

sh>> sh runprofiler.sh
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 (its
worth the wait to import the debug listing files).
Select on whether you want to view 10.2B profiler output or prior to 10.2B output.
Then Click on the View Session button to bring up the Session Summary window..

4GL Performance Profiler

6
Unsupported (Free) Software
Progress Software Corporation

Unsupported (Free) Software

4. 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.

5. 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.

4GL Performance Profiler

7
Unsupported (Free) Software
Progress Software Corporation