DEFINITION MODULE FileInfos;
(*******************************************************************
Module FileInfos (Version 1.0)
Copyright (c) 2006 by Dimitrios Gyalistras and ETH Zurich.
Purpose Handle information on format and content of
files containing numerical data for any number
of variables (e.g., simulation results).
Remarks The following types of information are supported:
- file format ('matrix', 'lola', 'other')
- file contents (unspecified data,
various statistics, histograms)
- basic file attributes (an address,
a long integer)
- any number of variables per file
- basic variable attributes (a pointer
to address the variable's data, a
procedure to be associated with the
variable, an address, a long integer).
This module further provides procedures for
defining 'FileInfo' objects from data frames
based on a formally defined syntax.
Programming
o Design
Dimitrios Gyalistras 25/01/2006
o Implementation
Dimitrios Gyalistras 25/01/2006
ETH Zurich
Systems Ecology
CHN E 35.1
Universitaetstrasse 16
8092 Zurich
SWITZERLAND
URLs:
<mailto:RAMSES@env.ethz.ch>
<http://www.sysecol.ethz.ch>
<http://www.sysecol.ethz.ch/SimSoftware/RAMSES>
Last revision of definition: 22/06/2006 DG
*******************************************************************)
FROM SYSTEM IMPORT ADDRESS;
IMPORT Errors;
CONST
allOk = Errors.allOk;
notDone = Errors.onlyAnInsert;
(*
The procedures exported below return resCode = allOk if the call
to the procedure was succesfull, and resCode = notDone if not.
*)
(**************************************)
(*##### General declarations #####*)
(**************************************)
TYPE
FileInfo;
FileVar;
TYPE
DataPtr = ADDRESS;
FIObjAdrAttr = ADDRESS;
TYPE
FileFormatType = ( undefFileFormat, mat1, mat2, lola, other );
StatisticsType = ( undefStatistic,
n, mean, sd, skw,
min, p05, p10, p25, med, p75, p90, p95, max );
StatisticsSet = SET OF StatisticsType;
VAR
undefFileInfo : FileInfo; (* read only *)
undefFileVar : FileVar; (* read only *)
undefDataPtr : DataPtr; (* read only *)
undefFIObjAdrAttr : FIObjAdrAttr; (* read only *)
TYPE
FileVarP = PROCEDURE ( FileInfo, FileVar );
(******************************************)
(*##### Testing of object access #####*)
(******************************************)
PROCEDURE ActivateFileInfosObjChecks;
(*
Call this procedure to switch on all checks when
accessing FileInfo or FileVar objects or their attributes
using one of the procedurs below.
*)
PROCEDURE DeactivateFileInfosObjChecks;
(*
Switch off all checks. Use this procedure for faster
access to FileInfo or FileVar objects and their attributes.
Note, passing of dangling or NIL pointers to some of the
procedures below may cause the program to crash.
*)
PROCEDURE FileInfosObjChecksActivated(): BOOLEAN;
(*
Find out whether object checks are currently activated.
The default setting is "TRUE".
*)
(**************************)
(*##### FileInfos #####*)
(**************************)
PROCEDURE DeclareFileInfo( VAR f : FileInfo;
ident : ARRAY OF CHAR;
fmt : FileFormatType;
(* matrix code if fmt = mat1 or mat2 *)
matCode : LONGINT;
(* parameters for possible statistical output *)
stats : StatisticsSet;
(* parameters for possible histogram output *)
minFirstClass : REAL;
maxLastClass : REAL;
numClasses : INTEGER;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE FindFileInfo( ident: ARRAY OF CHAR ): FileInfo;
PROCEDURE FileInfoExists( f: FileInfo ): BOOLEAN;
PROCEDURE FirstFileInfo(): FileInfo;
PROCEDURE NextFileInfo( f: FileInfo ): FileInfo;
PROCEDURE PrevFileInfo( f: FileInfo ): FileInfo;
PROCEDURE LastFileInfo(): FileInfo;
PROCEDURE RemoveFileInfo( VAR f: FileInfo );
PROCEDURE RemoveAllFileInfos;
(************************************)
(*##### FileInfo attributes #####*)
(************************************)
PROCEDURE SetFileInfoIdent( f : FileInfo;
ident : ARRAY OF CHAR;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE GetFileInfoIdent( f : FileInfo;
VAR ident : ARRAY OF CHAR );
PROCEDURE SetFileInfoFormatType( f: FileInfo; fmt: FileFormatType );
PROCEDURE FileInfoFormatType( f: FileInfo ): FileFormatType;
PROCEDURE SetFileInfoMatrixCode( f: FileInfo; matCode: LONGINT );
PROCEDURE FileInfoMatrixCode( f: FileInfo ): LONGINT;
PROCEDURE SetFileInfoStatisticsSet( f: FileInfo;
stats: StatisticsSet );
PROCEDURE GetFileInfoStatisticsSet( f: FileInfo;
VAR stats: StatisticsSet );
PROCEDURE SetFileInfoHistoParams( f: FileInfo;
minFirstClass : REAL;
maxLastClass : REAL;
numClasses : INTEGER );
PROCEDURE GetFileInfoHistoParams( f: FileInfo;
VAR minFirstClass : REAL;
VAR maxLastClass : REAL;
VAR numClasses : INTEGER );
PROCEDURE SetFileInfoAdrAttr( f: FileInfo; a: FIObjAdrAttr );
PROCEDURE FileInfoAdrAttr( f: FileInfo): FIObjAdrAttr;
PROCEDURE SetFileInfoLongIntAttr( f: FileInfo; l: LONGINT );
PROCEDURE FileInfoLongIntAttr( f: FileInfo ): LONGINT;
(*************************)
(*##### FileVars #####*)
(*************************)
PROCEDURE DeclareFileVar( f : FileInfo;
VAR v : FileVar;
ident : ARRAY OF CHAR;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE FindFileVar ( f: FileInfo; ident: ARRAY OF CHAR ): FileVar;
PROCEDURE ParentFileInfo( v: FileVar ): FileInfo;
PROCEDURE FileVarExists ( v: FileVar ): BOOLEAN;
PROCEDURE FirstFileVar( f: FileInfo ): FileVar;
PROCEDURE NextFileVar( v: FileVar ): FileVar;
PROCEDURE PrevFileVar( v: FileVar ): FileVar;
PROCEDURE LastFileVar( f: FileInfo ): FileVar;
PROCEDURE RemoveFileVar( v: FileVar );
PROCEDURE RemoveAllFileVars( f: FileInfo );
(***********************************)
(*##### FileVar attributes #####*)
(***********************************)
PROCEDURE SetFileVarIdent( v : FileVar;
ident : ARRAY OF CHAR;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE GetFileVarIdent( v : FileVar;
VAR ident : ARRAY OF CHAR );
PROCEDURE SetFileVarDataPtr( v: FileVar; d: DataPtr );
PROCEDURE FileVarDataPtr( v: FileVar ): DataPtr;
PROCEDURE SetFileVarProc( v: FileVar; p: FileVarP );
PROCEDURE GetFileVarProc( v: FileVar; VAR p: FileVarP );
PROCEDURE SetFileVarAdrAttr( v: FileVar; a: FIObjAdrAttr );
PROCEDURE FileVarAdrAttr( v: FileVar): FIObjAdrAttr;
PROCEDURE SetFileVarLongIntAttr( v: FileVar; l: LONGINT );
PROCEDURE FileVarLongIntAttr( v: FileVar): LONGINT;
(***********************************************************)
(*##### Operations on FileVars across all FileInfos #####*)
(***********************************************************)
PROCEDURE GetFileVarsStatisticsSet( varsIdent: ARRAY OF CHAR; VAR stats: StatisticsSet );
(*
Determines the union set of the requested statistics for all
FileVar objects with a given ident across all FileInfos.
*)
PROCEDURE NumFileVarsWithIdent( varsIdent: ARRAY OF CHAR ): INTEGER;
(*
Determines the total number of FileVar objects with a given ident
across all FileInfos.
*)
PROCEDURE NumFileVarsWithDataPtr( d: DataPtr ): INTEGER;
(*
Determines the total number of FileVar objects with a given DataPtr
across all FileInfos.
*)
PROCEDURE SetFileVarsDataPtr( fmt: FileFormatType; varsIdent: ARRAY OF CHAR; d: DataPtr );
(*
Sets for all FileInfos with format "fmt" the DataPtr attribute of all FileVar objects
with ident "varsIdent" to "d". Note: using fmt = "undefFileFormat" will set the tally
attribute for all matching FileVars in all existing FileInfos, regardless of the
file's format.
*)
(***************************)
(*##### Auxiliary #####*)
(***************************)
PROCEDURE GetIdentOfFileFormatType( ft : FileFormatType;
VAR ident : ARRAY OF CHAR );
PROCEDURE FileFormatTypeOfIdent( ident: ARRAY OF CHAR ): FileFormatType;
PROCEDURE GetIdentOfStatisticsType( stat : StatisticsType;
VAR ident : ARRAY OF CHAR );
PROCEDURE StatisticsTypeOfIdent( ident: ARRAY OF CHAR ): StatisticsType;
PROCEDURE GetIdentsListForStatisticsSet( ss : StatisticsSet;
VAR list : ARRAY OF CHAR );
(*
Constructs for StatisticsSet "ss" a list containing the
identifiers of the set elements, separated by ", ".
Note, elements of type "undefVarStatistic" are not included
in the list.
*)
PROCEDURE StatisticsSetCardinality( ss: StatisticsSet ): INTEGER;
(*
Returns number of elements in StatisticsSet "ss".
Elements of type "undefVarStatistic" are not counted.
*)
(*******************************************************************************)
(*##### Retrieval of files and variables information from data frames #####*)
(*******************************************************************************)
PROCEDURE ExtractFileContentsInfo( fileContentsSpecif : ARRAY OF CHAR;
VAR stats : StatisticsSet;
VAR minFirstClass : REAL;
VAR maxLastClass : REAL;
VAR numClasses : INTEGER;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Extracts file contents information from "fileContentsSpecif"
according to the following syntax:
fileContents = emptyString|ContentSpecif {";" ContentSpecif}.
emptyString = ""|"--".
ContentSpecif = StatisticsSpecif|HistogramSpecif.
StatisticsSpecif = "stats" ":" statisticId {"," statisticId}.
statisticId = "n"|"mean"|"sd"|"skw"|"min"|"p05"|"p10"|"p25"|"med"|"p75"|"p90"|"p95"|"max".
HistogramSpecif = "histo" ":" minFirstClass "," maxLastClass "," numClasses.
minFirstClass = REAL.
maxLastClass = REAL.
numClasses = INTEGER.
*)
PROCEDURE ExtractVariablesList( varsListSpecif : ARRAY OF CHAR;
VAR varsList : ARRAY OF CHAR;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Extracts a list of variables from "varsListSpecif"
according to the following syntax:
varsListSpecif = POrVSpecif {";" POrVSpecif}.
POrVSpecif = PrefixSpecif|VarsSpecif.
PrefixSpecif = "prefix" ":" "NONE"|qualifiedIdent.
VarsSpecif = "vars" ":" qidOrIndex {"," qidOrIndex}.
qidOrIndex = qualifiedIdent|INTEGER.
qualifiedIdent = ident {"." ident}.
ident = IDENTIFIER.
The found variables are stored in "varsList", separated by "|".
*)
PROCEDURE GetFileInfoParamsFromDataFrames( fileIdent : ARRAY OF CHAR;
VAR format : FileFormatType;
VAR matCode : LONGINT;
VAR stats : StatisticsSet;
VAR minFirstClass : REAL;
VAR maxLastClass : REAL;
VAR numClasses : INTEGER;
VAR varsList : ARRAY OF CHAR;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Retrieves specifications for FileInfo with identifier
"fileIdent" based on contents of the currently loaded data
frames (see procedure DataFrames.LoadDataFrames). Considered
are all data frames with definitions "MODEL = ANY;" and
"KEYCOLUMN = FileIdent;".
NOTE: The set of FileInfos actually considered is defined by
the FileInfos list available in the *last* loaded data frame
with a key column named "FileIdent" of type "Identifier"
(see also procedure DataFrames.GetIdVec).
*)
PROCEDURE DeclareFileInfosFromDataFrames( outFilesSetId : ARRAY OF CHAR;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Declares FileInfo objects and all associated variables based
on contents of the currently loaded data frames using above
procedure GetFileInfoParamsFromDataFrames.
Note, a particular FileInfo is only declared if a corresponding
data frame value definition "."
of type BOOLEAN exists and has the value "TRUE".
*)
(********************************)
(*##### Event handling #####*)
(********************************)
TYPE
FileInfosEventType = ( undefFileInfosEvent, fileDeclared, fileRemoved, varDeclared, varRemoved );
FileInfosEventHandler = PROCEDURE( FileInfosEventType, FileInfo, FileVar );
PROCEDURE InstallFileInfosEventHandler( h: FileInfosEventHandler );
PROCEDURE RemoveFileInfosEventHandler ( h: FileInfosEventHandler );
END FileInfos.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib