Enhanced Macro Processing

Starting with release 3.0, several new macro commands are available. While macro processing is still compatible with release 2.0, many powerful extensions have been added.

Note that these enhancements and new macro commands, discussed in the following, need not be of concern to users that do not intend to write complex macros. They will not affect the normal interactive use of EMME/2. Also, simple macro creation and recall, using only the macro save "~>" and macro recall "~<" commands, still works in the same way. However, for users that need to implement complex repetitive procedures, the new macro features open up a whole new range of possibilities.

In release 2.0, macros were limited to dialog for a particular module. Now macros may change modules freely.

Macros may now be invoked with optional arguments. The arguments are used to substitute for the formal positional parameters %1%, %2%, ..., %9% that appear in the macro. The formal parameter %0% is substituted by the current number of arguments. The substitution mechanism may also be used while a macro is being created, i.e. lines containing formal parameters are first saved in the macro file and then the substitution with the arguments in the save macro command is carried out, before the input line is passed along for further processing. A shift command "~%" shifts down by one index all current arguments, yielding a convenient way to process arguments one by one.

Three numerical registers are available to do simple integer arithmetic and comparisons. The registers are labeled x, y and z and their contents may be substituted by using the formal parameters %x%, %y% and %z%. A register can be initialized to a given value (e.g. "~x=5" sets register x to 5), be incremented by a given value (e.g. "~y+5" will add 5 to register y) or be decremented by a given value (e.g. "~z-%x%" will subtract the current value of register x from register z).

Three read-only registers m, s, b and q contain the current module number as a 3 digit integer, the current scenario, a batch mode indicator and a dialog state variable. The latter contains the type of the current dialog question:

      q=0 Enter question
      q=1 Yes/No question
      q>1 Select question (s=number of alternatives).

The m register can be used to test if a macro is called within the right module and e.g. stop with a message if not. The q register allows sensing the type of question at hand and branch accordingly to different sections. This is particularly useful for situations where a dialog section appears only under certain circumstances.

Conditional commands "~?condition" are used to execute the following line only if a certain condition is met, skipping it otherwise. The conditions may be based on the comparison of the current contents of a register (m,q,s,x,y,z) with a given value, using the format "reg comparison value". The available comparisons are ">", "=" and "<" As an example, the command "~?x>3" appearing in the macro will cause the following line to be executed only if register xx contains a value that is greater than 3. A condition of the form "~?e" will cause the following line to be executed only if an error has been detected while processing the last input line. This mechanism allows trapping and correction of errors that would normally cause the macro processing to stop immediately.

A terminal read command ("~*") that appears in a macro will prompt the user to input one line from the terminal. This line is processed instead of the terminal read command and the macro processing is continued normally thereafter.

A macro may contain labels ("~:label") and branch commands ("~$label"). These are especially useful in combination with the conditional commands discussed above.

A list of all macro commands supported in release 3.0 is given below:

Macro command: Action:

~>macrofile [params] Save dialog in macro file (with optional arguments). After an input line has been copied to the macro file, the optional argument will be used to substitute any formal parameters %1%, %2%, ..., %9% appearing in the input line, before it is passed to the calling module.

~<macrofile [params] Recall macro file (with optional arguments). The optional argument will be used to substitute the formal parameters %1%, %2%, ..., %9%, if they appear in the macro file.

~!command Command escape to operating system. Not supported on all host systems.

~:label Define a label (target for a branch command).

~label Branch to the specified label. Forward and backward branching is allowed.

~/comment Comment line (appears on screen).

~% Shift parameters by one (%1%<-%2%, %2%<-%3%, ...).

~* Read one line from terminal and continue macro.

~?e Execute next line only if error flag is set. This command also prevents the macro from being aborted after an error has occurred.

~?reg=value Execute next line only if register is equal to value. For example, the lines

~?reg>value Execute next line only if register is greater than value.

~?reg<value Execute next line only if register is less than value.

~reg=value Initialize register x, y or z to specified value.

~reg+value Add specified value to register x, y or z.

~reg-value Subtract specified value from register x, y or z.

The following formal parameters are recognized and substituted when appearing in a macro:

Parameter Substituted by

%0% Current number of arguments (number between 0 and 9)

%1% Argument 1 (string, empty if no argument given)

%2% Argument 2 (string, empty if no argument given)

... ...

%9% Argument 9 (string, empty if no argument given)

%b% Batch mode indicator (0=interactive, 1=batch)

%m% Current module number (integer, no decimal point)

%q% Dialog state (0=Enter, 1=Yes/No, 2=Select)

%s% Current scenario

%x% Current value of register x (integer value)

%y% Current value of register y (integer value)

%z% Current value of register z (integer value)