help dochar 


dochar - Running Stata commands stored in characteristics


dochar evarname[charname] [["]text["]] , [self(varname) tempnames(special name list) loud tmpfile ]


dochar is a utility for running commands stored as characteristics, in Stata parlance, doing characteristics. This can be used to attach simple do files to the dataset or to particular variables. This can be of great use for data validation. Warning: this could seem a bit obscure, but as long as you understand macros well, it could be very useful. See docharprog for the details of programming with chars.


self By default, dochar uses the local macro `self' to refer to the variable to which the characteristic is attached. It does this so that the command will still run if the variable is renamed. Sometimes, but rarely, it is worth using the self option to override the default with another variable name (for example, this is used for recursion within dochar).

tempnames is a method for passing values of local macros to the commands stored in the characteristics. This facilitates dochar being able to be used from within do or ado files which have any locally named items. The tempnames are passed as a space-delimited list of items, each of which is of the form lclname:value. This means that passing the local macro bleen would be done as bleen:`bleen', and passing the temporary variable `foo' would be done as foo:`foo'.

loud is primarily for debugging code which is run via dochar. It echos information at critical places, so that it is possible to see exactly what steps are being executed. Think of it as similar to using a set trace on when running a do-file.

tmpfile writes the characteristic as a temporary do file, and then executes the do file. This is worthwhile if the characteristic needs to have any commands which use curly braces ({ and }). If loud is specified, the temporary file is executed using do, so every step is echoed to the results window. If loud is not specified, then the temporary file is executed using the run command, so all output (including that from display statements) is silenced.


. dochar bling[valid_check] runs the list of commands stored in the characteristic bling[error_check]

. dochar foo[bar], tempnames(aVar:`aVar' aMacro:`aMacro') runs the list of commands stored in the characteristic foo[bar], allowing the use of the temporary variable aVar and local macro aMacro inside the mini-do-characteristic. Note that some care is needed when using local macros in characteristics. See docharprog for more direction.


To see how these are used, take a peek at docharprog, ckvar_overview and ckvaredit.

Also see

Online: docharedit, docharprog


Bill Rising, StataCorp email: web: