|Title||User-written programs and Stata version|
|Author||Nicholas J. Cox, Durham University, UK|
Suppose you have Stata 10.1. You may in fact have an earlier version, or indeed a later version, as you read this. You should be able to relate to examples here as long as you are clear that there are three possible situations: a Stata program may be written for the same version of Stata that you have, an earlier version, or a later version. It is the last situation that is the focus here.
You need to distinguish the four meanings of the word “version” in discussions of this and related problems. In programming jargon, the word is heavily overloaded.
Any copy of Stata you run has a version. Stata itself will tell you the version in several ways, such as in the GUI when you start a session or if you type version, about, or display c(version). (If you have a really old version of Stata, some of these methods may not work.)
The version of Stata you are using is always displayed, such as 12, 11.2, 11.1, 11, etc. If you are not using the most recent version of Stata, the version you are using imposes limits on what you can do with user-written programs.
Most Stata commands are defined by programs written in Stata and defined by ado-files. The exceptions are part of the executable and do not come under this FAQ. Many programmers keep track of the history of their programs by including a comment such as
*! version 3.10 20jan2009 Ben Jann
Usually, that comment is placed at or near the top of the ado-file. In the example above, the comment appears at the top of estout, a popular ado-file, as downloaded from SSC on 25 January 2009. The programmer, Ben Jann, has his own version number for estout so that he can keep track of which version is which. User-programmers often mimic a style used by StataCorp and common throughout computing: the first number marks major rewrites, and any following numbers mark minor changes.
The version number also can help users of any program keep track of which version they are using and whether they need to update. For example, if you have previously installed estout, then typing which estout will tell you which version you have installed.
This number also helps in dealing with bug reports. If you experience a problem with a user-written program, then check that you have the most recent version. Often a bug that bites you bit someone else first, and the bug is fixed in a later version.
As stated above, the line starting with *! is a comment. The initial * is what makes it a comment. Comments are generally ignored by Stata. However, the following ! makes that comment special, because the which command looks for lines beginning *! and echoes them to the Results window. Thus if you want to know which version of xyzzy you are using, then all you have to do is type which xyzzy, and you will see
. which xyzzy *! version 3.10 20jan2009 Ben Jann
The above works whether xyzzy is a user-written command or an official Stata command.
Some programmers do not use the *! version number. You will find Stata’s own commands and most of the heavily used user-written commands generally do use it, but this is mainly an issue of style.
However interesting or informative you find this, remember that the *! version number used personally by the programmer has no implications whatsoever for whether your version of Stata is modern enough to use the program.
The easy way to find out whether you can use a program is just to try it. Either the program will work or you might see something like
. xyzzy this is version 10.1 of Stata; it cannot run version 10.2 programs. A free update to version 10.2 is available; type update and follow the instructions, or visit http://www.stata.com/support/updates. If you are not connected to the Internet, you can contact StataCorp to obtain the latest version. r(9);
Or you might see
. xyzzy ... this is version 8.2 of Stata; it cannot run version 9.0 programs. You can purchase the latest version of Stata by visiting http://www.stata.com r(9);
Let me show you how this works. We are going to have to look inside the program to do so. The easy way to do that is to type
. viewsource name_of_ado_file
A Viewer window will display the source code.
For instance, say you have installed estout from SSC. If you type
. viewsource estout.ado
you will see in the Viewer window something like
*! version 3.10 20jan2009 Ben Jann program define estout, rclass version 8.2 ...
Look for the version statement—not to be confused with the *! comment. The version statement is usually found near the top of the program, after the program statement.
estout is declared to be version 8.2, meaning it requires Stata 8.2 or a more recent version to run.
Most programs include at least one version statement. The first—which is often the only one—is usually found at or near the top of the program definition.
Often programs call other programs, and sometimes those programs call yet other programs. When that happens, the highest version number is that which bites. Thus if foobar, which declares itself to require version 8.2, calls frogtoadandnewt, which declares itself to require version 9, then you need at least Stata version 9 to run foobar.
Some programmers write branching code within their programs that detects the version of Stata you have and calls other code accordingly. For example, if you have Stata 9 or above, then a clever program may call fast and efficient Mata routines to do some work; if you do not have Stata 9, then the program calls code that will do the same job, albeit more slowly. In this way, it is possible that a program containing some code that would not run on your version of Stata is usable by you, because the program itself is smart enough to work around that limitation.
Precisely what version does is too complicated to explain in full detail here. There is no substitute for careful reading of the documentation for version. But you are warned against a surprisingly common misconception: that the version command is a time machine. It emphatically is not a time machine. version cannot be used to make an old Stata behave like a newer Stata.
What version does is set the clock back to make a more modern Stata behave like an older version or, at least, behave like an older version where that older behavior is important.
Here is the main idea. Suppose you have Stata 12, and a program includes the statement
Your copy of Stata 12 does not remove all the improvements and new features of Stata 12. What the version 8.2 statement does, in any case where there is a conflict between what was in Stata 8.2 and what is now in Stata 12, is to use the Stata 8.2 interpretation.
It is difficult (impossible, really) for you to be certain that what you have within Stata 12 will work exactly as it would in Stata 8.2 unless you test it by running a physical copy of Stata 8.2. You might be exploiting a new, nonconflicting feature introduced since Stata 8.2 without realizing it.
Some users tend to look at version 8.2 at the top of a program and say, “Oh, this will work with Stata 8.2”. That statement is necessarily true if the program was written only on Stata 8.2. version is about forward compatibility, not backward. What is true, and all that is guaranteed to be true, is that a program written on Stata 8.2, with a version 8.2 statement at the top, will continue to work properly with future versions of Stata.
By the way, on occasion there can be good and subtle reasons for omitting a version statement. But, more commonly, a program (or a do-file for that matter) would benefit from a version statement.
If there is no version statement within a program, then that omitted statement can have no bite. But keep on reading.
Programmers can be a little cavalier about what they say in any version statement included in their programs. There are two common styles:
In either case, note that many Stata programmers either do not have older versions of Stata on their machines or lack the time and inclination to test whether their program would run successfully on an older version. So any version statement given explicitly within a program may not be the exact version of Stata that the program needs.
Also it is not wrong to declare a version statement either less than or more than what is really needed, so long as the version number is not greater than the version of Stata being written for.
You may want to look inside a program to see what version is declared. Even if the documentation includes information on the Stata version required, checking on the facts will do no harm. The documentation can be wrong, most commonly because the documentation itself is out of date. In any case, what the program requires is all that matters. Stata pays no attention to anything said in the help file or anywhere other than the program itself.
Using viewsource to look inside a program was mentioned earlier; you may also find it helpful to learn about findfile. Simply using type to type a program may be enough. (With ssc, be aware of the subcommand ssc type.)
Now the question can be answered directly.
If you have Stata 9, and the foobar command appears to require Stata 9.2 and the bazz command appears to require Stata 10.1, what can you do?
If your Stata version differs by 1 or more from what is required, you can purchase an upgrade to the current version from StataCorp.
If your Stata version has the same initial integer as what is required, you can update your Stata for free over the web. For example, you can update from Stata 10 to Stata 10.1 or from Stata 11 to Stata 11.2; just type update. You cannot update for free from (say) Stata 11.2 to Stata 12. That requires an upgrade, as described just above.
An older version of a program may be found. For example, the Stata Journal and the Stata Technical Bulletin archives retain all previous versions of any programs published therein; some packages in the SSC archives include versions for older Stata programs; some users’ websites allow you to download different versions of a program according to your version of Stata. Commonly, older versions are frozen as they were and are not updated, even when it is possible.
One common, but not universal, convention is that names like foobar7, foobar8, and foobar9 may signal versions of foobar for Stata 7, 8, or 9. The documentation will usually make this clear, but, if in doubt, you can look inside each program, as above. Another common convention is that foobar2 and foobar3 merely mark successive versions of foobar, but as Stata ages the chance of these two conventions clashing diminishes.
Similarly, there can be older alternatives. Using search (possibly with the historical option), using findit, or asking on Statalist can help here, perhaps by implying that no older alternative exists.
You can copy the program in question and try to change it so that it works under your version of Stata. This process will vary from being trivially easy to being essentially impossible, depending on how many newer features any program requires. The difficulty also depends on your knowledge of Stata.
At the easiest, it may simply be that the version statement specifies a version later than really needed. Thus, if you edit version 12 to version 11, then you may find that a program works under Stata 11.
But watch out:
But often a program would require more drastic surgery to the extent that your only real choices are to upgrade, update, or do without.
Stata 10 and later versions of Stata look first for help files with extension .sthlp and second for help files with extension .hlp. Conversely, Stata 9 and earlier versions know nothing about the .sthlp extension.
Thus if you managed to get a Stata 10 program working in Stata 9, then you would normally be best advised to rename any .sthlp files to have the .hlp extension.
The previous section implies that it is now good practice to edit the help files to indicate what has been changed and who is now responsible, namely, you.
David Elliott suggested, on Statalist, that an FAQ be written on this topic. He, William Gould, Ben Jann, and Richard Williams made very helpful comments on a draft.