System Environment and Files

PXL programs use many different files. A general feature of all the programs is that almost all files which are read and all files which are written are ASCII text files. Thus most of the files can be edited by any text editor. Text input files, however, should never contain any non-ASCII formatting characters. Table filetyps at the end of this chapter contains an overview over all types of files used by PXL programs, their names and where they usually are located.

System Support

The Environment Variable PXL

PXL programs use several global files that are needed to adapt the software to the local computer system and its hardware devices. These files are located in a special directory whose path name has to be communicated to each PXL program by an environment variable. The name of this variable is PXL. It has to be set to the full path name of the directory where the PXL system resides. An example for setting this variable in the MS-DOS AUTOEXEC.BAT file is
   set PXL = d:\pxl
which tells PXL that its base directory is the directory \pxl on drive D.

The PXL Base Directory and its Subdirectories

The PXL base directory pxl contains the following subdirectories: System wide initialization files are contained in the directory etc:

The System Initialization File

Most of a PXL program's behavior is controlled by experimental variables. This includes some basic installation and configuration features. In order to provide some configuration possibilities that are common to multiple runs or even to the whole computer system where the program is running on, there exists a startup file that defines experimental variables. The startup file is named startup.pxl it may either be in the local directory or in the global table directory which is defined by the environment variable PXL. The file startup.pxl is read during the initialization process which takes place before any other file or command line option is read. PXL programs first try to find startup.pxl in the current directory. If it is not found there, then the subdirectory etc of the directory specified by the environment variable PXL is searched. If startup.pxl does not exist, a warning message is printed on the screen, and the program is run with its built in defaults.

The syntactic structure of the startup file is similar to the variables assignment section of a parameter file, however the initial keyword is startup instead of var. This file tells PXL the physical size of the video screen. The program scrnsize may be used to measure the physical screen size and modify startup.pxl accordingly. Note that a startup file may notcontain any preprocessor directives, since it is not piped through the preprocessor.

One important purpose of the startup file is to disable preprocessing. If this is wanted, then startup.pxl is the correct place to do it. Simply include

   preprocessing = OFF
into the file and no preprocessing is done. You may also redefine PXL's preprocessing command by defining your own. The following definition makes the Microsoft C compiler's preprocessor the preprocessor for PXL parameter files:
   preprocmd = "cl -E -DPXLRUN"
Any preprocessor that runs as a filter from standard input to standard output may be used.

A Generally Useful Run Time Header File

Many parameters of PXL programs have numeric values which are fixed by the library. These values are hard to remember. The header file pxlruntm.h defines mnemonic names for many of these generally available parameters. Thus it might be a good idea to include this file into any parameter file which uses global constants in order to make the parameter file easier to read. This is especially useful for the many numeric constants needed with adaptive designs described in Chapter adaptive.

Parameter and Data Files

Finding the Parameter File

The first local file that is read by any program is the parameter file. Its name may be given explicitly in the command line. As usual this overrides every default. The option is -f parfile for telling the program to use parfile as its parameter file. The default name of the parameter file has the same root as the program name but uses the extension x. Thus the command line
would search for a file named icon.x to find its parameter definitions. Before that, however, the program tries to find a parameter file whose root name is identical to the current subject code. Since no subject code is given in the above example the default is vp and icon tries to find a parameter file named vp.x even before looking for icon.x. With the command line
   icon john
the program woud first try to find john.x and then try icon.x. The most common way to start a PXL program is to explicitly specify the subject code and the parameter file:
   icon -f sperling.x john
does not use any defaults but only looks for the file sperling.xwhich may either be in the current directory or in the subdirectory exp of the PXL base directory. If no parameter file is found the program will stop and give a fatal error message.

Data File Names

The subject code is used for creating the output file names. However, it is not sufficient to create the complete data file name. This is because one and the same subject may have to run more than a single session and additional training sessions may also be necessary. Thus the program takes the subject code and appends an underline character and up to 3 digits until the root part of the name contains at most 8 characters. The number that is appended to the subject name reflects the number of already existing files for the same subject code in the current directory. Thus if there is no data file for john in the current directory the above command line will create the file john_000.dat and write its data on this file. Using the same command line again will create file john_001.dat, a third one creates john_002.dat and so on. The same process is used to create the pdt and the res files. Thus we may also get john_000.pdt, john_001.pdt, ..., and john_000.res, john_001.res, ..., and so on. This mechanism makes sure that there is no way to overwrite an existing data file by using the same subject code twice.

As one might expect, there is an exception to this rule. If no subject code is given in the command line, then the program uses vp as a default. If this default name is used, then the corresponding data files get the name vp.dat, vp.pdt, and vp.res. These files are always overwritten if the program is started again without subject code. This mechanism is neccessary since otherwise hundreds of files would be created during the development process of a new experiment. Thus while a program is tested, one can simply run the program by typing its name without giving a subject code.

There is still another exception to these rules, since one method of file name creation beats them all: giving the file name in the command line. The option -o datfile replaces the default dat file by datfile, -p pdtfile replaces the default pdt file by pdtfile, and -r resfile specifies a special results file name. Furthermore the command line option -s will force data and results to be written to stdout.

Defining the Results File Format

PXL programs don't provide much support for data analysis. Instead they provide a complete protocol of each experimental session in the data file. In addition to that most programs provide a mechanism for printing results in a format which is suitable for other programs that do statistical analysis. Very convenient packages are UNIX|STAT by Perlman (1986) for statistical analysis and awk by Aho, Kernighan, and Weinberger (1988) for any other type of data tranformation. Both are available as public domain programs. They accept text files of data and usually expect a single line for each data element. The format of the data line depends on the program.

PXL's mechanism for creating a formatted output file is based on the experimental variable resformat. This is a string valued variable that defines the format and the content of each line of output into the results file with file name extension res. The string resformat may contain arbitrary characters which are printed into the output. resformat may also contain names of experimental variables written between two percent signs like %rtime%. In this case the actual value of the experimental variable rtime is printed instead of the variable's name. An example for resformat is

   resformat = "%subjectcode% %response% %signal% %stddev% %result%"
In this case each line of output into the results file will contain the values of the experimental variables subjectcode, response, signal, stddev, and result. An example of such a results file is
   john 1 1 80.3 345.23
   john 0 0 89.1 281.13
   john 0 1 145.6 418.78
Multiple files of this type may easily be concatenated and the sent to ANOVA, the analysis of variance program from the UNIX|STAT package.

The Run Time Protocol and Error Log File

During each run any PXL program creates a log file that contains a protocol of the last session. This includes the start and end time and the amount of heap memory used. The parameter file parsing process may also be protocolled in the log file. Error and warning messages are printed on the screen and into the log file. If the screen is not available for error messages because it is used as an experimental display, the log file is the only place to find error messages. The root of the log file name is identical to the program name. The extension is log. Each new start of the program overwrites the last log file.

Instructions for Subjects

PXL programs have an automatic feature built in for showing a text file of instructions to the subject. The name of the file to be shown may explicitly be defined in the parameter file by the variable introfile. It defaults to where prog is the name of the experimental program. Instructions are only shown if requested. This is done by either setting the variable instruction to ON or giving the option -i on the command line. The subject may browse through the instructions file by using the cursor keys or the response switches, depending what type of response key is installed during session initialization.

Insert Table filetyps here.

Back to table of contents

Author: Hans Irtel