Category: Macro Substitution

A macro is a dynamically declared name that represents a character string. When a macro call is encountered in an application program the macro call is replaced by the current character string value of the macro. Macros are sometimes called replacement parameters or substitution variables.

The following topics discuss how to work with macros in applications:

• Availability of macros

• How macros acquire values

• Macro Substitution

• Macros and Compiled Programs

A macro is a dynamically declared name that represents a character string. When a macro call is encountered in an application program the macro call is replaced by the current character string value of the macro. Macros are sometimes called replacement parameters or substitution variables.

The following topics discuss how to work with macros in applications:

• Availability of macros
• How macros acquire values
• Macro Substitution
• Macros and Compiled Programs

The Availability of Macros

You can declare two different kinds of macros during an application session:

• global macros
• local macros

Global Macros

The name declaration for a global macro uses the following syntax:

<name>

where

After a global macro is declared, you can reuse it in any application program for the duration of the application session. When the session ends, the macro is no longer available.

Local Macros

The name declaration for a global macro uses the following syntax:

<n>

where:

Every procedure has its own set of ten local macros, <0> through <9>. You can use a local macro only while the procedure to which it belongs continues to execute. Once execution control transfers elsewhere, the local macros particular to that procedure are discarded.

Examples

Consider a global macro, . If you define to represent the character string list all, then the statement

# Documents

is interpreted as

list all Documents

# is the macro call that is replaced by the character string the represents, list all. The number sign (#) is the macro call indicator.

If you redefine to represent the character string ENT, then the statement

list #s format #Name

is interpreted as

list ENTs format ENTName

Macros and Compiled Programs

A macro can appear anywhere and can be repeated any number of times in an application program.

Each time the software encounters a call to the macro, it substitutes the current character string value of the macro. Substitution takes place one command at a time, before each command is executed. To view these substitutions as they occur, issue a SET LEXTRACE ON command.

Consider a macroprogram called ShowSubstitution that contains the following line:

list #<1> Employees #<2> LastName = '#<3>' #<SortOrder>

If the commands shown below were used to execute the macroprogram ShowSubstitution

let <SortOrder> = 'Sorted by DeptNum'

ShowSubstitution "2" "where" "Smith"

then the LIST command shown above would be interpreted as

list 2 Employees where LastName = 'Smith' Sorted by DeptNum

Avoiding Macro Substitution

To use a character literal that could be mistaken for a macro – that is, the character literal contains the number sign and the macro name delimiters (#<1> or #) – you must employ the backslash (“\”, the escape character) to indicate that the number sign is to be taken literally.

For example, in the command

output 'The #<apples> in the box #<1> is:'

#<apples> and #<1> are recognized as macros. If they are not intended to be macros and therefore have not been previously defined, they are automatically replaced with the null string. Thus the command becomes

output 'The  in box  is:'

If the escape character precedes the number sign, the number sign is taken as a literal character as in:

output 'The \#<apples> in box \#<1> is:'

Nested Macros

The character string that a macro represents can contain references to other macros.

ZIM automatically performs multiple rounds of substitution when macros are nested outside quoted strings. If a nested macro appears inside a quoted string, macro substitution occurs only once.

Example

Consider two macros #<mac1> and #<mac2>. The following command could  be used to assign character strings to these macros:

let <mac1> = 'put' 
let <mac2> = 'out\#<mac1>'

Note the use of the backslash (“\”) to avoid macro substitution in the assignment to <mac2>

<mac1> put
<mac2> out\#<mac1>

With this arrangement, the command

#<mac2> 'Hello'

becomes

out#<mac1> 'Hello'

which in turn becomes

output 'Hello'

On the other hand, the command

output '#<mac2>'

is processed as

output 'out#<mac1>'

Macro substitution takes place only when the software is parsing a source (uncompiled) program.

During compilation, the software parses the source code and performs macro substitution based on current macro values. The resulting commands are then compile and stored in compiled form.

When the compiled program is executed, its source code is not parsed again. Therefore, changes to macro values in the interim are not reflected when the compiled program is executed.

For this reason, programs that use macros should not normally be compiled.

Problems that can arise

Consider a program called ExtremeCase that contains a single line of code:

#< CommandLine>

The program ExtremeCase could contain any command, depending on the character string value assigned to the macro < CommandLine>.

If ExtremeCase is not compiled, executing the commands

let = ‘list all Employees’
ExtremeCase
let = ‘form open fTotals’
ExtremeCase

is equivalent to executing

list all Employees
form open fTotals

If ExtremeCase were to be compiled at this point, the command that would be compiled is

form open fTotals

From this point forward, executing the compiled program ExtremeCase would always result in the execution of the FORM OPEN command, regardless of the current value of the macro .

If you choose to compile

IF you choose to compile programs that use macros, keep the following principles in mind:

• Values for local macros cannot be specified in a call to a compiled macro program

• After compilation, LET and INPUT assignments to a macro have no effect on the value of that macro in the compiled program.

• Global macros should be declared and assigned a value before the programs that call them are completed.

• The software issues a warning when a program that is being compiled contains global macros.

Macros vs Variables

Although macros appear to behave as variables do, they are, in fact, quite different:

• Variables are defined in the Object Dictionary, with a given data type, length, and so on.

• Variables are objects in the application database.

• Variables can be unassigned ($Null).

• The value of a variable can vary at execution time, even in fully compiled applications.

On the other hand

• macros are not defined in the Object Dictionary.

• macros are not objects in the application database.

• macros always have a value; they cannot be $Null.

• macro values are substituted for macro calls when commands are parsed. Data, object names, and entire commands can all be used as macro values.

• macro substitutions are not re-evaluated when a compiled program is executed. Once a program is compiled, changes to the values of macros have not effect on the compiled code.  

A macro acquires a value in one of two ways:

1. implicitly when the software encounters a call to a previously unknown global macro, or when a local macro is unassigned in a macro call program
2. explicitly in a LET or INPUT command (global or local macros), or in a call to a procedure (local macros only)

Implicit Value

If the software encounters a call to a previously unknown macro or an unassigned local macro, it substitutes the null string for the macro.

Example

Suppose the global macro #<NumToDo> has not been previously declared. The command

list #<NumToDo> WaterSamples

processes after replacing #<NumToDo> with a null string. The command executes as

list WaterSamples

Explicit Value

You can use the LET and INPUT commands to explicitly assign values to either global or local macros.

You can also explicitly assign values to local macros in a call to a procedure.

LET Command Examples

You can use the LET command to assign the character string value of an expression to a macro.

In the following example, the LET command assigns values to the global macros <mac1>, <mac2>, and <mac3>, and to the local macro <8>:

let <mac1> = 'Employees where LastName = Smith'
let <mac2> = 'abc'
let <mac3> = 'def'
let <8> = $concat('f', EntName)

You can make any number of assignments in a single LET command. The value assigned to a macro can be the result of a complex value expression.

Do not use the macro call indicator (#) when assigning a value to the macro. If you use the call indicator in an assignment statement, the macro call is replaced by the current character string value of the macro.

For example, suppose the global macro <mac> currently represents the character string <abc>. If you attempt to change the assigned value of <mac> by entering

let #<mac> = 'xyz'

the statement is interpreted as

let <abc> = 'xyz'

Instead of <mac> acquiring a new value, a new macro <abc> has been declared.

INPUT Command Examples

The INPUT command enables the application user to enter one line of data from the terminal. The software resolves the data into a series of values and assigns the values to the expressions listed in the INPUT command. The expressions in the INPUT command can be macros, variables, parameters, and so on, as shown in the following example:

input <mac1> <mac2> <mac3> <8> <mac4> <7>

The macro call indicator (#) is not used in the statement, because the INPUT command, like the LET command, is performing value assignments.

The data entered at the terminal by the user is parsed and separated into individual character strings. The strings are assigned to the specified macros, in order. If there are more strings than values, the remaining macros are assigned the null string.

For example, in response to the INPUT command above, the application user could enter

abc 4+3 '3*5' xyz !

If the current delimiter is the space, the macros are assigned values as follows:

Macro Program Call Examples

You can also assign values to local macros in the call to a macro application.

Normally, you call a macro program by issuing a command consisting of the program’s name. However, the program name can be followed by a list of character strings to assign to the local macros belonging to the main procedure in the program.

Any character string is valid, including

• reserved words
• object names
• special characters
• number literals
• character literals

The software reads any characters following the macro program name and separates them into individual character string values, based on the current field delimiter. The first value from the program call is assigned to macro <1>, the second to macro <2>, and so on.

If there are not enough values to be assigned to all local macros, the remaining local macros are assigned the null string.

If there are more than nine values, the first nine are assigned to the local macros <1> to <9>, then all remaining characters in the statement, including the spaces between them, are assigned to local macro <0>.

If a macro program call includes no character strings, all local macros <0> through <9> are assigned the null string.

Suppose ListFields is a macro program called by the command

ListFields Employees * 2 'Salary/Age'

If the field delimiter is space, values are assigned to the local macros as follows:

Discarding Macro Values

Once defined, a global macro persists until the end of the application session; a local macro persists until the procedure to which it belongs stops executing.

To explicitly discard a macro value, you can assign the null string to the macro as shown in the following example:

let <NumToDo> = ''

This command discards the value of the global macro <NumToDo>.