#define

Description

This macro preprocessor directive defines a macro. It has the form:

#define Macro[(Args)] [Value]

where

• Macro is the name of the macro being defined. A valid macro name is an alphanumeric string.

• Args (optional) are the one or more arguments that it accepts. These are of the form (arg1, arg2, ...). The name of each variable specifying a macro argument must begin with a percent sign. Argument values cannot include commas.

• Value (optional) is the value being assigned to the macro, where the value can be any valid ObjectScript code. This can be something as simple as a literal or as complex as an expression.

If a macro is defined with a value, then that value replaces the macro in ObjectScript code. If a macro is defined without a value, then code can use other preprocessor directives to test for the existence of the macro and then perform actions accordingly.

You can use ##continue to continue a #define directive to the next line. You can use ##; to append a comment to a #define line. But you cannot use ##continue and ##; on the same line.

Macros with Values

Macros with values provide a mechanism for simple textual substitutions in ObjectScript code. Wherever the ObjectScript compiler encounters the invocation of a macro (in the form $$$MacroName), it replaces the value specified for the macro at the current position in ObjectScript code. The value of a macro can be any valid ObjectScript code. This includes:

• A string

• A numeric value

• A class property

• The invoking of a method, function, or other code

Macro arguments cannot include commas. If commas are required, the #def1arg directive is available.

The following are examples of definitions for macros being used in various ways.

#define Macro1 22
#define Macro2 "Wilma"
#define Macro3 x+y
#define Macro4 $Length(x)
#define Macro5 film.Title
#define Macro6 +$h
#define Macro7 SET x = 4
#define Macro8 DO ##class(%Library.PopulateUtils).Name()
#define Macro9 READ !,"Name: ",name  WRITE !,"Nice to meet you, ",name,!

#define Macro1A(%x) 22+%x
#define Macro2A(%x) "Wilma" _ ": %x"
#define Macro3A(%x) (x+y)*%x
#define Macro4A(%x) $Length(x) + $Length(%x)
#define Macro5A(%x) film.Title _ ": " _ film.%x
#define Macro6A(%x) +$h - %x
#define Macro7A(%x) SET x = 4+%x
#define Macro8A(%x) DO ##class(%Library.PopulateUtils).Name(%x) 
#define Macro9A(%x) READ !,"Name: ",name  WRITE !,"%x ",name,!
#define Macro9B(%x,%y) READ !,"Name: ",name  WRITE !,"%x %y",name,!

Conventions for Macro Values

Though a macro can have any value, the convention is a macro is literal expression or complete executable line. For example, the following is valid ObjectScript syntax:

#define Macro7 SET x =

where the macro might be invoked with code such as:

 $$$Macro7 22

which the preprocessor would expand to

 SET x = 22

Though this is clearly valid ObjectScript syntax, this use of macros is discouraged.

Macros without Values

A macro can be defined without a value. In this case, the existence (or not) of the macro specifies that a particular condition exists. You can then use other preprocessor directives to test if the macro exists and perform actions accordingly. For example, if an application is compiled either as a Unicode executable or an 8-bit executable, the code might be:

#define Unicode

#ifDef Unicode
   // perform actions here to compile a Unicode
   // version of a program
#else
   // perform actions here to compile an 8-bit
   // version of a program
#endif

JSON Escaped Backslash Restriction

A macro should not attempt to accept a JSON string containing the \" escape convention. A macro value or argument cannot use the JSON \" escape sequence for a literal backslash. This escape sequence is not permitted in the body of a macro or in the formal arguments passed to a macro expansion. As an alternative, the \" escape can be changed to \u0022. This alternative works for JSON syntax strings used as both key names and element values. In the case where the JSON string containing a literal backslash is used as an element value of a JSON array or a JSON object, you can alternatively replace the JSON string containing \" with an ObjectScript string expression enclosed in parentheses that evaluates to the same string value.