fpt and WinFPT Reference Manual - Command-line Commands

| SimCon Home | Reference Manual Home |

BUILD ACCESS DATABASE

Syntax:

[DO NOT] BUILD ACCESS DATABASE

Function:

BUILD ACCESS DATABASE commands fpt to construct tables and data structures which relate the names of objects in COMMON blocks to their COMMON block addresses, data types and other attributes. The data structures support interactive access routines by which the user may examine or modify all objects in COMMON blocks, and a complete interactive and command file environment may be built automatically as described below. Access may be made from a subroutine called from the program itself, or from an external process which shares the COMMON blocks as shared memory.

The data structures may also be used to support data logging, data initialisation mechanisms, and other processes where objects must be accessed by name while the program is running.

The command BUILD ACCESS DATABASE implies IGNORE DEFAULT SIZES. This prevents unnecessary duplication of names in the database.

Building an Interactive User Interface

To add an interactive interface to an existing program:

  1. Choose one or more points in the program at which the interactive interface is to be invoked. At these points, add a call to the subroutine ADB. There are no arguments. When this subroutine is called, the program prompts for interactive commands at the user's screen or terminal (writing to Fortran logical unit number (LUN) 6, reading from LUN 5). One of the available commands is to continue execution; another is to continue until ADB has been called a specified number of times. In a simulation program, for example, a call to ADB may be inserted at the start of the simulation frame.
  2. Add a call to the subroutine ADINIT in the main program. This routine initialises the interactive environment. There are no arguments. It must be called before the first call to ADB.
  3. Write an FSP file for the program as described here.
  4. Run fpt on the program, adding the specification file fptmain:adbserve.fsp to the command line. It is convenient to direct the output files to a working directory. For example under Linux:
    $ fpt model.fsp fptmain:adbserve.fsp "%output_directory:../build"
  5. Compile and link all files generated by the fpt run. Take care to include the BLOCK DATA file model_ads.fpt (where 'model' is the program name) which is generated automatically.

Interactive Commands

The interactive environment is built using Software Validation Ltd's product ACL (Application Control Language). User's of ACL may extend and modify the command set, which is specified in the file abd.acl in the adbserve directory. The ACL script generates Fortran source code and a pre-generated default command set is provided. You do not need a copy of ACL to use this fpt command.

The pre-defined commands are shown below. Synonyms are provided to conform to familiar debuggers and simulation environments. Optional arguments are enclosed in square brackets, [], optionally repeated arguments in braces, {}: Commands are terminated by a carriage return.

Standard ACL services:

? Context-sensitive help, as for fpt.
LOG [ON] <file> Opens the named log file to record the interactive session.
LOG [ON] Opens a default log file to record the session.
LOG OFF Stops logging, but does not close the log file.
CLOSE LOG [FILE] Stops logging and closes the log file.
DETAIL [ON] Reports the arguments parsed by ACL (Used in debugging command scripts).
DETAIL OFF Turns off reporting of arguments.
ECHO [ON] Echoes the text of command files as they are executed.
ECHO OFF Turns off command script echoing.
@ <file> Invokes the named command file. Command file text is identical to the interactive commands.

Command files may be nested to a depth of 9. The default file name extension is .int.

Showing and changing values of variables

EXAMINE <identifier> [ ( <integer> [ : <integer> ] ] [{ ,( <integer> [ : <integer> ] }] ) ] [{ ,<identifier> ... }] Reports the value of one or more variables or array elements, entered as a comma separated list.
PEEK PRINT Synonyms for EXAMINE.
DEPOSIT <identifier> [ ( <integer> [ { , <integer> } ] ) ] [=] <value> Sets the value of the named variable or array element.
LET DATA POKE Synonyms for DEPOSIT.

Commands which control layout and behaviour of the reports

SET BOUNDS COLUMN [=] <integer>
SET TYPE COLUMN [=] <integer>
SET SIZE COLUMN [=] <integer>
SET VALUE COLUMN [=] <integer>
Control of the report format
CONFIRM DEPOSIT Reads back values deposited
CONFIRM LET Synonym of CONFIRM DEPOSIT.
CONFIRM DATA Synonym of CONFIRM DEPOSIT.
CONFIRM POKE Synonym of CONFIRM DEPOSIT.
DO NOT CONFIRM DEPOSIT Turns off read-back of values deposited
DO NOT CONFIRM LET Synonym of DO NOT CONFIRM DEPOSIT.
DO NOT CONFIRM DATA Synonym of DO NOT CONFIRM DEPOSIT.
DO NOT CONFIRM POKE Synonym of DO NOT CONFIRM DEPOSIT.

Program execution control

STEP Return from ADB and continue program execution until ADB is called again.
STEP <integer> Return from ADB the specified number of times.
STEP <real> SECONDS Return from ADB until the simulation time has advanced by the specified time. This command is applicable only for fixed step time-based simulations. The frame time is specified as a variable in COMMON.
EXIT Exit from the program.
QUIT Synonym for EXIT

The Interface Library

The source code for the library of access routines resides in the directory with the fpt logical name adbserve:, which, by default, is: /usr/lib/fpt/adbserve/ under Linux and Unix, C:\program files\simcon\fpt\adbserve\ under Microsoft Windows and FPTMAIN:[.ADBSERVE] under VMS.

Files Generated by the Command

The command BUILD ACCESS DATABASE adds three files to the user's program:

where model is the base name of the primary input file. The file name extensions .fpi and .fpt may be changed by the commands INCLUDE OUTPUT FILE NAME EXTENSION and PRIMARY OUTPUT FILE NAME EXTENSION.

The INCLUDE file model_adc.fpi contains:

  1. Declarations of Fortran parameters used to name the columns in the symbol attribute table.
  2. Declarations of Fortran parameters used to represent the Fortran data types.
  3. Resource parameters which specify:
  4. Then, for each COMMON block in turn:
  5. Lastly, declarations of four arrays which hold the access database information:

The BLOCK DATA file model_adb.fpt contains:

  1. An INCLUDE statement for model_adc.fpi.
  2. Then, for each symbol in a COMMON block:
  3. Then, for each COMMON block in turn, a DATA statement for the appropriate element of ADBCOMNAME, specifying the COMMON block name.

The dimension table, ADBDIMTAB(1:2,1:PNDIMENSIONS), holds the array dimension information for each array. The attribute entry for each symbol contains an index into ADBDIMTAB for each array. The index occupies the array element ADBATTRIB(n,P_DIMENSIONS), where n is the symbol sequence number. ADBDIMTAB(1,n) contains the number of array dimensions. ADBDIMTAB(2,n) contains the total number of array elements in the array. Each successive row of ADBDIMTAB then contains the upper and lower bounds of the array. Thus, for example, an object declared as:

REAL ALPHA(-3:3,1:10)

is represented by entries in ADBDIMTAB:

ADBDIMTAB(1,n) = 2 Number of dimensions
ADBDIMTAB(2,n) = 70 Total number of elements
ADBDIMTAB(1,n+1) = -3 Lower bound, dimension 1
ADBDIMTAB(2,n+1) = 3 Upper bound, dimension 1
ADBDIMTAB(1,n+2) = 1 Lower bound, dimension 2
ADBDIMTAB(2,n+2) = 10 Upper bound, dimension 2

The COMMON block access sub-program file, model_ads.fpt, contains the subroutine:

SUBROUTINE ACCESS_COMMON(ICOMMA,IADDRA, 1 ISIZEA,CHARFA,WRITEFA,NUMERICA,STRINGA)

This is the lowest level primitive used to access objects in COMMON blocks within the user's program. It is necessarily constructed separately for every program because it references the backbone arrays in the program-specific COMMON blocks. The arguments are:

ICOMMA - the integer sequence number assigned to the COMMON block;

IADDRA - the byte address at which the required object starts;

ISIZEA - the number of bytes to be copied;

CHARFA - LOGICAL, true if the data is character, false if numeric;

WRITEFA - LOGICAL, true if data is written to the object, false if read;

NUMERICA(*) - INTEGER*1 array containing the data if it is numeric;

STRINGA - CHARACTER*(*) variable containing the data if it is character.

The subroutine transfers ISIZEA bytes of data between either the INTEGER*1 array NUMERICA or the CHARACTER*(*) string STRINGA and the target COMMON block. The data is transferred at the COMMON block address ADDRESSA. Transfer of character or numeric data is specified by the LOGICAL argument CHARFA, and the direction of transfer is specified by the LOGICAL argument WRITEFA.

The subroutine begins with an INCLUDE statement for model_adc.fpi. The executable code consists of a CASE statement, implemented as a computed GOTO, in which the CASE selector is the COMMON block index, ICOMMA. Each CASE clause consists of code to transfer the appropriate number of bytes at the specified address between the numeric or character arguments and the COMMON block. The structure of the code is shown below:

1010 CONTINUE IF (CHARFA) THEN IF (WRITEFA) THEN DO I=1,ISIZEA B_COMMON(IADDRA+I-1)=ICHAR(STRINGA(I:I)) ENDDO ELSE DO I=1,ISIZEA STRINGA(I:I)=CHAR(B_COMMON(IADDRA+I-1)) ENDDO ENDIF ELSE IF (WRITEFA) THEN DO I=1,ISIZEA B_COMMON(IADDRA+I-1)=NUMERICA(I) ENDDO ELSE DO I=1,ISIZEA NUMERICA(I)=B_COMMON(IADDRA+I-1) ENDDO ENDIF ENDIF GOTO 8000

The label 8000 is the CASE collector and is followed by the RETURN statement. The backbone array shown here is B_COMMON. Note that character and numeric data are handled separately because they may not be mixed in the same COMMON block in some Fortran implementations.

The COMMON block access mechanism is supported by a library of subroutines which reside in the sub-directory adbserve below the main fpt directory. The steps in transferring data to or from a variable in a COMMON block are:

  1. The user's command (from command line or command file) is parsed and the name of the object is identified (subroutine ACPARS etc. in the adbserve library);
  2. The name is sought in the array ADBSYMNAME and the sequence number of the symbol is found (subroutine ADBSYM);
  3. The symbol address is found in the array ADBATTRIB. The array indices are decoded and the size and array dimensions from ADBATTRIB and ADBDIMTAB are used to compute the target address of the bytes to be accessed;
  4. The COMMON block number is found in the array ADBATTRIB.
  5. ACCESS_COMMON, the subroutine written automatically in model_ads.fpt, is called with the COMMON block number, the address and the appropriate access flags to transfer the data.

Fortran Logical Unit Numbers

ACL reads from unit 5 and writes to unit 6. Log files are opened on LUN 7 and Interactive command files are opened on LUN 8 to 19. Please take care that these LUNs are not used in the program code.

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

The access database is not built by default.

See Also:

IGNORE DEFAULT SIZES

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