fpt and WinFPT Reference Manual - Command-line Commands
| SimCon Home | Ref Manual Home |
INSERT RECORD/REPLAY (Hamlet)
[DO NOT] INSERT [ IO ] RECORD [ / ] REPLAY [DO NOT] INSERT [ IO ] RECORD AND REPLAY
The record/replay (Hamlet) facility is used:
Modifications to the Code
All input and output statements, and all call sites of subroutines and functions which have been declared to be external interfaces, are modified:
The data are captured to ASCII files. Data capture, and replay of captured data, are controlled at run-time. Replay may be selected separately for each logical unit number and for each external interface routine. For example, the statements:
READ(7,300) a(i),i=1,3 300 FORMAT (3F12.3)
are modified to become:
IF (replay_io(221,7)) THEN READ (rr_lun_for_replay,300)a(i),i=1,3 ELSE READ (7,300)a(i),i=1,3 ENDIF IF (rr_input_record_f) THEN WRITE (rr_lun_to_record_input,300)a(i),i=1,3 ENDIF 300 FORMAT (3F12.3)
In this code:
Similarly, a call to an interface routine:
is modified to:
IF (replay_interface(227,'get_name_wt')) THEN READ (rr_lun_for_replay,*)get_name_wt_val,rval READ (rr_lun_for_replay,'(A)')namestr ELSE get_name_wt_val=get_name_val(irec,namestr,rval) ENDIF istatus=get_name_wt_val IF (rr_input_record_f) THEN WRITE (rr_lun_to_record_input,*)get_name_wt_val,rval WRITE (rr_lun_to_record_input,'(a)')namestr ENDIF IF (rr_output_record_f) THEN WRITE (rr_lun_to_record_output,*)irec ENDIF
In this example, get_name_wt has been declared to be an interface routine. It is an integer function which returns a status. In the modified code:
The control variables rr_input_record_f, rr_output_record_f, rr_lun_for_replay, rr_lun_to_record_input etc. are declared in the INCLUDE file rr_cmn.fpi. INCLUDE statements for this file are automatically inserted into the code wherever the variables are needed. rr_cmn.fpi also contains declarations of the logical functions replay_io and replay_interface.
The control variables are initialised by the subroutine record_replay_init. A call to record_replay_init is automatically inserted as the first executable statement of every main program processed by fpt.
Instrumenting a Program for Record/Replay (Hamlet)
Instrument a program for record/replay as follows:
To specify that a sub-program or variable
is an interface:
%record/replay interface :: <name>
To specify a name in a sub-program:
%record / replay interface :: <sub_program>%<name>
To specify a name in a COMMON block:
%record / replay interface :: /<common>/<name>
To specify an entire COMMON block:
%record / replay interface :: /<common>/
To specify a foreign data type:
%bit pattern :: <name>
%record/replay interface :: <name>
The RECORD/REPLAY INTERFACE comands may, and the BIT PATTERN commands must be embedded in the code within the scope of declaration of the variable or sub-program. If the commands are written in the fsp files, take care that the names are unique.
The command inserts an INCLUDE statement for the INCLUDE file rr_cmn.fpi in all sub-programs which call record/replay interfaces or contain I/O statements. This file is generated automatically by fpt.
Running the Instrumented Code
The subroutine record_replay_init reads a control file from the current default directory. This file specifies whether data is to be recorded or replayed, the names of the record and replay data files, and which logical unit numbers and sub-program interfaces are to be replayed. The control file has the same base name as the main program and the file name extension .rrc (record/replay control). Under Linux and Unix the extension is written in lower case.
The control file is written in ASCII text. Specifications are written one to a line. Comments are introduced by exclamation marks. The commands are not case sensitive. White space must separate keywords from operands and may not occur within file names, but is not otherwise significant. Do not replace spaces in the keywords with underscores.
The commands are:
REPLAY_FILE <file_name> Specifies the file to be replayed. If no file is specified, data are not replayed.
INPUT_RECORD_FILE <file_name> Specifies the file for recording input. If no file is specified, input is not recorded.
OUTPUT_RECORD_FILE <file_name> Specifies the file for recording output. If no file is specified, output is not recorded.
LUN_FOR_REPLAY <integer> Specifies the Fortran unit number which the service routines will use for the replay file. This must not be used by the original program. By default it is 88.
LUN_FOR_INPUT_RECORD <integer> Specifies the unit number for recording the input. This must not be used by the original program. By default this is 87.
LUN_FOR_OUTPUT_RECORD <integer> Specifies the unit number for recording output. Again, this must not be used by the original program. By default this is 86.
REPLAY_LUN ALL Specifies that all logical units are to be replayed.
REPLAY_LUN <integer> Specifies that a unit is to be replayed. This command may be repeated.
REPLAY_INTERFACE ALL Specifies that data from all instrumented interface routines are to be replayed.
REPLAY_INTERFACE <sub-program_name> Specifies that data from the named interface routine are to be replayed. This command may be repeated.
NUMBER_OF_RECORDS <integer> Specifies a maximum number of records to be recorded or replayed. If this is not specified, record / replay continues until program termination.
When the instrumented program is run, the control (.rrc) file input is echoed to a diagnostic file with the same base name and the file name extension .rrd. The diagnostic file also receives diagnostics when a command is not recognised, when replay data are read out of sequence, and when the total number of records for record or replay is successfully reached.
If a maximum number of records is specified and is reached, the behaviour of the program depends on whether or not data is replayed. If data is being replayed, a message is written to the diagnostic file and the program terminates with CALL EXIT. If data are being recorded, a message is written to the diagnostic file, recording is terminated, but program execution continues.
A sample Template File
The following is a sample template used to specify the data type, protocol and intent (i.e. whether input or output) and the data types of sub-program arguments. It is taken from vms.ftm.
INTEGER*4 FUNCTION SYS$READEF ( I4_01, I4_02 ) IMPLICIT NONE INTEGER*4 I4_01 !% INTENT (IN) :: I4_01 !% VALUE :: I4_01 INTEGER*4 I4_02 !% INTENT (OUT) :: I4_02 !% REFERENCE :: I4_02 END
Where to Use this Command
|Operating system command line||No|
|Configuration file, config.fsp||No|
|Specification (fsp) files, *.fsp||Yes|
|Interactively, to FPT> prompt||No|
|Interactive command files||No|
|Embedded in the Fortran code||No|
Record/replay is not inserted by default.
A note: 'Hamlet'
The record / replay mechanism under fpt was first used in a study of a video store inventory program. The code was tested by searching for versions of Hamlet, and the data files were therefore named hamlet1.irc, hamlet2.irc etc. They were nick-named Hamlet files, and the record-replay system became 'Hamlet'.
RECORD REPLAY INTERFACE
SHOW UNRESOLVED REFERENCES
Copyright ©1995 to 2021 Software Validation Ltd. All rights reserved.