fpt Reference: INSERT RECORD/REPLAY

fpt and WinFPT Reference Manual - Command-line Commands

| SimCon Home | Ref Manual Home |

INSERT RECORD/REPLAY (Hamlet)

Syntax:

[DO NOT] INSERT [ IO ] RECORD [ / ] REPLAY [DO NOT] INSERT [ IO ] RECORD AND REPLAY

Function:

The record/replay (Hamlet) facility is used:

To construct repeatable test cases for programs with complex terminal or file I/O, or for programs with external hardware interfaces;
To build test environments for programs which are migrated from one host system to another, so as to separate issues of data file format and inter-process communication from the performance of the code;
To build separate test frames for programs which interact through messaging systems, so that each program may be tested independently.

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:

to capture the data flowing into or out of the program;
to replay the inputs from data captured in a previous run.

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:

replay_io is a logical function which returns .TRUE. or .FALSE. to indicate whether the logical unit concerned is to be replayed or not. The arguments to replay_io are a sequence number for the I/O statement and the logical unit number. The sequence number is used to check that the data are replayed in the correct order;
rr_input_record_f is a logical variable in COMMON which determines whether input data are to be recorded;
rr_lun_for_replay and rr_lun_to_record_input are integer variables in COMMON which specify the unit numbers to be used for the record-replay mechanism.

Similarly, a call to an interface routine:

istatus=get_name_wt(irec,namestr,rval)

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:

replay_interface is a logical function which is similar to replay_io in he first example. It returns a .TRUE. or .FALSE. value to indicate whether the data for get_name_wt are to be replayed from a previously captured file. The arguments are a sequence number which is used to check that the statements are read in the right order, and the name of the interface routine.
When replay_interface returns .TRUE., the data from get_name_wt are read from file. A new variable, get_name_wt_val, is used to receive the function return value. The arguments namestr and rval are output by get_name_wt and are therefore inputs to the program. These are also read in. When replay_interface returns .FALSE., the original function is called, but the return value is placed in the new variable get_name_wt_val.
The status return, istatus, is then assigned.
rr_input_record_f is a logical variable in COMMON which determines whether input data are to be recorded. If it is set, the three inputs to the program are written to file.
rr_output_record_f is a logical variable in COMMON which specifies whether or not the program outputs are recorded. The first argument to get_name_wt, irec, is an input to the function and is therefore an output from the program. This value is captured when rr_output_record_f is set.

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:

Write a specification (fsp) file for the program in the usual way.
Identify the interface routines (if any) for which data are to be captured and replayed (The SHOW SUB-PROGRAMS or, in the case of system calls, the SHOW UNRESOLVED REFERENCES commands may be useful in this step).
Identify volatile variables or COMMON blocks which also form interfaces with external programs.
Add specifications to the fsp file, or to the code, for the interface routines, COMMON blocks and variables.

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.

If the interface routines are not processed by fpt, for example, if they are external device handlers or routines written in C or another language, write templates (ftm files) for the interface routines. The Hamlet mechanism needs to know the data types of the arguments to the routines, and whether they are input, output or both. Templates are written in files with the extension .ftm
An example is shown below. The file FPTMAIN:ftm/vms.ftm contains templates for most VMS system routines. Add references to the templates into the fsp file.
Add a reference to the fsp file FPTMAIN:rec_rep.fsp at the end of the fsp file for the program. This file contains the command %insert record/replay, and references to the fpt library files which control the recording and replaying process.

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

Default

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'.