Appendix A: MAIS - Use of Application Programs

1. Input types

1.1. Parameter input

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 <return>.

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).

1.1.1. Example:

The command Modify vessel position requires 3 real parameters: X pos., Y-pos. and Heading.

 Vessel position : 10. 5 30

Comment: The input was accepted

Vessel position                          :     10. 5
** WARNING ** 3 input parameters are required
X - pos. (m)                             (           0.0 ) : 10
Y - pos. (m)                             (           0.0 ) :
Heading (deg)                            (           0.0 ) : 30

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.

Vessel position                          : 13572     -62471      30
** WARNING ** Allowable range of parameter 1 is (-9999. 9999 )
** WARNING ** Allowable range of parameter 2 is (-9999. 9999 )
X - pos. (m)                             (           0.0 ) : 135.72
Y - pos. (m)                             (           0.0 ) :
Heading (deg)                            (           0.0 ) : 30

Test on allowable range may be omitted by giving the macro command @ RANGE OFF (see Macro commands).

3 default values are obtained by typing 3 slashes separated by spaces.

Vessel position                          : / / /

1.2. Integer array input

An arbitrary number of integers up to a maximum number may be read. Any validation of the given parameters may be coded outside the MAIS routine.

Example:

 Parameters to be plotted
 Max. 2 numbers : 1 2

1.3. Selection of options from a menu

Answers in menus can be given as: - A number corresponding to the number in the option list - Characters with lower-case or upper-case letters and with spaces before or after the text.

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.

Examples:

|->    INPUT MODULE
|
|      0 : Return
|      1 : Read wind coefficients
|      2 : Read wave coefficients
|      3 : Read current coefficients
|
|->    Select option     :

|->    MAIN MENU
|
|      1 : Input module
|      2 : Static module
|      3 : Dynamic module
|     99 : Terminate
|
|-> Select option        :

Examples of answers:

|-> Select option        : dYn                 Accepted
|-> Select option        : d Yn                Not accepted
|-> Select option        : d m                 Accepted
|-> Select option        :                     Not accepted
|-> Select option        : 3                   Accepted
|-> Select option        : DYNAMISK            Not accepted

1.4. Yes/no question

The default answer is indicated behind the question. The program tests the first character different from <space> in the input. The default value is obtained by giving / or by pressing <return>. If the first letter is different from y, Y, n or N the question will be repeated.

1.4.1. Example:

Do you want to store the data ?            (Y) :

Comment: The default value here is YES. The following input would be interpreted as NO:

-     n
-     no thanks
-     NEI

1.5. Text input

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.

If the user gives spaces or nothing the default character string is used.

The string is cleared if > is given.

1.5.1. Example:

Give 3 text lines
            --------------------------
Old 1       (Run 1                        )
Txt 1 :      Run 4
Old 2       (                             )
Txt 2 :      4-JUL-1988
Old 3       (                             )
Txt 3 :      Calculations performed by NN

1.6. Program pause

A pause in the program may, or may not, be followed by the message : _~ Press to continue : _~ The program resumes execution when the <return> key is struck. If the command @ WAIT OFF (see Macro commands) has been given, the program will not make any pause.

2. Macro system

2.1. Macro commands

Macro commands can be used anywhere where the program waits for input. The commands must contain enough characters so that they are unique.

@ HELP - Writes a list of all macro system commands with short explanations.
- Can be stored in macro file
@ CREATE file or @ OPEN file - 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.
- Can not be stored in macro file
@ CLOSE - The command closes the file. Message is written at the screen.
- Can not be stored in macro file
@ DO filename <n> - Input is read from specified file with name FNAME.MAC <n> times. If <n> 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.
- Can be stored in macro file
@ LIST file - The content of the file is listed at the terminal.
- Can not be stored in macro file
@ SPAWN - The program is set in a waiting condition. A new process is created. This means that all operating system commands can be given.
- Can not be stored in macro file
@ WAIT ON/OFF - Changes the program switch IWAIT to 1/0, respectively.
- IWAIT = 1: enables pauses in the program execution. Such stops are normally followed by the message Press to continue.
- IWAIT = 0: pauses are disabled.
- Can be stored in macro file
@ DISP ON/OFF - Changes the program switch IDISP which determines the amount of output to screen. Changes the program switch IDISP which determines the amount of output to screen.
- IDISP = 0: Only comment lines from the macro file are written on the screen
- IDISP = 1: All questions, answers and comment lines are written on the screen when input is read from a macro file
- Can be stored in macro file
@ RANGE ON/OFF - Changes the program switch IRCK
- IRCK = 0: No check that input values are within allowable range
- IRCK = 1: (default) Check on allowable range is enabled
- Can be stored in macro file
@ BATCH ON/OFF - Changes the switch IBATCH to 1/0 respectively.
- 1⇒ ON (default) ⇒ Program behaves as a batch program. This means that it terminates if wrong input is given.
- Can be stored in macro file
@ FILE ifile - Changes the program switch IFILE. Allowable range is 0-5. This switch can be used to change the behavior of the program.
- Can be stored in macro file
@ RESULT iresu - Changes the program switch IRESU. Allowable range is 0-5. This switch can for example be used by the program to change the amount of printed information.
- Can be stored in macro file
@ IDENT <nwck> - Number of words in identifying text to be used. Allowable range is 0-5.
- Can be stored in macro file
@ BACK - Backspace macro file.
- Can not be stored in macro file
@ MSG_F file - Set file for printing messages. @ MSG_F close will close file.
- Can be stored in macro file
@ MSG message - Print message to file (defined by MSG_F)
- Can be stored in macro file
@ STATUS - Lists the values of the macro switches, and gives information about the macro files in use.
- Can be stored in macro file
* - Marks that this parameter shall be read from the keyboard when input is read from a macro file.
- Can be stored in macro file

The effect of the program switches IFILE and IRESU depends on the implementation of these variables in the application program:

@ FILE IFILE - Changes the program switch IFILE. Allowable range is 0-5. The switch is returned to the calling routine to change the amount of results to the print file.
- Can be stored in macro file
@ RESULT IRESU - Changes the program switch IRESU. Allowable range is 0-5. The switch is returned to the calling routine to change the amount of results shown at the screen.
- Can be stored in macro file

2.2. Macro file description

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.

The macro file may consist of 2 types of lines.

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.
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.

Some of the macro commands may be stored in a macro file.

2.3. Generating a macro file interactively

After the command `@ OPEN <file>' 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.

2.3.1. Parameter input

Only input that is accepted by the program is stored at the macro file.

Example :

 Vessel position : 10. 5. 30

Macro file:

 10. 5. 30 ’Vessel position

If a * is stored in the macro file then this parameter will always be read from the keyboard.

Example:

Vessel position                          :
X - pos. (m)                                    ( 0.0 )     : 10.
Y - pos. (m)                                    ( 0.0 )     : *
Z - pos. (m)                                    ( 0.0 )     : 5.
Heading (deg)                                   ( 0.0 )     :

Macro file :

!                                ' Vessel position
10.                                    ' X - pos. (m)
*                                      ' Y - pos. (m)
0.                                     ' Heading (deg)

2.3.2. Integer array input

Example:

Parameters to be plotted

Max. 2 numbers : 1 2

Macro file:

1 2

2.3.3. Menu input

Example :

|->    MAIN MENU
|
|       1 : Input module
|       2 : Static module
|       3 : Dynamic module
|      99 : Terminate
|
|->    Select option : DYNAMIC

Macro file:

 DYNAMIC ’ MAIN MENU

2.3.4. Yes/no input

Example :

 Do you want to store the data ? (Y ): NO

Macro file :

 NO ’ Do you want to store the data? ( Y )

2.3.5. Text input

Example :

Give 3 text lines
          ---------------------------------
Old 1     (                               )
Txt 1 :    Run 4
Old 2     (                               )
Txt 2 :    4-JUL-1988
Old 3     (                               )
Txt 3 :    Calculations performed by NN

Macro file :

Run 4
4-JUL-1988
Calculations performed by NN

2.3.6. Program pause

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.

2.4. Reading from macro file

If the parameter IDISP = 1 both questions written by the program and input read from a macro file will be displayed on the screen. If IDISP = 0 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 (IBATCH =0) a menu will be displayed. A wrong identificator will result in the following output:

***MACRO file error***
***Identifiers are not identical***

Expected from program   :   INPMOD MAIN MENU
Read from macro file    :   Body data manipu ' INPMOD MAIN MENU

|->Alternatives
|
|        A = Accept this input
|        R = Read this parameter from keyboard
|        I = Ignore this line from macro file
|        S = Stop reading from macro file
|
|-> Select option :

If for instance one parameter is outside the allowable range when input is read from a macro file, the following output will be written:

**WARNING **
Valid range of parameter 1 is           ( -10.00 , 10.00 )

***MACRO file error ***
***Wrong input ***

Read from macro file : 300 ' First real number

I->Alternatives
I
I     R = Read this parameter from keyboard
I     I = Ignore this line from macro file
I     S = Stop reading from macro file
I
I->  Select option :

If an error occurs when the program is run in batch (IBATCH =1 or 2) an error message will be written to the output device. If IBATCH = 1 IERR = -1 will be returned to the calling routine. If IBATCH = 2 a division by 0 is performed in order to provoke a program stop.