Consultor Eletrônico

Status: Verified

GOAL:

Documentation for the Profiler Object in Progress 9.x

GOAL:

Documentation for the Profiler Object in OpenEdge 10.x

GOAL:

What is the Progress Profiler?

GOAL:

Profiler

FACT(s) (Environment):

Progress 9.X
OpenEdge 10.0x
All Supported Operating Systems

FIX:

The Profiler object can be used to control 4GL program execution profiling, data recording, and analysis.

A more complete description of the Profiler tool can be found in the %DLC%\src\samples\profiler\readme.doc directory for Progress 9.x and OpenEdge 10 till version OpenEdge 10.0B.
From OpenEdge 10.1A you can download the documentation from the www.psdn.com Website. The tool is located here: http://communities.progress.com/pcom/docs/DOC-2808
There are command line startup parameters that can be used to set the
initial values of the attributes. The following lists and describes the Profiler object attributes:

- COVERAGE
Read/Write
Logical
Initial value is No

The value of this attribute determines whether or not the Profiler records information that can be used for coverage analysis.

When set to True, the Profiler records statement and internal procedure coverage information for each external .p procedure that is executed. This information is included in the output file that is written when the Profiler analyses all of the recorded data.

The information recorded for the PROFILER:COVERAGE attribute identifies the statements that could have been executed for any given procedure. These, combined with the timing data that tells what statements were actually executed, can be used to perform 4GL application code coverage analysis. For example, you can
determine that when the application was tested, only 30% of its code was executed.

The profiler records the information for coverage analysis only the first time an external .p procedure is executed. If the PROFILER:COVERAGE attribute is False the first time a procedure is executed, coverage analysis information is not registered, even if it is set to True at a later time.

- DESCRIPTION
Read/Write
Character.
Initial value is "Unspecified"

The value of this attribute is a character description of the current profiling session. This string is included as part of the data that is written to the profile output file.

- DIRECTORY
Read/Write
Character.
Initial value is either the -T directory or the current working directory if -T was not specified.

The value of the DIRECTORY attribute specifies the name of the file system directory into which automatically-generated profiler debug listing files should be written.

The attribute cannot be set to the Unknown value, and does not permit itself to be set to an invalid directory.

- ENABLED
Read/Write
Logical.
Initial value is False

The value of this attribute determines whether or not the Profiler is enabled. The True setting activates and initializes the Profiler.

When the profiling process is first enabled, Progress registers all currently active procedures and assigns module identifiers to them. An active procedure is any persistent procedure or any procedure on the Progress procedure call stack.

For each active procedure, except those that are part of the ADE, a PROFILER:LISTINGS setting of True also generates listing files. In addition, a True setting records coverage analysis information.

If you want listing files or coverage analysis information to be generated, you must set PROFILER:LISTINGS or PROFILER:COVERAGE attributes to True before you set PROFILER:ENABLED to True.

As long as profiling is enabled, Progress maintains a registry of the procedures that have executed, regardless of whether profiling is turned on or off (controlled by the setting of the PROFILER:PROFILING attribute).

When profiling is disabled (by setting PROFILER:ENABLED to False) Progress writes accumulated profiling data to the profiler output file and then discards the registry of procedures that have been executed.

- FILE-NAME
Read/Write
Character.
Initial val.ue is "profile.out"

The value of this attribute specifies the name of the output file into which the profiling output data should be written after the raw recorded data has been analyzed.

This attribute cannot be set to the Unknown value.


- LISTINGS
Read/Write
Logical
Initial value is False

The value of this attribute determines whether or not the profiler should try to automatically generate debug listing files for the 4GL code that is being profiled.

The profiler generates a debug listing file the first time that a procedure is executed. Therefore, if PROFILER:LISTINGS is False the first time a procedure is executed, setting it to True at a later time does 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 the module executes, and the profiler only generates debug listing files for modules that are external procedures. If PROFILER:LISTINGS is False when a procedure first executes, the profiler never tries to generate a debug listing file for that procedure.

The profiler can only try to generate debug listing files. It fails if the source files are not accessible. The source files that comprise a procedure must be in the PROPATH in order for the profiler to generate a debug listing file. If the profiler cannot generate a debug listing file for a given procedure, it treats the procedure as though the PROFILER:LISTINGS setting was False when that procedure first executes.

The only way to get a Progress session to try again to generate 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 discard its profiler registry of procedures) and then set it to True again.

- PROFILING
Read/Write
Logical
Initial value is False

The value of this attribute determines whether or not the Profiler should record data during application execution.

A change to the value of this attribute turns profiling data recording on or off. The settings of the attributes that control what data is to be recorded and the data that has been recorded, are unaffected when profiling is turned off. Data recording resumes when you turn it on again.

- TRACE-FILTER
Read/Write
Character
Initial value is "".

The value of this attribute is a comma-separated list of string matching patterns that specify the names of procedures for which the Profiler should record detailed timing information.

The expression patterns are interpreted in the same way as does the 4GL built-in MATCHES() function. If a procedure name matches one of the patterns on the list, the Profiler records detailed timing information for every executable line in that procedure.

In addition to recording summary timing data for each executable line, it records timing information each time a statement is executed. With this detailed information, you can establish a complete execution trace for the application.

If the value of TRACE-FILTER is "" (an empty string), the pattern matches no procedure names. When no procedure names are matched, the only tracing information the Profiler records is that which is specified by the PROFILER:TRACING attribute (see below).

If the value is "*", the pattern matches all procedure names.

The pattern matching for TRACE-FILTER is case insensitive.

Some examples:

To get tracing information for all enable_UI procedures, set TRACE-FILTER to "enable_UI *".

To get tracing information for all enable_UI procedures and also all executable lines in the procedure hello.p, set TRACE-FILTER to "enable_UI *,*hello.p".

The TRACE-FILTER patterns are examined by the Profiler only as it analyzes the data in the raw data temporary file in preparation for writing data to the output file. This usually occu.rs during PROFILER:WRITE-DATA() calls or at the end of the session.

In theory, the TRACE-FILTER value can be set any time before the Profiler writes the data for the session to its output file. However, when the raw data temporary file becomes too large, the Profiler does a partial analysis on the fly. Therefore, you should set the TRACE-FILTER pattern before any procedure intended
to match the pattern is run.

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


- TRACING
Read/Write
Character
Initial value is "".

The value of this attribute is a comma-separated list of procedure names and listing line numbers for specific 4GL statements that you want the Profiler to record detailed timing information for.

Each 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. The list elements are
separated by commas.

If TRACING is set to "" (the empty string), the only tracing
information that is recorded is what is specified by the
PROFILER:TRACE-FILTER attribute.

The TRACING list is examined by the Profiler only as it is
analyzing the data in the raw data temporary file in preparation
for writing data to the output file. This examination usually
occurs during PROFILER:WRITE-DATA() calls or at the end of the
session.

In theory, the TRACING value can be set any time before the
Profiler writes the data for the session to its output file.
However, when the raw data temporary file becomes too large, the
Profiler does a partial analysis on the fly. Therefore, you
should set the TRACING list before any the statements you want to
trace are executed.

Redundant entries in the PROFILER:TRACING are automatically
removed.

The following lists Profiler methods and their descriptions:

- USER-DATA (val AS Char)
Return value: Logical

This method allows an application to write its own information to
a special section at the end of the profile output file. The data
to be written is specified by the parameter value you pass in the
method call.

If successful, USER-DATA() returns True. It returns False if it
fails to write the data. A failure can occur only if the Profiler
is unable to open a temporary file.

If value (val) is Unknown, then a question mark (?) is written,
otherwise val is enclosed in quotes (any embedded quotes,
quoted). This is the standard format Progress uses for exported
data.

In addition to the string value, the Profiler writes an integer
value that represents the number of microseconds that have
elapsed since the start of the profiling process.

- WRITE-DATA()
Return value: Logical

This method instructs the profiler to analyze the data that has
been recorded and to write the current information to the profile
output file.

If the write is successful, the Profiler returns True. It returns
False if it fails to write the data. A failure to write data
could mean either there is no new data or that the Profiler could
not open the specified output file.

Time spent analyzing and writing the profiling data is deducted
from any future data profiling..