fpt and WinFPT Reference Manual - Command-line Commands

| SimCon Home | Ref Manual Home |





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:

  1. Write a specification (fsp) file for the program in the usual way.
  2. 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).
  3. Identify volatile variables or COMMON blocks which also form interfaces with external programs.
  4. 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.

  1. 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.
  2. 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


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

See Also




Copyright ©1995 to 2024 Software Validation Ltd. All rights reserved.