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

DEFINITION MODULE SysIODivert;

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

    Module  SysIODivert     (ISIS_Version_1.2)

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

    Purpose   Divert (redirect) subsystem inputs or outputs.

    Remarks   A diverted input is read from a file.
              A diverted output is written to a file.

              This module belongs to ISIS
              Integrative Systems Implementation Software.


    Programming

      o Design
        Andreas Fischlin          20/05/1998

      o Implementation
        Andreas Fischlin          20/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:  29/05/1998  AF

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


  TYPE
    Redirection;

  (* Error constants: sysIODivertMsgOffset = DMLanguage.userBase + 420 .. 430-1 *)

  VAR
    noRedirection: Redirection; (* read only *)

  (*

    Redirections can coexist with data linking among subsystems as
    provided by module SysModBase.  In case of an output redirection, the
    outpus are simply also written in parallel to the output file, in case
    of inputs the data received via links are overwritten with those which
    could be read from the currently open input file.

    Naming conventions are the same as those used for data linking, i.e.
    unqualified identifiers of outputs must match those of inputs in order
    to be successful, except for redirections which are established for
    individual pairs using DivertInV or DivertOutV.

    Files are specified using a file name which is optionally
    preceeded by a path.  Path construction follows the rules of the
    particular computer platform on which this module is executed.
    No redirection file is actually opened or created in case there
    are currently no output or input variables actually declared.
    The involved file is opened the moment a redirection is
    successfully declared.  You may also pass the empty string as
    actual argument for pfn.  In this case a file dialog is offered,
    which lets you choose a file interactively (see also routine
    GetDivertFile).  Similarily a file opening dialog is offered if
    the pfn does not denote correctly an existing file or if the
    file is not fully accessible according to the needs of the
    redirection (e.g.  already opened for writing by another
    application).

  *)

  PROCEDURE DivertInputsForSubSys(VAR r: Redirection; subSystemDescr,pfn: ARRAY OF CHAR);
  PROCEDURE DivertOutputsForSubSys(VAR r: Redirection; subSystemDescr,pfn: ARRAY OF CHAR);
  PROCEDURE DivertInputsForModel(VAR r: Redirection; model,pfn: ARRAY OF CHAR);
  PROCEDURE DivertOutputsForModel(VAR r: Redirection; model,pfn: ARRAY OF CHAR);

  PROCEDURE DivertInV(VAR r: Redirection; outVarQualIdent,inVarQualIdent,pfn: ARRAY OF CHAR);
    (*
      Searches in file 'pfn' a variable with identifier outVarQualIdent
      and diverts the values found in the file to the input variable
      with the name inVarQualIdent.  inVarQualIdent must be a currently
      declared model object.
    *)
  PROCEDURE DivertOutV(VAR r: Redirection; outVarQualIdent,inVarQualIdent,pfn: ARRAY OF CHAR);
    (*
      Diverts the value of output variable outVarQualIdent to the output
      file 'pfn' under the name of the potential input variable with the
      identifier inVarQualIdent.  outVarQualIdent must be a currently
      declared model object.
    *)

  PROCEDURE RedirectionActive(r: Redirection): BOOLEAN;
  PROCEDURE GetDivertFile(r: Redirection; VAR path,fn: ARRAY OF CHAR);
    (*
      Returns the path and name of the file involved in the
      redirection r.  Note, since it is also possible to divert by
      passing as actual argument the empty string for parameter
      pfn (see routines DivertInputsForSubSys,
      DivertOutputsForSubSys, ...  till DivertOutV) this routine
      returns to the program which file the user has actually
      chosen.  Returns empty strings only in case the redirection
      is not active.
    *)
  PROCEDURE GetDivertedMObjs (VAR inVQualIds, outVQualIds: ARRAY OF CHAR;
                              VAR noInVs,noOutVs: INTEGER);
    (*
      Return the identifiers and numbers of all model objects involved
      in a redirection, listed separately for inputs and outputs.  The
      identifiers are separated by the delimiter "|" (Hint: See routine
      ExtractSubString from module DMStrings to extract individual
      identifiers).
    *)

  PROCEDURE StopRedirection(VAR r: Redirection);
  PROCEDURE StopAllRedirections;
    (*
      Stopping a redirection does also close any possibly involved file.
    *)


END SysIODivert.