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.
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
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
The PXL Base Directory and its Subdirectories
The PXL base directory pxl
contains the following
System wide initialization files are contained in the directory etc:
- bin: executable files (this directory should be included in the
list PATH of directories containing executable files);
- exp: parameter files (if a parameter file is not found in the
current working directory then this directory is searched through);
- etc: support files for startup, fonts, gamma tables;
- texfonts: raster font files.
- A global startup file named startup.pxl that defines experimental
- Files with extension chr. These files contains the vector
font codes for
PXL's Hershey fonts in binary form.
- Gamma tables for high resolution color displays. On systems that allow
high resolution color displays in standard CIE coordinates PXL programs
need gamma tables in order to ensure precise color reproduction. The gamma
table files are described in Chapter rgb.
- Possibly a file named README that describes the contents of the gamma table
files and anything else concerning the tables directory.
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
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.
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
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
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.
default name of the parameter file has the same root as the program name
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
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
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
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
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
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 prog.is 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