macro — Macro definition and manipulation - Stata

1 Macro definition and manipulationDescriptionSyntaxRemarks and examplesReferencesAlso seeDescriptionglobalassigns strings to specified global Macro names (mnames).localassigns strings to localmacro names (lclnames). Both double quotes ("and") and compound double quotes ( "and" ) areallowed; see[U] Double quotes. If thestringhas embedded quotes, compound double quotesare names to the specified local Macro names that may be used as temporary variablenames in a dataset. When the program or do-file concludes, any variables with these assigned namesare names to the specified local Macro names that may be used as temporary localmacro, scalar, matrix, or frame names.

2 When the program or do-file concludes, any local macros,scalars, matrices, or frames with these assigned names are names to the specified local Macro names that may be used as names fortemporary files. When the program or do-file concludes, any datasets created with these assignednames are global and local [U] Macrosfor information on Macro [=exp|:macrofcn|"[string]"| "[string]" ]locallclname[=exp|:macrofcn|"[string]"| "[string]" ]tempvarlclname[lclname[..]]tempnamelcln ame[lclname[..]]tempfilelclname[lclname[ ..]]local{++lclname|--lclname} Macro dirmacro drop{mname[mname[..]]|mname*|all} Macro list[mname[mname[..]]|all] Macro shift[#][.]

3 ] expansionoptr [..]12 Macro Macro definition and manipulationwhereexpansionoptrislclname| ++lclname|lclname++|--lclname|lclname--| =exp|:macrofcn|.classdirective|macval(lc lname)and wheremacrofcnis any of the following: Macro function for extracting program propertiespropertiescommandMacro function for extracting program results classresultscommandMacro functions for extracting data attributes{type|format|value label|variable label}varnamedata labelsortedbylabel{valuelabelname|(varna me)}{maxlength|#[#2]}[, strict]constraint{#|dir}char{varname[ ]|varname[charname]}orchar{dta[ ]|dta[charname]} Macro functions for extracting attributes of alias variablesisaliasvarnametypevarnamealiasf ramevarnamealiaslinknamevarnamealiasvarn amevarnameMacro function for naming variablespermnamesuggestedname[, length(#)

4 ] Macro functions for filenames and file pathsadosubdir["]filename["]dir["]dirnam e["]{files|dirs|other}["]pattern["][, nofail respectcase]sysdir[ Stata |BASE|SITE|PLUS| PERSONAL|dirname] Macro function for accessing operating-system parametersenvironmentnamemacro Macro definition and manipulation 3 Macro functions for names of stored resultse(scalars|macros|matrices|functio ns)r(scalars|macros|matrices|functions)s (macros)all{globals|scalars|matrices}["p attern"]all{numeric|string}scalars["patt ern"] Macro function for formatting resultsdisplaydisplaydirectiveMacro function for manipulating listslistmacrolistdirectiveMacro functions related to matrices{rownames|colnames|rowfullnames| colfullnames}matname[, quoted]{roweq|coleq}matname[, quoted]{rownumb|colnumb|roweqnumb|coleqn umb}matname string{rownfreeparms|colnfreeparms|rownl fs|colnlfs}matname{rowsof|colsof|rowvarl ist|colvarlist}matname{rowlfnames|collfn ames}matname[, quoted] Macro function related to time-series operatorstsnormstring[, varname]

5 Macro function for copying a macrocopy{local|global}mnameMacro functions for parsingword{count|#of}stringpiece#piecen umber #lengthofpiecesof[ ]"string"[ ][, nobreak]strlen{local|global}mnameustrlen {local|global}mnameudstrlen{local|global }mnamesubinstr{globalmname2|locallclname 2}{"from"| "from" }{"to"| "to" }[, all count(globalmname3|locallclname3) word]4 Macro Macro definition and manipulationRemarks and are presented under the following headings:Formal definition of a macroGlobal and local Macro namesMacro assignmentMacro functionsMacro function for extracting program propertiesMacro function for extracting program results classMacro functions for extracting data attributesMacro functions for extracting attributes of alias variablesMacro function for naming variablesMacro functions for filenames and file pathsMacro function for accessing operating-system parametersMacro functions for names of stored resultsMacro function for formatting resultsMacro function for manipulating listsMacro functions related to matricesMacro function related to

6 Time-series operatorsMacro function for copying a macroMacro functions for parsingMacro expansion operators and functionThe tempvar, tempname, and tempfile commandsTemporary variablesTemporary scalars and matricesTemporary filesManipulation of macrosMacros as argumentsMacros are a tool used in programming Stata , and this entry assumes that you have read[U] 18 Pro-gramming Stataand especially[U] Macros. This entry concerns advanced issues not definition of a macroAmacrohas amacro nameandmacro contents. Everywhere a punctuated Macro name appears ina command punctuation is defined below the Macro contents are substituted for the Macro come in two types, global and local.

7 Macro names are up to 32 characters long for globalmacros and up to 31 characters long for local macros. The contents of global macros are defined withtheglobalcommand and those of local macros with thelocalcommand. Global macros, oncedefined, are available anywhere in Stata . Local macros exist solely within the program or do-file inwhich they are defined. If that program or do-file calls another program or do-file, the local macrospreviously defined temporarily cease to exist, and their existence is reestablished when the callingprogram regains control. When a program or do-file ends, its local macros are permanently substitute the Macro contents of a global Macro name, the Macro name is typed (punctuated)with a dollar sign ($) in front.

8 To substitute the Macro contents of a local Macro name, the Macro nameis typed (punctuated) with surrounding left and right single quotes ( ). In either case, braces ({ })can be used to clarify meaning and to form nested constructions. When the contents of an undefinedmacro are substituted, the Macro name and punctuation are removed, and nothing is substituted in Macro definition and manipulation 5 For example,The input..is equivalent to..global a "myvar"generate $a = oldvar generate myvar = oldvargenerate a = oldvar generate a = oldvarlocal a "myvar"generate a = oldvar generate myvar = oldvargenerate a = oldvar generate a = oldvarglobal a "newvar"global i = 2generate $a$i = oldvar generate newvar2 = oldvarlocal a "newvar"local i = 2generate a i = oldvar generate newvar2 = oldvarglobal b1 "newvar"global i=1generate ${b$i} = oldvar generate newvar = oldvarlocal b1 "newvar"local i=1generate b i = oldvar generate newvar = oldvarglobal b1

9 "newvar"global a "b"global i = 1generate ${$a$i} = oldvar generate newvar = oldvarlocal b1 "newvar"local a "b"local i = 1generate a i = oldvar generate newvar = oldvarGlobal and local Macro namesWhat we say next is an exceedingly fine point: global Macro names that begin with an underscoreare really local macros; this is why local Macro names can have only 31 characters. Thelocalcommand is formally defined as equivalent toglobal. Thus the following are equivalent:local x globalxlocal i=1 globali=1local name "Bill" globalname "Bill"local fmt : format myvar globalfmt : format myvarlocal 3 2 global3 $2tempvaris formally defined as equivalent tolocalname: tempvarfor each name specifiedaftertempvar.

10 Thustempvar a b cis equivalent tolocal a : tempvarlocal b : tempvarlocal c : tempvarwhich in turn is equivalent toglobal _a : tempvarglobal _b : tempvarglobal _c : tempvartempfileis defined Macro Macro definition and manipulationMacro assignmentWhen you type. local name "something"or. local name "something" somethingbecomes the contents of the Macro . The compound double quotes ( "and" ) are neededwhensomethingitself contains quotation marks. In fact, if the string is anything more complex thana single word, it is safest to enclose the string in compound quotes ( " " ). The outermost compoundquotes will be stripped, and all that remains will be assigned toname. Note that any embedded macroreferences insomethingare expanded before assignment tonamewhether or not compound quotesare you type.