Macros and Include Files

Macro Basics

A macro is a convenient substitution that you can define and use as follows:

1. You define the macro via special syntax, typically the #define directive. For example:

   #define StringMacro "Hello, World!"

   

   This syntax defines a macro called StringMacro. Note that macro names are case-sensitive.

2. Later, you invoke the macro with the syntax $$$macroname, for example:

     write $$$StringMacro

   

   The previous is equivalent to the following:

     write "Hello, World!"

   

The substitution occurs when the code (a class or routine) is compiled. Specifically, the class or routine itself is unchanged, but the generated .INT code shows the substitutions. (For a fuller picture of how code is compiled, see How These Code Elements Work Together.)

Remember that macros are text substitutions. After the substitution is performed, the resulting statement must be syntactically correct. Therefore, the macro defining an expression should be invoked in a context requiring an expression; the macro for a command and its argument can stand as an independent line of ObjectScript; and so on.

Include File Basics

Typically, you define macros within an include file, which you then include within other code, which enables that code to refer to the macros. This works as follows:

1. An include file is a specific kind of unit of code stored in the database. The following shows a partial example:

   #; Optional comment lines
   #define RELEASEID $GET(^MyGlobal("ReleaseID"),"")
   #define RELEASENUMBER $GET(^MyGlobal("ReleaseNumber"),"")
   #define PRODUCT $GET(^MyGlobal("Product"),"")
   #define LOCALE $GET(^MyGlobal("Locale"),"en-us")

   

   Notice that each line is either a comment line or starts with a #define directive. Blank lines are also permitted. There are alternatives to #define that enable you to define more complex macros; these are discussed elsewhere in more detail.

   In the typical scenario, you create an include file in your IDE and save it with a specific name, such as MyMacros.

2. Within a class or routine that needs to use the macros, include the include file. For example:

   include MyMacros
   
   Class MyPackage.MyClass {
   
   //
   }

   

   In this example, the name of the include file is MyMacros.

   This step makes macros of MyMacros available for use within the class or routine.

   For all the syntax variations, which are different for routines, see Including Include Files.

3. Within that same class or routine, use the syntax $$$macroname to refer to the macro. For example:

    set title=$$$PRODUCT_" "_$$$RELEASENUMBER

   

Defining Macros

In their most basic form, macros are created with a #define directive as shown in Macro Basics.

There are additional directives that enable you to define macros that accept arguments and that support more complex scenarios. Also you can use ##continue to continue a #define directive to the next line. See Preprocessor Directives Reference for more.

This section provides information on where you can define macros, what macro definitions can contain, the rules that macro names must follow, use of whitespace in macros, and macro comments.

Macro Comments and Typeahead Assistance

Macros can include comments, which are passed through as part of their definition. Comments delimited with /* and */, //, #;, ;, and ;; all behave in their usual way. See Comments.

Comments that begin with the /// indicator have a special functionality. If you want your IDEOpens in a new tab to provide typeahead assistance for a macro that is in an include file, then place a /// comment on the line that immediately precedes its definition; this causes its name to appear in the IDE typeahead popup. (All macros in the current file appear in that popup, without any intervention on your part.) For example, if the following code were referenced through an #include directive, then the first macro would appear in typeahead popup and the second would not:

/// A macro that is visible with IDE Typeahead
#define MyAssistMacro 100
 //
 // ...
 // 
 // A macro that is not visible with IDE Typeahead
#define MyOtherMacro -100

For information on making macros available through include files, see Including Include Files.

Including Include Files

This section describes how to include include files in your code.

• To include an include file in a class or at the beginning of a routine, use a directive of the form:

  #include MacroIncFile

  

  where MacroIncFile refers to an included file containing macros that is called MacroIncFile.inc. Note that the .inc suffix is not included in the name of the referenced file when it is an argument of #include. The #include directive is not case-sensitive.

  Note that when a class includes an include file, any subclass of that class automatically includes the same include file.

  For example, if you have one or more macros in the file MyMacros.inc, you can include them with the following call:

  #include MyMacros

  

• To include multiple include files in a routine, use multiple directives of the same form. For example:

  #include MyMacros
  #include YourMacros

  

• To include multiple include files at the beginning of a class definition, the syntax is of the form:

  include (MyMacros, YourMacros) 
  

  

  Note that this include syntax does not have a leading pound sign; this syntax cannot be used for #include.

See the reference section on #include.

Note that when you compile a class definition, that process normalizes the class definition in various ways such as removing whitespace. One of these normalizations converts the capitalization of the include directive.

The ObjectScript compiler provides a /defines qualifier that permits including external macros. For further details refer to the Compiler Qualifiers table in the $SYSTEM reference page.

Where to See Expanded Macros

As noted above, when you compile classes and routines, the system generates INT code (intermediate ObjectScript) code, which you can display and read the INT code, which is a useful way to perform some kinds of troubleshooting.

Also, the following globals contain MAC code (the original source code). Use ZWRITE to display these globals and their subscripts:

• ^rINDEX(routinename,"MAC") contains the timestamp when the MAC code was last saved after being modified, and the character count for this MAC code file. The character count including comments and blank lines. The timestamp when the MAC code was last saved, when it was compiled, and information about #include files used are recorded in the ^ROUTINE global for the INT code. For further details about INT code, refer to the ZLOAD command.

• ^rMAC(routinename) contains a subscript node for each line of code in the MAC routine, as well as ^rMAC(routinename,0,0) containing the line count, ^rMAC(routinename,0) containing the timestamp when it was last saved, and ^rMAC(routinename,0,"SIZE") containing the character count.

• ^rMACSAVE(routinename) contains the history of the MAC routine. It contains the same information as ^rMAC(routinename) for the past five saved versions of the MAC routine. It does not contain information about the current MAC version.

See Also

• #define

• #include

• Preprocessor Directives Reference

• System Macros