DEFINITION MODULE DatFraAux;
(*******************************************************************
Module DatFraAux (DF_Version_2.2)
Copyright (c) 1997-2006 by Andreas Fischlin and ETH Zurich.
Purpose Auxiliary routines for more advanced
use of Data Frames. It basically extends the
functionality of module DataFrames.
Remarks --
Programming
o Design
Andreas Fischlin 31/07/1997
o Implementation
Andreas Fischlin 31/07/1997
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: 11/04/1998 AF&DG
*******************************************************************)
FROM DataFrames IMPORT ReadingFilter, ValDefType, dtfOffset;
CONST
nosuchDataFrame = dtfOffset + 10; (* insert Δ (=306C) is data frame's identifier *)
idDlgCancelled = dtfOffset + 11; (* insert Δ (=306C) is operation name *)
missingIdent = dtfOffset + 12; (* insert Δ (=306C) is operation name *)
loadDFErrFromOp = dtfOffset + 13; (* insert Δ (=306C) is name of loading operation *)
internalMemExceeded = dtfOffset + 14; (* insert Δ (=306C) is name of operation *)
retrMethFailsOnScal = dtfOffset + 15; (* inserts: Δ (=306C) - identifier, Δ (=306C) - retrieval method *)
retrMethFailsOnVect = dtfOffset + 16; (* inserts: Δ (=306C) - identifier, Δ (=306C) - retrieval method *)
(* see GetDFErrMsg for retrieving associated error messages *)
maxDefsRemembered = 16; (* maximum number of (re)definitions
remembered for any data frame *)
onlyVectRetr = 0; (* see ListType and GetListOfIdents *)
onlyScalRetr = 1;
vectAndScalRetr = 2;
(* activity constants *)
scanNormally = 0; (* see AtSymbolDetectedProc and AddAtSymbolDetectedHandler *)
skipSinceFilterMismatch = 1;
circularFileRerence = 2;
missHistory = "..."; (* string returned for a vector element
denoting the missing history in case it
exceeds maxDefsRemembered *)
TYPE
DataFrame;
DataFramHandler = PROCEDURE ( DataFrame );
DataFrameFile;
DataFrameFileProc = PROCEDURE ( DataFrameFile );
ListType = [onlyVectRetr..vectAndScalRetr];
AtSymbolDetectedProc = PROCEDURE
( BOOLEAN, (* true if a data frame *)
ARRAY OF CHAR, (* data frame identifier or path and file name *)
INTEGER, (* activity: scanNormally, or skipSinceFilterMismatch etc. *)
INTEGER, (* number of files currently open *)
VAR BOOLEAN ); (* if true, continue loading, otherwise abort *)
AnyDFChangedHandler = PROC;
VAR
unknownDataFrame: DataFrame; (* READ ONLY *)
unknownDataFrameFile: DataFrameFile; (* READ ONLY *)
PROCEDURE IsDataFrameKnown(df: DataFrame): BOOLEAN;
PROCEDURE FirstDataFrame(): DataFrame;
PROCEDURE NextDataFrame(df: DataFrame): DataFrame;
PROCEDURE FindDataFrame(dataFrameIdent: ARRAY OF CHAR;
VAR df: DataFrame; VAR found: BOOLEAN);
PROCEDURE GetDataFrameIdent(df: DataFrame;
VAR dataFrameIdent: ARRAY OF CHAR);
(*
Returns the identifier (dataFrameIdent) of the data frame df.
*)
PROCEDURE GetDataFrameAttrIdents(df: DataFrame;
VAR parentIdent,modelIdent,
keyColumn: ARRAY OF CHAR);
(*
Returns the identifiers (parentIdent or modelIdent, plus
keyColumn) of the data frame df. Only either parentIdent
or modelIdent are returned, depending whether the data
frame was defined with the reserved keyword "OF PARENT"
or "OF MODEL". Note data frames using different
identifiers (to avoid implicit dropping) but the same
parentIdent (respectively modelIdent) are all treated like
a group of related data frames. From such a group value
definitions can be retrieved using the same identifier
(e.g. modelIdent) as if all data frames belonging to the
group would form a single huge data frame merging all its
components. This technique allows you to tabulate all
value definitions belonging to a particular model in
several formats, e.g. in one data frame with a format
useful to tabulate the model's parameters with standard,
minimum, and maximum values, and to list in another data
frame the model's state variables with only their initial
values etc.
*)
PROCEDURE InspectDataFrame(df: DataFrame;
VAR nrOfDefs,
totalVectValDefs, totalScalarValDefs: INTEGER;
sepChar: ARRAY OF CHAR;
VAR defNos, parentIdents, keyColumns, remarks,
maxRows, maxCols,
storedOnFsWithName, fileNos: ARRAY OF CHAR;
VAR fromFilters, tillFilters: ARRAY OF ReadingFilter;
VAR resCode: INTEGER);
(*
Returns detailed attributes of df:
- nrOfDefs returns how many definitions of the data
frame with identifier dataFrameIdent have been found
during any calls of ReadDataFramesIntoMemory (of course
only resulting from calls since the last drop of df);
Note, in case that multiple definitions were detected
during ReadDataFramesIntoMemory, the old data frame is
entirely deleted from memory and only the last read is
stored (implicit overwriting without warning); Note also,
if this number has changed since the last call of a
client to InspectDataFrame, the client learns that the
df's content could have been modified in the
meantime. Finally, note that any modification results
also in the deletion of the old data frame, i.e. if the
client has requested a notification of any data frame
deletion for df by calling AddDFDropHandler(df,..., she/he
will be notified of this fact anyway.
IMPLEMENTATION RESTRICTION: Only maxDefsRemembered of
definitions are actually kept in memory for inspection.
For the client's convenience the first few plus the
last ones to a total of maxDefsRemembered are actually
available for inspection. This is especially important
for the arguments defNos, parentIdents, keyColumns,
remarks, maxRows, maxCols, storedOnFsWithName, fileNos,
fromFilters, and tillFilters as explained in
more details below.
- totalVectValDefs returns the maximum total number of value
definitions (vector retrieval) currently available from df.
- totalScalarValDefs returns the maximum total number of value
definitions (scalar retrieval) currently available from df.
IMPLEMENTATION RESTRICTION: Above 2 numbers are valid
only for data frame df und thus reflects only a
potential maximum of value definitions, since some of
the value definitions provided by df may be obsolete,
for instance because another data frame may provides
data for same value definition(s) or some may be
overwritten even within df itself (e.g. in case of scalar
retrieval). Use GetListOfIdents to learn about the exact
number of identifiers a particular data frame provides.
- defNos contains the numbers of the definition of a data frame.
Counting of definitions starts with 1 and ends always with the
most recent one.
IMPORTANT NOTE:
--------------
Similar to most subsequent arguments, values are returned as
strings only and might need conversions if you wish to use
them in calculations (see module DMConversions). To extract
individual elements use a loop similar to this one
i := 0;
REPEAT
ExtractSubString(i,fromStr,subStr,delimiter);
(*. *** do with substring subStr what you want *** .*)
UNTIL i(*speed-up*)
VAR last: ARRAY OF CHAR);
VAR i: INTEGER;
BEGIN
i := 0;
WHILE i(*WHILE*);
END ExtractLast;
IMPORTANT NOTE:
--------------
If the history of the data frame exceeds the maximum
remembered definitions (nrOfDefs>maxDefsRemembered), then
defNos contains first the oldest definitions and ends with
the newest one. This supports easier analysis of complex
data frame loading; thus, the forgotten information is
missing from the list in its middle. If this happens the
returned list contains somewhere inbetween just one
additional element with the marker "..." ( = missHistory.
Note also, the vector thus contains nrOfDefs+1 elements!).
This behavior is not oly true for defNos, but also for
almost all following arguments, i.e. parentIdents,
keyColumns, remarks, maxRows, maxCols, storedOnFsWithName,
fileNos, fromFilters, and tillFilters (instead of
missHistory fromFilters, and tillFilters contain
DataFrames.undefLongInt as a marker).
- parentIdents (or model identifiers) contains the parent
identifier(s) (in case no parent or model identifier has
been used for df, parentIdents is the empty string).
Remember, the optional parentIdents is used to denote a
particular value definition, since it forms the first part
of a data frame entry (see example below under procedures
DataFrames.VR etc.).
- keyColumns contains the identifier(s) of the column
holding the keys used to designate rows (in case no such
key columns have been used in any data frame with
dataFrameIdent, keyColumns is the empty string).
- remarks contains the data frame's remarks (in case no such
remark has been attached to a data fame, the empty string is
returned).
- maxRows returns the number(s) of the last row (row
numbers start from 1) of each df
- maxCols returns the number(s) of the last column
(column numbers start from 1) of each df
- storedOnFsWithName holds the names (preceeded by the
access path) of the files on which definitions of the
data frame (all definitions with the same identifier
dataFrameIdent) have been found.
- fileNos contains the numbers associated with files. This
number is assigned to files while loading data frames and
denotes each file in a unique way during the existence of any
data frames which have been read from this particular file
- fromFilters and tillFilters return the nrOfDefs
filters used during the reading process of the data frame
df. For the meaning of these filters see module DataFrames.
- resCode returns whether the data frame definition is
without errors (resCode = Errors.allOk) especially in
case of multiple redefinitions (nrOfDefs>1) errors may
ocurr because the key columns definitions don't match in
all definitions or other inconsistencies).
*)
PROCEDURE InspectValDef(ident: ARRAY OF CHAR;
VAR vectRetr: BOOLEAN;
VAR nrOfDefs: INTEGER;
VAR fdt: ARRAY OF ValDefType;
sepChar: ARRAY OF CHAR;
VAR vals, dfIdents,
parentIdents, keyColumns: ARRAY OF CHAR);
(*
InspectValDef allows to learn about all attributes of
possible interest for any value definition denoted by
identifier ident (see module DataFrames for the syntax of
ident). In contrast to accompanying routines from module
DataFrames, such as GetValDefType, this routine returns
characteristics of all occurrences of the definition. This
is of particular interest in case of multiple definitions
(nrOfDefs>1). In such cases all routines from DataFrames,
like GetIVec, or GetValDefType return only the last
instance, i.e. the valid instance, for that particular
ident (all previous ones are ignored). However, routine
InspectValDef makes it possible to learn about all present
instances of value definitions. The last one is the instance
which would actually be retrieved with any retrieval routine
from module DataFrames such as VB or GetLRVec.
- vectRetr returns wether the value definition is a vector
retrieval or not
CASE vectRetr OF
| TRUE: A vector, i.e. all values contained in an entire
column of the data frame's table is targeted
for retrieval. E.g. ident = "SiteEdaphics.Site"
| FALSE: only a scalar, i.e. a single value is targeted
for retrieval. E.g. ident =
"SiteEdaphics.Bern.SiteID", then the value
from the column headed by SiteID from the row
where the value in the key column is the
string "Bern" is the wanted value.
- nrOfDefs returns the number of instances found in the
data frames currently hold in memory
Note, all other parameters are actually vectors with the dimension
nrOfDefs (or nrOfDefs+1 if nrOfDefs > maxDefsRemembered). In case of
vectors consisting of strings, elements are returned within the same
string parameter, but separated by sepChar, e.g. "|".
- fdt returns the types of every found instance of the value
definition
- sepChar, typically "|", is used to delimit invidiual
vector elements returned by the following string
parameters:
- vals returns in case of vector retrieval (e.g. ident =
"SiteEdaphics.Bucketsize") the length of the vectorial
value definitions, i.e. the number of rows of the data
frame table in which the vector was found.
In case of scalar retrieval (e.g. ident =
"SiteEdaphics.Bern.Bucketsize") vals returns all values
of the found value definitions converted to strings to
allow for any mixture of numbers and strings.
- dfIdents returns the identifiers of the data frames
in which the instance(s) of the value definition was
detected. Note in case that the same value definition is
made within the same data frame, the same data frame
identifier is listed several times in dfIdents to allow
for proper association among the various vector
elements at all times.
- parentIdents returns the parent or model identifiers (Note,
this vector is not entirely redundant to the input
parameter ident, since there may be data frames present
which use the predefined model identifiers ANY or ALL,
which potentially affect any value definition and which
have a specific meaning when data frames are used in
conjunction with RAMSES models, see module ModelObjects).
- keyColumns returns the identifiers of the key columns which
are required by scalar retrieval (e.g. ident =
"SiteEdaphics.Bern.Bucketsize" requires a key column
holding in a row an entry "Bern").
Ex.: For the following data frame (the only one present)
DATAFRAME SiteParams;
REMARK = 'Swiss site characteristics';
KEYCOLUMN = Site; DATA:
(*-------------------------------------*)
Site Bucketsize SiteID;
(*-------------------------------------*)
"Bern" 30.0 333333 ;
"Bever S" 20.0 222222 ;
"Davos" 25.0 666666 ;
"Bern" 40.0 333333 ;
END SiteParams;
the call
InspectValDef("SiteParams.Bern.BucketSize",vectRetr,fdt,nrOfDefs,vals,
dfIdents,parentIdents,keyColumns);
returns: vectRetr = FALSE
fdt[0] = real, fdt[1] = real fdt[2+] = undefined
nrOfDefs = 2
vals = "30.0|40.0"
dfIdents = "SiteParams|SiteParams"
parentIdents = ""
keyColumns = "SiteID"
Note, in this case fdt contains identical elements only,
otherwise SiteEdaphis would not have been read successfully
into memory and nrOfDefs would be 0. However, in the following
example
DATAFRAME SiteEdaphics1; MODEL = MyModel;
REMARK = 'Swiss sites';
KEYCOLUMN = Site; DATA:
(*-------------------------------------*)
Site Bucketsize SiteID;
(*-------------------------------------*)
"Bern" 30 333333 ;
"Bever S" 20 222222 ;
"Davos" 25 666666 ;
"Bern" 40 333333 ;
END SiteEdaphics1;
DATAFRAME SiteEdaphics2; MODEL = ANY;
REMARK = 'Miscellaneous sites';
KEYCOLUMN = SiteName; DATA:
(*-------------------------------------*)
SiteName Bucketsize SiteID;
(*-------------------------------------*)
"Medicine Hat" 30.0 333333 ;
"Churchill" 25.0 999999 ;
"Vancouver" 20.0 111111 ;
"Bern" 40.0 333333 ;
"Davos" 25.0 666666 ;
END SiteEdaphics2;
the call
InspectValDef("MyModel.Bern.BucketSize",vectRetr,fdt,nrOfDefs,vals,
dfIdents,parentIdents,keyColumns);
returns: vectRetr = FALSE
fdt[0] = real, fdt[1] = integer, fdt[2] = integer
nrOfDefs = 3
vals = "40.0|30|40"
dfIdents = "SiteEdaphics2|SiteEdaphics1|SiteEdaphics1"
parentIdents = "ANY|MyModel|MyModel"
keyColumns = "SiteName|Site"
Note, any data frames belonging to model ANY will be found
first, since they serve as overwritable defaults for any
value definition ("ANY.Bern.BucketSize" is accepted in case
no "MyModel.Bern.BucketSize" can be found in any data frame
currently present). This is true regardless of the sequence
in which data frames are read.
Note, it is always possible to retrieve value definitions with the
vector retrieval method, hereby just ignoring the key columns. E.g.
the call
InspectValDef("MyModel.BucketSize",vectRetr,fdt,nrOfDefs,vals,
dfIdents,parentIdents,keyColumns);
returns: vectRetr = TRUE
fdt[0] = real, fdt[1] = integer, fdt[2+] = undefined
nrOfDefs = 2
vals = "5|4"
dfIdents = "SiteEdaphics2|SiteEdaphics1"
parentIdents = "ANY|MyModel"
keyColumns = "SiteName|Site"
*)
CONST
(* regular retrieval methods *)
retrAsUndef = 0;
(* scalar retrieval *)
retrAsInt = 1;
retrAsReal = 2;
retrAsBool = 3;
retrAsIdent = 4;
retrAsStr = 5;
(* vector retrieval *)
retrAsIntVect = 6;
retrAsRealVect = 7;
retrAsBoolVect = 8;
retrAsIdentVect = 9;
retrAsIdsStr =10;
retrAsStrVect =11;
retrAsSStrsStr =12;
(* special retrieval methods *)
getUnknown =13;
getType =14;
getDim =15;
getKeyCol =16;
getSubKeyCol =17;
minRetrieveMethod = 0;
maxRetrieveMethod = 17;
TYPE
SimpleRetrieveMethod = [retrAsUndef..retrAsSStrsStr];
SpecialRetrieveMethod = [getUnknown..getSubKeyCol];
RetrieveMethod = [minRetrieveMethod..maxRetrieveMethod];
PROCEDURE RetrieveAValDef (vdident: ARRAY OF CHAR;
how: SimpleRetrieveMethod;
sepChar: ARRAY OF CHAR; decDig: CARDINAL;
VAR retrievedValue: ARRAY OF CHAR;
VAR n: INTEGER);
(*
Retrieves for value definition identifier vdident by
using the method how the value in retrievedValue in form
of a string. In case of vector retrieval sepChar is used
to delimit individual elements of the vector when
assigning them to retrievedValue. decDig specifies the
number of decimal digits used to retrieve reals. Note,
this routine retrieves all numbers (integers and reals)
with double precision. n returns the number of values
retrievable (may be larger than data actually returned in
retrievedValue, in case the latter is too small or some
internal memory limitations have been exceeded (see error
code internalMemExceeded)).
*)
PROCEDURE RetrieveForValDef (vdident: ARRAY OF CHAR; forType: ValDefType;
how: SpecialRetrieveMethod;
subKeyIdent, sepChar: ARRAY OF CHAR;
decDig: CARDINAL;
VAR retrievedValue: ARRAY OF CHAR;
VAR n: INTEGER);
(*
Retrieves for value definition identifier vdident by
using the method how the value in retrievedValue in form
of a string. In case of vector retrieval sepChar is used
to delimit individual elements of the vector when
assigning them to retrievedValue. decDig specifies the
number of decimal digits used to retrieve reals. Note,
this routine retrieves all numbers (integers and reals)
with double precision. n returns the number of values
retrievable (may be larger than data actually returned in
retrievedValue, in case the latter is too small or some
internal memory limitations have been exceeded (see error
code internalMemExceeded)).
*)
PROCEDURE ConvertValDefTypeToString (vdt: ValDefType;
VAR str: ARRAY OF CHAR);
(*
Auxiliary procedure which returns in str the string associated
with the type vdt. The values of str correspond to the
definition of ValDefType from module DataFrames.
*)
PROCEDURE ConvertRetrieveMethodString (retrMeth: RetrieveMethod;
VAR str: ARRAY OF CHAR);
(*
Auxiliary procedure which returns in str the string
associated with the retrieve method retrMeth. The values
of str correspond to the names of the procedures from
module DataFrames.
*)
PROCEDURE InspectDataFrameFile(dff: DataFrameFile;
VAR pfn: ARRAY OF CHAR;
VAR fileNo: INTEGER;
VAR creationDate, modifDate: LONGINT);
(*
Returns for the file denoted by dff the path and name string
pfn containing data frames, the file's number fileNo, plus the
creation and modification date (allows for efficient use in
relations; to translate the returned number into a human
readable format, use procedure InterpreteSeconds from optional
'Dialog Machine' module DMClock). You can access all data
frame files which have been used during the laoding of the
data frames currently in memory. (NOTE: There is no
limitation to the number of files remembered, i.e. the
limitation maxDefsRemembered does not apply for data frame
files themselves; maxDefsRemembered is only relevant for the
number of redefinitions of the data frames which are
remembered, i.e. the memory holding e.g. the comments which
were in the previously loaded data frames or the filters which
were used during loading etc.).
The unique number fileNo is assigned consequtively during
loading of data frames and remains fixed during the entire
existence of an individual data frame file. I.e., fileNo
denotes only a particular file with a specific path and
file name (Note, however, this has nothing to do with the
data frame file's content. The same data frame file can be
reread with DataFrames.ReadDataFramesIntoMemory as many
times you want, possibly each time with a new content, but
fileNo won't change and remains associated with this file).
There is one exception to this rule, however: When a
particular file is reread which has previously no longer
been used by any data frame, the file will have been
completely forgotten and will therefore obtain a new fileNo
during successful rereading.
Only if all data frames are dropped (see routines
DropDataFrame or DataFrames.DropAllDataFrames), the
numbering starts anew.
*)
PROCEDURE GetListOfIdents(df: DataFrame; sepChar: ARRAY OF CHAR;
lt: ListType;
VAR intIds, realIds, boolIds, strIds, idIds: ARRAY OF CHAR;
VAR ni,nr,nb,ns,nd,vectDim: INTEGER);
(*
Returns for data frame df in intIds, realIds, boolIds,
strIds, and idIds nr, ni, nb, ns, and nd respectively,
number of identifiers, separated from each other by
sepChar, typically "|". The identifiers are a complete
list of all those identifiers which define the value
definitions provided by the data frame df. The
identifiers are grouped into integer numbers (integer,
longint), real numbers (singlereal, doublereal), boolean,
and strings (identifier, string) (see DataFrames
ValDefType). Depending on lt the list are formed
differently: If lt = onlyVectRetr then each list contains
only the identifiers for vector retrieval. If lt =
onlyScalRetr then each list contains only the identifiers
for scalar retrieval. If lt = vectAndScalRetr then each
list contains first the identifiers for vector retrieval
followed by those for scalar retrieval. vectDim returns
the dimension of the vectors for vector retrievals.
*)
PROCEDURE FindDataFrameFile(pfn: ARRAY OF CHAR; VAR dff: DataFrameFile);
(*
Given a path and name string pfn, the associated dff is
returned, which may be used to inspect the data frame
file via routine InspectDataFrameFile. IMPLEMENTATION
RESTRICTION: This routine must not be called from within
a data frame file procedure (see also routine
DoForAllDataFrameFiles).
*)
PROCEDURE DoForAllDataFrameFiles(dffproc: DataFrameFileProc);
(*
For any data frame file currently known the procedure
dffproc is executed. IMPLEMENTATION RESTRICTION:
FindDataFrameFile must not be called from within dffproc.
*)
PROCEDURE DropDataFrame(VAR df: DataFrame);
(*
Deletes data frame df and frees memory. Note, any
currently known drop handlers of data frame df, which were
installed via routine AddDFDropHandler will be called
automatically. There is no need to call a drop handler
yourself, even if you are its owner. Finally all currently
installed AnyDFChangedHandler will also be called.
*)
PROCEDURE AddAnyDFChangedHandler (adfchghdl: AnyDFChangedHandler);
PROCEDURE VoidAnyDFChangedHandler (adfchghdl: AnyDFChangedHandler);
(*
Any client who has installed a procedure adfchghdl will be
notified in case any data frame is loaded (see procedures
ReadDataFramesIntoMemory and LoadDataFrames from module
DataFrames) or dropped (see procedures DropDataFrame (this
module) and/or DropAllDataFrames from DataFrames). A typical use of
this mechanisms is to update a view of the data frames (e.g.
module DatFraViewer uses this mechanism). The notification takes
always place after the change has fully been completed.
*)
PROCEDURE AddDFDropHandler (df: DataFrame; dfdhdl: DataFramHandler);
PROCEDURE VoidDFDropHandler (df: DataFrame; dfdhdl: DataFramHandler);
(*
Any client who has installed a DataFramHandler procedure will
be notified in case the data frame df is about to be dropped
(see procedures DropDataFrame and/or DropAllDataFrames). This
occurrs before the actual discarding of the data frame and all
operations (except DropDataFrame) are still fully functional.
*)
PROCEDURE AddAtSymbolDetectedHandler ( asdh : AtSymbolDetectedProc );
PROCEDURE VoidAtSymbolDetectedHandler( asdh : AtSymbolDetectedProc );
(*
Any client who has installed a handler of type
AtSymbolDetectedProc will be notified as soon as the loading
process of module DataFrames (see routines
ReadDataFramesIntoMemory and LoadDataFrames) detects an object.
This may happen for two kinds of objects: symbol 'FileReference'
and symbol 'DataFrame' (see syntax description of data frames in
module DataFrames). As soon as the name of the file (string
'fileName') or the identifier of a data frame (identifier
'dataFrameIdent') is scanned, asdh will be called. asdh gets
then a chance to learn about the kind of object encountered,
i.e. whether it is a data frame or not, its identifier (in case
of a data frame) or its file name (in case of a file reference),
respectively. Then it is possible to learn about the action to
be taken by the loading process, whether the object will be
fully scanned and loaded or skipped due to a filter mismatch or
not scanned due to a circular reference to a file currently
already open. The last parameter available is the number of
files currently opened simultaneously by the loading process.
Finally asdh can determine whether the loading process should
continue or not. This is accomplished by returning a value for
the boolean parameter 'continue' to the calling loading process.
Note, initally the software package data frame uses a handler
which returns always TRUE for 'continue'. A typical application
installing an asdh procedure, will use asdh to report about the
progress of the loading process and possibly to allow for user
interruption of the loading process.
IMPLEMENTATION RESTRICTION: It is actually only possible to add
a single asdh handler at a time. Thus, calling
VoidAtSymbolDetectedHandler will always reinstall the internally
provided default handler.
NOTE: DatFraViewer already uses AddAtSymbolDetectedHandler to
install an asdh procedure.
*)
PROCEDURE GetDFErrMsg(resCode: INTEGER; VAR msg: ARRAY OF CHAR);
(*
Returns data frame package specific message msg associated
with result code resCode. Note, this routine does also
retrieve the error messages from module DataFrames. See
module Errors for more details.
*)
PROCEDURE GetDFFileType(VAR fileType: ARRAY OF CHAR);
PROCEDURE SetDFFileType( fileType: ARRAY OF CHAR);
(*
Returns or allows to set the filetype used for data frame
files. The argument fileType may actually contain
several types, each given by up to a maximum of 4
characters. The first element is the one to be used
with highest priority. Initial default: "XLS |TEXT|MoTx" (but
actually depends on the values used by the RAMSES shell
and can be fully customized (see resource of type 'STR#',
ID = 7000 in RAMSES shell)).
*)
END DatFraAux.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib