cscript.hlp

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

{smcl}
{* 09mar2005}{...}
{cmd:help cscript}{right:also see:  {help undocumented}}
{hline}

{title:Title}

{p 4 17 2}
{cmd:cscript} {hline 2} Begin certification script


{title:Syntax}

{p 8 16 2}{cmd:cscript} [[{cmd:"}]{it:text}[{cmd:"}]]
		[{cmdab:adofile:s} {it:adofile-list}]


{title:Description}

{pstd}
{cmd:cscript} begins a Stata certification script.

{pstd}
It displays a header, performs a {cmd:which} on any listed ado-file (see
{helpb which}), and drops all

	value labels
	macros
	programs
	scalars
	matrices
	constraints
	equations
	previous estimation results

{pstd}
{cmd:cscript} resets {cmd:matsize} to 40 for Small Stata,
200 for Intercooled Stata, and 400 for {help SpecialEdition:Stata/SE});
see {help matsize}.  {cmd:cscript} also sets {cmd:maxiter} to
100; see {help maxiter}.

{pstd}
The purpose is to reset Stata to initial, default conditions so that
certification scripts may be run one after the other without the results of
one certification script affecting the results of another.  The default
for {cmd:maxiter} in Stata is 16000, but {cmd:cscript} sets it to 100
so that test scripts with bad models will not have excessive run times.
Programmers must specify the {cmd:iterate()} option on commands which
they wish to be able to iterate more than 100 times; see {help maximize}.


{title:Remarks}

{pstd}
{cmd:cscript} is not documented in the manual because it would not interest
many users.

{pstd}
A certification script is a do-file that tests whether a feature of Stata,
an ado-file, or even a user-written command works.

{pstd}
The first line of a certification script do-file should read

{phang2}{cmd:cscript} {it:description_of_test}

{pstd}
For instance,

{phang2}{cmd:cscript sktest}{p_end}
    or
{phang2}{cmd:cscript sktest under usual conditions}

{pstd}
might be the beginning of a do-file that tests {cmd:sktest}.  If
{cmd:sktest} is an ado-file -- as it is -- then a better opening would be

{phang2}{cmd:cscript sktest adofile sktest}{p_end}
    or
{phang2}{cmd:cscript "sktest under usual conditions" adofile sktest}

{pstd}
or, if you prefer, you may perform the {cmd:which} for yourself following
the {cmd:cscript} command:

{phang2}{cmd:cscript sktest}{p_end}
{phang2}{cmd:which sktest}

{pstd}
Which style you use makes no difference but you should perform the
{cmd:which}.  This way, if you save a log of running the certification script,
you will know which version of {cmd:sktest} you last tested.


{title:Other documented and undocumented commands for writing certification scripts}

{p 4 19 2}{helpb assert} {space 7} verify truth of claim{p_end}
{p 4 19 2}{helpb confirm} {space 6} argument verification{p_end}
{p 4 19 2}{helpb cscript_log} {space 2} control SMCL log files{p_end}
{p 4 19 2}{helpb lrecomp} {space 6} display log relative errors{p_end}
{p 4 19 2}{helpb mkassert} {space 5} generate {cmd:assert}s{p_end}
{p 4 19 2}{helpb rcof} {space 9} verify return code{p_end}
{p 4 19 2}{helpb savedresults} {space 1} manipulate and verify saved results {hi:r()} and {hi:e()}{p_end}
{p 4 19 2}{helpb version} {space 6} run command under version control

{pstd}
Type {cmd:help} followed by the command name for more information.

{pstd}
The {cmd:reldif()} (relative difference) and {cmd:mreldif()} (matrix
relative difference) functions are also helpful in certification scripts; see
{helpb reldif()}.


{title:An example certification script}

{pstd}
At StataCorp, if we have an ado-file called mycmd.ado, we write a
corresponding certification script called mycmd.do.  The script might be

	{hline 3} BEGIN {hline 3} mycmd.do {hline 48}
	{cmd}cscript mycmd adofile mycmd

	use xmpl
	mycmd x1 x2
	assert abs(r(z)-2.5)<=1e-15

	keep if x3==2
	mycmd x1 x2
	local hold = r(z)

	use xmpl, clear
	mycmd x1 x2 if x3==2
	assert r(z) == `hold'

	rcof "noisily mycmd x1" == 102       /* too few variables specified */
	rcof "noisily mycmd x1 x2 x3" == 103 /* too many variables specified */{txt}
	{hline 5} END {hline 3} mycmd.do {hline 48}

{pstd}
A real certification script would be much longer.


{title:Combining certification scripts}

{pstd}
At StataCorp, we then combine all of our certification scripts into a super
certification script.  mycmd.do then becomes one element of the super script:

	{hline 3} BEGIN {hline 3} super.do {hline 3}
	{cmd}do anova
	do assert{txt}
	...
	{cmd}do merge
	do mycmd{txt}
	...
	{hline 5} END {hline 3} super.do {hline 3}

{pstd}
We can run all the certification scripts by typing {cmd:do super}.


{title:Writing a good certification script}

{pstd}
The purpose of a certification script is to

{phang2}1.  test that the command produces the right answers in a few
cases where the solution is known;

{phang2}2.  establish that the command works as it should under extreme
conditions, such as R^2=1 regressions;

{phang2}3.  verify that the command responds to mistakes users are
likely to make in a dignified manner.

{pstd}
Certification scripts are written for two reasons:

{phang2}1.  To establish on day 1 (the day the command is written) that
the command works.

{phang2}2.  To allow future changes to be made to the command with some
assurance that the changes really are improvements.  (One simply reruns the
certification script.)

{pstd}
A good certification script stops when there is a problem.  This way, typing

	{cmd:. do mycmd}
	[output omitted]
	end of do-file

{pstd}
and seeing it run to completion (i.e., seeing Stata respond "end of do-file"
with return code 0) demonstrates that, at least for the recorded problems, the
command works as expected.  You do not want a script where you are required to
review the output to determine whether there are any mistakes.  Thus, a script
that included the lines

{phang2}{cmd:regress mpg weight}{p_end}
{phang2}{cmd:regress mpg weight displ}

{pstd}
would be a poor test of {cmd:regress}.  If the results were wrong, would you
notice?  A better test script would read

{phang2}{cmd:regress mpg weight}{p_end}
{phang2}{cmd:assert abs(_b[weight]- -.0060087) < 1e-7}{p_end}
{phang2}{cmd:assert abs(_b[_cons]- 39.44028) < 1e-5}

{phang2}{cmd:regress mpg weight displ}{p_end}
{phang2}{cmd:assert abs(_b[weight]- -.0065671) < 1e-7}{p_end}
{phang2}{cmd:assert abs(_b[displ]- -.0052808) < 1e-7}{p_end}
{phang2}{cmd:assert abs(_b[_cons]- 40.08452) < 1e-5}

{pstd}
and one that read

{phang2}{cmd:regress mpg weight}{p_end}
{phang2}{cmd:assert abs(_b[weight]- -.0060087) < 1e-7}{p_end}
{phang2}{cmd:assert abs(_b[_cons]- 39.44028) < 1e-5}{p_end}
{phang2}{cmd:assert abs(_se[weight]-.0005179) < 1e-7}{p_end}
{phang2}{cmd:assert abs(_se[_cons]- 1.614003) < 1e-6}

{phang2}{cmd:regress mpg weight displ}{p_end}
{phang2}{cmd:assert abs(_b[weight]- -.0065671) < 1e-7}{p_end}
{phang2}{cmd:assert abs(_b[displ]- -.0052808) < 1e-7}{p_end}
{phang2}{cmd:assert abs(_b[_cons]- 40.08452) < 1e-5}{p_end}
{phang2}{cmd:assert abs(_se[weight]-.0011662) < 1e-7}{p_end}
{phang2}{cmd:assert abs(_se[displ]-.0098696) < 1e-7}{p_end}
{phang2}{cmd:assert abs(_se[_cons]- 2.02011) < 1e-6}

{pstd}
would be even better.

{pstd}
To establish that the command responds to mistakes, see
{helpb rcof}.  Scripts should include intentional mistakes and then verify
results are as expected.  For instance,

{phang2}{cmd:discard} {space 15} /* eliminate regression results         */{p_end}
{phang2}{cmd:rcof "regress" == 301} {space 1} /* should be "last estimates not found" */

{pstd}
{cmd:rcof} suppresses all output of the command, so induced errors are
usually coded with a {cmd:noisily} placed in front of the command.

{phang2}{cmd:rcof "noisily regress" == 301}

{pstd}
See {helpb noisily}.


{title:Also see}

{psee}
Online:  {helpb assert}, {helpb cscript_log},
{help matsize}, {helpb rcof},
{helpb savedresults}, {helpb which}
{p_end}