A little over a year into my Stata 10 license, I can see some usage patterns over the two feet's worth of Stata documentation: Data Management and Programming are pretty well worn, the rest not so much. User's Guide,  [U], has been among the least popular, which is a pity, because chapter 18, Programming Stata, is supremely useful. Here's a tidbit:

If you write code using formally defined programs, as I suggested in my previous post, then you may have already run into the problem of making your programs pass each other various results. One way is to have the programs store their results as global macros, which then are available to any subsequent programs within the same Stata instance. This is inelegant and risky, because your globals might stick around longer than you want them (OK, they won't survive shutting Stata down and restarting it, if you care to do that all the time).

The other way of enabling programs to use each other's results is rclass. Defining your program this way enables it to return r() results, which are then available to subsequent programs, no globals needed. An example is below:

// my first program defines the answer
capture prog drop theAnswer
program define theAnswer, rclass

return scalar myanswer=42


// my second program calls the first
// and uses its r() result.
capture prog drop theAnswerIs
program define theAnswerIs

local answer=r(myanswer)
di "The answer is `answer'."


Now call the second program in Stata:


Congratulations. You now have the answer to the Ultimate Question.