Program debugging command                                         [STB-13: ip4]
-------------------------

		^pause^ { ^on^ | ^off^ | [message] }


Description
-----------

If pause is on, a ^pause^ in a Stata program temporarily suspends execution of
the program and returns control to the keyboard.  Execution of keyboard com-
mands continues until you type ^end^ or ^q^, at which time execution of the pro-
gram resumes.  Typing ^BREAK^ in pause mode (as opposed to pressing the Break
key) also resumes program execution, but the Break signal is sent back to the
calling program.

If pause is off, ^pause^ does nothing.

Pause is off by default.  Type ^pause on^ to turn pause on.  Type ^pause off^
to turn it back off.


Remarks
-------

You have a program that is not working properly.  A piece of this program
reads:

		^gen `tmp'=exp(`1')/`2'^
		^summarize `tmp'^
		^local mean=_result(3)^

	
You think the error may be in the creation of `tmp'.  You change the 
program to read:

		^gen `tmp'=exp(`1')/`2'^
		^pause Just created tmp^        /* this line is new */
		^summarize `tmp'^
		^local mean=_result(3)^



Interactively, now type:


Remarks, continued
------------------

	. (command to invoke your program)
			     (output from your program appears)

That is, ^pause^ does nothing.  It does nothing because pause is off and so 
^pause^s in your program are ignored.  If you set pause on:

	. ^pause on^

	. (command to invoke your program)
			     (any output your program creates up to the pause
			      appears here)
	pause:  Just created tmp
	-> . ^describe^
	                     (output omitted)
	-> . ^list^
	                     (output omitted)
	-> . ^end^
	execution resumes...
	                     (output from your program)


Remarks, continued
------------------

The "->" is called the pause-mode prompt.  You can give any Stata command.
You can examine variables and, if you wish, even change them.  

If, while in pause mode, you wish to terminate execution of your program, 
you type ^BREAK^ (in capitals):

	. (command to invoke your program)
			     (any output your program creates up to the pause
			      appears here)
	pause:  Just created tmp
	-> . ^list^
	                     (output omitted)
	-> . ^BREAK^
	sending Break to calling program...
	--Break--
	r(1);

	.



Remarks, continued
------------------

The results are the same as if you pressed Break while your program were 
executing.  If you press the Break key in pause mode (as opposed to typing
^BREAK^), however, it means only that the execution of the command you have 
just given interactively is to be interrupted.





Notes
-----

1)  You may put many pauses in your programs.


2)  By default, pause is off, so the pauses will not do anything.  Even so,
    you should remove the pauses after your program is debugged because 
    each execution of a do-nothing ^pause^ will slow your program slightly.



Notes, continued
----------------


3)  ^pause^ is implemented as an ado-file; this means the definitions of local
    macros in your program have been made unavailable to you.  To see the 
    value of local macros, display them in the ^pause^ message; for instance

		^pause Just created tmp, i=`i'^

    Then, when the line is executed, you will see something like:

	pause:  Just created tmp, i=1
	-> .










Notes, concluded
----------------

4)  Remember, temporary variables (e.g., ^tempvar tmp^, ^gen `tmp'=^...") are 
    assigned real names such as __00424 by Stata.  Thus, in pause mode you
    want to examine __00424 and not tmp.  Generally, you can determine the
    real name of your temporary variables from ^describe^'s output, but in the
    example above, it would be better had ^pause^ been invoked with:

	. ^pause Just created tmp, called `tmp', i=`i'^

    Then, when the line is executed, you will see something like:

	pause:  Just created tmp, called __00424, i=1
	-> .
.
.
.