1 item has been added to your cart.
| Title | Stata 5: Stata’s search path for ado-files | |
| Author | Alan Riley, StataCorp |
Stata maintains a path that is a list of the directories over which it will search to find a command. In order to execute a command, Stata first looks to see if the command name is an internal command. If so, it executes that command. If not, it searches the path for the command that was issued. It searches for the command by appending ".ado" to the end of the command and looking for the file named command.ado in the directories.
That search happens like this:
The above is hard to read without examples but is the shortest accurate description I can come up with. Read on and the examples will highlight everything for you. Afterward, read the above again, and it should make more sense.
You can see what Stata is using for the path. It stores that information in the global macro S_ADO as a semicolon separated list of directories to search.
By default, Stata comes setup to search in the following manner (using the DOS notation):
You should place the personal ado-files you write in the C:\ADO directory and never in the C:\STATA\ADO or C:\STATA\ADO\<single-character> directories. In the event of the next upgrade, we will replace all of our ado-files in the official Stata directory. If we have developed a new command that is the same name as your command, you will lose your file (we will write over it).
You can change the order of the search using the adopath command. You can also add or subtract directories from the search path using that command. You can also find out exactly which ado-file Stata runs using the which command.
Now let’s look at some examples to make this somewhat more clear:
. display "$S_ADO"
c:\stata\ado;c:\ado;.
The contents of the S_ADO are the list of directories to search. The order that they appear in the list is the order that they are searched. You are free to add more directories to the list, take directories out, or rearrange the order. For all of the following examples, let’s assume the above is our list.
. which fit
c:\stata\ado\f\fit.ado
*! version 3.1.1 17nov1995
Stata looked in the following directories to find the command:
. which mvreg
c:\stata\ado\mvreg.ado
*! version 3.2.1 12nov1996
Stata looked in the following directories to find the command:
This brings up an interesting point. Why was that file there and not in c:\stata\ado\m\mvreg.ado? Actually, it is there too. When we update a command via the Stata Technical Bulletin, the installation process places the replacement file in the ado directory rather than the ado\m directory. The reason is that we know Stata will find the replacement first, so it will run the new version. We also have the assurance that if there is anything wrong with the replacement version, we can always go back to the old version by simply deleting the new one.
. which myprog
c:\ado\myprog.ado
*! version 1.0.0 my new program
Stata looked in the following directories to find the command:
. which sortcat
.\sortcat.ado
*! version 1.0.0 Written for Project A
Stata looked in the following directories to find the command:
. which psortc
.\p\psortc.ado
*! version 1.0.0 Generic sorter for Project A
Stata looked in the following directories to find the command:
. which regress
ado-file for regress not found
r(111)
Stata looked in the following directories to find the command:
In other words, the which command is good for finding ado-files only and not for querying about the existence of a command (because it does not know anything about the built-in commands).
