Macros and Preprocessing

Parameter files may contain macro definitions and preprocessor directives. Actually PXL's macro language is identical to a C language compiler's macro language since PXL uses a compiler's preprocessor to expand the macro statements. A very useful side-effect of this is that applications may have header files that are not only used for compilation but also during run time. For this purpose PXL defines the macro PXLRUN when it calls the compiler's preprocessor. Thus if a header file contains statements like typedef which are not understood by PXL it should be enclosed between the conditional statements like
   #define      YES     0
   #define      NO      1

   #if !defined(PXLRUN)
   typedef unsigned long NewType;
   #endif
In this example the macros YES and NO are defined both in the program text and in the parameter file. Since during the program's compilation the macro PXLRUN will not be defined, the typedef will be used by the compiler. It will, however, not be used during run time, since in this case PXLRUN will be defined. The advantage is, that this header file can also be used during run time and thus makes the symbolic constants YES and NO available for the parameter file. This file may start with
   #include "app.h"
   var
      response = YES
      ...
where app.h is the above header file. The example applications in part two of this manual make extensive use of this feature. They never give numeric constants, but always use symbolic names for the values of experimental variables. The files to be included must reside either in the current directory or in the subdirectory expof the PXL root directory.

Sometimes it may be necessary to run only the preprocessor in order to get an expanded version of the parameter file. The following command does it with PXL's preprocessor command prepxl.exe for the parameter file par.x:

   prepxl par.x > par.i
Note that it is not necessary here to define PXLRUN since prepxl.exe defines PXLRUN by default. The output of prepxl.exe is sent to the standard output and thus has to be redirected into a file if it is to be used later.

Some installations may not be able to run the preprocessor and want a stand-alone application. There are two possibilities to disable preprocessing. The first one is to give the command line option -mwhich disables preprocessing for the current run. The second one is to disable preprocessing by setting the experimental variable preprocessing to OFF. System wide disabling is possible by doing this in the startup file startup.pxl. This disables preprocessing for each run that has access to this startup file. See Chapter run for a description of the startup process during each run.

Parameter values may only be defined in parameter files. The macro processing feature, however, indirectly allows parameter definitions in the command line also. The trick is to define a parameter value by using a macro and then define the macro in the command line. Here is an example from the application game for the Tower of Hanoi:

   ...
   #if     defined(NDISKS)
     disks = NDISKS
   #else
     disks = 4
   #endif
   ...
This section may be part of a parameter file for game defining a Tower of Hanoi game. In this case the parameter disks gets the value 4 if the macro NDISKS is not defined and it gets the value of NDISKS if it is defined. Running game with the command line
   game -f toh.x -DNDISKS=5
will set disks to 5 and thus create a 5 disk problem.

The PXL macro preprocessor is a standard C language macro preprocessor filter. It has been copied from Martin Minow's cpp public domain source code and modified to fit PXL's needs. In addition to the usual default macros prepxl.exe has the macro PXLRUN defined. This makes it possible to use compilation code header files during run time by excluding code with conditional definitions.

The main purpose of the preprocessor is to include external files into a parameter file during run time and to define mnemonic names for numbers in order to make the parameter files more legible. The preprocessor also removes C language comments from the parameter file. This does not affect comment lines starting with the percent sign. These are removed by PXL's own parser.

If memory is sparse then the parameter file may be filtered through prepxl.exe before running the experiment. Suppose bene.x is the parameter file then the appropriate command line is

   prepxl < bene.x > bene.i
This generates the parameter file bene.i which may then be used by the following command
   mvg -f bene.i -m 
Note the use of the command line option -m which does prevent mvg from running the preprocessor once again on bene.i. This may be necessary for running the experiment from within a debugger in order to save memory consumption.


Back to table of contents


Author: Hans Irtel

irtel@psychologie.uni-mannheim.de