<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 98.1p1 release (March 2nd, 1998)
originally by Nikos Drakos (nikos@cbl.leeds.ac.uk), CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Passing Parameters in MIDAS Procedures</TITLE>
<META NAME="description" CONTENT="Passing Parameters in MIDAS Procedures">
<META NAME="keywords" CONTENT="vol1">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="vol1.css">
<LINK REL="next" HREF="node40.html">
<LINK REL="previous" HREF="node38.html">
<LINK REL="up" HREF="node38.html">
<LINK REL="next" HREF="node40.html">
</HEAD>
<BODY >
<!--Navigation Panel-->
<A NAME="tex2html977"
HREF="node40.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
SRC="icons.gif/next_motif.gif"></A>
<A NAME="tex2html973"
HREF="node38.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
SRC="icons.gif/up_motif.gif"></A>
<A NAME="tex2html967"
HREF="node38.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
SRC="icons.gif/previous_motif.gif"></A>
<A NAME="tex2html975"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents"
SRC="icons.gif/contents_motif.gif"></A>
<A NAME="tex2html976"
HREF="node216.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index"
SRC="icons.gif/index_motif.gif"></A>
<BR>
<B> Next:</B> <A NAME="tex2html978"
HREF="node40.html">Symbol Substitution in Command</A>
<B> Up:</B> <A NAME="tex2html974"
HREF="node38.html">MIDAS Command Language</A>
<B> Previous:</B> <A NAME="tex2html968"
HREF="node38.html">MIDAS Command Language</A>
<BR>
<BR>
<!--End of Navigation Panel-->
<H2><A NAME="SECTION00661000000000000000"> </A> <A NAME="1891"> </A>
<BR>
Passing Parameters in MIDAS Procedures
</H2>
<P>
A MIDAS command procedure may be created with an editor or via the command
<BR>
<TT>WRITE/COMMANDS</TT> which constructs a MIDAS procedure from the current
command buffer. Default type for such a procedure file is <TT>.prg</TT> .
This MIDAS procedure can then be executed with the commands:<BLOCKQUOTE>
<TT>@ file par1 par2 ... par8
</TT>! if the procedure is in <TT>MID_PROC <BR>
@@ file par1 par2 ... par8
</TT>! if in current directory or <TT>MID_WORK
<A NAME="tex2html8"
HREF="footnode.html#fnm"><SUP>3.1</SUP></A>
<BR>
@a file par1 par2 ... par8
</TT>! if in <TT>APP_PROC <BR>
@s file par1 par2 ... par8
</TT>! if in <TT>STD_PROC
<BR>
@c file par1 par2 ... par8
</TT>! if in <TT>CON_PROC</TT></BLOCKQUOTE>where <TT>par1 ... par8</TT> are the actual parameters which may be accessed
within the command procedure through the character keywords P1 ... P8.
<BR>
<TT>SET/MIDAS_SYSTEM PATH=directory</TT>.
<BR>
<BR>
The maximum size of a single parameter<A NAME="1909"> </A> 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.
<BR>
In the following, let us assume that all procedures are stored in
the directory specified by
<TT>MID_WORK</TT> so that we always use the MIDAS command <TT>@@</TT> 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
<TT>RETURN</TT> or <TT>ENTRY</TT> will bring you back up to the next higher level.
<BR>
To pass parameters back to a higher level command,
use the command
<BR>
<TT>RETURN retpar1 ... retpar3</TT> . These return values can then be accessed
via the character keywords <TT>Q1, Q2, Q3</TT>.
This technique is an alternative to using global keywords for that purpose.
<BR>
To use the actual values of a parameter in the procedure, the formal
parameters P1,...,P8 have to be enclosed in curly brackets (<IMG
WIDTH="17" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img32.gif"
ALT="$\{$">,
<IMG
WIDTH="16" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img33.gif"
ALT="$\}$">):<BLOCKQUOTE>
<TT>!+ <BR>
! Example 1, MIDAS procedure exa1.prg <BR>
!+ <BR>
READ/KEYWORD </TT><IMG
WIDTH="17" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img34.gif"
ALT="$\{$"><TT>P1</TT><IMG
WIDTH="16" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img35.gif"
ALT="$\}$">! read keyword the name of which is given as par1 <TT>
<BR>
@@ test </TT><IMG
WIDTH="17" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img36.gif"
ALT="$\{$"><TT>P2</TT><IMG
WIDTH="16" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img37.gif"
ALT="$\}$">! execute test.prg and pass par2 as first parameter<TT>
<BR>
WRITE/KEYWORD INPUTC </TT><IMG
WIDTH="17" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img38.gif"
ALT="$\{$"><TT>P2</TT><IMG
WIDTH="16" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img39.gif"
ALT="$\}$">! write contents of par2 into keyword INPUTC</BLOCKQUOTE>Entering the MIDAS command <TT>@@ exa1 OUTPUTC ESO-Garching</TT> will lead
to the execution of:<BLOCKQUOTE>
<TT>READ/KEYWORD OUTPUTC <BR>
@@ test ESO-Garching <BR>
WRITE/KEYWORD INPUTC ESO-Garching</TT></BLOCKQUOTE>
<P>
<BR>
The command <TT>@@</TT> 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 <TT>`?'</TT>
(question mark))
are internally appended.
<BR>
Therefore, <TT>@@ exa1 OUTPUTC</TT> will put the character <TT>`?'</TT> into the
first element of the character keyword INPUTC.
<BR>
<BR>
If we enter the command <TT>ECHO/ON</TT> before executing the procedure we would
actually see the above commands displayed on the terminal
(cf. subsection <A HREF="node49.html#debugging-procedures-and-modules">3.8.1</A>).
<P>
<BLOCKQUOTE>
<DIV ALIGN="CENTER">
<B>Note</DIV>
<I>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 </I></B><IMG
WIDTH="17" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img40.gif"
ALT="$\{$"><B><I> and </I></B><IMG
WIDTH="16" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img41.gif"
ALT="$\}$"><B><I> instead, makes nesting
of substitutions possible.</I></B></BLOCKQUOTE> <BR>
The command <TT>DEFINE/PARAMETER</TT> 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 <TT>DEFINE/PARAMETER</TT> command.
<BR>
The default values defined inside the procedure will be used in case the
parameters are not explicitly provided (i.e. entered as <TT>`?'</TT>):
<P>
<BLOCKQUOTE>
<TT>!+ <BR>
! Example 2, MIDAS procedure exa2.prg <BR>
!+ <BR>
DEFINE/PARAM P1 999 NUMBER "Enter first input number:" 22,1024
<BR>
DEFINE/MAXPAR 1 </TT>! only 1 parameter expected<TT>
<BR>
WRITE/KEYWORD INPUTI/I/7/1 </TT><IMG
WIDTH="17" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img42.gif"
ALT="$\{$"><TT>P1</TT><IMG
WIDTH="16" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img43.gif"
ALT="$\}$">! store contents of P1 in INPUTI(7)</BLOCKQUOTE>The MIDAS command: <TT>@@ exa2 77</TT> will set INPUTI(7) to 77,
whereas <TT>@@ exa2</TT> will set INPUTI(7) to 999. <BR>
Entering <TT>@@ exa2 17</TT> will result in an error since the valid
interval for the number passed as the first
parameter is <TT>[</TT>22,1024<TT>]</TT>.
<BR>
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 <TT>`?'</TT> 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 <TT>DEFINE/PARAMETER</TT> command) .
<BR>
The <TT>DEFINE/PARAMETER</TT> 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.
<BR>
<BR>
The <TT>DEFINE/PARAMETER</TT> command also checks the type of the parameter<A NAME="1948"> </A>.
The types which may be tested are:
I(mage), T(able), F(itfile) , N(umber), C(haracter).
<BR>
If for any reason you do not want type checking, use the character
<TT>`?'</TT> instead of any of the types listed above.
<BR>
For file-type parameters the following translations are executed:
<BR>
catalog entry numbers, e.g. <TT>#27</TT> are replaced by the corresponding
file name in the catalog
(if that catalog is active!) and the asterisk (<TT>`*'</TT>) is substituted by
the currently displayed image, if any. <BR>
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.
<BR>
<BR>
Using the plus sign (<TT>`+'</TT>) 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 <TT>`?'</TT> and an explicitly entered
<TT>`?'</TT> parameter (see example 14a, 14b in
subsection <A HREF="node43.html#conditional-statements">3.6.5</A>).
<BR>
The system keyword <TT>PARSTAT</TT> holds 8 flags (for P1,...,P8) which are
set to 1 or 0, if the type of the <I>ith</I> parameter conforms
to the specified type or not.
If <TT>PARSTAT(i)</TT> is 0 for any i the MIDAS
procedure is aborted.
<BR>
However, if <TT>/C(ONTINUE)</TT> is appended to
any of the types listed above, the keyword
<TT>PARSTAT</TT> will only be set to 0 or 1 and the execution of the
procedure continues, leaving it to the user
to test <TT>PARSTAT(i)</TT> and decide how to go on.
<BR>
So in our example above
the command <TT>@@ exa2 KB</TT> will result in an error message
and the procedure is aborted.
<BR>
If we change the procedure to:<BLOCKQUOTE>
<TT>!+ <BR>
! Example 3, MIDAS procedure exa3.prg <BR>
!+ <BR>
DEFINE/PARAM P1 999 N/CONT "Enter first input number:" <BR>
DEFINE/MAXPAR 1 </TT>! only 1 parameter expected<TT>
<BR>
IF PARSTAT(1) .EQ. 1 - <BR>
WRITE/KEYWORD INPUTI/I/7/1 </TT><IMG
WIDTH="17" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img44.gif"
ALT="$\{$"><TT>P1</TT><IMG
WIDTH="16" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img45.gif"
ALT="$\}$">!store contents of P1 in INPUTI(7)</BLOCKQUOTE>then <TT>@@ exa3 KB</TT> will not yield any error.
<BR>
If we enter <TT>@@ exa3 RW PG CG KB MP PB</TT> the message
<BR>
<TT>Warning: 5 parameter(s) more entered than required...</TT>
<BR>
will be displayed
but the execution of the procedure continues (the additional parameters
are ignored). Note also the use of the continuation<A NAME="1970"> </A>
character (<TT>-</TT>) in the <TT>IF</TT> statement above.
<BR>
<BR>
The MIDAS command <TT>CROSSREF</TT> defines labels (of maximum 10 characters)
for the
<BR>
parameters P1,...,P8 to enable cross-referencing
of parameters if they are passed in arbitrary order.
<BLOCKQUOTE>
<DIV ALIGN="CENTER">
<B>Note</DIV>
<I>The command <TT>CROSSREF</TT> has to be the first executable
command (i.e. any command but a comment line) in a MIDAS procedure!
<BR>
The command <TT>DEFINE/MAXPAR</TT> 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.</I></B></BLOCKQUOTE> <BR>
If we modify <TT>exa3.prg</TT> to:<BLOCKQUOTE>
<TT>!+ <BR>
! Example 4, MIDAS procedure exa4.prg <BR>
!+ <BR>
CROSSREF IN_FILE OUT_FILE METHOD ALPHA <BR>
DEFINE/PARAM P1 ? IMA "Enter name of input file: " <BR>
DEFINE/PARAM P2 ? IMA "Enter name of result file: " <BR>
DEFINE/PARAM P3 ? C "Enter method: " <BR>
DEFINE/PARAM P4 999 NUM "Enter alpha value: " 22,1024
<BR>
DEFINE/MAXPAR 4 </TT>! max. 4 parameters expected<TT>
<BR>
WRITE/KEYWORD INPUTI/I/7/1 </TT><IMG
WIDTH="17" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img46.gif"
ALT="$\{$"><TT>P4</TT><IMG
WIDTH="16" HEIGHT="44" ALIGN="MIDDLE" BORDER="0"
SRC="img47.gif"
ALT="$\}$"></BLOCKQUOTE>then the following command lines will all be equivalent:<BLOCKQUOTE>
<TT>@@ exa4 in out FILTER 33 <BR>
@@ exa4 P2=out P1=in P4=33 P3=FILTER <BR>
@@ exa4 OUT_FILE=out IN_FILE=in alpha=33 METHOD=FILTER </TT></BLOCKQUOTE>
<P>
<BR>
The labels may be truncated, so also<BLOCKQUOTE>
<TT>@@ exa4 OUT=out IN_F=in al=33 METH=FILTER </TT></BLOCKQUOTE>is o.k.
<BR>
<BR>
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 <TT>INQUIRE/KEYWORD</TT> in the procedure. The execution of the
procedure is then interrupted and the user is prompted for a value before
continuing. For example,<BLOCKQUOTE>
<TT>!+ <BR>
! Example 5, MIDAS procedure exa5.prg <BR>
!+ <BR>
CROSSREF IN_FILE OUT_FILE <BR>
DEFINE/PARAM P1 ? IMA "Enter name of input file: " <BR>
DEFINE/PARAM P2 ? IMA "Enter name of result file: " <BR>
DEFINE/MAXPAR 2 </TT>! max. 2 parameters expected<TT>
<BR>
WRITE/KEYWORD IN_B " " all </TT>! fill keyword IN_B with blanks<TT>
<BR>
INQUIRE/KEYWORD IN_B "Which filter, enter LOW or HIGH: " <BR>
IF AUX_MODE(7) .EQ. 0 IN_B = "LOW" </TT>! LOW is the default<TT>
<BR></TT></BLOCKQUOTE> <BR>
The command <TT>@@ exa5 old new</TT> will stop with the message
<BR>
<TT>Which filter, enter LOW or HIGH: </TT>
<BR>
and wait for user input. The 7th
element of keyword <TT>AUX_MODE</TT> will contain the number of characters typed
in response to the <TT>INQUIRE/KEYWORD</TT> command. <TT>AUX_MODE(7)</TT> is
set to 0 if the user just types
<!-- MATH: $\fbox{\tt Return}$ -->
<IMG
WIDTH="83" HEIGHT="27" ALIGN="BOTTOM" BORDER="0"
SRC="img48.gif"
ALT="\fbox{\tt Return}">.
<P>
<HR>
<!--Navigation Panel-->
<A NAME="tex2html977"
HREF="node40.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
SRC="icons.gif/next_motif.gif"></A>
<A NAME="tex2html973"
HREF="node38.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
SRC="icons.gif/up_motif.gif"></A>
<A NAME="tex2html967"
HREF="node38.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
SRC="icons.gif/previous_motif.gif"></A>
<A NAME="tex2html975"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents"
SRC="icons.gif/contents_motif.gif"></A>
<A NAME="tex2html976"
HREF="node216.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index"
SRC="icons.gif/index_motif.gif"></A>
<BR>
<B> Next:</B> <A NAME="tex2html978"
HREF="node40.html">Symbol Substitution in Command</A>
<B> Up:</B> <A NAME="tex2html974"
HREF="node38.html">MIDAS Command Language</A>
<B> Previous:</B> <A NAME="tex2html968"
HREF="node38.html">MIDAS Command Language</A>
<!--End of Navigation Panel-->
<ADDRESS>
<I>Petra Nass</I>
<BR><I>1999-06-09</I>
</ADDRESS>
</BODY>
</HTML>
