nag_history produces a listing of cumulative execution frequencies from the history_file generated by running the instrumented program created by nag_profile. History_file is the filename specified to the -history option of nag_profile command.
A table showing execution frequencies will be produced each time the instrumented program is run, by default this is written to stdout, or optionally to the selected file. This table also lists separately segments that are not executed.
If the -history option is selected the first run of the instrumented program causes a data file containing segment execution frequencies to be created. Subsequent runs cause this file to be updated. This data file may be listed using the nag_history command to produce a table in exactly the same format as the single-run table.
Routine Entry.
This is the first segment of a routine, and counts all entries to the routine,
including those via ENTRY points.
ENTRY Statements.
The first executable statement following an ENTRY statement will start a
segment.
Labelled Statement.
A labelled executable statement will begin a segment unless it is the
termination statement of a DO-loop.
Computed GOTO.
A computed GOTO will have as many segments as it has branches.
The fall-through "branch" of a computed GOTO will not have a specific segment.
Following a computed GOTO.
The statement following a computed GOTO will start a segment.
Following DO statement.
The statement following a DO statement will start a segment.
End of DO loop.
The end of a DO loop will only be segmented if additional segments have
been formed inside the DO loop.
Following End of DO loop.
The statement after the end of a DO loop will start a segment.
Following CALL Statement.
The statement following a CALL which has alternate return arguments will start
a segment.
Following Input/Output Statements.
A statement following an i/o statement which has an END= or ERR= control-list
item will start a segment.
Block IF.
The statements following IF(...)THEN, ELSEIF(...)THEN, ELSE and ENDIF statements
will start a segment.
The ELSEIF statement will itself form a segment.
Simple logical IF Statements.
A logical IF which ends with a "simple" consequence (not an arithmetic IF or
a computed GOTO) will form a segment for the .TRUE. consequence, and a segment
for the "test" portion as well if the IF is labelled or is the first statement
in a segment.
However, if the IF is the terminal statement of a DO-loop, the "test" will
only form a segment if additional in-loop segmentation has been formed.
Arithmetic IF.
An arithmetic IF will form a segment for each branch, and a segment for the
"test" as well if the IF is labelled or is the first statement in a segment.
Logical IF with Arithmetic IF consequence.
A logical IF with an arithmetic IF will form a segment for each branch of the
arithmetic IF, and for the "test" case of the logical IF as in the cases above.
The test portion for the arithmetic IF will not form a segment as the
information may be derived by adding the three branch segments' data.
Logical IF with computed GOTO consequence.
All branches of the GOTO will form segments.
A segment for the test portion of the IF will be formed according to the simple
IF rules.
Following Logical IF.
The statement following a logical IF statement will start a segment.
STOP Statement.
The STOP statement will be changed into a call to the instrumentation wrapup
routine, which itself will terminate program execution.
END Statement.
An END statement which is labelled will form a segment.
An assertion is a special comment in the input program which contains a logical expression. This expression is inserted by the tool in an IF statement that is inserted, in the same place as the comment, in the instrumented program. The number of times each assertion is not true is counted and reported in the tables produced by both a single run and the history report.
An assertion comment starts with an asterisk and is followed by "$as$". A
logical expression inside parentheses follows. For example:
*$as$ (I.GE.1 .AND. I.LE.10)
An assertion may be continued on successive lines, and will be terminated by
a closing parenthesis.
Thus,
*$as$ ((I.NE.0) .OR.
*$as$ FOUND)
is a two-line assertion, while
*$as$ (I.NE.0)
*$as$ (FOUND)
are two separate assertions.
Note that since assertions are translated by the instrumentor into statements to perform the run-time checks, they must appear only in places where executable statements may legally appear (and not between continuation lines for another statement for example).
nag_profile may be used to instrument only a part of the user's program. This part must consist of complete subprograms (i.e. you cannot instrument only part of a subprogram).
To partially instrument a program, simply split it into two or more files, one of which contains exactly those routines which require instrumentation. This file should then be processed in the usual manner by nag_profile to produce the instrumented version of those routines.
If the part of the program which is being instrumented does not include any STOP statements or the main program unit, nag_profile will issue a warning saying that the user must insert calls to the "wrapup" subroutine at program termination points. This subroutine has no parameters, and its name is 'RZZ4QX'. The wrapup routine terminates with a STOP statement itself, so the user simply replaces "STOP" with, for example, "CALL RZZ4QX". This must be done to all program termination points, even if nag_profile doesn't produce its warning (i.e. because it found at least one termination point) if the instrumentation is to function correctly.
The nag_profile generates a number of file names which are detailed here. The name of these files is derived from the base file name. This may be specified using the -base option. By default it is the first file argument name with the file extension removed, e.g. if the file is called abcd.f the base name is abcd.
File Description
basename_ano.f The "annotated" listing of the input
source file(s), showing segment
numbers and any assertion comments.
basename_pro.f The output instrumented source code.
basename_pro.o The result of compilation of
basename_pro.f. This file will not
be produced if -nocompile is
specified.
basename_pro.exe The executable program. This file
will not be produced if
-nocompile is specified.
basename_seg.map The segment map produced by
nag_profile. This file is
essential for the nag_history
report generator.
nag_profile was developed from parts of the public domain Fortran 77 Analyser developed for the US National Bureau of Standards.
Copyright, Numerical Algorithms Group, Oxford, 1991-2001