ETHZ_Logo RAMSES_Logo_Right   RAMSES   RAMSES_Logo_Left Systems Ecology  
Start    search button      Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

DEFINITION MODULE SysStrctAux;

  (*******************************************************************

    Module  SysStrctAux     (ISIS_Version_1.2)

      Copyright (c) 1998-2006 by Andreas Fischlin and ETH Zurich.

    Purpose   Supports the interactive management of the structure
              of a complex system consisting of several so-called
              subsystems.

    Remarks   This module allows to configure subsystem variants
              or to establish the data exchange among subsystems
              (establishing I/O-links for data exchange among
              subsystems).  It is useful while working with
              complex, structured systems consisting of several
              dynamic models, e.g. when studying entire ecosystems.

              This module provides a part of the standard user
              interface offered by ISIS, i.e. the part which
              deals with the system structure (for the part
              dealing with data cf. module SysDatAux).

              See also modules SysStructure and SysVariants.

              This module belongs to ISIS
              Integrative Systems Implementation Software.


    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:  28/05/2002  AF

  *******************************************************************)


  FROM DMMenus IMPORT Menu, Command;
  FROM SysStructure IMPORT SubSystem;

  (* Error constants: sysStructAuxMsgOffset = DMLanguage.userBase + 430 .. 460-1 *)


  (*********************************************)
  (*#####   Subsystems' User Interfaces   #####*)
  (*********************************************)

  PROCEDURE HandOverSubSysMenuManagement(subSys: SubSystem;
                                         installCmdsP, removeCmdsP: PROC);

    (*
      Installs a section of the so-called system structure menu (see
      e.g.  procedure SysStructMenu from this module) for the
      subsystem denoted by subSys and which has been previously
      proclaimed as subsystem by procedure UseAsSubSystem from
      module SysStructure.  In this menu section the subsystem can
      maintain its own, subsystem specific menu commands.  However,
      since the display of that menu section typically depends on
      the current system structure, i.e.  the activation status or
      current variant of the subsystem subSys, the actual
      installation or deinstallation has to be done under control of
      ISIS (modules SysStrctAux and SysStructure).  The procedures
      handed over will be called whenever needed, e.g.  when the
      system structure is changed by the user (see menu command
      ConfigureSystem this module) or if the system definition
      program changes the structure by a call to procedure
      SetSysStructure (from module SysStructure).  Thus it is highly
      recommended to call this procedure whenever a subsystem wishes
      to maintain its own menu commands.

      The procedures passed as actual arguments have to fulfill the
      following functions:

      installCmdsP    Installs the subsystems specific
                      menu commands by calling install
                      routines from module DMMenus

      removeCmdsP     Removes the subsystems specific
                      menu commands as installed by installCmdsP
                      by calling remove routines from
                      module DMMenus

    *)


  (*****************************************)
  (*#####   Standard User Interface   #####*)
  (*****************************************)

  (*---------------------------------------------------*)
  (*=====   Easy menu and commands installation   =====*)
  (*---------------------------------------------------*)

  PROCEDURE InstallSysMenuAndUtils(menutitle: ARRAY OF CHAR);
    (*
      Installs a menu with the title 'menutitle' or if menutitle
      is the empty string, with the default title "System" plus
      all general utilities with standard names (cf.
      InstallSystemMenu, InstallSysConfigCmd, and InstallSysUtils
      for individual or otherwise custom use of these functions).
      Use SysStructMenu to learn about this menu if you wish to
      install further commands.
    *)

  (*-------------------------------------------------------------------*)
  (*=====   Custom installation of menu and individual commands   =====*)
  (*-------------------------------------------------------------------*)

  PROCEDURE InstallSystemMenu(menutitle: ARRAY OF CHAR);
    (*
      Installs a menu with the title 'menutitle' or if
      menutitle is the empty string, with the default title
      "System".  Use SysStructMenu to learn about this menu if
      you wish to install further commands.
    *)

  PROCEDURE InstallSysConfigCmd(configCmdTxt, configAlCh: ARRAY OF CHAR);
    (*
      Installs within menu SysStructMenu the main configuration
      command with the text 'configCmdTxt'.  The latter menu
      command is associated with procedure 'ConfigureSystem'
      and can also be activated with the alias char (keyboard
      equivalent) 'configAlCh'.  Use SysConfigCmd to learn
      about this command if you wish to control its behavior,
      e.g.  to enable or disable it according to specific
      needs.
    *)

  PROCEDURE InstallSysUtils(ioLinkCmdTxt,       ioLinkAlCh,
                            ioBrkLinkCmdTxt,    ioBrkLinkAlCh,
                            startDivertsCmdTxt, startDivertsAlChr,
                            stopDivertsCmdTxt,  stopDivertsAlCh: ARRAY OF CHAR);


  (*--------------------------------------------------*)
  (*=====   Accessing system menu and commands   =====*)
  (*--------------------------------------------------*)

  PROCEDURE SysStructMenu(): Menu;
  PROCEDURE SysConfigCmd(): Command;
  PROCEDURE GetSysStructMenuCmds(VAR cmds: ARRAY OF Command);



  (*------------------------------------------------*)
  (*=====   The commands offered by the menu   =====*)
  (*------------------------------------------------*)

  PROCEDURE ConfigureSystem;
    (*
      Procedure used by menu command installed via routine
      InstallSysConfigCmd. It lets the simulationist configure
      the system structure interactively.
    *)
  (* ------ *)
  PROCEDURE LinkSubSystems; (* calls implicitely SysModBase.EstablishAllLinks *)
  PROCEDURE UnlinkSubSystems;
  (* ------ *)
  PROCEDURE StartRedirections;
  PROCEDURE StopRedirections;
  (* ------ *)
  PROCEDURE AnyErrorsPresent;
  PROCEDURE EditAliasChars;
  PROCEDURE EditSysStructPrefs;
  PROCEDURE ResetSysStrctAux;


  (*********************************)
  (*#####   Extra Utilities   #####*)
  (*********************************)

  PROCEDURE ChooseSubSysVariant(subSys: SubSystem);
    (*
      Offers a dialog which lets the user set the variant of the
      subsystem denoted by subSys.  The routine is the same as that
      automatically installed by ISIS in the system menu for every
      currently active subsystem.
    *)

  PROCEDURE AssignDataToSubSysByDlg;
    (*
      Offers a dialog which lets the user check a subsystem and
      edit the content of the data assign command string
      (actually using SysMsgLingua.bulletinBoard) which is sent
      to the subsystem if the user clicks the 'Ok' button.  The
      utility uses routine AssignSubSysData from ISIS module
      SysStructure.
    *)


  (****************************************************)
  (*#####   Client Interface for Customization   #####*)
  (****************************************************)


  PROCEDURE SetSysStructPreferences(    packageErrMode : INTEGER;
                                        globLikePkgErrMode,
                                        showSysMode,
                                        showModelsMode,
                                        showInVsMode,
                                        showOutVsMode,
                                        showDerivsMode,
                                        showNewStatesMode,
                                        showAuxVsMode: BOOLEAN);

  PROCEDURE GetSysStructPreferences(VAR packageErrMode : INTEGER;
                                    VAR globLikePkgErrMode,
                                        showSysMode,
                                        showModelsMode,
                                        showInVsMode,
                                        showOutVsMode,
                                        showDerivsMode,
                                        showNewStatesMode,
                                        showAuxVsMode: BOOLEAN);

  CONST
    suppressAllErrMode = 0;  (* values used for packageErrMode *)
    warnOnceErrMode    = 1;
    immediateErrMode   = 2;
    debugErrMode       = 3;

    (*
      Routines SetSysStructPreferences and GetSysStructPreferences 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 SetSysStructPreferences 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 SetSysStructPreferences 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 SetSysStructPreferences affects the error
      mode of the packages 'ModelWorks' Data extension (SimData, menu
      "Data") and ISIS 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 + 450, i.e. [600..750]) 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 this package, e.g. file opening
                              or memory shortage errors etc.

      Parameters showSysMode till showAuxVsMode determine the way the
      about information on any ISIS system is displayed. You can
      control whether the about command in the I/O-window 'Models'
      of the standard user interface used by ISIS lists systems,
      models, and or model objects. Of course the about command
      (click into '?' button) can only be executed for non-hidden
      ISIS systems (see ISIS module SysModBase procedure HideSystem).

    *)

  PROCEDURE SetSysMenuShortCuts (     configAlCh,
                                      iolnkAlCh, iobrkAlCh,
                                      startRedirAlCh, stopRedirAlCh,
                                      chkErrAlCh, editPrefsAlCh, editAlChsAlCh: CHAR);
  PROCEDURE GetSysMenuShortCuts ( VAR configAlCh,
                                      iolnkAlCh, iobrkAlCh,
                                      startRedirAlCh, stopRedirAlCh,
                                      chkErrAlCh, editPrefsAlCh, editAlChsAlCh: CHAR);
   (*
     Above two procedures lets you control the keyboard short
     cuts used by the system structure menu commands.
     GetSysMenuShortCuts is typically used if you wish to modify
     only a few of the keyboard shortcuts in a

       GetSysMenuShortCuts(chkErrAlCh,...  ;
       SetSysMenuShortCuts(chkErrAlCh,...

     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:

        configAlCh        - ConfigureSystem
        iolnkAlCh         - LinkSubSystems
        iobrkAlCh         - UnlinkSubSystems
        startRedirAlCh    - StartRedirections
        stopRedirAlCh     - StopRedirections
        chkErrAlCh        - AnyErrorsPresent
        editAlChsAlCh     - EditAliasChars
        editPrefsAlCh     - EditSysStructPrefs
     *)

END SysStrctAux.

  Contact RAMSES@env.ethz.ch Last updated: 25-Jul-2011 [Top of page]