% @(#)write_erro.mlq	13.1.1.1 (ESO-IPG) 09/01/98 12:03:53 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      write_err.mlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, WRITE/ERROR
%.PURPOSE    On-line help file for the command: WRITE/ERROR
%.VERSION    1.0  20-FEB-1986 : Creation, KB
%----------------------------------------------------------------
\se
SECTION./ERRO
\es\co
WRITE/ERROR						16-JAN-1999  KB
\oc\su
WRITE/ERROR err_spec [message]
	force an error within a Midas procedure
\us\pu
Purpose: 
           Enforce a Monitor or application error from a Midas procedure.
\up\sy
Syntax: 
           WRITE/ERROR err_spec [message]
\ys\pa
           err_spec = errno[,err_source[,display_flag]] with 
\\
               errno = error no., err_source = MONITOR or APPLIC,
\\
               for APPLIC you can also set display_flag for `message' to 
               No or Yes (default),
\\
               for MONITOR `message' is always displayed;
\\
               defaulted to Monitor
\ap\pa
           message = optional text string to be displayed
\ap\sa
See also:
           WRITE/OUT, HELP/KEYW PROGSTAT
\as\no
Note:  
           For Monitor errors, the error no. should be > 0;
\\
             then it serves as pointer into the relevant section in the 
             ASCII file MID_MONIT:syserr.dat .
\\
             The text in this section is displayed (after display of 
             `message', if any) and also stored in the keyword MID$ERRMESS. 
\\
             If error no. < 0 just the text "Error no. `errno'" is stored
             in MID$ERRMESS.
\\
           For application errors, `message' itself is displayed if the
              display_flag is set to Yes (default) and always stored
              in MID$ERRMESS. If no `message' given, it's set to
              "Error no. `errno'".
\\
           The value of `errno' is always stored in keyword PROGSTAT(1)
\\
           The procedure containing WRITE/ERROR as well as any procedure 
           calling this procedure will be aborted.
\on\exs
Examples:
\ex
           WRITE/ERROR 5 "my error stuff"
\\
             This line in a procedure would result in the following output:
             My error stuff
             Wrong syntax...
                                 if you're an expert user, or:
             My error stuff
             Wrong syntax... Use the HELP command to verify the command syntax.
                                 if you're a novice user
\\
             because file MID_MONIT:syserr.dat contains:
             NOVICE.005
             Wrong syntax... Use the HELP command to verify the command syntax.
\\
             The procedure will then terminate and also any procedure calling 
             this one.
\\
             Keword MID$ERRMESS will contain the string:
             Wrong syntax... Use the HELP command to verify the command syntax.
\xe\ex
           WRITE/ERROR 100
             leads to:
             Invalid input... The input for this MIDAS command is not correct. 
             Check the spelling of names, the data format, the file protection,
             etc.
             Use the HELP of the command to check out the parameters.
\\
             Keword MID$ERRMESS will contain the string:
             Invalid input... The input for this MIDAS command is not correct.
\xe\ex
           WRITE/ERROR 5,app "my error stuff"
             leads to the display of:
             My error stuff
             And also keword MID$ERRMESS will contain the string above.
\xe\ex
           WRITE/ERROR 100,app
             leads to the display of:
             Error no. 100
             And also keyword MID$ERRMESS will contain the string above.
\xe\ex
           WRITE/ERROR 100,app,no
             doesn't display anything but stores the message: "Error no. 100"
             into keyword MID$ERRMESS.
\xe \sxe