Passing Parameters in MIDAS Procedures

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 ^3.1
@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.
SET/MIDAS_SYSTEM PATH=directory.
  
The maximum size of a single parameter  is 100 characters, but all parameters together may not exceed 400 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 25 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 ($\{$, $\}$):

!+
! Example 1, MIDAS procedure exa1.prg
!+
READ/KEYWORD $\{$P1$\}$! read keyword the name of which is given as par1
@@ test $\{$P2$\}$! execute test.prg and pass par2 as first parameter
WRITE/KEYWORD INPUTC $\{$P2$\}$! 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 3.8.1).

Note

Up to MIDAS release 88NOV apostrophes were used for symbol substitutions (e.g. 'P1'). Because of the backward compatibility of MIDAS you could still use apostrophes to indicate symbol substitutions, which is, however, discouraged. The main reason being that using $\{$ and $\}$ instead, 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/1 $\{$P1$\}$! 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 (see example 14a, 14b in subsection 3.6.5).   
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/1 $\{$P1$\}$!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

The 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/1 $\{$P4$\}$

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 .