Re: st: exiting mata completely

["William Gould, StataCorp LP" <wgould@stata.com>]

Patrick Roland <patrick.rolande@gmail.com> writes, 

> I'm have some mata code, and if some event occurs, then the code
> should immediately teminate and not execute any more statements. I'm
> having trouble achieving this simple task.
> 
> Take the following example. I do not want x to be assigned the value
> 0. But "exit(1)" does not stop "x=0" from being executed.
> 
>         mata
>         x = 9
>         exit(1)
>         x = 0
>         end

Are these lines in a do-file?  I assume they are, and if so, 
the solution is to change 

          mata

to read 

          mata:

That is, you must add a colon.  

See [M-3] mata, which you can do by typing 

        . help [M-3] mata
   or
        . help m3 mata 

When you type -mata- without a colon, you invoke Mata, and are telling 
Mata that you do not want Mata to exit (stop) when there's an error.  
One usually types -mata- withouta colon when using Mata interactively. 

When you type -mata:- with a colon, you invoke Mata, and are telling
Mata that you want Mata to exit (stop) when there's an error.

-exit()- is a lot easier to understand when it appears inside a Mata 
program.  Imagine the following 

         : function myprogram()
         > { 
         >         ...
         >         exit(1)
         >         x = 0
         >         ...
         > }

         : myprogram()
         --Break--
         r(1);


In this case, -exit(1)- would do exactly what Patrick expects it to do 
whether he specified -mata- or -mata:-.  What would it do?  It would 
exit the function, reporting a return code of 1.  Whether that would 
in turn cause an exiting of Mata would depend on whether Mata had been 
invoked by -mata- or -mata:-. All that means is that the next prompt 
we will see will be a Mata colon-prompt if we invoked by typing 
-mata- without the colon, 

        . mata        <- We omit the colon ...
        : ...
        : myprogram()
        --Break--
        r(1);

        : _           <- .. and we are still in Mata

or we will see a Stata dot prompt if we typed -mata- with the colon,



        . mata:       <- We type the colon ...
        : ...
        : myprogram()
        --Break--
        r(1);

        . _           <- ... and we are in Stata 


The effect of using -exit()- inside of programs is easy to understand. 
It exits the program.  The decision of where we exit to is determined 
by whether we invoked Mata by typing -mata- or -mata:-, because it's when 
we invoke Stata that we define what we mean by exit, and we do that by 
omitting or specifying the colon.

The effect of -exit()- outside of programs is more difficult to think about.
Just consider the line:

        : x=9
        : exit(1)
        : x=0

It's more diffulct to think about until you appreciate that when you 
type commands directly into Mata, each line is interpreted as its
own little program.  You see three lines above.  Mata sees three 
programs.  The first program sets x to 9.  The next program exits and 
sets the return code to 1.  The third third program sets x to 0. 

So what happens after -exit(1)-?  Does Mata continue to set x to 0, or 
does it exit Mata, too?  That depends on how Mata was invoked, whether 
it was -mata- or -mata:-.  

Patrick invoked Mata by typing -mata-.  So Mata stopped executing the 
second line -- the second program -- gave the corresponding error message, 
and continued executing.

This all sounds more confusing than it is because -exit()- is really 
indended for use in real programs and not intended so much for using 
in line-by-line mode. 

I wonder what Patrick is up to.  One possibility is Patrick as a do-file 
he's writing that looks like this, 

        -------------------------------------- myfile.do --------
        clear all

        use mydata 
        gen newvar = ... 

        mata:
        <do something useful to the dataset>
        end

        <now continue using Stata>
        -------------------------------------- myfile.do --------

In that case, Patrick needs to invoke Mata using -mata:-. 

Another way Patrick could organize this same problem is

        -------------------------------------- myfile.do --------
        clear all

        mata:
        function myprogram(...)
               <do semething useful to a dataset>
        }
        end

        use mydata
        mata: myprogram(...)
        <and continue using Stata>
        -------------------------------------- myfile.do --------

I bet -exit()- would have worked just as Patrick would have expected 
if he had used this second organization.  

-- Bill
wgould@stata.com
*
*   For searches and help try:
*   http://www.stata.com/help.cgi?search
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/