m3_mata.hlp

是一个经济学管理应用软件 很难找的 但是经济学学生又必须用到

{smcl}
{* 28mar2005}{...}
{cmd:help m3 mata}
{hline}
{* index mata tt invocation command}{...}

{title:Title}

{p 4 4 2}
{bf:[M-3] mata -- Mata invocation command}


{title:Syntax}

{p 4 4 2}
{it:(The} {cmd:mata} {it:command documented here is for use from Stata.}
{it:It is how you enter Mata.}  
{it:You type {cmd:mata} at a Stata dot prompt,} 
{it:not a Mata colon prompt.)}


	Syntax 1{col 41}comment
	{hline 70}
	{cmd:mata}{col 41}no colon following {cmd:mata}
		{it:istmt}
		{it:istmt}{col 41}if an error occurs, you stay in 
		..{col 41}{cmd:mata} mode
		{it:istmt}
	{cmd:end}{col 41}you exit when you type {cmd:end}
	{hline 70}
	Syntax 1 is the best way to use Mata interactively


	Syntax 2{col 41}comment
	{hline 70}
	{cmd:mata:}{col 41}colon following {cmd:mata}
		{it:istmt}
		{it:istmt}{col 41}if an error occurs, you are 
		..{col 41}dumped from {cmd:mata}
		{it:istmt}
	{cmd:end}{col 41}otherwise, you exit when you type {cmd:end}
	{hline 70}
	Syntax 2 is mostly used by programmers in ado-files.
	Programmers want errors to stop everything.


	Syntax 3{col 41}comment
	{hline 70}
	{cmd:mata}  {it:istmt}{col 41}rarely used
	{hline 70}
	Syntax 3 is the single-line variant of Syntax 1, but it is not
	very useful


	Syntax 4{col 41}comment
	{hline 70}
	{cmd:mata:} {it:istmt}{col 41}for use by programmers
	{hline 70}
	Syntax 4 is the single-line variant of Syntax 2, and it exists for
	the same reason as Syntax 2:  for use by programmers in ado-files.


{title:Description}

{p 4 4 2}
The {cmd:mata} command invokes Mata.
An {it:istmt} is something Mata understands; {it:istmt} stands for 
"interactive statement of Mata".


{title:Remarks}

{p 4 4 2}
For interactive use, use syntax 1.  Type {cmd:mata} (no colon), press 
enter, and then use Mata freely.  Type {cmd:end} to return to Stata.
(When you exit from Mata back into Stata, Mata does not clear itself; 
so if you later type {cmd:mata}-followed-by-enter again, you will be 
right back where you were.)

{p 4 4 2}
For programming use, use Syntax 2 or Syntax 4.
Inside a program or an ado-file, you can just call a Mata function

	{cmd}program myprog
		{txt:...}
		mata: utility("`varlist'")
		{txt:...}
	end{txt}

{p 4 4 2}
and you can even include that Mata function in your ado-file

	{hline 50} myprog.ado {hline}
	{cmd}program myprog
		{txt:...}
		mata: utility("`varlist'")
		{txt:...}
	end

	mata:
	function utility(string scalar varlist)
	{
		{txt:...}
	}
	end{txt}
	{hline 50} myprog.ado {hline}
		
{p 4 4 2}
or you could separately compile {cmd:utility()} and put it in an 
.mo file or in a Mata library.


{title:The fine distinction between syntaxes 3 and 4}

{p 4 4 2}
Syntaxes 3 and 4 are both single-line syntaxes.  You type {cmd:mata}, 
perhaps a colon, and follow that with the Mata {it:istmt}.

{p 4 4 2}
The differences between the two syntaxes is whether they allow 
continuation lines.  With a colon, no continuation line is allowed.
Without a colon, you may have continuation lines.

{p 4 4 2}
For instance, let's consider 

	{cmd}function renorm(scalar a, scalar b)
	{c -(}
		...
	{c )-}{txt}

{p 4 4 2}
No matter how long the function, it is a single {it:istmt}.
Using {cmd:mata:}, if you were to try to enter that {it:istmt}, 
here is what would happen:

	. {cmd:mata: function renorm(scalar a, scalar b)}
	{err:<istmt> incomplete}
	r(197);

{p 4 4 2}
When you got to the end of the first line and pressed enter, you got an 
error message.  Using the {cmd:mata:} command, the {it:istmt} must 
all fit on one line.

{p 4 4 2}
Now try the same thing using {cmd:mata} without the colon:

	. {cmd:mata function renorm(scalar a, scalar b)}
	> {cmd:{c -(}}
	>     ...
	> {cmd:{c )-}}

	. 

{p 4 4 2}
That worked!  Single-line {cmd:mata} without the colon allows continuation
lines and, on this score at least, seems better than single-line {cmd:mata}
with the colon.  In programming contexts, however, this feature can bite.
Consider the following program fragment:

	{cmd}program example
		{txt:...}
		mata utility("`varlist'"
		replace `x' = ...
		{txt:...}
	end{txt}

{p 4 4 2}
Note that we used {cmd:mata} without the colon and that we made an error:  we
forgot the close parenthesis.  {cmd:mata} without the colon will be looking
for that close parenthesis and so will eat the next line -- a line not
intended for Mata.  In this case, we will get an error message because
"{cmd:replace `x' = }..." will make no sense to Mata, but that error will be
different from the one we should have gotten.  In the unlikely worse case,
that next line will make sense to Mata.

{p 4 4 2}
Ergo programmers want to include the colon.  It will make your programs
easier to debug.

{p 4 4 2}
There is, however, a programmer's use for single-line {cmd:mata} without the
colon.  In our sample ado-file above when we included the routine
{cmd:utility()}, we bound it in {cmd:mata:} and {cmd:end}.  It would be
satisfactory if instead we coded

	{hline 50} myprog.ado {hline}
	{cmd}program myprog
		{txt:...}
		mata: utility("`varlist'")
		{txt:...}
	end

	mata function utility(string scalar varlist)
	{
		{txt:...}
	{c )-}{txt}
	{hline 50} myprog.ado {hline}

{p 4 4 2}
Using {cmd:mata} without the colon, we can omit the {cmd:end}.
We admit we sometimes do that.


{title:The fine distinction between syntaxes 1 and 2}

{p 4 4 2}
Nothing said above about continuation lines applies to syntaxes 1 and 2.
The multiline {cmd:mata}, with or without colon, always allows continuation
lines because where the Mata session ends is clear enough:  {cmd:end}.

{p 4 4 2}
The difference between the two multiline syntaxes is whether Mata is
tolerant of errors or instead dumps you back into Stata.
Interactive users appreciate tolerance.  Programmers want strictness.
Programmers, consider the following (using {cmd:mata} without the colon):

	{cmd:program example2}
		...
		{cmd:mata}
			{cmd:result = myfunc("`varlist'")}
			{cmd:st_local("n" result)}           /* <- mistake here */
			{cmd:result = J(0,0,"")}
		{cmd:end}
		...
	{cmd:end}

{p 4 4 2}
In the above example, we omitted the comma between {cmd:"n"} and
{cmd:result}.  We also used multiline {cmd:mata} without the colon. 
Therefore, the incorrect line will be tolerated by Mata, which will 
merrily continue executing our program until the {cmd:end} statement, 
at which point Mata will return control to Stata and not tell Stata that 
anything went wrong!  This could have serious consequences; all of which 
could be avoided by substituting multiline {cmd:mata} with the colon.


{title:Also see}

{p 4 13 2}
Manual:  {hi:[M-3] mata}

{p 4 13 2}
Online:  help for 
{bf:{help m3_intro:[M-3] intro}}
{p_end}