fpt and WinFPT Reference Manual - Command-line Commands

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

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

Showing and changing values of variables

Commands which control layout and behaviour of the reports

Program execution control

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:

• model_adc.fpi an INCLUDE file for new declarations;
• model_adb.fpt a BLOCK DATA sub-program which contains the descriptions of the variables;
• model_ads.fpt the subroutines which reads and writes data in the program COMMON blocks;

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:
   • 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.
4. 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.
5. 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.
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:

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

Default

The access database is not built by default.

See Also:

IGNORE DEFAULT SIZES

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