Stata | FAQ: Stata 5: Stata's search path for ado-files

>> Home >> Resources & support >> FAQs >> Stata 5: Stata's search path for ado-files

Note: This FAQ is for users of Stata 5, an older version of Stata. It is not relevant for more recent versions.

Stata 5: Where does Stata look for ado-file commands?

Title		Stata 5: Stata’s search path for ado-files
Author		Alan Riley, StataCorp
Date		March 1996

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:

For each directory in the path:

Look in the directory for command.ado. Did you find it?
YES: Execute that ado-file and stop searching
Take the first letter from command and look in the subdirectory with that first character for a file named command.ado. Did you find it?
YES: Execute that ado-file and stop searching

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):

C:\STATA\ADO ← The ADO directory from the official installation directory
C:\ADO ← The ADO directory on the C: drive (always C:)
. ← The current directory

Aside on where you should place your own ado-files

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