FPT and WinFPT Reference Manual - Command-line Commands

| SimCon Home | Reference 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:

Modifications to the Code

The command INSERT RECORD / REPLAY modifies the code as follows:

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:

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:

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, variable or COMMON block is an interface:

    %record / replay interface :: <name> Where the name is unique
    %record / replay interface :: <sub-program>\<name> To specify a name in a sub-program
    %record / replay interface :: /<common>/<name> To specify a name in a COMMON block
    %record / replay interface :: /<common>/ To specify a volatile COMMON block
    %bit pattern :: <name> To specify a foreign data type

    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.

  5. 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/vax.ftm contains templates for most VMS system routines (FPTMAIN is a logical name always recognised by FPT, even under Unix, Linux or Windows). Add references to the templates into the fsp file.

  6. For FPT version 3.2-m and later, 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.

    For versions of FPT before 3.2-m, process the program with FPT, with the command:

    %insert record / replay

The instrumented code 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.

Calls are added to the code for the functions replay_io and replay_interface. These are distributed in the file rep_io.for. A call to the subroutine record_replay_init is added at the start of the main program. This is distributed in the file rr_init.for. These files reside in the sub-directory rec_rep (FPT 3.2-l and earlier) or rr_lib (FPT 3.2-m and later) of the main FPT directory. For versions of FPT earlier than FPT 3.2-m, copy these file to the build directory and build the program. In FPT 3.2-m and later a specification script, FPTMAIN:rec_rep.fsp, is provided which adds the required library routines to the FPT output. Add a reference to this FSP file at the end of the FSP file for the FPT project.

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 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 is 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 a unit is to be replayed. This command may be repeated.

REPLAY_INTERFACE ALL Specifies that data from all instrumented interface routine 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 vax.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

Yes


Configuration file, config.fsp

No


Specification (FSP) files, *.fsp

Yes


Interactively, to FPT> prompt:

Yes


Interactive command files

Yes


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

See also:

RECORD REPLAY INTERFACE

SHOW SUB-PROGRAMS

SHOW UNRESOLVED REFERENCES


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