|
|
|
|
||
|
DEFINITION MODULE SysStructure; (******************************************************************* Module SysStructure (ISIS_Version_1.2) Copyright (c) 1998-2006 by Andreas Fischlin and ETH Zurich. Purpose Support the management of the structure of a complex system consisting of several so-called subsystems. Remarks This module allows to configure subsystem variants and to send messages to subsystems to assign their data. It is useful while working with complex, structured systems consisting of several dynamic models, e.g. when studying entire ecosystems. See also modules SysStrctAux and SysVariants. This module belongs to ISIS Integrative Systems Implementation Software. IMPLEMENTATION RESTRICTION: Note, this module uses the module StructModAux from the RAMSES auxiliary library. In particular be aware that it preempties the latter's functionality. Thus, you should no longer use StructModAux at all (this module is a full replacement with additional features) or you might get unpredictable results. Programming o Design Andreas Fischlin 28/05/1998 o Implementation Andreas Fischlin 28/05/1998 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: 21/01/2001 AF *******************************************************************) FROM SysModBase IMPORT System; (* Error constants: sysStructureMsgOffset = DMLanguage.userBase + 430 .. 460-1 *) (*********************************************************) (*##### Declaring Subsystems & System Structure #####*) (*********************************************************) (*-----------------------------*) (*===== Master System =====*) (*-----------------------------*) TYPE SystemStructure = BITSET; SubSystem = INTEGER; (* actually limited to range [0..Cardinality(SystemStructure)]! *) DefSysStructProc = PROCEDURE (VAR SystemStructure); MakeMsgProcedure = PROCEDURE (SubSystem, VAR ARRAY OF CHAR); PreparationRoutine = PROC; PROCEDURE UseAsMasterSystem(masterSys: System; mainAnchor: ARRAY OF CHAR; defSysStructP: DefSysStructProc; configInitP: PROC; makeSetVariCmdP: MakeMsgProcedure; makeDatAssgnCmdP: MakeMsgProcedure; configTermP: PROC ); (* Proclaims masterSys as the main master system. It also installs a few global procedures which are needed to manage the message exchange among the master and the subsystems during reconfigurations of the system structure (see also routine UseAsSubSystem from this module). You have to be the owner of the system to proclaim it as master, i.e. argument 'masterSys' may not be the 'unknownSystem', but has to be declared prior to the call of UseAsMasterSystem by means of routines DeclSystem from module SysModBase. The meaning of the other arguments: mainAnchor File name (possibly preceeded by a path) which denotes the main data frame file used by the system (see module DataFrames). This file is loaded into memory automatically during ISIS' AUTOCONFIGURATION (see routine ExecuteEntirePreparation, this module), but no assignments are done (see module SysDatAccess). The data frames in 'mainAnchor' are typically used for an automatic configuration of the system structure, given a data frame 'SystemStructure' can be loaded (see also below the routines GetSysStructureFromDTF, GetSubSysVariantFromDTF, AddPreparationRoutine, section AUTOCONFIGURATION of ExecuteEntirePreparation). If the empty string is passed as actual argument for mainAnchor, a file opening dialog is offered (in this case, should you want to learn about the name of the file which was actually opened, you need to use module DatFraAux (see procedure InspectDataFrame, parameter storedOnFsWithName and/or procedure InspectDataFrameFile)). No filtering takes place while loading the data frames, i.e. the filter range is set to [DataFrames.minFilter..DataFrames.maxFilter]. All following handlers are optional and can be passed as actual argument using the dummy procedures such as NoAction exported from this module (see below). defSysStructP Procedure used to define the system structure. It overrules the automatic self-configuration ISIS will otherwise perform by retrieving and analyzing the data frame 'SystemStructure'. Typically the latter data frame is automatically loaded via the data frame file 'mainAnchor'. Note the argument is an in/out parameter; upon entering the procedure it contains the system structure as defined according to the priority rules described in comment of routine AddPreparationRoutine, section AUTOCONFIGURATION. Thus defSysStructP serves as a filtering routine possibly altering the system structure as retrieved by ISIS (see also comments on routines GetSysStructureFromDTF). configInitP Procedure which is executed at the very begin of a (re)configuration of the system's structure which starts at the very end of all preparations which have typically loaded data frames. You may set here global simulation parameters, e.g. call routine AssignGlobalSimulationData from ISIS module SysDatAccess. makeSetVariCmdP Procedure used to construct a "set variant command" on behalf of a particular subsystem (see also below routine UseAsSubSystem) while (re)configuring the system's structure. A set variant command typically consists of value definitions according to the SML (System Message Language) as provided by module SysMsgLingua. The command is expected to contain at least the reserved value definition 'variantList' (type charstring). A variant list typically defines a combination of variants for a given subsystem by listing the variants in the string delimited by "|" (= variDelim from ISIS module SysVariants) (see also comment of routine SetSubSysVariant from this module). This procedure is called whenever a variant needs to be set, e.g. after a (re)configuration of a subsystem, i.e. the subsystem is being activated, or the entire system structure is to be modified. Note in case you pass DontMakeMsg as actual argument for this procedure this module follows a default strategy to define variants for its subsystems by the following steps: 1) GetSubSysVariantFromDTF 2) GetSubSysVariant 3) GetDefltSubSysVariant (all procedures from this module, see also their comments). As soon as one of the involved procedures returns actually a variant list (value definition 'variantList' is no longer empty) no further steps are executed. makeDatAssgnCmdP Procedure used to construct a data assignment command on behalf of a particular subsystem (see also below routine UseAsSubSystem) while (re)configuring the system's structure. A data assignment command typically consists of value definitions according to the SML (System Message Language) as provided by module SysMsgLingua. This procedure is called whenever some data assignment may have become necessary; e.g. after a (re)configuration of a subsystem, i.e. a new variant has been set, or the entire system structure is to be modified. Note: ISIS does automatically publish in the datAssgCmd string these reserved value definitions in addition to what makeDatAssgnCmdP has generated (see also formal parameter assignDataP of procedure UseAsSubSystem, this module): ident type -------------- ------- newStructure boolvar newVariant boolvar dataAssigned boolvar Consequently, there is no need for makeDatAssgnCmdP to maintain these value definitions. It is recommeded to reserve and maintain from within makeDatAssgnCmdP also ident type -------------- ------- dataAreNew boolvar configTermP Procedure which is executed at the very end of a (re)configuration of the system's structure. E.g. you may pass EstablishAllLinks (from ISIS module SysModBase) as actual parameter for configTermP. NOTE: None of the passed event handler routines is executed immediately, i.e. while calling UseAsMasterSystem. All event handler routines are used at a later time and may be called by the following routines: this module module SysStrctAux ------------------------ ------------------- SetSysStructure ConfigureSystem SetSubSysVariant ChooseSubSysVariant AssignSystemsData AssignSubSysData AssignDataToSubSysByDlg ExecuteEntirePreparation AUTOCONFIGURATION defSysStructP, configInitP, and configTermP are only called by SetSysStructure, ConfigureSystem, ExecuteEntirePreparation, and AUTOCONFIGURATION. makeSetVariCmdP and makeDatAssgnCmdP are called by all tabulated routines. *) (* For your convenience use following routines as actual argument when calling UseAsMasterSystem in case you don't want to make use of any of the optional handlers. *) PROCEDURE DontSetSysStructure(VAR struct: SystemStructure); (* as defSysStructP *) PROCEDURE NoAction; (* as configInitP or configTermP *) PROCEDURE DontMakeMsg(subSys: SubSystem; VAR datAssgCmd: ARRAY OF CHAR); (* as makeSetVariCmdP or makeDatAssgnCmdP *) (*--------------------------*) (*===== SubSystems =====*) (*--------------------------*) TYPE SSShortID = ARRAY [0..7] OF CHAR; (* Sub System Short Identifier *) BooleanFct = PROCEDURE (): BOOLEAN; SendMsgProcedure = PROCEDURE (VAR (* In/Out *) ARRAY OF CHAR); VAR unknownSubSystem: SubSystem; (* read only! *) unknownSSShortID: SSShortID; (* read only! *) PROCEDURE UseAsSubSystem( subSysName, subsysShortId: ARRAY OF CHAR; VAR subSys: SubSystem; declVariantsP: PROC; activateSubSysP, deactivateSubSysP: PROC; subSysIsActiveP: BooleanFct; setVariantsP: SendMsgProcedure; linkInsP: PROC; assignDataP: SendMsgProcedure; updateSysP: PROC); (* Proclaims system with name 'subSysName' as a subsystem. It also installs associated procedures which are needed to manage its presence, structure via variants, and data. Parameter 'subSysName' is a string used to name the subsystem (see also parameter sysName of procedures DeclChildSystem (or DeclSystem) from module SysModBase; but note, for your convenience, subSysName may differ from sysName (not inforced by ISIS), but it is recommended to use the same name for clarity in the resulting user interface: For instance the automatic display of the variants in the about window of a system as provided by ISIS functions only if 'subSysName' and 'sysName' match exactly (of course case sensitively). Parameter 'subsysShortId' is a short identifier which denotes again uniquely the subsystem, e.g. in data frames (see also SSShortID; note, may contain '_'). Parameter 'subSys' denotes the subsystem and returns a unique value associated with the subsystem. For instance use it to configure a particular system structure (see type SystemStructure) by listing the subsystem you wish to activate as an element in a set of type SystemStructure. All other parameters serve to exchange messages among this module, the master system, and the installed subsystems. The procedures passed as actual arguments have to fulfill the following functions: declVariantsP Declares all variants known by the subsystem e.g. if several variants of model equations can be used, they are typically defined as so-called variants of the subsystem. Call routines DeclareVariantSet and AddVariant from module SysVariants from within this procedure. Note, this routine is executed only once during execution of UseAsSubSystem. activateSubSysP Activates the subsystem as a dynamic subsystem. It typically declares all its dynamic models and model objects whenever SetSysStructure or another ISIS routine asks the subsystem to do so. Note, this routine is only called by ISIS, when the subsystem is currently not dynamically active, i.e. subSysIsActiveP (see below) has returned FALSE. deactivateSubSysP Deactivates the subsystem as a dynamic subsystem. It typically undeclares all its dynamic models and model objects. Outputs required by other subsystems ought still to be provided, e.g. as sample and hold values or, alternatively, if other subsystems have installed an AtLinkBreakProc, they can try to get the needed inputs from other sources, e.g. from a file (see in this context also module SysIODivert). Note, this routine is only called by ISIS, when the subsystem is currently dynamically active, i.e. subSysIsActiveP (see below) has returned TRUE. subSysIsActiveP Returns wether subsystem is currently active as a dynamic subsystem (level DESS, SQM, or DEVS) setVariantsP Configures the subsystem according to a particular new set of variants. The latter is passed within the argument message, which lists all current variants in the same sequence as they have been declared by declVariantsP (see above). IMPORTANT NOTE: The string parameter is called by name (not value), since the subsystem should deal with this message string as an input/output parameter. It contains the variant list as the reserved SML value definition 'variantList' (see also module SysMsgLingua). ISIS expects your routine to retrieve this list with GetStrFrom from SysMsgLingua, to set the variants and if successful to report this back to ISIS by calling PublishBool(msg,"variantSet",TRUE). Only if this result is returned, ISIS will actually store the new variant by setting the current variant for each variant set used by the subsystem (see also module SysVariants). If the value definition 'variantSet' is returned with value FALSE, ISIS produces an error message. The variantList is always checked by ISIS, and setVariantsP is only called by ISIS if the variant is really new, i.e. different from that possibly previously set, and is a legal one. in summary ISIS does automatically publish in the setVariantCmd string these reserved SML value definitions (see module SysMsgLingua): ident type -------------- ------- variantList charstring newStructure boolvar newVariant boolvar variantSet boolvar The current variant settings as returned by ISIS (see e.g. procedure GetCurOrdTuple, this module) are not yet changed when ISIS calls setVariantsP. This takes only place as soon as you return control back to ISIS, i.e. you can expect that a routine like GetCurOrdTuple returns the new variants only in the procedure(s) called next, e.g. linkInsP or assignDataP (see below). linkInsP (Re)establishes links in case the subsystem has some inputs which depend on outputs from other subsystems. For an autonomous subsystem pass as actual argument NoInputs. For a subsystem with only global inputs (e.g. provided by the master system), pass as actual argument DontLinkIns. For a subsystem with inputs which depend on the outputs of other subsystems, but all unqualified input identifiers match unqualified output identifiers (see also routine EstablishAllLinks from module SysModBase), pass as actual argument DontLinkIns. Then the global routine EstablishAllLinks is sufficient, e.g. passed as actual argument for configTermP when calling UseAsMasterSystem to establish all linking for all your subsystems. One call to the global EstablishAllLinks is likely to be more efficient when called at the end of the entire system (re)configuration as if it would be called by every subsystem repeatedly. A non empty procedure linkInsP is only needed if the subsystem subSys requires explicit pairing between output variables of an another subsystem and its inputs. It typically calls routine EstablishLink and AddLinkHandlers from module SysModBase. assignDataP Asks the subsystem to assign all data to its models and model objects. Data are typically taken from data frames by using routines from module DatFraUsage, e.g. by announcing its interest in particular data via routine AnnounceDataInterest. IMPORTANT NOTE: The parameter is called by name (not value), since the subsystem should deal with this message string as an input/output parameter. E.g. the subsystem should set the value definition "dataAssigned" (boolvar, see module SysMsgLingua) to let the master know about the final success of the data assignment. IMPORTANT NOTE: ISIS does automatically publish in the datAssgCmd string these reserved SML value definitions (see module SysMsgLingua) in addition to what makeDatAssgnCmdP has generated (see formal parameter makeDatAssgnCmdP of procedure UseAsMasterSystem, this module) before ISIS calls assignDataP: ident type -------------- ------- newStructure boolvar newVariant boolvar dataAssigned boolvar updateSysP Asks the subsystem to update its representation e.g. according to current configuration See also routine HandOverSubSysMenuManagement from module SysStrctAux for further possibilities to manage subsystems, should you wish to have a subsystem specific user interface. NOTE: Routine declVariantsP is executed immediately, i.e. while calling UseAsSubSystem. All other installed event handler routines are used at a later time. For more details on the exact sequence of execution of the installed routines, see comments on AUTOCONFIGURATION and procedure ExecuteEntirePreparation from this module. IMPLEMENTATION RESTRICTION: Note, a proclamation of a subsystem is considered to be irreversible (There is no routine to revert this effect for an individual subsystem). However, since the overall system dynamics depend on the status of individual subsystems, i.e. whether particular subsystems are dynamically active or not (see parameters activateSubSysP or deactivateSubSysP), and since this status can be controlled at run time, this should not be a major restriction. What is basically proclaimed irreversibly is only the maximum usable subsystems. However, as an entire system, the master system and all subsystems can be deinstalled at once (routine ForgetSystemUsage), allowing for another round of usage of a master and its subsystems. IMPLEMENTATION RESTRICTION: This module supports only a single, structured system at a time which can consist of at most as many elements as fit into the basic Modula-2 type BITSET (e.g. 16 subystems). *) (* for your convenience use following routines as actual arguments when calling UseAsMasterSystem or UseAsSubSystem in case you don't wanna use any of the optional functions. Note, procedures activateSubSysP, deactivateSubSysP, and subSysIsActiveP are mandatory and need always to be provided. *) PROCEDURE NoInputs; PROCEDURE DontLinkIns; PROCEDURE NoVariants; PROCEDURE NoSetVariants(VAR (*In/Out*) setVariantCmd: ARRAY OF CHAR); (* Returns via reserved value definition 'variantSet' always TRUE *) PROCEDURE NoDataAssign (VAR (*In/Out*) datAssgCmd: ARRAY OF CHAR); (* Returns via reserved value definition 'dataAssigned' always TRUE *) PROCEDURE NoUpdate; (******************************************************************* (*--------------------------------------------------------*) (*===== General Rules on Event Handling Routines =====*) (*--------------------------------------------------------*) In summary, the event handling routines as installed by UseAsMasterSystem and UseAsSubSystem may be called directly or indirectly by the following routines: this module module SysStrctAux ------------------------ ------------------- SetSysStructure ConfigureSystem SetSubSysVariant ChooseSubSysVariant AssignSystemsData AssignSubSysData AssignDataToSubSysByDlg ExecuteEntirePreparation AUTOCONFIGURATION You can always learn where your handler is called from. First observe that some routines may call the core routines SetSysStructure, SetSubSysVariant, and AssignSubSysData directly or indirectly. The actual procedure chain is formed according to these calling relationships: Routine calls --------------- --------------- AUTOCONFIGURATION * SetSysStructure ExecuteEntirePreparation * SetSysStructure ConfigureSystem SetSysStructure SetSysStructure SetSubSysVariant ChooseSubSysVariant SetSubSysVariant SetSubSysVariant AssignSubSysData AssignSystemsData AssignSubSysData AssignDataToSubSysByDlg AssignSubSysData Secondly, look at these reserved value definitions newStructure only TRUE if SetSysStructure in procedure chain newVariant only TRUE if SetSubSysVariant in procedure chain to learn by which way your handler has been called. E.g. if you call AssignSystemsData, both newStructure as well as newVariant are FALSE. If you call SetSubSysVariant, newStructure is FALSE and newVariant is TRUE. If you call SetSysStructure, both newStructure as well as newVariant are TRUE. ------------------- * WhileConfiguringFromScratch (this module) returns TRUE, otherwise FALSE ********************************************************************) PROCEDURE ForgetSystemUsage; (* Forgets at once the master system and all subsystems currently in use, allowing for another round of usage. Note, the actual existence of the involved systems as declared by routine DeclSystem or DeclChildSystem from SysModBase is not affected in any way by ForgetSystemUsage. Note also that data frames are neither affected, i.e. the effect of the loading of the mainAnchor file (see routine UseAsMasterSystem) is not reverted; call DropAllDataFrames from DataFrames or DropDataFrame from DatFraAux to acchieve such an effect. *) (******************************************************************) (*##### Controlling Actual System Structure & SubSystems #####*) (******************************************************************) (*--------------------------------*) (*===== System Structure =====*) (*--------------------------------*) PROCEDURE DefineSysStructure ( syss: SystemStructure); (* Defines a default system structure as given by syss without actually affecting the system structure right away or triggering any events such as SetSysStructure does. The passed system structure is only remembered and affects the current or next AUTOCONFIGURATION. It is typically used during start-up of a system definition program to provide a configuration definition in case no data frame "SystemStructure" is available; the AUTOCONFIGURATION mechanism of ISIS may then use it (see also comment on routine AddPreparationRoutine this module, section AUTOCONFIGURATION). RESTRICTION: This routine is without effect if called during a configuration such as an AUTOCONFIGURATION or a call to SetSysStructure, i.e. by calling it from within defSysStructP (see UseAsMasterSystem). *) PROCEDURE SetSysStructure ( syss: SystemStructure); (* Forces all installed subsystems to activate (or to deactivate, respectively), their dynamic models as given by the actual argument for syss. Thus this function allows to configure the overall system structure under control of the callee. Any given system structure can be described by a set, which lists an element for each subsystem to be activated (subsystems are referenced with the value returned in subSys when calling UseAsSubSystem). It is also possible to access this function via the standard user interface offered by module SysStrctAux, i.e. routine ConfigureSystem. IMPORTANT NOTE: This routine will cause a whole chain of actions to take place. In particular it will also call all routines installed by UseAsMasterSystem and for every subsystem those installed by UseAsSubSystem. Consequently, this routine must be without any effect if called during an already running (re)configuration, e.g. like that taking place during an AUTOCONFIGURATION. Furthermore, if SetSysStructure can be called successfully, DefineSysStructure must have no effect at all. In this context see please also the comments on routine DefineSysStructure and on AddPreparationRoutine, in particular the section AUTOCONFIGURATION, both from this module. *) PROCEDURE GetSysStructure (VAR syss: SystemStructure); (* Returns the current system structure or overall system configuration in syss. *) PROCEDURE GetSysStructureFromDTF(VAR syss: SystemStructure); (* Returns the system structure as specified in the data frame "SystemStructure" (see module DataFrames for syntax and semantics of data frames). Ex.: DATAFRAME SystemStructure; KEYCOLUMN = SubSystem; REMARK = 'Structure of ForClim System'; DATA: (*-------------------------*) SubSystem Active ; (*-------------------------*) C TRUE ; W TRUE ; E TRUE ; M FALSE ; T TRUE ; S TRUE ; D FALSE ; H FALSE ; I FALSE ; P FALSE ; (*-------------------------*) END SystemStructure; Column 'SubSystem' lists for every installed subsystem its subsysShortId (SSShortID) and the desired activation status in the column 'Active'. The identifiers 'SystemStructure' and 'Active' are reserved. Of course the data frame SystemStructure may contain more columns than just the one shown here (cf. routine GetSubSysVariantFromDTF). *) (*--------------------------------------*) (*===== Variant of a Subsystem =====*) (*--------------------------------------*) PROCEDURE SetSubSysVariant(subSys: SubSystem; vlist: ARRAY OF CHAR); (* Forces the subsystem denoted by subSys (value returned by UseAsSubSystem) to configure itself according to the combination of variants as specified in the actual argument variantlist. Variants are specified via an identifier (see also module SysVariants). Since a subsystem can have several properties where it distinguishes variations or versions, a variantlist typically consists of several elements. Each element represents a particular variant of a particular property. E.g. ForClim-C may distinguish the following properties: - internal temporal resolution (TemporalResolution) recognized by equations and data (note, is independent from climate dynamics) - model variant of stochastic process to simulate temporal variability, such as interannual variability with an autoregressive model, or correlations among weather variables (StochasticProcess), - OutputTransformation, - the type of function used to compute climate changes (ClimChgFunction). A typical variantlist to be sent to ForClim-C may then look like: "monthly|crossCorr|outTransfA|noCC". Use variDelim from SysVariants to delimit individual variants. Note, it is also possible to access the functionality of SetSubSysVariant via the standard user interface offered by module SysStrctAux. If you have installed it (see routines InstallSystemMenu or InstallSysMenuAndUtils from module SysStrctAux), each subsystem in use (see UseAsSubSystem) has its own special menu command in this menu while it is active. It allows you to modify the current variants by dialogs with the same final effect as a call to SetSubSysVariant. IMPORTANT NOTE: vlist can optionally also be a SML command (see ISIS module SysMsgLingua). This means that the actual argument for vlist may be a message which contains any SML value definitions; e.g. the message string may be constructed via routine makeSetVariCmdP. In all of these cases you have only to make sure, the variant to which you want to set the subsystem is published in the message string as the reserved value definition 'variantList'. Ex.: makeSetVariCmdP(subSys, msg); PublishStr(msg,'variantList',vlist); SetSubSysVariant(subSys,msg); *) PROCEDURE GetSubSysVariant(subSys: SubSystem; VAR vlist: ARRAY OF CHAR); (* Returns in vlist the current internal variant combination of the subsystem denoted by subSys (value returned by UseAsSubSystem). See also routine SetSubSysVariant for further explanations on the meaning of vlist. *) PROCEDURE GetSubSysVariantFromDTF(subSys: SubSystem; VAR vlist: ARRAY OF CHAR); (* Returns in vlist the variant combination as specified in the data frame "SystemStructure" (see moduele DataFrames for syntax and semantics of data frames) for the subsystem denoted by subSys (value returned by UseAsSubSystem). See also routine SetSubSysVariant for further explanations on the meaning of vlist. Ex.: DATAFRAME SystemStructure; KEYCOLUMN = SubSys; REMARK = 'Configuration of ForClim System'; DATA: (*--------------------------------------------------------------*) SubSys Variant ; (*--------------------------------------------------------------*) C 'monthly|phaseAvrgdAR1|outTransfE|transientCC'; W 'phaseAvrgdAR1'; E 'pet24|swb24|drStr24'; M ''; T 'fct24'; S ''; D ''; H ''; I ''; P ''; (*--------------------------------------------------------------*) END SystemStructure; Column 'SubSys' lists for every installed subsystem its subsysShortId (SSShortID) and the desired variant combination in the column 'Variant'. The identifiers 'SystemStructure' and 'Active' are reserved. Of course the data frame SystemStructure may contain more columns than just the one shown here (cf. routine GetSysStructureFromDTF). *) PROCEDURE GetDefltSubSysVariant(subSys: SubSystem; VAR vlist: ARRAY OF CHAR); (* Returns in vlist the default variant combination for the subsystem denoted by subSys (value returned by UseAsSubSystem). See also routine SetSubSysVariant for further explanations on the meaning of vlist. The default variant combination is given by the first variant for each variant set maintained by the subsystem (see also module SysVariants). *) (*---------------------------------------------*) (*===== Assigning Data to a Subsystem =====*) (*---------------------------------------------*) PROCEDURE AssignSystemsData(VAR(*In/Out*) datAssgCmd: ARRAY OF CHAR); (* Asks all installed subsystems to assign their data to the models and model objects. msg contains a SML (System Message Language) message (see ISIS module SysMsgLingua) which describes the data involved in the assignment. E.g. if the site changes the msg may be: "Site = 'Churchill'". ISIS expects, that each subsystem publishes the reserved value definition 'dataAssigned' accordingly to its success in the parameter datAssgCmd it receives; otherwise ISIS will produce an error message. *) PROCEDURE AssignSubSysData( subSys: SubSystem; VAR(*In/Out*) datAssgCmd: ARRAY OF CHAR); (* Asks the subsystem denoted by subSys to assign its data to the models and model objects it owns. msg contains a SML (System Message Language) message (see ISIS module SysMsgLingua) which describes the data involved in the assignment. E.g. if the site changes the msg may be: "Site = 'Churchill'". datAssgCmd is an in/out parameter. ISIS expects, that the subsystem publishes the reserved value definition 'dataAssigned' accordingly to its success. *) (**********************************************************) (*##### Preparation of System Structure and Data #####*) (**********************************************************) PROCEDURE AddPreparationRoutine(rp: PreparationRoutine); PROCEDURE VoidPreparationRoutine(rp: PreparationRoutine); (* A PreparationRoutine makes something ready for use, i.e. it deals with some task which can only be executed if the entire system has been installed and needs some final preparation in order to be ready for simulation experiments. Such a routine is called automatically at the end of the starting up process of a System Definition Program (SDP) which installs a system. Typically you use this routine to process some data, e.g. to load some data frames from files into memory (in addition to the mainAnchor file, see above routine UseAsMasterSystem). This may serve to perform some global, initial computations needed at the begin of a complex simulation experiment (global means a task different from a model specific Initialize task, see module SysModBase, e.g. routine DeclModel and formal parameter initialize). Preparation routines are called in the same order as they have been installed. AUTOCONFIGURATION: Note, there is a default preparation routine installed internally. It is a routine which configures automatically the system structure as the last of all preparation routines. Definitions of the system structure are recognized according to these priority rules: 1) DefineSysStructure (called previously) 2) GetSysStructureFromDTF 3) defSysStructP (as installed via UseAsMasterSystem) If GetSysStructureFromDTF has success in retrieving valid data from the data frame "SystemStructure" the structure as previously defined by DefineSysStructure is ignored. Typically the 'mainAnchor'-file (see above, routine UseAsMasterSystem) contains the reserved data frame 'SystemStructure'. This will then automatically result in a system structure according to the specifications given in the data frame. Alternatively, you can ensure to overrule what is present in the data frames by routine defSysStructP, which you have installed while calling procedure UseAsMasterSystem. This gives you a last word over the actual system structure resulting from the auto-configuration. Note, if you never called DefineSysStructure, nor the data frame "SystemStructure" can be used successfully, nor defSysStructP defines a non-trivial system structre, the empty set is used and consequently no subsystems will be activated. For more details on exact sequence of events during an AUTOCONFIGURATION see comments on routine ExecuteEntirePreparation (this module). IMPLEMENTATION RESTRICTION: Preparation routines are a replacement for 'ModelWorks'' InstallDefSimEnv from module SimMaster, which you should no longer use or you defy all preparation routines. *) PROCEDURE ExecuteEntirePreparation; (* Executes an entire system preparation. Note, the AUTOCONFIGURATION, which occurrs automatically when you enter the simulation environment by a call to RunSimEnvironment (from 'ModelWorks' module SimMaster), does simply call ExecuteEntirePreparation. ExecuteEntirePreparation calls routines you have installed in ISIS by UseAsMasterSystem and UseAsSubSystem in this sequence: 1) FOR all installed subsystems which are active - deactivateSubSysP 2) DataFrames.DropAllDataFrames 3) DataFrames.LoadDataFrames('mainAnchor' (see UseAsMasterSystem) 4) any client installed preparation routines in sequence of installation (see AddPreparationRoutine) 5) defSysStructP (see UseAsMasterSystem) 6) configInitP (see UseAsMasterSystem) 7) FOR all installed subsystems - activateSubSysP (if to be activated, see UseAsSubSystem) or - deactivateSubSysP (if to be deactivated, see UseAsSubSystem) 8) FOR all installed subsystems (if newly to be activated) - makeSetVariCmdP (see UseAsMasterSystem) - setVariantsP (see UseAsSubSystem) - makeDatAssgnCmdP (see UseAsMasterSystem) - assignDataP (see UseAsSubSystem) - linkInsP (see UseAsSubSystem) 9) FOR all installed subsystems - updateSysP (see UseAsSubSystem) 10) configTermP (see UseAsMasterSystem) Note, if you call SetSysStructure (this module) or ConfigureSystem (from module SysStrctAux), not the entire sequence listed above is executed. Instead the steps 5 (if currently no subsystem active), 6,7,8, and 9 are executed only. Thus steps 1) to 5) can be considered to form the primary initialization, steps 6) to 9) the reconfiguration of a system structure. During a configuration where all steps are executed, procedure WhileConfiguringFromScratch (this module) returns TRUE. Finally note, subSysIsActiveP may be called anytime throughout the execution of ExecuteEntirePreparation. IMPORTANT NOTE: The effect of ExecuteEntirePreparation is the same as when you call the 'ModelWorks'' InstallDefSimEnv routine from module SimMaster, or by choosing any of the corresponding menu command(s) from within 'ModelWorks'' standard simulation environment (all preparations are done on all subprogram levels, i.e. by every InstallDefSimEnv routine, given AddPreparationRoutine has been called on that subprogram level). *) PROCEDURE WhileConfiguringFromScratch(): BOOLEAN; (* Returns TRUE during any running configuration which involves all steps as described in the comment of routine ExecuteEntirePreparation, i.e. an AUTOCONFIGURATION or a call to ExecuteEntirePreparation. In particular it lets you know wether the running configuration has also reloaded the main anchor with all the consequences this may have on system structure, variants, and data usage. This routine may be useful for you, since several routines you have installed in ISIS by UseAsMasterSystem and UseAsSubSystem can be called in many circumstances (e.g. setVariantsP, linkInsP, assignDataP, updateSysP etc.). *) (***************************) (*##### Utilities #####*) (***************************) PROCEDURE ShowSubSysVariant(subSys: SubSystem; inAboutW: BOOLEAN); (* Documents the current configuration of the subsystem, i.e. its variants. If inAboutW = TRUE, the output is written into the about window (see enumeration type MWWindow, i.e. element AboutMW, from module SimBase) of the 'ModelWorks' standard simulation environment, and only, if this window is currently already open. If inAboutW = FALSE, any currently selected output window receives the documentation. You can use this utility to implement an about procedure of a model which makes use of variants (see procedure DeclModel from ISIS module SysModBase). Note, if the subsystem is currently not dynamically active, then the window is only cleared and no visible documentation is generated. *) PROCEDURE CheckVariantList(subSys: SubSystem; VAR(*speed-up*) vlist: ARRAY OF CHAR; VAR listIsOk: BOOLEAN); (* Returns in listIsOk wether the combination of variants as given by vlist is well defined, i.e. contains only variant elements which have been properly declared (see procedure AddVariant from SysVariants), belonging to a known variant set (see procedure CreateVariantSet from SysVariants), and define a combination which has not been forbidden as illegal (see procedure ForbidVCombination from SysVariants). If any error is detected, the routine generates an error message using module Errors and the error constants as described at the begin of this definition. IMPORTANT NOTE: Normally, you don't need to call CheckVariantList in procedure setVariantsP (see routine UseAsSubSystem, this module) yourself. This is already done by ISIS and your setVariantsP procedure is never called if an attempt has been made to pass an invalid vlist, e.g. via data frames or by a call to SetSubSysVariant (this module). *) PROCEDURE VListToOrdTuple( subSys: SubSystem; VAR(*speed-up*) vlist: ARRAY OF CHAR; VAR ordTuple: ARRAY OF INTEGER); (* Returns in ordTuple the tuple of ordination numbers corresponding to the variant combination given by vlist for the subsystem subSys. You call this routine typically from within setVariantsP (see routine UseAsSubSystem, this module); thus, no checking for the correctness of vlist is made (that's already done by ISIS when passing a vlist to setVariantsP). In case an element in vlist has never been properly declared as a variant of a variant set owned by the subsystem (see procedures CreateVariantSet and AddVariant from SysVariants), the corresponding element in ordTuple will not be defined and a negative number will be returned instead (VListToOrdTuple calls internally procedure OrdInVS from SysVariants). The same is true if any dimensions should mismatch, i.e. ordTuple is always filled up to its last element, i.e. HIGH(ordTuple), with undefined values if any of the input parameters does not sufficiently define all elements of ordTuple. *) PROCEDURE GetCurOrdTuple( subSys: SubSystem; VAR ordTuple: ARRAY OF INTEGER); (* Returns in ordTuple the tuple of ordination numbers corresponding to the current variant combination of the subsystem subSys. You call this routine typically from within setVariantsP (see routine UseAsSubSystem, this module). Note, should a particular variant combination not have been set yet, which is for instance the case the very first time ISIS calls setVariantsP or after activating the subsystem, ordTuple contains not valid, negative values, i.e. undefined ordination numbers, to signal that the current ones are not yet set (see also module SysVariants, in particular routines CreateVariantSet and AddVariant). Any superfluous elements in ordTuple are again filled with undefined ordination numbers, i.e. negative values. *) PROCEDURE GetMainAnchor(VAR mainAnchor: ARRAY OF CHAR); (* Returns the main anchor file name (may contain a path) as declared by the last call to UseAsMasterSystem. *) PROCEDURE NoOfSubSystems(): INTEGER; (* Returns the number of subsystems which are currently in use *) PROCEDURE NoOfVSetsInSubSystem(subSys: SubSystem): INTEGER; (* Returns the number of variant sets the subsystem 'subSys' currently uses. *) PROCEDURE GetSSShortID(subSys: SubSystem; VAR ssshortid: ARRAY OF CHAR); (* Returns in ssshortid the short identifier which has been installed for subsystem subSys by a call to procedure UseAsSubSystem. It returns the empty string in case the subystem denoted by subSys has never been installed, thus this routine can also be used to learn whether the subsystem is currently actually installed. *) PROCEDURE GetSubSysName(subSys: SubSystem; VAR subSysName: ARRAY OF CHAR); (* Returns in subSysName the name string which has been installed for subsystem subSys by a call to procedure UseAsSubSystem. It returns the empty string in case the subystem denoted by subSys has never been installed. *) END SysStructure.
|
||
|
|
|