USING 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 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 s
et 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.