<?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">Appendix A: MAIS - Use of Application Programs </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#ug_mais_input">Input types</a><ul><li class="level2"><a href="#ug_mais_input_parameter">Parameter input</a></li>
<li class="level2"><a href="#ug_mais_input_integer">Integer array input</a></li>
<li class="level2"><a href="#ug_mais_input_selection">Selection of options from a menu</a></li>
<li class="level2"><a href="#ug_mais_input_yes">Yes/no question</a></li>
<li class="level2"><a href="#ug_mais_input_text">Text input</a></li>
<li class="level2"><a href="#ug_mais_input_program">Program pause</a></li>
</ul>
</li>
<li class="level1"><a href="#ug_mais_macro">Macro system</a><ul><li class="level2"><a href="#ug_mais_macro_commands">Macro commands</a></li>
<li class="level2"><a href="#ug_mais_macro_file">Macro file description</a></li>
<li class="level2"><a href="#ug_mais_macro_generating">Generating a macro file interactively</a><ul><li class="level3"><a href="#ug_mais_macro_generating_parameter">Parameter input</a></li>
<li class="level3"><a href="#ug_mais_macro_generating_integer">Integer array input</a></li>
<li class="level3"><a href="#ug_mais_macro_generating_menu">Menu input</a></li>
<li class="level3"><a href="#ug_mais_macro_generating_yes">Yes/no input</a></li>
<li class="level3"><a href="#ug_mais_macro_generating_text">Text input</a></li>
<li class="level3"><a href="#ug_mais_macro_generating_program">Program pause</a></li>
</ul>
</li>
<li class="level2"><a href="#ug_mais_macro_reading">Reading from macro file</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="ug_mais_input"></a>
Input types</h1>
<h2><a class="anchor" id="ug_mais_input_parameter"></a>
Parameter input</h2>
<p>The parameters to a command may be of different types (character, real, integer) and are normally given on a single line separated by spaces. Default values are obtained by slashes, "/". If an incorrect number of parameters are given the program asks for each parameter. Default values are then obtained by giving "/" or by pressing &lt;return&gt;.</p>
<p>All real and integer variables have a defined allowable range, and all variables have default values. If one of the parameters is outside the allowable range the program prompts for all parameters. Character parameters may only be single words, (maximum 16 characters).</p>
<h4>Example:</h4>
<p>The command "Modify vessel position" requires 3 real parameters: X pos., Y-pos. and Heading. </p>
<div class="fragment"><div class="line">Vessel position                          :     10. 5 30</div>
</div><!-- fragment --><p>Comment: The input was accepted</p>
<div class="fragment"><div class="line">Vessel position                          :     10. 5</div>
<div class="line">** WARNING ** 3 input parameters are required</div>
<div class="line">X - pos. (m)                             (           0.0 ) : 10</div>
<div class="line">Y - pos. (m)                             (           0.0 ) :</div>
<div class="line">Heading (deg)                            (           0.0 ) : 30</div>
</div><!-- fragment --><p>Comment: The program produces warnings if too few or too many input parameters are given. The only exception is when "/" is given as input to obtain the default values. See below. </p>
<div class="fragment"><div class="line">Vessel position                          : 13572     -62471      30</div>
<div class="line">** WARNING ** Allowable range of parameter 1 is (-9999. 9999 )</div>
<div class="line">** WARNING ** Allowable range of parameter 2 is (-9999. 9999 )</div>
<div class="line">X - pos. (m)                             (           0.0 ) : 135.72</div>
<div class="line">Y - pos. (m)                             (           0.0 ) :</div>
<div class="line">Heading (deg)                            (           0.0 ) : 30</div>
</div><!-- fragment --><p>Test on allowable range may be omitted by giving the macro command @ <b>RANGE OFF</b> (see <a class="el" href="a00038.html#ug_mais_macro_commands">Macro commands</a>).</p>
<p>3 default values are obtained by typing 3 slashes separated by spaces.</p>
<div class="fragment"><div class="line">Vessel position                          : / / /</div>
</div><!-- fragment --><h2><a class="anchor" id="ug_mais_input_integer"></a>
Integer array input</h2>
<p>An arbitrary number of integers up to a maximum number may be read. Any validation of the given parameters may be coded outside the <code>MAIS</code> routine.</p>
<p>Example: </p>
<div class="fragment"><div class="line">Parameters to be plotted</div>
<div class="line">Max. 2 numbers : 1 2</div>
</div><!-- fragment --><h2><a class="anchor" id="ug_mais_input_selection"></a>
Selection of options from a menu</h2>
<p>Answers in menus can be given as:</p>
<ul>
<li>A number corresponding to the number in the option list</li>
<li>Characters with lower-case or upper-case letters and with spaces before or after the text.</li>
</ul>
<p>The input string is first converted to an integer which is compared to the option list. If the conversion fails the text is split into words and the words are compared to the option texts.</p>
<p>Examples: </p>
<div class="fragment"><div class="line">|-&gt;    INPUT MODULE</div>
<div class="line">|</div>
<div class="line">|      0 : Return</div>
<div class="line">|      1 : Read wind coefficients</div>
<div class="line">|      2 : Read wave coefficients</div>
<div class="line">|      3 : Read current coefficients</div>
<div class="line">|</div>
<div class="line">|-&gt;    Select option     :</div>
<div class="line"></div>
<div class="line">|-&gt;    MAIN MENU</div>
<div class="line">|</div>
<div class="line">|      1 : Input module</div>
<div class="line">|      2 : Static module</div>
<div class="line">|      3 : Dynamic module</div>
<div class="line">|     99 : Terminate</div>
<div class="line">|</div>
<div class="line">|-&gt; Select option        :</div>
</div><!-- fragment --><p>Examples of answers:</p>
<div class="fragment"><div class="line">|-&gt; Select option        : dYn                 Accepted</div>
<div class="line">|-&gt; Select option        : d Yn                Not accepted</div>
<div class="line">|-&gt; Select option        : d m                 Accepted</div>
<div class="line">|-&gt; Select option        :                     Not accepted</div>
<div class="line">|-&gt; Select option        : 3                   Accepted</div>
<div class="line">|-&gt; Select option        : DYNAMISK            Not accepted</div>
</div><!-- fragment --><h2><a class="anchor" id="ug_mais_input_yes"></a>
Yes/no question</h2>
<p>The default answer is indicated behind the question. The program tests the first character different from &lt;space&gt; in the input. The default value is obtained by giving "/" or by pressing &lt;return&gt;. If the first letter is different from "y", "Y", "n" or "N" the question will be repeated.</p>
<h4>Example:</h4>
<div class="fragment"><div class="line">Do you want to store the data ?            (Y) :</div>
</div><!-- fragment --><p>Comment: The default value here is YES. The following input would be interpreted as NO:</p>
<div class="fragment"><div class="line">-     n</div>
<div class="line">-     no thanks</div>
<div class="line">-     NEI</div>
</div><!-- fragment --><h2><a class="anchor" id="ug_mais_input_text"></a>
Text input</h2>
<p>Text input may contain up to 70 characters in each line, any number of lines. In the example below 30 characters is used. The text can not start with @, * or ' in any line because these characters have a special meaning.</p>
<p>If the user gives spaces or nothing the default character string is used.</p>
<p>The string is cleared if "&gt;" is given.</p>
<h4>Example:</h4>
<div class="fragment"><div class="line">Give 3 text lines</div>
<div class="line">            --------------------------</div>
<div class="line">Old 1       (Run 1                        )</div>
<div class="line">Txt 1 :      Run 4</div>
<div class="line">Old 2       (                             )</div>
<div class="line">Txt 2 :      4-JUL-1988</div>
<div class="line">Old 3       (                             )</div>
<div class="line">Txt 3 :      Calculations performed by NN</div>
</div><!-- fragment --><h2><a class="anchor" id="ug_mais_input_program"></a>
Program pause</h2>
<p>A pause in the program may, or may not, be followed by the message : </p>
<div class="fragment"><div class="line">Press &lt;return&gt; to <span class="keywordflow">continue</span> :</div>
</div><!-- fragment --><p> The program resumes execution when the &lt;return&gt; key is struck. If the command @ <b>WAIT OFF</b> (see <a class="el" href="a00038.html#ug_mais_macro_commands">Macro commands</a>) has been given, the program will not make any pause.</p>
<h1><a class="anchor" id="ug_mais_macro"></a>
Macro system</h1>
<h2><a class="anchor" id="ug_mais_macro_commands"></a>
Macro commands</h2>
<p>Macro commands can be used anywhere where the program waits for input. The commands must contain enough characters so that they are unique.</p>
<ul>
<li>@ <b>HELP</b> - Writes a list of all macro system commands with short explanations.<ul>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>CREATE file</b> or @ <b>OPEN file</b> - The command opens the given file for writing. All questions and answers until '@ CLOSE' is given will be stored on the macro file. The file name is converted to uppercase, and suffix .MAC is added if "." is not in the file name. If the command is given a second time before '@ CLOSE', '@ DO file' is stored at the macro file.<ul>
<li>Can not be stored in macro file</li>
</ul>
</li>
<li>@ <b>CLOSE</b> - The command closes the file. Message is written at the screen.<ul>
<li>Can not be stored in macro file</li>
</ul>
</li>
<li>@ <b>DO filename &lt;n&gt;</b> - Input is read from specified file with name <code>FNAME.MAC</code> &lt;n&gt; times. If &lt;n&gt; is omitted the file is read once. In the command the file name may be written in uppercase or lowercase letters, with or without the extension.<ul>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>LIST file</b> - The content of the file is listed at the terminal.<ul>
<li>Can not be stored in macro file</li>
</ul>
</li>
<li>@ <b>SPAWN</b> - The program is set in a "waiting condition". A new process is created. This means that all operating system commands can be given.<ul>
<li>Can not be stored in macro file</li>
</ul>
</li>
<li>@ <b>WAIT ON/OFF</b> - Changes the program switch <code>IWAIT</code> to 1/0, respectively.<ul>
<li><code>IWAIT = 1</code>: enables pauses in the program execution. Such stops are normally followed by the message "Press &lt;return&gt; to continue".</li>
<li><code>IWAIT = 0</code>: pauses are disabled.</li>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>DISP ON/OFF</b> - Changes the program switch <code>IDISP</code> which determines the amount of output to screen. Changes the program switch <code>IDISP</code> which determines the amount of output to screen.<ul>
<li><code>IDISP = 0</code>: Only comment lines from the macro file are written on the screen</li>
<li><code>IDISP = 1</code>: All questions, answers and comment lines are written on the screen when input is read from a macro file</li>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>RANGE ON/OFF</b> - Changes the program switch <code>IRCK</code><ul>
<li><code>IRCK = 0</code>: No check that input values are within allowable range</li>
<li><code>IRCK = 1</code>: (default) Check on allowable range is enabled</li>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>BATCH ON/OFF</b> - Changes the switch <code>IBATCH</code> to 1/0 respectively.<ul>
<li>1=&gt; ON (default) =&gt; Program behaves as a batch program. This means that it terminates if wrong input is given.</li>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>FILE ifile</b> - Changes the program switch <code>IFILE</code>. Allowable range is 0-5. This switch can be used to change the behavior of the program.<ul>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>RESULT iresu</b> - Changes the program switch <code>IRESU</code>. Allowable range is 0-5. This switch can for example be used by the program to change the amount of printed information.<ul>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>IDENT &lt;nwck&gt;</b> - Number of words in "identifying text" to be used. Allowable range is 0-5.<ul>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>BACK</b> - Backspace macro file.<ul>
<li>Can not be stored in macro file</li>
</ul>
</li>
<li>@ <b>MSG_F file</b> - Set file for printing messages. @ <b>MSG_F close</b> will close file.<ul>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>MSG message</b> - Print message to file (defined by <b>MSG_F</b>)<ul>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>STATUS</b> - Lists the values of the macro switches, and gives information about the macro files in use.<ul>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>* - Marks that this parameter shall be read from the keyboard when input is read from a macro file.<ul>
<li>Can be stored in macro file</li>
</ul>
</li>
</ul>
<p>The effect of the program switches <code>IFILE</code> and <code>IRESU</code> depends on the implementation of these variables in the application program:</p>
<ul>
<li>@ <b>FILE IFILE</b> - Changes the program switch <code>IFILE</code>. Allowable range is 0-5. The switch is returned to the calling routine to change the amount of results to the print file.<ul>
<li>Can be stored in macro file</li>
</ul>
</li>
<li>@ <b>RESULT IRESU</b> - Changes the program switch <code>IRESU</code>. Allowable range is 0-5. The switch is returned to the calling routine to change the amount of results shown at the screen.<ul>
<li>Can be stored in macro file</li>
</ul>
</li>
</ul>
<h2><a class="anchor" id="ug_mais_macro_file"></a>
Macro file description</h2>
<p>A macro file is defined as an ascii file which contains input that can be read by the program. Comments (explaining text) may be stored in the file in addition to the program input.</p>
<p>The macro file may consist of 2 types of lines.</p>
<ul>
<li>Comment lines are lines where " ' " is the first nonblank character. Comment lines may be placed anywhere on the macro file. They are read and written on the screen when the macro file is used, but have no effect on the calculations.</li>
<li>Input lines. An input line may also contain a comment field starting with " ' ". Comment text which is located between the first and second occurrence of " ' " is during execution checked against the prompt text normally shown on the screen. If inconsistency is found, a warning is displayed and the user is asked whether the next line on the file should be read or the macro file(s) should be closed.</li>
</ul>
<p>Some of the macro commands may be stored in a macro file.</p>
<h2><a class="anchor" id="ug_mais_macro_generating"></a>
Generating a macro file interactively</h2>
<p>After the command '@ OPEN &lt;file&gt;' has been given, the user input will be logged at the file. Input that is not accepted by the program is not stored. If for instance an erroneous option is given in a menu, the menu will be displayed again and only the valid option will be stored at the macro file.</p>
<h3><a class="anchor" id="ug_mais_macro_generating_parameter"></a>
Parameter input</h3>
<p>Only input that is accepted by the program is stored at the macro file.</p>
<p>Example : </p>
<div class="fragment"><div class="line">Vessel position                 : 10.   5.   30</div>
</div><!-- fragment --><p>Macro file: </p>
<div class="fragment"><div class="line">10. 5. 30                       <span class="stringliteral">&#39;Vessel position</span></div>
</div><!-- fragment --><p>If a * is stored in the macro file then this parameter will always be read from the keyboard.</p>
<h4>Example:</h4>
<div class="fragment"><div class="line">Vessel position                          :</div>
<div class="line">X - pos. (m)                                    ( 0.0 )     : 10.</div>
<div class="line">Y - pos. (m)                                    ( 0.0 )     : *</div>
<div class="line">Z - pos. (m)                                    ( 0.0 )     : 5.</div>
<div class="line">Heading (deg)                                   ( 0.0 )     :</div>
</div><!-- fragment --><p> Macro file : </p>
<div class="fragment"><div class="line">!                                <span class="stringliteral">&#39; Vessel position</span></div>
<div class="line"><span class="stringliteral">10.                                    &#39;</span> X - pos. (m)</div>
<div class="line">*                                      <span class="stringliteral">&#39; Y - pos. (m)</span></div>
<div class="line"><span class="stringliteral">0.                                     &#39;</span> Heading (deg)</div>
</div><!-- fragment --><h3><a class="anchor" id="ug_mais_macro_generating_integer"></a>
Integer array input</h3>
<p>Example: </p>
<div class="fragment"><div class="line">Parameters to be plotted</div>
<div class="line"></div>
<div class="line">Max. 2 numbers : 1 2</div>
</div><!-- fragment --><p>Macro file: </p>
<div class="fragment"><div class="line">1 2</div>
</div><!-- fragment --><h3><a class="anchor" id="ug_mais_macro_generating_menu"></a>
Menu input</h3>
<p>Example : </p>
<div class="fragment"><div class="line">|-&gt;    MAIN MENU</div>
<div class="line">|</div>
<div class="line">|       1 : Input module</div>
<div class="line">|       2 : Static module</div>
<div class="line">|       3 : Dynamic module</div>
<div class="line">|      99 : Terminate</div>
<div class="line">|</div>
<div class="line">|-&gt;    Select option : DYNAMIC</div>
</div><!-- fragment --><p> Macro file : </p>
<div class="fragment"><div class="line">DYNAMIC           <span class="stringliteral">&#39; MAINMENU</span></div>
</div><!-- fragment --><h3><a class="anchor" id="ug_mais_macro_generating_yes"></a>
Yes/no input</h3>
<p>Example : </p>
<div class="fragment"><div class="line">Do you want to store the data ?           (Y ): NO</div>
</div><!-- fragment --><p> Macro file : </p>
<div class="fragment"><div class="line">NO                            <span class="stringliteral">&#39; Do you want to store the data?    ( Y )</span></div>
</div><!-- fragment --><h3><a class="anchor" id="ug_mais_macro_generating_text"></a>
Text input</h3>
<p>Example : </p>
<div class="fragment"><div class="line">Give 3 text lines</div>
<div class="line">          ---------------------------------</div>
<div class="line">Old 1     (                               )</div>
<div class="line">Txt 1 :    Run 4</div>
<div class="line">Old 2     (                               )</div>
<div class="line">Txt 2 :    4-JUL-1988</div>
<div class="line">Old 3     (                               )</div>
<div class="line">Txt 3 :    Calculations performed by NN</div>
</div><!-- fragment --><p>Macro file : </p>
<div class="fragment"><div class="line">Run 4</div>
<div class="line">4-JUL-1988</div>
<div class="line">Calculations performed by NN</div>
</div><!-- fragment --><h3><a class="anchor" id="ug_mais_macro_generating_program"></a>
Program pause</h3>
<p>Answers to these are not recorded, and such input is read from keyboard in interactive execution mode. It might be a good idea to put '@ WAIT OFF' in the macro file to avoid program pauses.</p>
<h2><a class="anchor" id="ug_mais_macro_reading"></a>
Reading from macro file</h2>
<p>If the parameter <code>IDISP = 1</code> both questions written by the program and input read from a macro file will be displayed on the screen. If <code>IDISP = 0</code> only comment lines, error messages and questions that should be answered from the keyboard will be displayed. If an error occurs when the program is run in demand (<code>IBATCH =0</code>) a menu will be displayed. A wrong identificator will result in the following output: </p>
<div class="fragment"><div class="line">***MACRO file error***</div>
<div class="line">***Identifiers are not identical***</div>
<div class="line"></div>
<div class="line">Expected from program   :   INPMOD MAIN MENU</div>
<div class="line">Read from macro file    :   Body data manipu <span class="stringliteral">&#39; INPMOD MAIN MENU</span></div>
<div class="line"><span class="stringliteral"></span></div>
<div class="line"><span class="stringliteral">|-&gt;Alternatives</span></div>
<div class="line"><span class="stringliteral">|</span></div>
<div class="line"><span class="stringliteral">|        A = Accept this input</span></div>
<div class="line"><span class="stringliteral">|        R = Read this parameter from keyboard</span></div>
<div class="line"><span class="stringliteral">|        I = Ignore this line from macro file</span></div>
<div class="line"><span class="stringliteral">|        S = Stop reading from macro file</span></div>
<div class="line"><span class="stringliteral">|</span></div>
<div class="line"><span class="stringliteral">|-&gt; Select option :</span></div>
</div><!-- fragment --><p>If for instance one parameter is outside the allowable range when input is read from a macro file, the following output will be written:</p>
<div class="fragment"><div class="line">**WARNING **</div>
<div class="line">Valid range of parameter 1 is           ( -10.00 , 10.00 )</div>
<div class="line"></div>
<div class="line">***MACRO file error ***</div>
<div class="line">***Wrong input ***</div>
<div class="line"></div>
<div class="line">Read from macro file : 300 <span class="stringliteral">&#39; First real number</span></div>
<div class="line"><span class="stringliteral"></span></div>
<div class="line"><span class="stringliteral">I-&gt;Alternatives</span></div>
<div class="line"><span class="stringliteral">I</span></div>
<div class="line"><span class="stringliteral">I     R = Read this parameter from keyboard</span></div>
<div class="line"><span class="stringliteral">I     I = Ignore this line from macro file</span></div>
<div class="line"><span class="stringliteral">I     S = Stop reading from macro file</span></div>
<div class="line"><span class="stringliteral">I</span></div>
<div class="line"><span class="stringliteral">I-&gt;  Select option :</span></div>
</div><!-- fragment --><p>If an error occurs when the program is run in batch (<code>IBATCH =1</code> or <code>2</code>) an error message will be written to the output device. If <code>IBATCH = 1</code> <code>IERR = -1</code> will be returned to the calling routine. If <code>IBATCH = 2</code> a division by 0 is performed in order to provoke a program stop. </p>
</div></div><!-- contents -->
	</body>
</html>