Macro Tech-Tips

The EMME/2 macro language has developed from a simple ``save and recall'' mechanism in the early days to the powerful macro programming language that is available in Release 6. From now on, in each issue of EMME/2 NEWS, this new column ``Macro Tech-Tips'' will bring you some useful tips and hints on how to use the various macro commands. Today, we will start with a few practical tips that should not be too difficult to apply to your own macros.

Quitting modules with ``q''
When writing macros, always use ``q'' or ``quit'' to leave a module, and not the number that denotes the selection ``end'' in the primary select of the current module. This reduces compatibility problems if, in a future release, new functionalities are added to the module, causing the selection ``end'' to appear at a different position of the primary select.

Restoring file names
Often it is necessary to redirect the output generated by a macro to files with specific names, so that they can be read back as batch input or be further processed with ~! command escapes. Thus in many macros, the menu commands reports=, plots=, batchout= and batchin= are used to change the active file names. In these cases, the macro should always take care to reinstate the original file namings before the macro terminates. This can be done easily by using the file name specification ^. For example, if at the beginning of a macro the batch output file is changed with the command batchout=transfer.211, the original batch output file naming (the one in effect before the macro was called) is reinstated at the end of the macro with the command batchout=^.

``Select: List Device''
When coding a macro, particular care is needed regarding the question ``Select: list device''. This question normally appears before a report is generated. However, this question only appears if EMME/2 is run interactively and if switch 0 is on, otherwise the question is suppressed. Thus any macro which assumes that this question is always asked is prone to fail if run in a different environment. This problem can easily be avoided by preceding the list device selection by a test of the q register of the form

   ~?q=2         / does the "Select: List device" question appear?
   2             / if yes, send output to report file

Remember that the q register can be used to sense the type of the current question. A value of 0 implies an ``Enter:'' question, 1 a ``Yes/No?'', and N>1 a ``Select:'' question with N alternatives.

Suppressing unwanted reports
In more complex macros, there are often reports produced, just as unavoidable side products of the modules used, which are not needed as result of the macro run. Such reports can be easily suppressed by temporarily setting the report file name to the null device of the operating system. Since the name of these null devices depend on the operating system, the system parameter 2004 can be used to detect the current type of operating system (1=UNIX, 2=DOS, 3=VMS) in the following way

   ~p=2004 (check for operating system)
   ~?p=1 (UNIX)
   reports=/dev/null
   ~?p=2 (DOS)
   reports=NUL
   ~?p=3 (VMS)
   reports=SYS$NULL

After the unwanted reports have been discarded in this way, don't forget to set the report file name back with reports=^. Note that the same approach can also be used for other operating system dependent parts of the macro, such as ~! command escapes.

Suppressing standard dialog
Since Release 6 it is possible to use the dialog output register o to control the generation of dialog while a macro is executing. This register is implemented as a bit vector, each bit having a different effect on the dialog output, as described in section III-7.2.1 of the User's Manual. Here, we limit ourselves to show how this register can be used to make a macro run ``silently'', i.e. to suppress all the dialog that is normally generated and scrolling of the screen as the macro proceeds. Putting the lines

   ~?!i&32768    / test if switch 15 (echo dialog mode) is OFF
   ~o=7          / set bits 0,1,2 of o (suppress output, ~/, input)

at the beginning of the macro will do the trick. Neither the dialog questions nor the answers generated by the macro will be displayed. Only the macro comments will be displayed as the macro is executing (with the initial ~/ stripped off). The command ~?!i&32768, which contains a test if switch 15 is off, is not absolutely necessary. But it is quite useful for debugging purposes, since with a simple on=15 (i.e. set switch for dialog echo mode), the dialog can be made to reappear without any need to modify the macro. Once the standard dialog is disactivated, nothing prevents the macro from setting up its own dialog. This is done by using ~/ comments to display messages and ~*prompt-string commands for interactive prompts. E.g. the command

   ~t3=~* Enter: Matrix containing independent variable=

generates an ``Enter:'' question similar to those used in the EMME/2 modules and stores the answer entered by the user in text register t3 for further use. If the standard dialog is to be switched back on before the end of the macro, it suffices to add the line ~o=0 at the corresponding place in the macro.