Macro Tech-Tips

In the last issue of EMME/2 NEWS this column was introduced as a forum to provide hints and practical advice on macro writing. Today, we shall first look at two general recommendations, before digging into the more technical stuff.

Generation of log book comment
EMME/2 records all module calls in a log book, which then can be queried by means of module 1.21. The menu command ``c='' can be used to record any kind of comments into the log book. For important macros it is good practice to use such log book comments to record the invocation of the macro and the parameters used. This can be done by simply inserting a line of the form

c=calling macro: macroname %t0%

just before calling the first module from the main menu. Note that the substitution ``%t0%'' is equivalent to ``%1%, %2%, ...'', i.e. is replaced by the run time parameters of the macro. For some macros it is even sometimes advisable to generate two log book comments, one at the beginning to record the macro invocation and the parameters, and another one at the end to indicate the successful completion of the macro, e.g . ``c=macro macroname has terminated normally''. This way, the log book can be used to trace successful, as well as unsuccessful, invocations of your macro.

Use scalars ms90 - ms99 for temporary results
Scalars are invaluable to store floating point intermediate values in a macro and to transport them from one module to another. To avoid conflicts of such temporary scalars with existing scalars that contain important permanent information, it is recommended to adhere to the following convention: the high-numbered scalars ms90 - ms99 should not be used to hold permanent application specific data, but are set aside for local use by macros. If all applications and all macros follow this simple rule, exchanging and sharing of macros becomes much easier.

Testing for assignment status
Many macros only make sense if they are called from a scenario which contains a valid auto or transit assignment. In particular, this is true for any macro which does some kind of analysis or automatic output generation of assignment results. In this case, it is useful to add a test right at the beginning of the macro to verify if the scenario indeed contains the required assignments. For this purpose, the f-register can be used. This is a read-only bitmap register which contains the following scenario status flags:

Bit: Mask: Flag:

0 1 scenario is protected against forced module execution

1 2 scenario is protected against network modifications

2 4 scenario is protected against scenario deletion

5 32 scenario is ready for an auto assignment

6 64 scenario is ready for a transit assignment

10 1024 scenario contains valid auto assignment

11 2048 scenario contains valid transit assignment

Thus, testing if a scenario contains an auto assignment can be done easily with a sequence of the type

   ~?!f&1024
   ~$scenario_not_assigned

The first line tests if bit 10 of the f-register is zero by performing a bit-wise AND operation of the register value and the corresponding masking value. If this condition is met, i.e. no valid auto assignment in scenario, the second line is executed and the macro branches to the specified label. The same method can be used to test for a transit assignment, in which case the first line would read ``~?!f&2048'', or any other of the above mentioned flags.

Erasing the terminal screen
Sometimes, a macro might need to erase the current terminal screen and restart displaying at the top left corner of a new page. This can be done easily by inserting the macro command

   ~o|256

at the corresponding place in the macro. This line sets bit 8 (2^8=256) of the output control register o, which causes an ``erase page'' command sequence to be sent to the terminal device. This command is particularly useful in macros which suppress the standard dialog output and generate their own screen output, as discussed in the last Tech-Tips column.

Erratum: Unfortunately, a small error crept into the Tech-Tips column in the last issue of EMME/2 NEWS. The null device for the VAX/VMS operating system is ``NL:'' and not ``SYS$NULL'', as was incorrectly stated under Suppressing unwanted reports.