A MIDAS command procedure may be created with an editor or via the command
WRITE/COMMANDS which constructs a MIDAS procedure from the current
command buffer. Default type for such a procedure file is .prg .
This MIDAS procedure can then be executed with the commands:
@ file par1 par2 ... par8 ! if the procedure is in MID_PROC
@@ file par1 par2 ... par8 ! if in current directory or MID_WORK
@a file par1 par2 ... par8 ! if in APP_PROC
@s file par1 par2 ... par8 ! if in STD_PROC
@c file par1 par2 ... par8 ! if in CON_PROC
where par1 ... par8 are the actual parameters which may be accessed
within the command procedure through the character keywords P1 ... P8.
The maximum size of a single parameter is 80 characters, but all parameters
together may not exceed 256 characters (which is the maximum size of
a command line).
The size of the code of a procedure is not limited.
In the following, let us assume that all procedures are stored in
the directory specified by
MID_WORK so that we always use the MIDAS command @@ to execute
them.
A command procedure in turn can execute another command procedure (or
itself) -- up to 20 procedure levels deep. The end of a procedure file or the commands
RETURN or ENTRY will bring you back up to the next higher level.
To pass parameters back to a higher level command,
use the command
RETURN retpar1 ... retpar3 . These return values can then be accessed
via the character keywords Q1, Q2, Q3.
This technique is an alternative to using global keywords for that purpose.
To use the actual values of a parameter in the procedure, the formal
parameters P1,...,P8 have to be enclosed in curly brackets (
and 
)
():
!+
! Example 1, MIDAS procedure exa1.prg
!+
READ/KEYWORDP1
! read keyword the name of which is given as par1
@@ testP2
! execute test.prg and pass par2 as first parameter
WRITE/KEYWORD INPUTCP2
! write contents of par2 into keyword INPUTC
Entering the MIDAS command @@ exa1 OUTPUTC ESO-Garching will lead to the execution of:
READ/KEYWORD OUTPUTC
@@ test ESO-Garching
WRITE/KEYWORD INPUTC ESO-Garching
The command @@ always passes 8 parameters
to a command procedure. If fewer than 8 parameters are specified in the
command line, dummy parameters (indicated by the special character `?'
(question mark))
are internally appended.
Therefore, @@ exa1 OUTPUTC will put the character `?' into the
first element of the character keyword INPUTC.
If we enter the command ECHO/ON before executing the procedure we would
actually see the above commands displayed on the terminal
(cf. subsection 
).
Note You can also use apostrophes to indicate symbol substitutions (e.g. 'P1'). However, it is preferable to useand
instead, since it makes nesting of substitutions possible.
The command DEFINE/PARAMETER should be used for each parameter
that is referenced in the procedure. This command will set the defaults,
the type, and the prompt string for each parameter. For numeric values
passed as parameter also lower and upper limits can be specified
in the DEFINE/PARAMETER command.
The default values defined inside the procedure will be used in case the
parameters are not explicitly provided (i.e. entered as `?'):
!+
! Example 2, MIDAS procedure exa2.prg
!+
DEFINE/PARAM P1 999 NUMBER "Enter first input number: " 22,1024
DEFINE/MAXPAR 1 ! only 1 parameter expected
WRITE/KEYWORD INPUTI/I/7/1P1
! store contents of P1 in INPUTI(7)
The MIDAS command: @@ exa2 77 will set INPUTI(7) to 77,
whereas @@ exa2 will set INPUTI(7) to 999.
Entering @@ exa2 17 will result in an error since the valid
interval for the number passed as the first
parameter is [22,1024 ].
If you do not want to give default values for a parameter (in other
words, if specific input is required for this parameter), use the
symbol `?' as default. In that case, and if the relevant parameter is
not given, the user will be prompted for this parameter (using the prompt
string specified in the DEFINE/PARAMETER command) .
The DEFINE/PARAMETER line above also demonstrates how to put a character
string with embedded blanks into a single parameter (remember that
blanks are parameter delimiters in MIDAS) by enclosing the prompt string with
double quotes.
The DEFINE/PARAMETER command also checks the type of the parameter .
The types which may be tested are:
I(mage), T(able), F(itfile) , N(umber), C(haracter).
If for any reason you do not want type checking, use the character
`?' instead of any of the types listed above.
For file--type parameters the following translations are executed:
catalog entry numbers, e.g. #27 are replaced by the corresponding
file name in the catalog
(if that catalog is active!) and the asterisk ( `*') is substituted by
the currently displayed image, if any.
For numerical parameters it is tested if the input is a number;
for character strings it is only checked that the first character is a
non--numeric character.
Using the plus sign ( `+') as default value is another way to
disable parameter type checking.
This is the correct way to test inside a procedure whether a certain
parameter has been entered or not, because it is impossible to distinguish
between a parameter defaulted to `?' and an explicitly entered
`?' parameter. For an example see example 14a, 14b in
subsection .
The system keyword PARSTAT holds 8 flags (for P1,...,P8) which are
set to 1 or 0, if the type of the ith parameter conforms
to the specified type or not.
If PARSTAT(i) is 0 for any i the MIDAS
procedure is aborted.
However, if /C(ONTINUE) is appended to
any of the types listed above, the keyword
PARSTAT will only be set to 0 or 1 and the execution of the
procedure continues, leaving it to the user
to test PARSTAT(i) and decide how to go on.
So in our example above
the command @@ exa2 KB will result in an error message
and the procedure is aborted.
If we change the procedure to:
!+
! Example 3, MIDAS procedure exa3.prg
!+
DEFINE/PARAM P1 999 N/CONT "Enter first input number:"
DEFINE/MAXPAR 1 ! only 1 parameter expected
IF PARSTAT(1) .EQ. 1 -
WRITE/KEYWORD INPUTI/I/7/1P1
!store contents of P1 in INPUTI(7)
then @@ exa3 KB will not yield any error.
If we enter @@ exa3 RW PG CG KB MP PB the message
Warning: 5 parameter(s) more entered than required... will be displayed
but the execution of the procedure continues (the additional parameters
are ignored).
Note also the use of the continuation character ( --) in the
IF statement above.
The MIDAS command CROSSREF defines labels (of maximum 10 characters)
for the
parameters P1,...,P8 to enable cross-referencing
of parameters if they are passed in arbitrary order.
Note command CROSSREF has to be the first executable command (i.e. any command but a comment line) in a MIDAS procedure!
The command DEFINE/MAXPAR provides an additional consistency check and helps to detect erroneous usage of MIDAS procedures. Therefore, it's highly recommended to include it in all procedures.
If we modify exa3.prg to:
!+
! Example 4, MIDAS procedure exa4.prg
!+
CROSSREF IN_FILE OUT_FILE METHOD ALPHA
DEFINE/PARAM P1 ? IMA "Enter name of input file: "
DEFINE/PARAM P2 ? IMA "Enter name of result file: "
DEFINE/PARAM P3 ? C "Enter method: "
DEFINE/PARAM P4 999 NUM "Enter alpha value: " 22,1024
DEFINE/MAXPAR 4 ! max. 4 parameters expected
WRITE/KEYWORD INPUTI/I/7/1P4
then the following command lines will all be equivalent:
@@ exa4 in out FILTER 33
@@ exa4 P2=out P1=in P4=33 P3=FILTER
@@ exa4 OUT_FILE=out IN_FILE=in alpha=33 METHOD=FILTER
The labels may be truncated, so also
@@ exa4 OUT_=out IN_F=in al=33 METH=FILTER
is o.k.
If you do not know a parameter value at the time you execute a MIDAS
procedure,
e.g. the value depends on the execution inside the procedure itself, use the
command INQUIRE/KEYWORD in the procedure. The execution of the
procedure is then interrupted and the user is prompted for a value before
continuing. For example,
!+
! Example 5, MIDAS procedure exa5.prg
!+
CROSSREF IN_FILE OUT_FILE
DEFINE/PARAM P1 ? IMA "Enter name of input file: "
DEFINE/PARAM P2 ? IMA "Enter name of result file: "
DEFINE/MAXPAR 2 ! max. 2 parameters expected
WRITE/KEYWORD IN_B " " all ! fill keyword IN_B with blanks
INQUIRE/KEYWORD IN_B "Which filter, enter LOW or HIGH: "
IF AUX_MODE(7) .EQ. 0 IN_B = "LOW" ! LOW is the default
The command @@ exa5 old new will stop with the message
Which filter, enter LOW or HIGH:
and wait for user input. The 7th
element of keyword AUX_MODE will contain the number of characters typed
in response to the INQUIRE/KEYWORD command. AUX_MODE(7) is
set to 0 if the user just types 
.
