This will probably only be of interest to ado file writers wanting to
reference return codes following official Stata values when doing
error checking in routines.
It is easy to find an explanation of a return code because the code
displayed in the results window is hyperlinked to the relevant help
file. However, the reverse is not true. One often has to -hsearch
"words I'd expect to be in the error I'm trapping"- and then sort
through a long list to find the relevant return code.
I decided to create a help file of all Stata return codes so that one
could search the text directly. Once it has created the help file
one can -help returncodes- to bring it up. The rc2help.ado only has
to be run once to create the help file although you may want to run it
again after major upgrades as I'm sure Stata adds new codes from time
to time.
Notes:
Stata version - I've named the help file with the new ".sthlp"
extension for Stata 10 users. Pre-Stata 10 will get ".hlp"
Error range logic - Stata appears to have reserved ranges for
different error types which may help with searching:
Range Error type
1-499 general
500-600 matrix
601-622 file I/O
623-678 net connection
679-699 file I/O
700-950 memory
1000-1400 limits
2000-2001 too many/few obs
3000-3998 mata
4005-4031 class
9000+ kiss your butt goodbye
Future development - I've inserted SMCL {marker ##} codes for each
return code. This allows you to go directly to a return code in the
viewer address box by typing something like: help returncodes##601 .
However, I can't figure out how to do that from the command line other
than doing something like: -di "{help returncodes##601}"- and clicking
the hyperlink. If anyone could enlighten me... I may create an index
at the top in some future iteration.
save as rc2help.ado
x----------------begin code----------------x
program define rc2help
version 9.0
*! version 1.0.0 2009.01.09
*! Create a consolidated help file of error (return) codes
*! by David C. Elliott
findfile stata14.key
tempname hi ho
file open `hi' using "`r(fn)'" , r
// watch following line for wrapping
file open `ho' using
"`c(sysdir_personal)'returncodes.`=cond(`c(stata_version)'
>=10,"sthlp","hlp")'" , w replace
file write `ho' "{smcl}" _n "{com}{sf}{ul off}{txt}" _n
local write 0
local newcode 0
file read `hi' line
while r(eof)==0 {
if !inlist(substr(`"`macval(line)'"',2,1),"e","c","k","x") {
if strpos(`"`line'"',".t")==1 { // each section starts with a ".t"
local write 1
local newcode 1
}
else if `"`line'"' == "" {
local write 0
file write `ho' _n
}
if `write' {
if `newcode' {
if regexm(`"`line'"',".*Return code ([0-9]+)") == 1 {
local rc `=regexs(1)'
file write `ho' ///
"{smcl}" _n ///
"{title:Return code `rc'{marker `rc'}}" _n ///
"{s6hlp}" _n
local newcode 0
}
}
else {
file write `ho' `"`macval(line)'"' _n
}
}
}
file read `hi' line
}
file close _all
help returncodes
end
x------------------end code----------------x
I suspect this could be generalized to make a quick and dirty help
file out of any of the stata##.key files.
--
David Elliott
*
* 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/
