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.