I don't think anything has changed to affect the advice to be given
since that thread, except for the twist about .hlp and .sthlp. I am not
clear how widely this matter is confusing, but what follows is an
attempt at a zeroth draft of such a FAQ. It's longer than I thought it
would be, which lends support to David's point.
StataCorp is willing in principle to host user-written FAQs, but doesn't
commit itself to accepting any submitted. I am happy to accept comments
from others on errors and omissions in what is below, but I don't commit
myself to publishing the results anywhere else if StataCorp won't accept
this.
This isn't really a precedent. In general, if you want to read an FAQ,
you may need to write it first. In fact, it's not so dopey to set that
as an exercise for yourself if you want to understand a topic better.
Nick
[email protected]
================= Draft begins
I have a certain version of Stata and have come across a user-written
program that is apparently written for a later version of Stata. What
are my options?
1. Introduction
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, or an earlier version, or a later version. It is the last
that is problematic, to at least some extent.
2. The different meanings of version
You need to distinguish four senses of the word _version_ in discussions
of this and related problems. In programming jargon, the word is heavily
overloaded.
a. The version of Stata you are using
-------------------------------------
Any copy of Stata you run has a version. Stata itself will tell you the
version in several ways, such as when you start a session, in the GUI,
or if you type -version-, -about- or -di c(version)-. (If you have a
really old version of Stata, some of these methods may not work.)
The result is the version of Stata you are using. If not the most recent
version of Stata, it imposes limits on what you can do with user-written
programs.
b. The programmer's personal version number
-------------------------------------------
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 very 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 personal version numbering, so that he
can keep track of which version is which. User-programmers often mimic a
style used by StataCorp and common throughout computing, so that the
first number marks major rewrites and any following numbers mark minor
changes.
The version numbering 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-, typing -which
estout- will tell you which version you have installed.
This numbering also helps in dealing with bug reports. Conversely, if
you experience a problem with a user-written program, check first 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.
Note that, as stated, the line starting with *! is a comment that will
be ignored by Stata. The initial * is what makes it a comment. Comments
are generally ignored by Stata. However, the following ! makes that
comment special, as the -which- command looks for lines beginning *! and
echoes them to the Results window.
However interesting or informative you find this, note that the version
numbering used personally by the programmer has no implications
whatsoever for whether that program can be used by you and is nothing to
do with the rest of this question.
Some programmers do not use this kind of version numbering. You will
find that Stata's own commands and most of the heavily-used user-written
commands generally do use it, but that raises no more than questions of
style.
c. The version declared within a program
----------------------------------------
Most programs include a -version- statement, which also is usually given
at or near the very top of the program definition within an .ado file.
In the example given, -estout- as downloaded from SSC on 25 January,
this is
version 8.2
This -version- statement limits what you can do. If the -version-
declared within a program is greater than the version of Stata you are
using, then you can not run that program on your Stata. Thus if you have
Stata 8.1 or earlier, this version of -estout- will not run on your
Stata.
Often programs call other programs, and sometimes yet other programs.
When that happens, the highest version number of those declared is that
which bites. Thus if -foobar- declares -version 8.2- but calls
-frogtoadandnewt- which declares -version 9-, then you need version 9 at
least to run -foobar-. But typically there is no need to look inside
program files to find this out: Stata itself will tell you whether it
can run a program.
Precisely what -version- does is too complicated to explain fully here.
There is no substitute for careful and detailed reading of the
documentation for -version-. But you are warned against a surprisingly
common misconception: The -version- command is emphatically not a time
machine. Not only can -version- never be used to make an old Stata
behave like a newer Stata, -version- does not even set the clock back to
behave exactly like an older version, even temporarily.
On occasion, there can be good and subtle reasons for omitting a
-version- statement. But more commonly a program (or .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.
d. The version needed within a program
--------------------------------------
Note that programmers can be a little cavalier about what they say in
any -version- statement that they include in their programs. There are
two common styles:
* Some programmers just write the version of Stata they are using as the
-version- needed by their programs. If there is a conscious reasoning
behind this style, it often runs like this: "I believe that this program
runs fine on this version of Stata, because that is the version on which
it has run and been tested by me. I am not going to commit myself about
any backward compatibility". On the other hand, it may well be that the
-version- declared is exactly what is needed and the programmer knows
that.
* Other programmers write down an earlier version of Stata as the
-version- needed by their program. If there is a conscious reasoning
behind this style, it may run like this: "I believe that this program
does require at least that version of Stata, because it needs certain
features introduced then". For example, a program may require the
current Stata graphics introduced in Stata 8 or a particular version of
the -ml- engine introduced in one or other version of Stata.
In either case, do note carefully 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 any
older version. So, any -version- statement given explicitly within a
program may well not be the exact version of Stata that program needs.
Also, it is not an error to declare a -version- statement either less or
more than what is really needed, so long as the -version- number is not
greater than the version of Stata being written for.
3. Looking inside a program
An implication of the above is that 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 may be wrong, most commonly
because it 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 or
anywhere other than the program itself.
In order to look inside a program, it may help you to learn more about
-findfile- or -viewsource-. Simply using -type- to type a program may be
enough. (With -ssc-, be aware of the subcommand -ssc type-.)
4. Choices
Now the question can be answered directly.
If you had 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?
a. Upgrade
You can arrange to upgrade to the latest version of Stata by purchasing
it from StataCorp. Thus if you upgrade to Stata 10, and then -update,
then you will be able to run -bazz-, which requires Stata 10.1.
b. Update
You can -update- within a version, for example from Stata 9 to Stata 9.2
or from Stata 10 to Stata 10.1. That is free to people who hold a
licence for Stata 9 or 10, respectively. Thus if you -update- to at
least Stata 9.2, then you will be able to run -foobar-, which requires
Stata 9.2. If you had Stata 10, and -update- to Stata 10.1, then you
will be able to run -bazz-.
c. Look for older versions, or older alternatives
You may find that an older version of a program can be found. For
example, the Stata Journal and the Stata Technical Bulletin archives
retain all previous versions of any programs published therein; some
packages on SSC include versions for older Statas; some users' websites
allow you to download different versions of a program according to
users' versions of Stata. Commonly, older versions are frozen as was and
not updated, even when that 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
naturally that -foobar2- and -foobar3- merely mark successive versions
of -foobar-, but as Stata ages the chance of these two conventions
clashing diminishes.
Similarly, there may be older alternatives. Using -search- (possibly
with the -historical- option) and -findit- or asking on Statalist may
help here, perhaps by implying that no older alternative exists.
d. Change the program
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 trivially
easy to essentially impossible, depending on how far any program really
does require features introduced in the -version- declared or implied,
and also on your knowledge of Stata.
At the easiest, it may simply be that the -version- statement is later
than needed. Thus if you edit -version 10- to -version 9-, you may find
that a program works under Stata 9.
But watch out:
* Etiquette requires that you now take full responsibility for what you
have done, while giving full credit as appropriate to previous authors.
Some program authors take mild or even strong exception to others
changing their program and asking why it no longer works, for example.
* You are well advised to change the name of the program. Otherwise you
may confuse yourself, and any others you distribute the program to, even
if you only use the program privately or within a restricted group. You
should certainly not put your version into the public domain where it
may be confused with the original.
* Even if an edited program appears to work satisfactorily, that is not
a guarantee that your version produces identical results to the
original.
* Although mileage varies, the original program authors will commonly
have little or no interest in re-writing a program to work on an older
Stata.
Often, a program would require more drastic surgery to the extent that
your only real choices are to upgrade, -update- or do without.
5. A note on help files
Stata 10 looks first for help files with extension .sthlp and only
second for help files with extension .hlp. Conversely, Stata 9 and
earlier versions know nothing about the extension .sthlp.
Thus if you managed to get a Stata 10 program working in Stata 9, you
would normally be best advised to rename any .sthlp files to have
extension .hlp.
An implication of the previous section is that it is now good practice
to edit the help files to indicate what has been changed and who is
responsible.
-----Original Message-----
From: [email protected]
[mailto:[email protected]] On Behalf Of David Elliott
Sent: 24 January 2009 17:43
To: [email protected]
Subject: st: Stata version in user ados
I recently installed a couple of user ados into a Stata 9.2 system but
couldn't run them because they were identified as version 10 (and had
a *.sthlp help file). On inspection, the ados made no use of advanced
version 10 code and probably could have been identified as version 8
(one of them was graphical). I was able to run the routines after
editing them to read version 8.
I found an old discussion thread regarding this at [
http://www.stata.com/statalist/archive/2004-01/msg00396.html ] and am
just wondering, philosophically, I guess, about submitters of adofiles
versioning higher than necessary and locking out users of prior Stata
versions (unless the users manually edit the version number as I did).
I realize that, unless an ado writer has access to earlier Stata
installations, they have no way of absolutely confirming the program
will work on a version prior to the one in which they developed it.
This may not be an issue to most users, but I am wondering if it is
worth a FAQ? There is a very dated Stata FAQ regarding version
numbers at [ http://www.stata.com/support/faqs/lang/stbado.html ] that
doesn't really address the issue I'm discussing.
I realize users editing existing ados do so at their own risk and have
to be aware of the consequences of a -adoupdate , update- if a new
version of the edited ado becomes available. It might be wise to
always save the edited version as origname8.ado to avoid an overwrite.
This numbering convention is discussed in the older thread regarding
versioning.
*
* 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/
