Title
Putting Simple Programs in Characteristics
Description
Stata's characteristics allow metadata to be attached to individual variables and to the data set itself. Metadata is a great idea, since it goes wherever the variable goes. This can be exploited, for validation (see ckvar) by allowing Stata commands to be attached directly to variables themselves. The dochar program runs the code; this help file tells how to write the code so that it will execute properly.
The point of view for this help file is that of writing simple validation rules, so the programs (or snippets) will typically be called as such. Do not let this deter you from using dochar for other purposes!
Remarks
dochar will run a series of commands, separated by semi-colons (;), which are stored in a characteristic. This is its main purpose. Because dochar was originally written to aid in data validation, however, it can also recognize some other non-Stata constructions which are useful for specifying ranges of values. These are mentioned at the end of this file.
The characteristics may be (and really should be) edited by using the docharedit utility, as it is much less error-prone. There are some tips at the end of this file for editing by hand, which could be of some use for changing the characteristics in a do or ado file.
Writing mini do-files which are stored within characteristics is like writing any other do-file, with just a couple of things to note:
It is best to use a the local macro `self' to refer to the variable which holds the characteristic. This will keep the mini do file from breaking if the variable is renamed. Do not fear -- it is OK to use `self' exactly as it stands (with the open and close quotes) within the program.
If you use branching or looping without using the slow option when invoking dochar, Stata will complain about not finding curly braces ({ or }), even if they are not needed. You could even get into an infinite loop! Thus, it is probably best to use as cond() command in place of if commands, when possible. If looping is really needed, go ahead and use it, but be sure to the slow option when using dochar. You do not need to worry if writing mini do-files for ckvar, because it works around this limitation.
How dochar echos results to the screen depends on whether the slow option is used. If the slow option is not invoked, then output appears as expected. If the slow option is invoked, output will appear if an only if the loud option is also invoked, in which case the mini-do file will also appear in the Results window. This is because the slow option writes the mini-do file to disk and then either {help:run}s it or {help:do}es it. This behavior might change in a future version, but it currently seems too esoteric to cause much worry.
dochar can be useful when called from within do or ado files. Such files are often filled with temporary names, such as those given to temporary variables. Names and values can be passed through dochar by using the tempnames option. If local names are passed through in such a fashion, refer to the local macros by `lclname' when editing the file via docharedit. If you are editing by hand, prevent immediate expansion by putting a backslash in front of the open quote: \`lclname'.
To program mini-do files by hand, take care to use the construction \`self' in place of `self'. This will ensure that Stata does not immediately expand the `self' macro before assigning the command to the characteristic. Clearly, this needs to be done for all other local macros which might be used in the mini do-file.
INCLUDE help ckvar_rule_syntax
Also see
Online: dochar, docharedit
Author
Bill Rising, StataCorp email: brising@stata.com web: http://homepage.mac.com/brising