MACRO

The MACRO compiler directive associates a commonly used set of PL/B instructions with a label reference. The directive uses the following format:

Where:

macrolabel

Required. A label reference associated with a set of PL/B instructions.

parm

Optional. A parameter replacement label reference.

default

Optional. A valid data or program execution label.

Flags Affected: NONE

Note the following:

1. {macrolabel} is the label reference associated with a set of PL/B instructions. The instructions immediately follow the MACRO directive up to a required MEND directive that terminates the macro instruction set.

2. The {macrolabel} label reference follows normal PL/B label reference guidelines. If the compiler is operating with labels having case sensitivity, the {macrolabel} reference is also case sensitive. Otherwise, the {macrolabel} reference is forced to uppercase.

3. The {macrolabel} can be used in a program just as a PL/B instruction. The compiler will expand the macro's PL/B instruction set into the program where the {macrolabel} is used.

4. The MACRO directive must have a {macrolabel} reference. It can optionally have macro parameter replacement references that allow specific string replacement to occur at any location within the body of the macro.

5. Compilation errors will occur if a MACRO or MEND directive is specified in the body of another macro. However, it is allowed to invoke one or more nested macros within another macro.

6. The {&param} label must always begin with the '&' character and allows normal PL/B label characters.

7. The {&param} parameter reference is always case sensitive.

8. If the {&param} parameter does not have an equal sign (=) immediately following the label, an input replacement string is required when the {macrolabel} macro is invoked.

9. If the {&param} replacement label has an equal sign (=) following it, a default replacement string is defined. The default replacement string is used should the {macrolabel} be invoked with no replacement string input being provided for that one parameter reference.

10. There are two syntax formats allowed to specify a default as follows:

 

Syntax	Meaning
{&param}=	The {&param} followed only by the equal sign (=) character sets the default to a single blank.
{&param}={default}	The {&param} followed by the equal sign (=) character and a specific {default} string sets the default to the {default} string. The {default} can be specified as a literal using double quote characters. Note that all double quote characters are included as part of the replacement string default. If double quote characters do not enclose the replacement string, all characters up to and not including a comma or a colon as last source line character are the default replacement string.

 

11. Special character operators can be specified in the body of a macro. These operators are:

 

Characters	Meaning
|	This character is used in the macro body as a concatenation mark. Concatenation appends two strings together.
@	This character is used in the macro body as a forcing character. The character immediately following this character is forced into an expanded macro.
&id	This character sequence identifies a macro system index that can be used in a macro body to generate unique symbol references. The system index has an initial value of zero and is incremented each time any macro is invoked whether '&id' is used in the macro body or not. The maximum system index value is 65535. When '&id' is found in the body of a macro, the '&id' character sequence is replaced with the current system index string. Note that '&id' is case sensitive and only represents the system index value when specified as shown.

 

12. MACRO expansion stops processing the input parameter list when a non leading blank (white space) is encountered that is not included in a string literal. This processing action was changed from prior releases that included all non-leading blanks for parameters. Please see the MMODE compiler directive to control this processing during a program compilation phase.

13. The designer supports an internal built in macro named &OBJNAME. This macro is transparent to the compiler and only applies to code in the designer. The macro allows use of generic routines or statements in any number of object procedures without code modification.

Example:

     SETPROP      &OBJNAME,ENABLE=0

This line will work equally well with an EDITTEXT object named 'txtCustomer' or a radio button named 'rdoOption'. When the form is saved, the designer expands this macro to the name of the object to which this code is attached.

14. The MACRO processing allows local variable substitution strings to reference local variables that are declared at the same include level as the macro execution level. By default, any local variable (#label) substitution reference resolves to the same include level where the macro is defined. However, there are some cases where a user wants to reference local variables that are declared at the same INCLUDE level where the macro verb is executed and not where the macro verb is defined. In this case, a special syntax format for a local variable (##label) is used.

Example:

The MACRO replacement processing allows a comment that is specified using the '//' comment identifier or a user specified delimiter (-zr compiler option) to terminate the input parameters used as replacement values.

See Also: Example Code, Compiler Directives