Defining and Using Macros

To control how raw survey data is interpreted during compilation, you normally assign values to named parameters on #Units directive lines. For example,

#units  IncV=-0.15  ... etc.

will cause a correction of -0.15 degrees to be applied to inclination measurements. Such parameter settings will apply to all compass-and-tape data lines that follow in the file until the next such directive overrides them. #Units directives not only can appear multiple times in a data file, but their allowed parameters can also be set in the Compile Options property fields of project tree branches. In the latter case, they set the defaults for possibly many data files (leaves) in the tree.

A problem with this approach is that some kinds of parameters, especially those intended for particular instruments or surveys, might need to be experimented with or revised fairly often. For example, you might want to adjust a compass correction iteratively (multiple recompiles) to discover the "best fit" correction for an instrument's data scattered throughout a larger project. Another example: The relative variance you may want to assign to a high quality subset of data (see UV parameter) could change as the survey grows and overall quality improves.

To avoid having to edit many individual files, or to group the files so that #units parameters can be set as branch properties, you can instead take advantage of defined variables, or macros. Here is a #units directive containing two macro definitions:

#units  $sunto112_IncA=0.25  $sunto112_typeAB="N,2"  ...etc.

A macro definition resembles an ordinary parameter assignment, except that the parameter name is prefixed with a dollar sign ($) and can be a name of your own choosing. In this example you're defining two macros named sunto112_IncA and sunto112_typeAB, and are assigning them values 0.25 and N,2. Normally, each name will be followed by an equals sign and one or more characters representing a value. (You can, however, assign an empty string to a macro by simply dropping the equals sign.) Unlike the pre-defined parameter names, macro names are case sensitive and can be of any reasonable length.

Important Note: The text to the right of the equals sign can also be a long string, but it must be enclosed in double quotes if it has embedded spaces, commas, or equals signs (as in the second definition above). Also, it's a good idea to use quotes if the replacement string itself contains a macro reference (see below).

Referencing Defined Macros

While it may be more convenient to define macros with Compile Options properties, the actual directives in data files are where you'll normally reference the macros that have been defined at a higher level. Such a directive might look like this:

#units IncA=$(sunto112_IncA)  typeAB=$(sunto112_typeAB) ...etc.

Note that when macros are being referenced, their names are delimited by "$(" and ")". No spaces are allowed inside the parentheses. During compilation, Walls will perform macro replacement before the directive line is processed in the usual fashion. The above would be equivalent to

#units IncA=0.25  typeAB=N,2 ...etc.

A macro's defined value, or replacement string, can be used to construct any portion of a directive line apart from the directive's name. For example, to simplify the above case we can define a single macro to assign two different parameters:

#units  $sunto112="IncA=0.25 typeAB=N,2" ...etc.

The quotes are obviously necessary in this case. In the data files we could then produce the same result as above with this line:

#units $(sunto112)  ...etc.

Likewise, you may want to control only a portion of a parameter setting:

#units $suunto112_tolerance=",2" ...etc.

#units typeAB=N$(suunto112_tolerance) ...etc.

Then you could restore the default FS/BS tolerance by simply redefining the macro to the empty string by dropping the equals sign:

#units $suunto112_tolerance ...etc.

Macro replacement can occur in Compile Options strings and in most hash-prefixed directive lines in data files. #FIX directives are the only exception. A macro expression, $(...), in an ordinary data line or vector definition will most likely generate an error message. Attempting to use an undefined macro will also generate an error message.

Finally, you might ask why we require parentheses in a macro reference, $(name), but not in the definition, $name="...".  The reason this is customary is that a macro reference can be embedded anywhere in a string of text and must be distinguishable from surrounding characters that are not necessarily separators. A macro definition has a different syntax so the compiler can distinguish it from a reference.