Macros |
Top Previous Next |
Macros are single expressions that can be called by name from within any other expression, with optional "replacement" parameters. They allow re-using common expressions, or simplifying things by calling a complex expression inside another expression. They basically work the same way as macros in the C programming language.
Macros Setup
To create a Macro, go to Maintenance / Advanced Customizations / Macros. This opens the Macro Setup dialog, which lists all current user-defined Macros and allows the typical functions for adding, editing, etc. Note that while there are functions to Move Up and Move down, their position in the list does not affect any other functionality -- it's mainly for your own preferences. However if you have many Macros defined, it may help the speed of your expressions to put the most speed-critical ones nearer the top, since they are searched in this order when executing expressions.
You can also Export one or more Macros to a text file, or Import Macros. This is primarily for you to import Macros created by the software provider, though it can also be used to transfer Macros between multiple databases.
Some sample Macros are included with Campground Master which are actually used by the sample forms. While these have specific uses for the sample forms, you can also look at them as examples. Click the Import macros button, and you'll get a typical Windows file dialog labelled "Import Macros". You need to locate the samples folder, which is typically in C:\Program Files\Campground Master\Samples (most likely you just need to double-click the "Samples" folder to get there). Now select the appropriate "Sample Macro" file, and click Open. Once the sample is imported, you'll see it appear in the list.
Note that the import/export files use the "CSV" file extension (e.g. Sample.csv), which means it's a comma-separated-value text file. Windows may recognize this file extension as something another program can open like Excel, but these are in a special format for importing records to Campground Master and should not be used in other functions. Also avoid opening different kinds of samples which use the same extension (e.g. don't open a Form sample from an Import Script function).
Be aware that Macros should not have duplicate names (or else it would just use the first one encountered by that name). If you make a Copy, text will be added to the name to make it unique. If imported Macros have duplicate names, the imported names are automatically changed to avoid duplication. This might affect the expressions where the Macros are used, so a warning will be shown and indicate which Macro name(s) were changed.
Note that Macro names are not case-sensitive. "MyMacro" is the same as "MYmacro".
Editing Macro Definitions
When editing a Macro, a simple Edit Macro dialog is used where you enter the Macro Name (which is used to invoke the Macro in an expression), the Description (which is shown if the Macro is selected in the Expression Elements dialog), and the Macro's definition itself. Buttons are available to Insert Expression Element and Test/Edit Expression, which invoke the corresponding dialogs to help build the Macro expression.
The Macro definition is just like any other Expression, with one difference. A Macro can have "Replacement arguments", and there is a special placeholder format you use in the definition to indicate where these arguments will go. The format for the placeholder is #n#, where the 'n' is the argument number starting at 1. So you may have #1# and #2#, indicating the first and second argument to the Macro. Here's an example:
iif( VarExists('#1#'), SetVar('#1#', #1#+1), SetVar('#1#',0))
This Macro takes 1 argument, which in this case is a variable name. The expression increments the variable by 1, or sets it to 0 if it did not exist.
Using Macros in Expressions
To invoke a Macro, you use the function Macro( ). Using the example above, assuming the Macro's name is "Inc", and the variable you want to increment is called MyVar:
Macro("Inc", "MyVar")
Note that the Macro name and all arguments must be text values. The argument's text that's inside the quotes, not including the quotes, will be inserted into the text of the Macro's expression, and then the expression will be executed. So in the above example, the Macro function results in this expression being parsed and executed:
iif( VarExists('MyVar'), SetVar('MyVar', MyVar+1), SetVar('MyVar',0))
There are a few important points to make about arguments for the Macro's expression:
•The Macro's expression, after replacing arguments, is actually parsed during the execution of the expression containing the Macro( ) function. This can greatly affect the speed of the parent expression.
•The replacement is strictly a text replacement, so the arguments can be anything -- an expression, a variable, or even an operator or function name. It can be any length, and could also be the result of another expression as long as it's a text result.
•Since the replacement may be done multiple times as in the example above, be careful what you use. For instance, don't use an argument that should not be executed more than once. Also keep in mind that it will need to be parsed many times (avoid huge expressions as arguments).
•Be careful about quotation marks in arguments, like " 'Text' ", if the argument is intended to be a text expression. While the example here is accurate for a text expression, the macro definition might also have quotation marks that conflict, creating an invalid expression (e.g. if the argument is enclosed in other quotation marks).
Macro Return Value
The "value" of the Macro( ) function will simply be the value of the executed expression, which can be any value type. If this is used within a more complex expression, you might need to use a type-conversion function so the parser knows what type it's supposed to return. For instance, if you know the Macro will return text but the parser gives an error that it's an unknown type, use the "C" function to force it to text form. For example: Upper( C( Macro("MyName")))
Macros can be powerful tools when used correctly, but it's best to use them sparingly in places where speed is important. You could still create the Macros as a handy reference for commonly used expressions, but then copy the text out of the Macro definition into the expression where it's needed, instead of actually "calling" the Macro, so it doesn't delay the parsing until execution time.
Additional Topics:
Advanced Customizations Overview & other topics