A macro is a holder for a dynamic text. If you for example need to have the current date in your text you can either change your text every day or you can use a date macro which will replace the date macro with the current date. This behaviour makes the macro extremely powerful in tools which requires dynamic text.
A macro text may contain both macro tags and regular text. It may contain zero, one or more macro tags.
A macro field looks similar to a regular text field. The only difference is that the macro field has a yellow background while the regular text fields has a white background.
In this image you can see two regular text fields (Root destination and Prefix), two macro text fields (Routing and File name) and one macro text area (Text).
Image 13-1 Macro fields.
A macro tag starts and ends with a percent sign (%). The macro name is found immediately after the first percent sign.
Example of a simple macro
The macro for the file path for a certain file is named 'FILE_PATH'. The macro is written as %FILE_PATH%
The example above contains a 'simple' macro. The simple macros only have a name. There are however 'complex' macros which need a little extra information to be handled correctly. Many macros have both a simple version and at least one complex version.
The complex macros are written as the simple macro with an extra part where the parameters are written. The parameters are written immediately after the macro name within straight brackets ([ and ]).
Example of a complex macro
The macro for the current date is named 'D'.
This macro
has the simple form %D%
There is an extended alternative to the date macro where the format of the current date may be entered (read more about the formats in the macro specification), e.g. %D[yyyy-MM]%
The complex macros may have one or more parameters. In the example above the date macro is using one parameter in the complex form to indicate what format of the date that should be the result. If more than one parameter is used, each parameter is separated with a comma (,).
Macro with more than one parameter
The date macro has a version where the result date may be the current date plus or minus a certain number of days. If we want to add one day and want the result to be on the format yyyy-MM-dd the macro would be:
%D[+1,yyyy-MM-dd]%
A macro is built with four special characters;
- Percent sign: %
- Left bracket: [
- Right bracket: ]
- Comma character: ,
The parameters in a macro may be built with other macros which in their turn may contain more macros etcetera. A macro's parameters may not contain any of the four special characters except if a new macro is specified. None of the four special characters may be used directly as simple text in a macro, instead the following replacements can be used to get the characters as output;
- Percent sign: %%
- Left bracket: %CHAR[91]%
- Right bracket: %CHAR[93]%
- Comma character: %,
Note that this restriction of using the four characters is only necessary when static text is written as part of a macro's parameter list.
Special characters in macro parameter list
The macro LENGTH will return the number of characters in the parameter, e.g. %LENGTH[the text]% would return '8' (the space between the and text is also counted). If the text that is in the parameter contain any of the special characters it may cause an error, e.g. %LENGTH[100%]%.
In this case the % character in the text could be mistaken as a macro start and result in an error. To be able to count the characters in the text '100%' we will need to escape it with a percent character. The macro %LENGTH[100%%]% will return '4'.
Alternative to the escaping %
There is a special macro named CHAR which will return a character based on a UTF value. This macro may be used to return a wanted special character. If the text '100%' is wanted the macro text could be '100%CHAR[37]%'.
Note that the restriction of not using the special characters in the macro parameter list is only count for when the characters are used directly. If a macro is used which may result in any of the special characters this will not be an error.
Macros returning special characters are ok
Looking back to the examples above we want to have a macro that gives us the length of the text '100%'. We will use the macro CHAR to represent the single percent character (we could have used '%%' as well). The final macro (which is ok and will not raise an error) will be;
%LENGTH[100%CHAR[37]%]%
Note that this will not be an error where you might have suspected that the macro CHAR will result in a single percent and it would then be an error when the macro LENGTH is seeing the single percent character. The macros are parsed in a way that this error never will occur.