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

An interactive interface may be added to the user's program by the following procedure:

  1. Choose one or more points in the program at which the interactive interface is to be invoked. At these points, add the statement:

CALL ADB

When this subroutine is called, the program prompts for interactive commands at the user's 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.

  1. Add a call to ADINIT in the main program. This routine initialises the interactive environment. It must be called before the first call to ADB.

CALL ADINIT

  1. Write an FSP file for the program in the usual way.

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

> fpt model.fsp fptmain:adbserve.fsp /output_directory:build

  1. 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 compiles to Fortran and a pre-compiled default command set is provided. The commands are as follows. Synonyms are provided to conform to familiar debuggers and simulation environments. Optional arguments are enclosed in square brackets, [], optionally repeated arguments in braces, {}:

Standard ACL services:

?

Context-sensitive help, as for FPT.

LOG [ON] <file> <eol>

Opens the named log file to record the interactive session.

LOG [ON] <eol>

Opens a default log file to record the session.

LOG OFF <eol>

Stops logging, but does not close the log file.

CLOSE LOG [FILE] <eol>

Stops logging and closes the log file.

DETAIL [ON] <eol>

Reports the arguments parsed by ACL (Used in debugging command scripts).

DETAIL OFF <eol>

Turns off reporting of arguments.

ECHO [ON] <eol>

Echoes the text of command files as they are executed.

ECHO OFF <eol>

Turns off command script echoing.

@ <file> <eol>

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> [ ( <integer> [ : <integer> ]

[ { ,<integer> [ : <integer> ] } ] ) ] } ] <eol>


Reports the value of one or more variables or array elements, entered as a comma separated list.

PEEK

Synonym for EXAMINE.

PRINT

Synonym for EXAMINE.

DEPOSIT <identifier> [ ( <integer> [ { , <integer> } ] ) ] [=] <value> <eol>


Sets the value of the named variable or array element.

LET

Synonym for DEPOSIT.

DATA

Synonym for DEPOSIT.

POKE

Synonym for DEPOSIT.

Format control - commands which control layout of the reports:

SET BOUNDS COLUMN [=] <integer> <eol>

SET TYPE COLUMN [=] <integer> <eol>

SET SIZE COLUMN [=] <integer> <eol>

SET VALUE COLUMN [=] <integer> <eol>

CONFIRM DEPOSIT <eol>

Reads back values deposited

CONFIRM LET <eol>

Synonym of CONFIRM DEPOSIT.

CONFIRM DATA <eol>

Synonym of CONFIRM DEPOSIT.

CONFIRM POKE <eol>

Synonym of CONFIRM DEPOSIT.

DO NOT CONFIRM DEPOSIT <eol>

Turns off read-back of values deposited

DO NOT CONFIRM LET <eol>

Synonym of DO NOT CONFIRM DEPOSIT.

DO NOT CONFIRM DATA <eol>

Synonym of DO NOT CONFIRM DEPOSIT.

DO NOT CONFIRM POKE <eol>

Synonym of DO NOT CONFIRM DEPOSIT.

Program execution control

STEP <eol>

RETURN from ADB and continue program execution until ADB is called again.

STEP <integer> <eol>

RETURN from ADB the specified number of times.

STEP <real> SECONDS <eol>

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 <eol>

Exit from the program.

QUIT <eol>

Synonym for EXIT

The Interface Library

The library of access routines resides in the directory with the logical name adbserve:, which is:

FPTMAIN:[.ADBSERVE] VMS

...\FPT\FPTxx\ADBSERVE DOS

.../fpt/fptxx/adbserve Unix


Files Generated by the Command

In response to BUILD ACCESS DATABASE, FPT adds three new files to the user's program:

model_adc.fpi INCLUDE file for new declarations

model_adb.fpt BLOCK DATA sub-program

model_ads.fpt Access sub-program for COMMON blocks.


where model is the base name of the primary input file.

The INCLUDE file model_adc.fpi contains:

  1. Declarations of Fortran parameters used to name the columns in the symbol attribute table, P_COMMON=1, P_ADDRESS=2, P_TYPE=3, P_SIZE=4 and P_DIMENSION=5.

  2. Declarations of Fortran parameters used to represent the Fortran data types: PTYERROR=-1, PTYNULL=0, PTYLOGICAL=1, PTYBIT=2, PTYINTEGER=3 etc.

  3. Resource parameters which specify:

PNCOMMONS - the number of COMMON blocks in the program;

PNSYMBOLS - the number of symbols representing objects in the COMMON blocks;

PNDIMENSIONS - the number of entries in the table which stores array dimensions;

PNAMELENGTH - the length of the character string required to store the longest symbol name in the program.

  1. Then, for each COMMON block in turn:

A Fortran parameter which represents the sequence number of the COMMON block. The parameter names are of the form C_NAME where NAME is the name of the COMMON block.

An INTEGER*1 or BYTE array which overlays the entire COMMON block. These arrays may be thought of as 'backbone' arrays. Objects in the COMMON block are accessed by accessing the appropriate bytes in the backbone. The backbone array names are of the form B_NAME.

  1. Lastly, declarations of four arrays which hold the access database information:

CHARACTER*(PNAMELENGTH) ADBSYMNAME(PNSYMBOLS)

The names of the symbols

CHARACTER*(PNAMELENGTH) ADBCOMNAME(PNCOMMONS)

The names of the COMMON blocks

INTEGER*4 ADBATTRIB(5,PNSYMBOLS)

The attributes of the symbols

INTEGER*4 ADBDIMTAB(2,PNDIMENSIONS)

The array bounds.

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:

A DATA statement for the appropriate element of ADBSYMNAME, specifying the symbol name string. The symbols are sorted in alphabetical order.

A DATA statement for the corresponding row of ADBATTRIB, specifying the symbol attributes. These are specified as the parameterised COMMON block number (using the Fortran parameters for the COMMON blocks described above), the byte address, the parameterised value for the data type, the data size of each element in bytes and a pointer into the dimension table where the array dimensions are stored. A null dimension pointer denotes a scalar object.

The dimension table entries (if any) required to describe the array dimensions of the object.

  1. 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 a pointer into ADBDIMTAB for each array. The pointer 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 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,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

Yes


Specification (FSP) files, *.fsp

Yes


Interactively, to FPT> prompt:

No


Interactive command files

No


Embedded in the Fortran code

No


Default:

The access database is not built by default.

See also:

IGNORE DEFAULT SIZES


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