DEFINITION MODULE SysDatAux;
(*******************************************************************
Module SysDatAux (ISIS_Version_1.2)
Copyright (c) 1997-2006 by Andreas Fischlin and ETH Zurich.
Purpose Support the use of systems, models, and model
objects declared via module SysModBase plus their
needed data as provided by data frames.
Remarks The core routine is AssignDatFraData, which assigns
data from all data frames currently stored in
memory to all models and model objects given the
identifier match according to the rules of data
frames (see module DataFrames).
This module provides operations to make the link
between systems, models, and model objects declared
via SysModBase and data frames.
Further it supports menu commands which can be
installed with a single command, or can be used for
installation in any other context of all major
functions provided.
This module provides a part of the standard user
interface offered by ISIS, i.e. the part which deals
with the data needed by the system (for the part dealing
with structure cf. module SysStrctAux).
Note, this module does not let you look at the
actual data frames, they remain invisible to the
user at all times. However, module DatFraViewer,
lets you view and inspect all data frames
and their data currently stored in memory.
See also modules SysModBase, SysDatAccess,
DataFrames, and DatFraViewer.
The following modules/packages are used: SysModBase,
ModDatAccess, DumpMWMoObjs, and DataFrames plus
'ModelWorks' and the 'Dialog Machine'.
This module belongs to ISIS
Integrative Systems Implementation Software.
Programming
o Design
Andreas Fischlin 16/09/1997
o Implementation
Andreas Fischlin 16/09/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: 25/05/1998 AF
*******************************************************************)
FROM DMMenus IMPORT Menu;
(* Error constants: sysDatAuxErrOffset = DMLanguage.userBase + 380 .. 390-1 *)
(********************************************************)
(*##### Model Data Base menu and menu commands #####*)
(********************************************************)
PROCEDURE InstallSDAMenuCmds (title: ARRAY OF CHAR);
(*
Installs a menu with the title 'title' plus the basic
model data base management commands (see routines below).
Typical usage: InstallSDAMenuCmds(''). In case 'title'
is the empty string, a default menu title will be
provided.
*)
PROCEDURE RemoveSDAMenuCmds;
(*
Reverts the effect of InstallSDAMenuCmds by removing the
current model base menu (plus any possibly client installed
commands as well!).
*)
(*******************************)
(*##### Customization #####*)
(*******************************)
PROCEDURE SysDatAuxMenu(): Menu;
(*
Returns the model data base's menu in order to customize
the menu by installing additional commands in it, e.g. by
using routines from DMMenus.
*)
PROCEDURE SetSDAPreferences( clearAtDeassignMode : BOOLEAN;
showIDsAlways : BOOLEAN;
reportOnCheckFail : BOOLEAN;
packageErrMode : INTEGER;
globLikePkgErrMode : BOOLEAN);
PROCEDURE GetSDAPreferences(VAR clearAtDeassignMode : BOOLEAN;
VAR showIDsAlways : BOOLEAN;
VAR reportOnCheckFail : BOOLEAN;
VAR packageErrMode : INTEGER;
VAR globLikePkgErrMode : BOOLEAN);
(*
Lets you control the current preferences. The values
will be remembered and stored as part of the permanent
preferences. Meaning:
clearAtDeassignMode A call to routine DeassignData clears
all assignments instead of restoring
the last present while calling
AssignDatFraData
showIDsAlways Identifiers are shown of model objects
even if they have been fully cleared
reportOnCheckFail After an assignment of data using
core procedure AssignDatFraData
from this module a dialog will
report in case any model objects
have still invalid data. This
warns the user about possible
failures of subsequent simulations.
*)
CONST
suppressAllErrMode = 0; (* values used for packageErrMode *)
warnOnceErrMode = 1;
immediateErrMode = 2;
debugErrMode = 3;
(*
Routines GetSDAPreferences and SetSDAPreferences recognize
these values for preference packageErrMode
packageErrMode meaning
-------------- -------
suppressAllErrMode Never show any error messages, i.e.
SuppressMsgDisplay from Errors is
called. Investigation of error presence
and possible display of them is
completely the callees responsibility.
Use module Errors to check for error
occurrence and display of possibly
accumulated errors.
warnOnceErrMode Inform about single or warn and ask for
inspection if many errors (default mode).
immediateErrMode No suppression of error displays at all
and all errors are shown immediately, i.e.
SuppressMsgDisplay from Errors is not called
like in above modes.
debugErrMode Similar to above but offers the advantage
that Errors.Info messages are displayed
as Errors.Halt messages and may display
additional, internal debugging messages
(calls Errors.SetDebugMode(TRUE)).
Note, if you call SetSDAPreferences and change
packageErrMode, this may trigger the display of errors if
the mode changes to a less quiet one. You can use this
effect for instance to acchieve temporarily a completely
quiet mode (suppressAllErrMode) and then call
SetSDAPreferences to change to warnOnceErrMode to learn
about the possible presence of some errors encountered in
the past.
IMPLEMENTATION RESTRICTION: Note changing packageErrMode values
by calling SetSDAPreferences affects the error mode of the
packages SimData, SysModBase, and SysData throughout.
globLikePkgErrMode This flags lets you control the
behavior of error handling for
the category of global errors identical
to that as defined by packageErrMode.
Note, any errors not falling within the
range DMLanguage.userBase + 300
and + 400, i.e. [600..700]) are not
affected by packageErrMode. All errors
as defined by modules DMLanguage (or
Errors) are predefined global errors
and may also be raised by any operation
of the SimData package, e.g. file opening
or memory shortage errors etc.
*)
PROCEDURE GetSDAMenuAliasChars ( VAR loadDatAlCh, loadDatFromAlCh,
sdfAlCh, sasdfAlCh,
assgnDatAlCh, deassignDatAlCh,
assgnGloSiPsAlCh, chMLevAlCh, chTLevAlCh,
placeWinsAlCh, chkErrAlCh,
editPrefsAlCh, editAlChsAlCh: CHAR);
PROCEDURE SetSDAMenuAliasChars ( loadDatAlCh, loadDatFromAlCh,
sdfAlCh, sasdfAlCh,
assgnDatAlCh, deassignDatAlCh,
assgnGloSiPsAlCh, chMLevAlCh, chTLevAlCh,
placeWinsAlCh, chkErrAlCh,
editPrefsAlCh, editAlChsAlCh: CHAR);
(*
Above two procedures lets you control the keyboard short
cuts used by the model data base menu commands.
GetSDAMenuAliasChars is typically used if you wish to modify
only a few of the keyboard shortcuts in a
GetSDAMenuAliasChars(loadDatAlCh,... ;
SetSDAMenuAliasChars(loadDatAlCh,...
sequence. The values will be remembered and stored as part
of the permanent preferences. The characters are used as
alias characters for the commands (see below) as follows:
loadDatAlCh - LoadDFFromFileIntoMem
loadDatFromAlCh - LoadDFFromOtherFileIntoMem
sdfAlCh - SaveDF
sasdfAlCh - SaveAsDF
assgnDatAlCh - AssignDatFraData
deassignDatAlCh - DeassignData
assgnGloSiPsAlCh - AssignGlobSimPars
chMLevAlCh - AssignModelsMonitoringForLevel
chTLevAlCh - AssignModelsTallyingForLevel
placeWinsAlCh - PlaceSimEnvsWindows
chkErrAlCh - CheckForErrPresence
editAlChsAlCh - (not available, but see SetSDAMenuAliasChars)
editPrefsAlCh - (not available, but see SetSDAPreferences)
*)
PROCEDURE ResetSDAToPresettings;
(*
Resets all preferences to factory settings (defaults) as
described above.
*)
(*******************************************)
(*##### Model Data Base Functions #####*)
(*******************************************)
(* each function is available as a command in the default menu *)
PROCEDURE LoadDFFromFileIntoMem;
(*
Starting from the current anchor file, routine
LoadDFFromFileIntoMem scans the file's (and possibly
therein referenced other files') content and loads all the
data found into memory (for details see module DataFrames).
Note, no filtering takes place and all data frames and file
references are recognized during this reading and loading
process. If the user has never selected an anchor file,
this routine behaves like LoadDFFromOtherFileIntoMem
(called with empty string parameters). After successful
completion data are kept in memory and are ready to be
used, e.g. to be assigned to models and model objects.
Use AssignDatFraData to actually assign the data to the
currently known model and model objects. Loading can also
be repeated and the result will be a merging and
accumulation of all data encountered during any previous
loading process. However, if the same data are
encountered, especially if the data frame identifier is
identical, the previously stored data are discarded and
replaced with the latest read, supporting a convenient
updating.
NOTE: As an alternative you may also use module
DatFraViewer to load data frames into memory. The latter
module offers the advantage to allow for inspection of the
data currently stored in memory, plus many more functions,
such as unloading and versatile filtering during the
loading process etc. Note, it does not matter by which
method data were actually loaded into memory; the data are
always accessible via the retrieval methods offered by
module DataFrames.
*)
PROCEDURE LoadDFFromOtherFileIntoMem(path,filename: ARRAY OF CHAR);
(*
Like LoadDFFromFileIntoMem but operates on the anchor
file denoted by path and filename. In case path and
filename are the empty string, this routine offers the
standard file opening dialog to interactively select an
anchor file for reading.
*)
(********************************************)
(*##### Assigning/Deassigning Data #####*)
(********************************************)
PROCEDURE AssignDatFraData;
(*
Assigns all data presently stored in memory in form of so
called data frames (see module DataFrames) to the
currently known models and model objects in case they are
public for writing (see DataAccess in module SysModBase).
To achieve the same goal for non-public, i.e. private,
models and model objects use routines from module
SysDatAccess. Use DeassignData to revert the effect of
this routine.
Such an assignment is only possible if the identifier of a
particular model object and its owning model match the
identifier given by the data value definition (see module
DataFrames for details). For instance the following data given
according to the data frame syntax (for EBNF see module
DataFrames):
(*============================================================*)
(* Model Parameters *)
(*============================================================*)
DATAFRAME Parameters; REMARK = 'For any logistic growth model' ;
MODEL = ANY; KEYCOLUMN = Ident; DATA:
(*============================================================*)
Ident Descr DfltVal MinVal MaxVal Unit RTC ;
(*------------------------------------------------------------*)
r 'Relative growth rate' 0.7 0.0 10.0 'd^-1' TRUE ;
K 'Carrying capacity' 700.0 0.0 1.0E+38 'g/m^2' FALSE ;
(*------------------------------------------------------------*)
END Parameters;
(*============================================================*)
will match model objects of the logistic growth model equation,
given they have been declared in the model definition program
with matching identifiers like this:
VAR
s : System;
m : Model;
grass : StateVar;
grassDot : Derivative;
r, K : Parameter;
DeclMObj ( s, "m.r", r, modParam );
DeclMObj ( s, "m.K", K, modParam );
and made public by calling
SetDataAccess (s, "m.r", rda, public);
SetDataAccess (s, "m.K", rda, public);
Routine DeclMObj and the other objects are all available from
module SysModBase. Above data frame Parameters can be assigned
to any model (see phrase MODEL = ANY) as long as the
identifiers listed in the key column headed with the identifier
'Ident' (see phrase KEYCOLUMN = Ident) match those specified in
DeclMObj. E.g. the DfltVal 0.7 tabulated for Ident = r is
assigned to the variable r (type Parameter). With the phrase
MODEL = LogGrowth it would be possible to have a more specific
match, i.e. 'LogGrowth.r'. The success of AssignDatFraData
requires the model has been declared as follows:
m := "m";
DeclModel(s, m, Euler, DESS, Dynamic,
NoInitialize, NoInput, NoOutput, NoTerminate, NoAbout);
To numerically solve the logistic equation use the parameters r
and K in this procedure as follows:
PROCEDURE Dynamic;
BEGIN
grassDot:= r*((K-grass)/K)*grass;
END Dynamic;
Data frames can be formatted freely, as long as they observe
the syntax (see module DataFrames). In addition
AssignDatFraData requires that column headers use reserved
identifiers. These are:
Reserved identifier State Model Monitoring
Variables Parameters attributes
------------------- --------- ---------- ----------
S Ident yes yes yes
S Descr yes yes yes
S Unit yes yes -
R DfltInit yes - -
R MinInit yes - -
R DfltVal - yes -
R MinVal - yes -
R MaxVal - yes -
B RTC - yes -
R ScaleMin - - yes
R ScaleMax - - yes
B Filing - - yes
B Tabulation - - yes
I Graphing * - - yes
where S = Identifier or string, R = real, I = integer number, B =
boolean. * denotes monitoring level
*)
PROCEDURE DeassignData;
(*
Reverts the effect of a previous call to
AssignDatFraData. Depending on the current preferences
(clearAtDeassignMode), either the previously present data
are restored or an undefined value is assigned to any
model or model object public for writing. Note: This
routine has no effect if executed in the 'ModelWorks' state
simulating or sub-state running (see module SimMaster)
respectively to avoid a crash during simulation because
you may assign undefREAL (from module DMConversions) to
model objects which are used in calculations. Instead a
sound is generated to inform the simulationist about the
refused operation.
*)
PROCEDURE AssignGlobSimPars;
(*
Assigns all data presently stored in memory in form of so
called data frames (see module DataFrames) to the global
simulation parameters. Use DeassignData to revert the
effect of this routine. Such an assignment is only
possible if the identifier of a particular global
simulation parameter matches the identifier given by the
data value definition (see module DataFrames and routine
AssignGlobalSimulationData from module SysDatAccess for
details).
*)
PROCEDURE AssignModelsMonitoringForLevel;
(*
Offers an entry form which let's the user define a level
on which the monitoring attributes are to be assigned to
the currently present model objects. If the dialog is
answered with OK all monitoring attributes of the entered
level such as curves, scales, or colors, are assigned
accordingly. The monitoring level is an integer as
tabulated in a column with reserved heading 'MonitLev'.
Any variable whose monitoring level is equal the current
monitoring level will be in display, any other will
remain invisible. At monitoring level 0 all monitoring
variables are discarded and there is normally no
monitoring done. Beyond an upper limit the same settings
from the last level are used at all times. This
mechanism allows for easy activation or deactivation,
respectively, of many monitoring variables with a single
command. There are even keyboard short cuts available to
alter the current monitoring level without this dialog.
IMPORTANT NOTE: Each time the monitoring level is changed
there happens actually a full assignment (calls
AssignAllMonitoring from module SysDatAccess), i.e. any
graphs, tables, graphing settings etc. present previously
to the switch of the level will be discarded and
overwritten. Thus, always save the current state to the a
data frame if you wish to preserve at least the monitoring
settings before changing to another level. Moreover, from
this principle follows, if you wish to preserve the
monitoring settings from several levels, make sure you
always save AND load (!) the to and from the data frame
before switching the monitoring level. Otherwise you loose
your precious editing since the saving does only write
newly edited monitoring attributes to the data frame for
the current monitoring level; for all other monitoring
levels it uses only the values currently stored in memory
from the last load of the data frame. IMPLEMENTATION
RESTRICTION: Only a maximum of 7 monitoring levels are
fully remembered.
*)
PROCEDURE AssignModelsTallyingForLevel;
(*
Similar to AssignModelsMonitoringForLevel. Offers an entry
form which lets the simulationist edit the tallying level
and cause an assignment of the tallying attributes to the
present model objects. For any model object with a
TallyLev equal to the current tallying level tally
statistics will be computed and output made according to
the current tallying specifications, typically provided
by means of data frames. Implies a data assignment as
provided by the routine AssignAllTallying from module
SysDatAccess.
*)
PROCEDURE PlaceSimEnvsWindows;
(*
Places all windows according to the frame definitions as
specified in the data frame with name "Windows". In case
the data frame has not been loaded into memory, procedure
does nothing. (Note, that the RAMSES shell may
automatically call this procedure when entering the
Simulation Session in case the sessions preferences are
set such that the data frame utils are automatically
activated!)
*)
(***********************************************************)
(*##### Storing Current Data on a Data Frame File #####*)
(***********************************************************)
PROCEDURE SaveDF;
(*
Saves the data of all currently available models and
model objects as data frames in the current anchor file.
Separate data frames are created for each class of model
objects, i.e. one for variables, for parameters, and for
monitoring attributes, again on a per model basis. Note,
all these data frames are written into the same file,
regardless of the number of files the data may have come
from when they were originally loaded. Upon first time
call to SaveDF, the standard file creating dialog is
offered, which lets the user choose the file on which to
save the data. Subsequent calls will write to the same
file unless SaveAsDF is called. IMPORTANT NOTE: During
the first call to this routine after having loaded
freshly data, the user is asked whether the original data
may actually be overwritten. However, subsequent calls
quietly overwrite the file without any warning!!!
*)
PROCEDURE SaveAsDF;
(*
Similar to SaveDF but offers always a file creating
dialog.
*)
(********************************)
(*##### Error Handling #####*)
(********************************)
PROCEDURE CheckForErrPresence;
(*
Checks for the presence of errors which might have been
encountered during past operations. In case
packageErrMode = suppressAllErrMode OR packageErrMode =
warnOnceErrMode possibly occurring errors are not
displayed but kept in memory for display till you call
this procedure.
*)
END SysDatAux.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib