Overview

Macros (or variables) are used to substitute values in a job. This might be useful if you want to run a job in different modes at different times. For example, you might want to run the job every week, but read from a different file every time it runs. In this situation, you would specify the filename with a macro rather than the actual name of the file. Then, set that macro value either on the command line (if running in batch) or by using another method.

About Macros and Variables

Using Macros and Variables

Using GETVAR() and SETVAR()

About Macros and Variables

Multiple macro files are supported along with the concept of user- and system-level macros, in a specific order.

System macros are defined in the dfexec_home location and displayed through the user interface, but they cannot be added or edited. User settings are stored in the %apdata% location. You can view, add, or edit through the user interface. Changes to the system-level macro cause an override where the new value is written to the user location. To promote this change, you must update the system location outside of Data Management Studio. New system macros and macro files must be created outside the software.

Load order is important because technical support can use load order to force a macro to be a specific value. In the following, the base directory is defined by dfexec_home. In a typical installation, this is the root directory where DataFlux Data Management Studio is installed.

Command line declarations override environment variables which in turn override macro variable values declared in any of the system or user configuration files. Refer to the DataFlux Data Management Studio Online Help for more information about using macro variables. The results from the Expression node are determined by the code in the Expression Properties dialog box.

Using Macros and Variables

All of the settings in the DataFlux configuration file are represented by macros in the Data Job Editor. For example, the path to the QKB is represented by the macro DQ/QKB. To use a macro in a job, enter it with double percent signs before and after the value. For example:

Old Value:

C:\myfiles\inputfile01.txt

Using Macros, You Enter:

%%MYFILE%%

You can also use the macro to substitute some part of the parameter as in this example, C:\myfiles\%%MYFILE%%. A macro can be used anywhere in a job where text can be entered. If a data job step (such as a drop-down list) prevents you from entering a macro, go to the Advanced tab and enter it there. After you enter a macro under the Advanced tab, you get a warning if you try to return to the standard property dialog box. Depending on your macro, you might need to avoid the standard property dialog box and use the advanced dialog box thereafter. If the property value is plain text, you can return to the standard dialog box.

You can choose to use variables for data input paths and filenames in the data job Expression node. You can declare macro variables by any of these ways:

entering them in the Macros folder of the Administration riser bar
editing the macro.cfg file directly
specifying a file location when you launch a job from the command line

When you add macros using the Administration riser, Data Management Studio directly edits the macro.cfg file. If you edit the macro.cfg file directly, you can also add multiple comments.

Command line declarations override the macro variable values declared in app.cfg. The results from Expression are determined by the code in the Expression Properties dialog box.

Specifically, the value of a macro is determined in one of the following ways:

In the first case, if you are running in batch in Windows, the -VAR or -VARFILE option lets you specify the values of the macros. For example:
```
-o key1=value1 -o key2=value2
-C "C:\mymacros.txt"
```
Note: The return code can be checked by creating a batch file, and checking the error level in the batch file by using the following:
```
IF ERRORLEVEL [return code variable] GOTO
```
If the return code is not set, it returns a 0 on success and 1 on failure. The return code can be set using the RETURN_CODE macro.
In the second case, the file contains each macro on its own line, followed by an equal sign and the value.
- If running in batch on UNIX, all current environment variables are read in as macros.
- If running data jobs in Windows, the values specified in Tools > Options > Global are used.
- If running the Data Management Server, the values can be passed in the SOAP request packet.
- If using an embedded job, the containing job can specify the values as parameters.
- The app.cfg file can be used to store additional values. These values are always read regardless of which mode is used.

Using GETVAR() and SETVAR()

Macro variable values can be read within a single function using the %my_macro% syntax. If you are using more than one expression in your job, use GETVAR() to read variables and SETVAR() to read and modify variables. With GETVAR() and SETVAR(), changes to the value persist from one function to the next. Note that changes affect only that session of the Data Job Editor and are not written back to the configuration file.

The following table contains information about predefined macros:

Predefined Macro	Description
_JOBFILENAME	The name of the current job.
_JOBPATH	The path of the current job.
_JOBPATHFILENAME	The path and filename to the current job.
TEMP	The path to the temporary directory.

Note: For SETVAR(), if you set a macro in an expression step on a page, the new value cannot be reflected in nodes on that page. This condition is because those nodes have already read the old value of the macro and might have acted upon it (such as opening a file before the macro value was changed). This issue arises only from using SETVAR(). Thus, SETVAR() is useful only for setting values that are read on following pages or from other expression nodes with GETVAR().