🛂 Stata errors

[Sergiy Radyakin]

Dear All,

the following section of the manual contains the error codes that Stata may issue:
https://www.stata.com/manuals/perror.pdf

It is apparently incomplete, as errors in the 5000+ range seem to be related to Java interaction:

. error 5001
unable to allocate memory for Java virtual machine
r(5001);

. error 5002
failure to dynamically load Java runtime library
r(5002);

. error 5003
unable to create Java virtual machine
r(5003);

1. Is it possible to get an updated list of all defined error codes?
By "defined error code" I mean such a code #, that the command error # produces not just the r(#) message, but also an explanatory message of any kind. For example, error code 5003 is defined and 6003 is not defined according to this definition.

2. Is it possible [for Stata developers] to indicate a range for user error codes?
By "user error code" I mean such a code # , that no future Stata version will decorate with an explanatory message (or will not make a "defined error code" according to the above definition).

The reason for request #2 is that I had an archaic code which used to signal errors in the 5000+ range with own messages, such as

display as error "Error! Parameter 'a' may not be larger than the sum of 'b' and 'c'"
error 5001

which worked fine in Stata 8/9, but is now decorated with the totally confusing "unable to allocate memory for Java virtual machine" message.

Thank you, Sergiy

[Sebastian Kripfganz]

Whenever I display my own error message, I code

exit #

instead of

error #

to avoid any default error message to be displayed.

For something like "Parameter 'a' may not be larger than the sum of 'b' and 'c'", I would probably use error code 498 or 499 which are reserved for "various messages" related to statistical problems. Depending on the problem, error codes 322 or 459 might also be appropriate.

But I agree that an updated list of error codes would be nice.

[William Lisowski]

The root documentation problem is that output of help error does not suggest that if you want to exit with an error code, without the decoration, the exit command accepts an optional return code, and this feature is documented only in the Stata Programming Reference Manual PDF. In the output of help exit the link

If you wish to use exit in do-files or programs to set return codes or terminate programs, see [P] exit.

is the hint to what you seek.

. capture program drop gnxl

. program define gnxl
  1. display as error "Error! Parameter 'a' may not be larger than the sum of 'b' and 'c'"
  2. exit 5001
  3. end

. gnxl
Error! Parameter 'a' may not be larger than the sum of 'b' and 'c'
r(5001);

end of do-file

r(5001);

.

With that said, I agree that Stata should set aside a range of error codes for which "basic" error messages will never be defined, so that your r(5001) is not confused with the default r(5001), as it were.

[Jesse Wursten]

I'll admit this was not the content I was expecting when I read the title, even though it is exactly what the title describes

[Sergiy Radyakin]

Dear Sebastian and William,

thank you very much for looking into the issue and suggesting the use of exit # instead of error #.

This fits what I was looking for. Even better, reworking older code should not be problematic, with just substituting one command for the other.

Thank you, and best regards, Sergiy