Finding a syntax error

[Helder Costa]

Hello!

I wrote a Stata program that is being used by other people in machines to which I don't have access to. In a single instance (of around 5 to 10 people using the program independently), someone using Stata 14 reported back with a syntax error r(197). A log file with trace on (see bellow exact settings) doesn't reveal anything about the error. The error occurs immediately as the program starts.

Because the data is confidential, I can't have access to it and try to debug it on my side. We think the problem is the Stata version because we attempted mock datasets which also result in the same problem.

Things I tried were:
- setting trace on
- try a mock dataset (error still occurs)
- use the version command on my Stata 18 to try to replicate the error, but without success

Settings used for trace on:

set tracedepth 32000
set traceexpand on
set tracesep on
set traceindent off
set tracenumber on
set trace on

As I can't actually have access to the machine/data in question, I've run out of ideas.

Is anyone aware of possible changes from Stata 14 that could cause this?

Does anyone have any suggestions on what we could do to find the error?

Thank you very much!

Best,
Hélder

[daniel klein]

The return code 197 points to a problem in the syntax (or another parsing command) itself rather than in what is being parsed. Unless someone misused the return code, you should be able to narrow down the problem quite a bit.

[Helder Costa]

Thank you daniel klein. Can you elaborate on what is a parsing command? What does being parsed mean? What is the return code?

[Nick Cox]

Here's my informal definition.

A parsing command in general takes a string and splits it into parts (and, often, tests its consistency with some declared syntax).

syntax is a parsing command in the sense that it specifies an allowed syntax for a command but as side-effect either parses your syntax into elements or rejects your syntax as incompatible with what syntax says is allowed. Note the use of different fonts there.

If you have program foo then whatever you type after foo becomes the content of local macro 0 (zero). It's that which is matched against what syntax says.

There are plenty of exceptions. For example gettoken can be mighty useful as a parsing command and args might suit your purpose more simply.

daniel klein already exemplified return code. A return code is an integer which is 0 if everything was OK from Stata's point of view and is positive otherwise.

A return code is implicit when 0 and explicit otherwise.

If I type STOP which is a fine way to stop execution of code when you want to go only so far

.

 STOP
command STOP is unrecognized
r(199);

. error 199
unrecognized command
r(199);

I get an error message and an return code 199. In this case and many others the generic meaning of that code is not much clearer from what error returns, but the manual entry can be helpful.

I've seen 1776 as appropriate error code in some context where British and American spellings were both envisaged.

[daniel klein]

So here is an example. Consider the program

program no_error_in_syntax
    
    version 18
    
    syntax varname
    
end

The command syntax is a parsing command because it parses, i.e., analyzes and interprets arguments; here, the arguments to be passed to the program no_error_in_syntax. When there is something wrong with what's being parsed, syntax complains.

. no_error_in_syntax 42
42 invalid name
r(198);

Here, I typed 42 where syntax expected a varname. In Stata, 42 is not a valid (variable) name and, thus, not what syntax expected. Thus, syntax tells me what's wrong and points me to the return code of 198, which indicates a syntax error. Compare this with the following.

program error_in_syntax
    
    version 18
    
    syntax variable
    
end

Here, I typed variable where the syntax command takes varlist or varname as valid arguments. When I call the program error_in_syntax, I get

. error_in_syntax 42
invalid syntax
r(197);

The error message is more generic here. It's a syntax error. The return code is different, too. It's 197. The syntax error is the invalid argument variable that I fed to syntax, the parsing command, rather than 42, the argument to be parsed.



Edit / added:

I realize that my example above isn't exactly great. I wanted to show a situation where you would get the same, generic error message: syntax error, with different return codes. It's surprisingly hard to get syntax to display a generic error message. And, that's a good thing! Anyway, I hope that together with Nick Cox explanation, the example is still helpful. My point is this: Whenever you see r(197), the syntax error is on the programmer's side, not the users'.

[Helder Costa]

Thank you both, Daniel Klein and Nick Cox, for your super clear explanation.

However, I’m still struggling to pinpoint why an error occurs on one computer but not the other, even though I’m using the same dataset, do-files, and ado-files on both. Could it be related to differences in the Stata version (e.g., using Stata 14 on one computer)? How can I definitively confirm whether the issue is due to the older version?

[daniel klein]

You are not giving us a lot to work with. You say that

A log file with trace on (see bellow exact settings) doesn't reveal anything about the error.

which I do not understand, especially because you then say

The error occurs immediately as the program starts.

So, you seem to have a pretty good idea where the error occurs, i.e., which program causes the error. Now, what's the last line(s) in the log before the error occurs? What are the first couple of lines into the program in question? Does the program have a syntax statement? If so, what does it look like?

[daniel klein]

I wrote a Stata program that is being used by other people in machines to which I don't have access to.n a single instance (of around 5 to 10 people using the program independently), someone [...] reported back with a syntax error r(197).

So here are more questions that would help us help you:

How many versions of this program did you write? How many did you distribute? How did you distribute them? Are you sure you're using the same version of your program as the person who reports the problems? Why are you sure, i.e., what exactly did you and the other person do to compare the versions?

[Helder Costa]

Indeed, I completely understand your comment Daniel Klein. The main issue is that I'm not sure which information I can collect so that I can find the error or to share here to get help.
Addressing your points, I'm sharing bellow a blanked version of the log file. I believe I'm not allowed to share the unblanked version, which is why I didn't provide any in the first place.
Regarding the other points, several versions where written, but only two were distributed. I know that the person is using the latest and same as myself because the version is printed into the log file (in this case v1.1). They were distributed by email. Having this in mind, and considering that I generated a specific mock data and inserted all options myself in the dofile that calls the program, then I tested the program in my machine (Stata 18) and then asked the person to check if the error would still occur on his side (which it did) - I'm quite confident that everything is the same but the Stata version/ operating system/ machine.

Thanks once again!

Blanked log file:

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
name: <unnamed>
log: blanked
log type: text
opened on: 13 Nov 2024, 14:02:45

. timer on 1

.
.
. set tracedepth 32000

. set traceexpand on

. set tracesep on

. set traceindent off

. set tracenumber on

. set trace on

.
. **# 6. Define inputs to used
. blanked_prog_name, ///
> blanked(blanked /*string*/) ///
> blanked(blanked /*string*/) ///
> blanked(blanked /*string*/) ///
> blanked(blanked /*varname numeric*/) ///
> blanked(blanked /*varname numeric*/) ///
> blanked(1 /*integer 1*/) ///
> blanked(1 /*integer 1*/) ///
> blanked(1 /*integer 1*/) ///
> blanked(1 /*integer 1*/) ///
> blanked(1 /*integer 1*/) ///
> blanked(0 /*integer 1*/)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------- begin blanked_prog_name ---
02 - noi di _n _n "================================"


================================
02 - noi di "================================"
================================
02 - noi di " blanked project name v1.1 "
blanked project name v1.1
02 - noi di " blanked "
blanked 2024
02 - noi di "================================"
================================
02 - noi di "================================" _n _n
================================


02 - syntax, blanked(string) blanked(string) [blanked(string) blanked(string) blanked(string) blanked(name) blanked(name) blanked(name) blanked(integer 1) blanked(integer 5) blanked(integ
> er 5) blanked(integer 1) blanked(integer 1) blanked(integer 0) blanked(integer 1) blanked(integer 1) blanked(integer 1) blanked(integer 0
> ) blanked(integer 1) blanked(integer 1) blanked(integer 1) blanked(integer 0) blanked(integer 0) blanked(integer 10) blanked(namelist) blanked
> (name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist)
> blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name
> ) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name
> ) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(
> namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(na
> melist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist) blanked(name) blanked(namelist)
> blanked(name) blanked(namelist) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(na
> me) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(nam
> e) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(name) blanked(string) blanked(str
> ing) blanked(string) blanked(string) blanked(string)]
invalid syntax
------------------------------------------------------------------------------------------------------------------------------------------------------------------------- end blanked_prog_name ---
r(197);

end of do-file

r(197);

[daniel klein]

From a two-second glance:* syntax has a maximum of allowed options, which used to be around 70 and now seems to be above 200; you may have exceeded this limit, which bites in older versions of Stata.

Edit: The workaround is something like:

    syntax blanked() [ blanked() ... * ] // <- asterisk captures additional options
    local 0 , `options'
    syntax [ , blanked() ... * ]
    local 0 , `options'
    syntax , [ ... ]
    ...

* Edit 2: The implied meaning of the two-second glance wasn't showing off. It's supposed to demonstrate how quickly we can sometimes identify problems when provided with proper information. It also implied that I hadn't looked up the details. The limits were exactly 70 (in Stata 11) and 256 in Stata 18. The change must have been made somewhere between Stata 14 and 18; I won't look that up.

[Helder Costa]

Thanks for the super insightful comment, Daniel Klein. This fixed the issue!

In case anyone is interested, I found a page that documents the change you were mentioned.
https://www.stata.com/support/faqs/p.../option-limit/