Macros (global and local)

"Global" and "local" are notions (and Stata commands) you will encounter in chapters on "Stata programming". However, they can be helpful for the work of 'normal' users as well. In the Stata handbook, they are described as "local macros" and "global macros", but in what follows I will often use the abbrevations "global(s)" and "local(s)", as these are the commands used to invoke them; also, in programmer's usual parlance a macro is sort of a small subprogram that is used repeatedly, which is not the case here.

While it is important to know that both global and local macros exist (if only to understand the manual), this section will deal only with globals, as locals most likely are less important for the average user. Local macros work basically the same way as global macros, but there are some important differences which you have to look up should you have to deal with locals.

Assignment of content to global macros

In Stata, a global macro is something that is stored in memory and can be used anytime during a Stata session by reference to its name (a local macro differs basically inasmuch it can be used only within a circumscribed piece of a program or a do-file). There are two basic ways to assign content to a global. The first goes like this:

global x this-and-that

Here, "global" is the Stata command to define a global macro, "x" is the name of the global and "this-and-that" is what is stored under the name of x, and will substitute x whenever x is invoked.

A second way is:

global x = 2 * 5

Here, the expression following the equals sign is evaluated, i.e., what is stored to x is not "2 * 5" but rather "10".

A number of things have to be noted:

1) The name of a global can be up to (and including) 32 characters long, but it may be as short as a single character.

2) You will find many examples where the content of the macro is enclosed in double quotes (such as in global x "this-and-that". This will never hurt if you are dealing with non-numeric characters. But please be sure to note the following:

If the character string stored to the macro does itself contain double quotes (an example will be given below under the heading of "using macros"), the macro must be enclosed in compound quotes, i.e. "single plus double" quotation marks, as in:

global x `"this-"and"-that"'

Be sure to use the correct single quotation marks: The accent grave, or gravis, at the beginning, and the apostrophe at the end. (The Stata manual is not particularly helpful here.)

Since compound quotes will not hurt even if no double quotes occur within the macro, it may be best to always use compound quotes; the Stata manual suggests to do so whenever the content of the macro exceeds a single word.

3) In the case of evaluated expressions, it makes a slight difference whether or not you use quotes. Consider the following:

global x = "2+2"
global y = 2 + 2

Both globals will be evaluated as 4; thus, both dis $x and dis $y will display the number 4. However, macro list $x will display 2+2, whereas macro list $y will display 4. In other words, macro y will store the number 4, whereas macro x will store 2+2 and the addition will be performed only when the macro is invoked.

(Note that earlier version of this paragraph (up to July 12, 2020) contained an error I was kindly alerted of by Nicholas Winter, Unversity of Virginia.)

4) Whereas you may read occasionally that the content of a global is always a string, a global that consists of a number only (as in the latter example) may be used like a number; that is, it can used in arithmetic operations.

Using globals (accessing the content of globals)

So, how can globals be used? Here's some examples from my own work which will also help to explain some technical details.

Suppose that you do some data preparation and analysis work on a number of files that are all stored in a directory which is not (and is not supposed to become) your current working directory. Instead of repeatedly looking up (or copying) the complicated name of that directory, you might define a macro like this:

global datadir C:\mydirectory\mydata\GSOEP\2012\statafiles\

Then, you might access the content of "datadir" like this to get some file:

use "${datadir}householdmembers"

and Stata will interpret this as use "C:\mydirectory\mydata\GSOEP\2012\statafiles\householdmembers"

Note the braces that enclose "datadir". They make clear where the global ends and the ensuing text begins. If the global were to stand alone, the braces would not be needed. Note also the quotation marks that enclose the entire expression. These quotation marks are required only if the path or the name of the file contain (blank) spaces; but as they won't do any harm even in the absence of spaces, I consider it good practice to always use quotation marks when referring to paths and/or files.

Globals can make your work very much easier. Recently, I had to produce a set of histograms, which all were to look alike. Instead of adding a huge number of options again and again to each of the histogram commands, I simply stored the options in a global and added the global to each histogram. This went like this (using only very few options for illustration):

global histoption `"ysc(r(0 80)) xtitle("Health Status", size(medlarge))"'

hist var15, $histoption

Please note three things:

First, the definition of the global "histoption" is now enclosed in "single plus double" quotation marks. As pointed out above, they are needed here because the global itself contains quotation marks (see the xtitle option). Be sure to use the correct single quotation marks: The accent grave, or gravis, at the beginning, and the apostrophe at the end.

Second, as in the second line the macro "histoption" stands alone, no curled braces (as in the first example) are required.

Third, I have used a very short list of options here, hoping that the list will fit on a single line on most screens. In fact, the list of options is not limited. But note: In defining macros, you cannot use the three slashes that inform Stata that the command is continued on the next line. In other words, the entire global must be written in a single line.

On a final note, how can you display the content of a global macro? Well, again there is a difference. If the content contains non-numeric characters, it goes like this:

display "$name-of-global"

Here, the double quotes are required. In contrast, if the content is a number only, the double quotes can be omitted. Yet, they won't hurt, and therefore you may wish to grow accustomed to always using them.