<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
		<link type="text/css" rel="stylesheet" href="doxygen.css"/>
		<link type="text/css" rel="stylesheet" href="tabs.css"/>
	</head>
	<body>
	<div>
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Principles for Use </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#ug_principles_interactive">Interactive Communication</a><ul><li class="level2"><a href="#ug_principles_interactive_macro">Macro System</a></li>
</ul>
</li>
<li class="level1"><a href="#ug_principles_selection">Selection of execution mode</a></li>
<li class="level1"><a href="#ug_principles_units">Units and physical constants</a></li>
<li class="level1"><a href="#ug_principles_error">Error Messages</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="ug_principles_interactive"></a>
Interactive Communication</h1>
<p>The program is basically an interactive program, but can also be run in batch mode. The input from the terminal can be divided into five types:</p>
<ul>
<li>Selection among a number of options that are presented on the screen.</li>
<li>Giving parameters to a command.</li>
<li>Giving text strings for identification.</li>
<li>Yes/no answers.</li>
<li>Waiting on user response.</li>
</ul>
<p>Common to all types of input is that they allow definition of a macro file, they allow a macro file to be executed and they allow temporary switching of control to the operating system.</p>
<p>The program uses <code>MAIS - MArintek Input System</code> for handling the interactive communication. This system is described in appendix B. Useful features of this system are :</p>
<ul>
<li>Numerical values have default values and allowable range. Range check can be deactivated by <code>'range off'</code>.</li>
<li>Lower-case and upper-case letters are accepted as input.</li>
<li>The program will never stop because of wrong input.</li>
<li>Switch commands (print, file) may be given anywhere.</li>
<li>User input may be logged on a macro file for documentation or later input.</li>
</ul>
<h2><a class="anchor" id="ug_principles_interactive_macro"></a>
Macro System</h2>
<p>Macro system commands (starting with <code>@</code>) can be used anywhere where the program waits for input. The commands must contain enough characters so that they are unique. When the user writes <code>@ HELP</code> a short description is written at the terminal.</p>
<p>The following macro commands are available:</p>
<ul>
<li>@ <b>HELP</b> - Writes a list of all macro system commands.</li>
<li>@ <b>CREATE filename</b> or @ <b>OPEN filename</b> - The command opens a macro file for writing. All questions and answers until '@ CLOSE' is given will be stored on the macro file. If the command is given a second time before '@ CLOSE', '@ DO filename' is stored on the macro file.</li>
<li>@ <b>CLOSE</b> - The command closes the macro file which is opened for writing.</li>
<li>@ <b>DO filename &lt;n&gt;</b> - Input is read from the specified file. The file is read <b>n</b> times, <b>n</b> may be omitted.</li>
<li>@ <b>LIST filename</b> - The contents of the file are listed at the terminal.</li>
<li>@ <b>SPAWN</b> or @ <b>PAUSE</b> - The program is set in a "waiting
    condition". A new process is created. This means that all operating system commands can be given.</li>
<li>@ <b>WAIT ON/OFF</b> - Changes the program switch <code>IWAIT</code> to <code>1/0</code> respectively. This switch is used internally in the program to check whether 'press return to continue' shall be written on the terminal</li>
<li>@ <b>DISPLAY ON/OFF</b> - Changes the program switch <code>IDISP</code> to <code>1/0</code> respectively. This switch is used by the program to enable/supress output to the terminal.</li>
<li>@ <b>RANGE ON/OFF</b> - Changes the switch <code>IRCK</code> to <code>1/0</code> respectively.<ul>
<li><code>1 =&gt;ON</code> (default) <code>=&gt;</code> Numerical input is checked to be within specified range.</li>
</ul>
</li>
<li>@ <b>BATCH ON/OFF</b> - Changes the switch <code>IBATCH</code> to 1/0 respectively.<ul>
<li><code>1=&gt; ON</code> (default) <code>=&gt;</code> Program behaves as a batch program. This means that it terminates if wrong input is given.</li>
</ul>
</li>
<li>@ <b>FILE ifile</b> - Changes the program switch <code>IFILE</code>. Allowable range is <code>0-5</code>. This switch can be used to change the behavior of the program.</li>
<li>@ <b>RESULT iresu</b> - Changes the program switch <code>IRESU</code>. Allowable range is <code>0-5</code>. This switch can for example be used by the program to change the amount of printed information.</li>
<li>@ <b>IDENT &lt;nwck&gt;</b> - Number of words in "identifying text" to be used. Allowable range is <code>0-5</code>.</li>
<li>@ <b>STATUS</b> - Lists the values of the macro switches.</li>
<li>@ <b>BACK</b> - Backspace macro file.</li>
<li>@ <b>MSG_F file</b> - Set file for printing messages. '@ MSG_F close' will close file.</li>
<li>@ <b>MSG message</b> - Print message to file (defined by 'MSG_F')</li>
<li>* - The parameter parameter that is currently read shall be read from terminal when a macro file is executed.</li>
</ul>
<p>Assume that the user wants to undertake several batch runs. To prepare an input file, the user first runs the desired program and logs the terminal input on the file <code>FILA.MAC</code>. This is done by giving the command</p>
<p>@ <b>open fila</b></p>
<p>This causes the file <code>FILA.MAC</code> to be opened. All input to the program that is given from terminal will be stored on this file. When this first run is finished, <code>FILA.MAC</code> may be duplicated and modified if wanted.</p>
<p>When the program waits at the same question where recording of the macro file started, the commands can be repeated by:</p>
<p>@ <b>do fila</b></p>
<h1><a class="anchor" id="ug_principles_selection"></a>
Selection of execution mode</h1>
<p>Each <code>SIMO</code> program may be run in two different ways:</p>
<ul>
<li>interactive mode.</li>
<li>batch mode.</li>
</ul>
<p>Selection between interactive and batch mode is done within the modules. A symbolic file with name <code>'SIMO_DEF.DAT'</code> is searched for at the default directory. The file should contain 3 lines with a character variable on each line:</p>
<div class="fragment"><div class="line">CHMODE</div>
<div class="line">CHSYS</div>
<div class="line">CHINI</div>
</div><!-- fragment --><p>If the file is not found, the execution mode will be interactive, and both <code>CHSYS</code> and <code>CHINI</code> will be blank. Batch mode is selected only if <code>CHMODE</code> has the value <code>&gt;batch=</code> or <code>BATCH</code>. <code>CHSYS</code> and <code>CHINI</code> are used for generation of default file names as explained in <a class="el" href="a00006.html#ug_program_file">File system</a>.</p>
<p>Batch mode is useful when several simulations shall be undertaken. The necessary input for running the program may be prepared with a text editor, but it is recommended that the user prepares the input "run-file" by running the program in demand mode and logging the input at a macro file. If necessary the macro file can be edited.</p>
<p>Batch mode and interactive mode are different only in the way they respond to detected errors in the program execution and the amount of output presented at standard output device (screen).</p>
<p>Details about running the program on different computers are found in the implementation and testing manual.</p>
<h1><a class="anchor" id="ug_principles_units"></a>
Units and physical constants</h1>
<p>All input data must be given in a consistent set of SI units, which are defined as a part of the input data set.</p>
<table class="doxtable">
<tr>
<th align="left"></th><th align="left">Property </th><th align="left">Notation </th><th align="left">Example  </th></tr>
<tr>
<td align="left">Basic units </td><td align="left">Length </td><td align="left"><img class="formulaInl" alt="$ L $" src="form_0.png"/> </td><td align="left"><img class="formulaInl" alt="$\mathrm{m}$" src="form_1.png"/> </td></tr>
<tr>
<td align="left"></td><td align="left">Time </td><td align="left"><img class="formulaInl" alt="$ T $" src="form_2.png"/> </td><td align="left"><img class="formulaInl" alt="$\mathrm{s}$" src="form_3.png"/> </td></tr>
<tr>
<td align="left"></td><td align="left">Mass </td><td align="left"><img class="formulaInl" alt="$ M $" src="form_4.png"/> </td><td align="left"><img class="formulaInl" alt="$\mathrm{Mg = tonne}$" src="form_5.png"/> </td></tr>
<tr>
<td align="left">Derived units </td><td align="left">Force </td><td align="left"><img class="formulaInl" alt="$ F = ML/T^2 $" src="form_6.png"/> </td><td align="left"><img class="formulaInl" alt="$\mathrm{Mgm/s^2 = kN}$" src="form_7.png"/> </td></tr>
<tr>
<td align="left"></td><td align="left">Pressure </td><td align="left"><img class="formulaInl" alt="$ P = F/L^2 $" src="form_8.png"/> </td><td align="left"><img class="formulaInl" alt="$\mathrm{kN/m^2 = kPa}$" src="form_9.png"/> </td></tr>
<tr>
<td align="left"></td><td align="left">Velocity </td><td align="left"><img class="formulaInl" alt="$ V = L/T $" src="form_10.png"/> </td><td align="left"><img class="formulaInl" alt="$\mathrm{m/s}$" src="form_11.png"/> </td></tr>
<tr>
<td align="left"></td><td align="left">Acceleration </td><td align="left"><img class="formulaInl" alt="$ A = V/T $" src="form_12.png"/> </td><td align="left"><img class="formulaInl" alt="$\mathrm{m/s^2}$" src="form_13.png"/> </td></tr>
</table>
<p>Angles are given in degrees, <img class="formulaInl" alt="$\mathrm{[deg]}$" src="form_14.png"/>, and coefficients which are multiplied with rotational state variables are given for rotations in radians. Angular velocity is given in radians per time unit, for instance <img class="formulaInl" alt="$\mathrm{[rad/s]}$" src="form_15.png"/>. Thruster speed and rotation are given in revolutions per minute, <img class="formulaInl" alt="$\mathrm{[RPM]}$" src="form_16.png"/>. Internally in the program, all angles and rotations are converted to radians.</p>
<h1><a class="anchor" id="ug_principles_error"></a>
Error Messages</h1>
<p>An error is reported where it is detected. The string to be searched for on the print file is:</p>
<div class="fragment"><div class="line">*** ERR</div>
</div><!-- fragment --><p>Error flags and messages are transferred towards the root of the call tree. In interactive mode, the user is given control at a high level and can decide whether to continue or terminate the program. In batch mode, the program is terminated at the top level. </p>
</div></div><!-- contents -->
	</body>
</html>