This macro works in a similar way to DEFINE except that it
defines a user macro whose ultimate value is dependent on the processing of
the equate expression. It provides a level of processing that occurs after
preprocessing (unlike ordinary user macros). Although user defined macros
are not expanded within an equate definition, equates will be but they
should be prefixed by the # character (not %%).
Only simple conditional equate expressions are discussed here (that can be used
to do something like an ifdef pragma). In fact equate expressions can be much
more complex but the details of this are given in
section Equate Expressions on equate
expressions and section Reversed Equate Expressions on reversed equate expressions.
The argument given to this predefined macro is a macro argument as for
defining user macros. However the macro definition part is slightly more
complex in that it supports the ? operator. The syntax for this is
?field["string"]:["string"];. The square brackets surround optional
syntax.
The semantics of the ? operator are that if the value of the given
field is null (or equals 0 or 0.0 in the case of numeric fields) then
do not print the field at all. So in the program fragment below
%%EQUATE EXAMPLE ?YEAR:;
the EXAMPLE equate macro has a definition saying if the value of the
YEAR field is null print nothing else print the value of the
YEAR field. This is a shorthand notation for the example below.
%%EQUATE EXAMPLE ?YEAR"%YEAR":;
The definition for this example says that if the value of the YEAR
field is null print nothing, else evaluate the following string. The example
below shows the third possible form of this operator.
%%EQUATE EXAMPLE ?YEAR"%YEAR":"Unknown";
The definition for this example says that if the value of the YEAR
field is null evaluate the string following the colon character, else evaluate
the string preceeding the colon character.
Below is a more complex example program fragment which also shows how the equate macro is used within a text body.
%%EQUATE NAME ?NAME1:"";?NAME2"; %NAME2":"";+ %%EQUATE SALARY \ ?SALARY"Salary is %SALARY":"No Salary for #NAME"; %%RECORD Details: %%NAME, %%SALARY
In the above example the NAME equate prints the contents of the NAME1 field
only if it isn't null and follows this with nothing if the contents of the NAME2 is
null else with a semicolon followed by the contents of the NAME2 field.
Note the + operator to concatenate the results from each condition into
one (an equate must return only one value) and as a result of this each
condition must always return a value so "" is used in the else clause
to return an empty string when the field is empty.
The SALARY equate prints a different string dependent on whether the
contents of the SALARY field is null or not. Note that the last string actually
includes a nested call to the NAME equate macro. Note also the use
of the backslash character to carry the definition onto the next line (the
backslash can be used to escape newlines in an equate definition).
An equate macro is used in a text body in the same way as a user defined
macro, that is, by using the defined name preceeded by the %% or
the # character sequence. The preprocessing stage will replace a
%% sequence with a # character sequence if the name does not
match a user defined macro. This triggers an evaluation of the equate
definition associated with the subsequent name at that point in the text
body, the result replacing the # and the equate macro name in the
same way as user macros. Note that because a hash is used to identify an
equate macro any other hash in a text body should be escaped (by using
\# which will be substituted with #).
The equate definition macro can be used to redefine previous macros. This will not produce any error messages. An equate macro definition can also have a null argument (as in user macros) in which case it is given a null definition.
Note that the GPPEQUATE and TEXEQUATE predefined macros which the above replaces are deprecated and hsould not be used.
Go to the first, previous, next, last section, table of contents.