[pspp-builds.git] / doc / pspp.texi

\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename pspp.info
@settitle PSPP
@set TIMESTAMP Time-stamp:  Sat Dec 20 20:25:33 WST 2003 jmd
@set EDITION 0.2
@set VERSION 0.3
@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c %**end of header

@macro cmd{CMDNAME}
\CMDNAME\
@end macro

@iftex
@finalout
@end iftex

@dircategory Math
@direntry
* PSPP: (pspp).             Statistical analysis package.
@end direntry

@ifinfo
PSPP, for statistical analysis of sampled data, by Ben Pfaff.

This file documents PSPP, a statistical package for analysis of
sampled data that uses a command language compatible with SPSS.

Copyright (C) 1996-9, 2000 Free Software Foundation, Inc.

This version of the PSPP documentation is consistent with version 2 of
``texinfo.tex''.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission notice
identical to this one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this
manual into another language, under the above condition for modified 
versions, except that this permission notice may be stated in a 
translation approved by the Free Software Foundation.
@end ifinfo

@titlepage
@title PSPP
@subtitle A System for Statistical Analysis
@subtitle Edition @value{EDITION}, for PSPP version @value{VERSION}
@author by Ben Pfaff

@page
@vskip 0pt plus 1filll

PSPP Copyright @copyright{} 1997, 1998 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
@end titlepage

@node Top, Introduction, (dir), (dir)
@ifinfo
@top PSPP

This file documents the PSPP package for statistical analysis of sampled
data.  This is edition @value{EDITION}, for PSPP version
@value{VERSION}, last modified at @value{TIMESTAMP}.

@end ifinfo

@menu
* Introduction::                Description of the package.
* License::                     Your rights and obligations.
* Credits::                     Acknowledgement of authors.

* Installation::                How to compile and install PSPP.
* Configuration::               Configuring PSPP.
* Invocation::                  Starting and running PSPP.

* Language::                    Basics of the PSPP command language.
* Expressions::                 Numeric and string expression syntax.

* Data Input and Output::       Reading data from user files.
* System and Portable Files::   Dealing with system & portable files.
* Variable Attributes::         Adjusting and examining variables.
* Data Manipulation::           Simple operations on data.
* Data Selection::              Select certain cases for analysis.
* Conditionals and Looping::    Doing things many times or not at all.
* Statistics::                  Basic statistical procedures.
* Utilities::                   Other commands.
* Not Implemented::             What's not here yet

* Data File Format::            Format of PSPP system files.
* Portable File Format::        Format of PSPP portable files.
* q2c Input Format::            Format of syntax accepted by q2c.

* Bugs::                        Known problems; submitting bug reports.

* Function Index::              Index of PSPP functions for expressions.
* Concept Index::               Index of concepts.
* Command Index::               Index of PSPP procedures.

@end menu

@node Introduction, License, Top, Top
@chapter Introduction
@cindex introduction

@cindex PSPP language
@cindex language, PSPP
PSPP is a tool for statistical analysis of sampled data.  It reads a
syntax file and a data file, analyzes the data, and writes the results
to a listing file or to standard output.

The language accepted by PSPP is similar to those accepted by SPSS
statistical products.  The details of PSPP's language are given
later in this manual.

@cindex files, PSPP
@cindex output, PSPP
@cindex PostScript
@cindex graphics
@cindex Ghostscript
@cindex Free Software Foundation
PSPP produces output in two forms: tables and charts.  Both of these can
be written in several formats; currently, ASCII, PostScript, and HTML
are supported.  In the future, more drivers, such as PCL and X Window
System drivers, may be developed.  For now, Ghostscript, available from
the Free Software Foundation, may be used to convert PostScript chart
output to other formats.

The current version of PSPP, @value{VERSION}, is woefully incomplete in
terms of its statistical procedure support.  PSPP is a work in progress.
The author hopes to support fully support all features in the products
that PSPP replaces, eventually.  The author welcomes questions,
comments, donations, and code submissions.  @xref{Bugs,,Submitting Bug
Reports}, for instructions on contacting the author.

@node License, Credits, Introduction, Top
@chapter Your rights and obligations
@cindex license
@cindex your rights and obligations
@cindex rights, your
@cindex obligations, your

@cindex Free Software Foundation
@cindex GNU General Public License
@cindex General Public License
@cindex GPL
@cindex distribution
@cindex redistribution
Most of PSPP is distributed under the GNU General Public
License.  The General Public License says, in effect, that you may
modify and distribute PSPP as you like, as long as you grant the
same rights to others.  It also states that you must provide source code
when you distribute PSPP, or, if you obtained PSPP
source code from an anonymous ftp site, give out the name of that site.

The General Public License is given in full in the source distribution
as file @file{COPYING}.  In Debian GNU/Linux, this file is also
available as file @file{/usr/share/common-licenses/GPL-2}.

To quote the GPL itself:

@quotation
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
@end quotation

@node Credits, Installation, License, Top
@chapter Credits
@cindex credits
@cindex authors

@cindex Pfaff, Ben
Most of PSPP, as well as this manual,
was written by Ben Pfaff.  @xref{Contacting the Author}, for
instructions on contacting the author.

@cindex Covington, Michael A.
@cindex Van Zandt, James
@cindex @file{ftp.cdrom.com}
@cindex @file{/pub/algorithms/c/julcal10}
@cindex @file{julcal.c}
@cindex @file{julcal.h}
The PSPP source code incorporates @code{julcal10} originally
written by Michael A. Covington and translated into C by Jim Van Zandt.
The original package can be found in directory
@url{ftp://ftp.cdrom.com/pub/algorithms/c/julcal10}.  The entire
contents of that directory constitute the package.  The files actually
used in PSPP are @code{julcal.c} and @code{julcal.h}.

@node Installation, Configuration, Credits, Top
@chapter Installing PSPP
@cindex installation
@cindex PSPP, installing

@cindex GNU C compiler
@cindex gcc
@cindex compiler, recommended
@cindex compiler, gcc
PSPP conforms to the GNU Coding Standards.  PSPP is written in, and
requires for proper operation, ANSI/ISO C.  You might want to
additionally note the following points:

@itemize @bullet
@item
The compiler and linker must allow for significance of several
characters in external identifiers.  The exact number is unknown but at
least 31 is recommended.

@item
The @code{int} type must be 32 bits or wider.

@item
The recommended compiler is gcc 2.7.2.1 or later, but any ANSI compiler
will do if it fits the above criteria.
@end itemize

Many UNIX variants should work out-of-the-box, as PSPP uses GNU
autoconf to detect differences between environments.  Please report any
problems with compilation of PSPP under UNIX and UNIX-like operating
systems---portability is a major concern of the author.

The pages below give specific instructions for installing PSPP
on each type of system mentioned above.

@menu
* UNIX installation::           Installing on UNIX-like environments.
@end menu

@node UNIX installation,  , Installation, Installation
@section UNIX installation
@cindex UNIX, installing PSPP under
@cindex installation, under UNIX
@noindent
To install PSPP under a UNIX-like operating system, follow the steps
below in order.  Some of the text below was taken directly from various
Free Software Foundation sources.

@enumerate
@item
@code{cd} to the directory containing the PSPP source.

@cindex configure, GNU
@cindex GNU configure
@item
Type @samp{./configure} to configure for your particular operating
system and compiler.  Running @code{configure} takes a while.  While
running, it displays some messages telling which features it is checking
for.

You can optionally supply some options to @code{configure} to
give it hints about how to do its job.  Type @code{./configure --help}
to see a list of options.  One of the most useful options is
@samp{--with-checker}, which enables the use of the Checker memory
debugger under supported operating systems.  Checker must already be
installed to use this option.  Do not use @samp{--with-checker} if you
are not debugging PSPP itself.

@cindex @file{Makefile}
@cindex @file{config.h}
@cindex @file{pref.h}
@cindex makefile
@item
(optional) Edit @file{Makefile}, @file{config.h}, and @file{pref.h}.
These files are produced by @code{configure}.  Note that most PSPP
settings can be changed at runtime.

@file{pref.h} is only generated by @code{configure} if it does not
already exist.  (It's copied from @file{prefh.orig}.)

@cindex compiling
@item
Type @samp{make} to compile the package.  If there are any errors during
compilation, try to fix them.  If modifications are necessary to compile
correctly under your configuration, contact the author.
@xref{Bugs,,Submitting Bug Reports}, for details.

@cindex self-tests, running
@item
Type @samp{make check} to run self-tests on the compiled PSPP package.

@cindex installation
@cindex PSPP, installing
@cindex @file{/usr/local/share/pspp/}
@cindex @file{/usr/local/bin/}
@cindex @file{/usr/local/info/}
@cindex documentation, installing
@item
Become the superuser and type @samp{make install} to install the
PSPP binaries, by default in @file{/usr/local/bin/}.  The
directory @file{/usr/local/share/pspp/} is created and populated with
files needed by PSPP at runtime.  This step will also cause the
PSPP documentation to be installed in @file{/usr/local/info/},
but only if that directory already exists.

@item
(optional) Type @samp{make clean} to delete the PSPP binaries
from the source tree.
@end enumerate

@node Configuration, Invocation, Installation, Top
@chapter Configuring PSPP
@cindex configuration
@cindex PSPP, configuring

PSPP has dozens of configuration possibilities and hundreds of
settings.  This is both a bane and a blessing.  On one hand, it's
possible to easily accommodate diverse ranges of setups.  But, on the
other, the multitude of possibilities can overwhelm the casual user.
Fortunately, the configuration mechanisms are profusely described in the
sections below@enddots{}

@menu
* File locations::              How PSPP finds config files.
* Configuration techniques::    Many different methods of configuration@enddots{}
* Configuration files::         How configuration files are read.
* Environment variables::       All about environment variables.
* Output devices::              Describing your terminal(s) and printer(s).
* PostScript driver class::     Configuration of PostScript devices.
* ASCII driver class::          Configuration of character-code devices.
* HTML driver class::           Configuration for HTML output.
* Miscellaneous configuring::   Even more configuration variables.
* Improving output quality::    Hints for producing ever-more-lovely output.
@end menu

@node File locations, Configuration techniques, Configuration, Configuration
@section Locating configuration files

PSPP uses the same method to find most of its configuration files:

@enumerate
@item
The @dfn{base name} of the file being sought is determined.

@item
The path to search is determined.  

@item
Each directory in the search path, from left to right, is searched for a
file with the name of the base name.  The first occurrence is read
as the configuration file.
@end enumerate

The first two steps are elaborated below for the sake of our pedantic
friends.

@enumerate
@item
A @dfn{base name} is a file name lacking an absolute directory
reference.  Some examples of base names are: @file{ps-encodings},
@file{devices}, @file{devps/DESC} (under UNIX), @file{devps\DESC} (under
M$ environments).

Determining the base name is a two-step process:

@enumerate a
@item
If the appropriate environment variable is defined, the value of that
variable is used (@pxref{Environment variables}).  For instance, when
searching for the output driver initialization file, the variable
examined is @code{STAT_OUTPUT_INIT_FILE}.

@item
Otherwise, the compiled-in default is used.  For example, when searching
for the output driver initialization file, the default base name is
@file{devices}.
@end enumerate

@strong{Please note:} If a user-specified base name does contain an
absolute directory reference, as in a file name like
@file{/home/pfaff/fonts/TR}, no path is searched---the file name is used
exactly as given---and the algorithm terminates.

@item
The path is the first of the following that is defined:

@itemize @bullet
@item
A variable definition for the path given in the user environment.  This
is a PSPP-specific environment variable name; for instance,
@code{STAT_OUTPUT_INIT_PATH}.

@item 
In some cases, another, less-specific environment variable is checked.
For instance, when searching for font files, the PostScript driver first
checks for a variable with name @code{STAT_GROFF_FONT_PATH}, then for
one with name @code{GROFF_FONT_PATH}.  (However, font searching has its
own list of esoteric search rules.)

@item
The configuration file path, which is itself determined by the
following rules:

@enumerate a
@item
If the command line contains an option of the form @samp{-B @var{path}}
or @samp{--config-dir=@var{path}}, then the value given on the
rightmost occurrence of such an option is used.

@item
Otherwise, if the environment variable @code{STAT_CONFIG_PATH} is
defined, the value of that variable is used.

@item
Otherwise, the compiled-in fallback default is used.  On UNIX machines,
the default fallback path is

@enumerate 1
@item
@file{~/.pspp}

@item
@file{/usr/local/lib/pspp}

@item
@file{/usr/lib/pspp}
@end enumerate

On DOS machines, the default fallback path is:

@enumerate 1
@item
All the paths from the DOS search path in the @samp{PATH} environment
variable, in left-to-right order.

@item
@file{C:\PSPP}, as a last resort.
@end enumerate

Note that the installer of PSPP can easily change this default
fallback path; thus the above should not be taken as gospel.
@end enumerate
@end itemize
@end enumerate

As a final note: Under DOS, directories given in paths are delimited by
semicolons (@samp{;}); under UNIX, directories are delimited by colons
(@samp{:}).  This corresponds with the standard path delimiter under
these OSes.

@node Configuration techniques, Configuration files, File locations, Configuration
@section Configuration techniques

There are many ways that PSPP can be configured.  These are
described in the list below.  Values given by earlier items take
precedence over those given by later items.

@enumerate
@item
Syntax commands that modify settings, such as @cmd{SET}.  @xref{SET}.

@item
Command-line options.  @xref{Invocation}.

@item
PSPP-specific environment variable contents.  @xref{Environment
variables}.

@item
General environment variable contents.  @xref{Environment variables}.

@item
Configuration file contents.  @xref{Configuration files}.

@item
Fallback defaults.
@end enumerate

Some of the above may not apply to a particular setting.  For instance,
the current pager (such as @samp{more}, @samp{most}, or @samp{less})
cannot be determined by configuration file contents because there is no
appropriate configuration file.

@node Configuration files, Environment variables, Configuration techniques, Configuration
@section Configuration files

Most configuration files have a common form:

@itemize @bullet
@item
Each line forms a separate command or directive.  This means that lines
cannot be broken up, unless they are spliced together with a trailing
backslash, as described below.

@item
Before anything else is done, trailing whitespace is removed.

@item
When a line ends in a backslash (@samp{\}), the backslash is removed,
and the next line is read and appended to the current line.

@itemize @minus
@item
Whitespace preceding the backslash is retained.

@item
This rule continues to be applied until the line read does not end in a
backslash.

@item
It is an error if the last line in the file ends in a backslash.
@end itemize

@item
Comments are introduced by an octothorpe (@samp{#}), and continue until the
end of the line.

@itemize @minus
@item
An octothorpe inside balanced pairs of double quotation marks (@samp{"})
or single quotation marks (@samp{'}) does not introduce a comment.

@item
The backslash character can be used inside balanced quotes of either
type to escape the following character as a literal character.  

(This is distinct from the use of a backslash as a line-splicing
character.)

@item
Line splicing takes place before comment removal.
@end itemize

@item
Blank lines, and lines that contain only whitespace, are ignored.
@end itemize

@node Environment variables, Output devices, Configuration files, Configuration
@section Environment variables

You may think the concept of environment variables is a fairly simple
one.  However, the author of PSPP has found a way to complicate
even something so simple.  Environment variables are further described
in the sections below:

@menu
* Variable values::             Values of variables are determined this way.
* Environment substitutions::   How environment substitutions are made.
* Predefined variables::        A few variables are automatically defined.
@end menu

@node Variable values, Environment substitutions, Environment variables, Environment variables
@subsection Values of environment variables

Values for environment variables are obtained by the following means,
which are arranged in order of decreasing precedence:

@enumerate
@item
Command-line options.  @xref{Invocation}.

@item
The @file{environment} configuration file---more on this below.

@item
Actual environment variables (defined in the shell or other parent
process).
@end enumerate

The @file{environment} configuration file is located through application
of the usual algorithm for configuration files (@pxref{File locations}),
except that its contents do not affect the search path used to find
@file{environment} itself.  Use of @file{environment} is discouraged on
systems that allow an arbitrarily large environment; it is supported for
use on systems like MS-DOS that limit environment size.

@file{environment} is composed of lines having the form
@samp{@var{key}=@var{value}}, where @var{key} and the equals sign
(@samp{=}) are required, and @var{value} is optional.  If @var{value} is
given, variable @var{key} is given that value; if @var{value} is absent,
variable @var{key} is undefined (deleted).  Variables may not be defined
with a null value.

Environment substitutions are performed on each line in the file
(@pxref{Environment substitutions}).

See @ref{Configuration files}, for more details on formatting of the
environment configuration file.

@quotation
@strong{Please note:} Support for @file{environment} is not yet
implemented.
@end quotation

@node Environment substitutions, Predefined variables, Variable values, Environment variables
@subsection Environment substitutions

Much of the power of environment variables lies in the way that they may
be substituted into configuration files.  Variable substitutions are
described below.

The line is scanned from left to right.  In this scan, all characters
other than dollar signs (@samp{$}) are retained unmolested.  Dollar
signs, however, introduce an environment variable reference.  References
take three forms:

@table @code
@item $@var{var}
Replaced by the value of environment variable @var{var}, determined as
specified in @ref{Variable values}.  @var{var} must be one of the
following:

@itemize @bullet
@item
One or more letters.

@item
Exactly one nonalphabetic character.  This may not be a left brace
(@samp{@{}).
@end itemize

@item $@{@var{var}@}
Same as above, but @var{var} may contain any character (except
@samp{@}}).

@item $$
Replaced by a single dollar sign.
@end table

Undefined variables expand to a empty value.

@node Predefined variables,  , Environment substitutions, Environment variables
@subsection Predefined environment variables

There are two environment variables predefined for use in environment
substitutions:

@table @samp
@item VER
Defined as the version number of PSPP, as a string, in a format
something like @samp{0.9.4}.

@item ARCH
Defined as the host architecture of PSPP, as a string, in standard
cpu-manufacturer-OS format.  For instance, Debian GNU/Linux 1.1 on an
Intel machine defines this as @samp{i586-unknown-linux}.  This is
somewhat dependent on the system used to compile PSPP.
@end table

Nothing prevents these values from being overridden, although it's a
good idea not to do so.

@node Output devices, PostScript driver class, Environment variables, Configuration
@section Output devices

Configuring output devices is the most complicated aspect of configuring
PSPP.  The output device configuration file is named
@file{devices}.  It is searched for using the usual algorithm for
finding configuration files (@pxref{File locations}).  Each line in the
file is read in the usual manner for configuration files
(@pxref{Configuration files}).

Lines in @file{devices} are divided into three categories, described
briefly in the table below:

@table @i
@item driver category definitions
Define a driver in terms of other drivers.

@item macro definitions
Define environment variables local to the the output driver
configuration file.

@item device definitions
Describe the configuration of an output device.
@end table

The following sections further elaborate the contents of the
@file{devices} file.

@menu
* Driver categories::           How to organize the driver namespace.
* Macro definitions::           Environment variables local to @file{devices}.
* Device definitions::          Output device descriptions.
* Dimensions::                  Lengths, widths, sizes, @enddots{}
* papersize::                   Letter, legal, A4, envelope, @enddots{}
* Distinguishing line types::   Details on @file{devices} parsing.
* Tokenizing lines::            Dividing @file{devices} lines into tokens.
@end menu

@node Driver categories, Macro definitions, Output devices, Output devices
@subsection Driver categories

Drivers can be divided into categories.  Drivers are specified by their
names, or by the names of the categories that they are contained in.
Only certain drivers are enabled each time PSPP is run; by
default, these are the drivers in the category `default'.  To enable a
different set of drivers, use the @samp{-o @var{device}} command-line
option (@pxref{Invocation}).

Categories are specified with a line of the form
@samp{@var{category}=@var{driver1} @var{driver2} @var{driver3} @var{@dots{}}
@var{driver@var{n}}}.  This line specifies that the category
@var{category} is composed of drivers named @var{driver1},
@var{driver2}, and so on.  There may be any number of drivers in the
category, from zero on up.

Categories may also be specified on the command line
(@pxref{Invocation}).

This is all you need to know about categories.  If you're still curious,
read on.

First of all, the term `categories' is a bit of a misnomer.  In fact,
the internal representation is nothing like the hierarchy that the term
seems to imply: a linear list is used to keep track of the enabled
drivers.

When PSPP first begins reading @file{devices}, this list contains
the name of any drivers or categories specified on the command line, or
the single item `default' if none were specified.

Each time a category definition is specified, the list is searched for
an item with the value of @var{category}.  If a matching item is found,
it is deleted.  If there was a match, the list of drivers (@var{driver1}
through @var{driver@var{n}}) is then appended to the list.

Each time a driver definition line is encountered, the list is searched.
If the list contains an item with that driver's name, the driver is
enabled and the item is deleted from the list.  Otherwise, the driver
is not enabled.

It is an error if the list is not empty when the end of @file{devices}
is reached.

@node Macro definitions, Device definitions, Driver categories, Output devices
@subsection Macro definitions

Macro definitions take the form @samp{define @var{macroname}
@var{definition}}.  In such a macro definition, the environment variable
@var{macroname} is defined to expand to the value @var{definition}.
Before the definition is made, however, any macros used in
@var{definition} are expanded.

Please note the following nuances of macro usage:

@itemize @bullet
@item
For the purposes of this section, @dfn{macro} and @dfn{environment
variable} are synonyms.

@item
Macros may not take arguments.

@item
Macros may not recurse.

@item
Macros are just environment variable definitions like other environment
variable definitions, with the exception that they are limited in scope
to the @file{devices} configuration file.

@item
Macros override other all environment variables of the same name (within
the scope of @file{devices}).

@item
Earlier macro definitions for a particular @var{key} override later
ones.  In particular, macro definitions on the command line override
those in the device definition file.  @xref{Non-option Arguments}.

@item
There are two predefined macros, whose values are determined at runtime:

@table @samp
@item viewwidth
Defined as the width of the console screen, in columns of text.

@item viewlength
Defined as the length of the console screen, in lines of text.
@end table
@end itemize

@node Device definitions, Dimensions, Macro definitions, Output devices
@subsection Driver definitions

Driver definitions are the ultimate purpose of the @file{devices}
configuration file.  These are where the real action is.  Driver
definitions tell PSPP where it should send its output.

Each driver definition line is divided into four fields.  These fields
are delimited by colons (@samp{:}).  Each line is subjected to
environment variable interpolation before it is processed further
(@pxref{Environment substitutions}).  From left to right, the four
fields are, in brief:

@table @i
@item driver name
A unique identifier, used to determine whether to enable the driver.

@item class name
One of the predefined driver classes supported by PSPP.  The
currently supported driver classes include `postscript' and `ascii'.

@item device type(s)
Zero or more of the following keywords, delimited by spaces:

@table @code
@item screen

Indicates that the device is a screen display.  This may reduce the
amount of buffering done by the driver, to make interactive use more
convenient.

@item printer

Indicates that the device is a printer.

@item listing

Indicates that the device is a listing file.
@end table

These options are just hints to PSPP and do not cause the output to be
directed to the screen, or to the printer, or to a listing file---those
must be set elsewhere in the options.  They are used primarily to decide
which devices should be enabled at any given time.  @xref{SET}, for more
information.

@item options
An optional set of options to pass to the driver itself.  The exact
format for the options varies among drivers.
@end table

The driver is enabled if:

@enumerate
@item
Its driver name is specified on the command line, or

@item
It's in a category specified on the command line, or

@item
If no categories or driver names are specified on the command line, it
is in category @code{default}.
@end enumerate

For more information on driver names, see @ref{Driver categories}.

The class name must be one of those supported by PSPP.  The
classes supported depend on the options with which PSPP was
compiled.  See later sections in this chapter for descriptions of the
available driver classes.

Options are dependent on the driver.  See the driver descriptions for
details.

@node Dimensions, papersize, Device definitions, Output devices
@subsection Dimensions

Quite often in configuration it is necessary to specify a length or a
size.  PSPP uses a common syntax for all such, calling them
collectively by the name @dfn{dimensions}.

@itemize @bullet
@item
You can specify dimensions in decimal form (@samp{12.5}) or as
fractions, either as mixed numbers (@samp{12-1/2}) or raw fractions
(@samp{25/2}).

@item 
A number of different units are available.  These are suffixed to the
numeric part of the dimension.  There must be no spaces between the
number and the unit.  The available units are identical to those offered
by the popular typesetting system @TeX{}:

@table @code
@item in
inch (1 @code{in} = 2.54 @code{cm})

@item "
inch (1 @code{in} = 2.54 @code{cm})

@item pt
printer's point (1 @code{in} = 72.27 @code{pt})

@item pc
pica (12 @code{pt} = 1 @code{pc})

@item bp
PostScript point (1 @code{in} = 72 @code{bp})

@item cm
centimeter

@item mm
millimeter (10 @code{mm} = 1 @code{cm})

@item dd
didot point (1157 @code{dd} = 1238 @code{pt})

@item cc
cicero (1 @code{cc} = 12 @code{dd})

@item sp
scaled point (65536 @code{sp} = 1 @code{pt})
@end table

@item
If no explicit unit is given, PSPP attempts to guess the best unit:

@itemize @minus
@item
Numbers less than 50 are assumed to be in inches.

@item
Numbers 50 or greater are assumed to be in millimeters.
@end itemize
@end itemize

@node papersize, Distinguishing line types, Dimensions, Output devices
@subsection Paper sizes

Output drivers usually deal with some sort of hardcopy media.  This
media is called @dfn{paper} by the drivers, though in reality it could
be a transparency or film or thinly veiled sarcasm.  To make it easier
for you to deal with paper, PSPP allows you to have (of course!) a
configuration file that gives symbolic names, like ``letter'' or
``legal'' or ``a4'', to paper sizes, rather than forcing you to use
cryptic numbers like ``8-1/2 x 11'' or ``210 by 297''.  Surprisingly
enough, this configuration file is named @file{papersize}.
@xref{Configuration files}.

When PSPP tries to connect a symbolic paper name to a paper size, it
reads and parses each non-comment line in the file, in order.  The first
field on each line must be a symbolic paper name in double quotes.
Paper names may not contain double quotes.  Paper names are not
case-sensitive: @samp{legal} and @samp{Legal} are equivalent.

If a match is found for the paper name, the rest of the line is parsed.
If it is found to be a pair of dimensions (@pxref{Dimensions}) separated
by either @samp{x} or @samp{by}, then those are taken to be the paper
size, in order of width followed by length.  There @emph{must} be at
least one space on each side of @samp{x} or @samp{by}.

Otherwise the line must be of the form
@samp{"@var{paper-1}"="@var{paper-2}"}.  In this case the target of the
search becomes paper name @var{paper-2} and the search through the file
continues.

@node Distinguishing line types, Tokenizing lines, papersize, Output devices
@subsection How lines are divided into types

The lines in @file{devices} are distinguished in the following manner:

@enumerate
@item
Leading whitespace is removed.

@item
If the resulting line begins with the exact string @code{define},
followed by one or more whitespace characters, the line is processed as
a macro definition.

@item
Otherwise, the line is scanned for the first instance of a colon
(@samp{:}) or an equals sign (@samp{=}).

@item
If a colon is encountered first, the line is processed as a driver
definition.

@item
Otherwise, if an equals sign is encountered, the line is processed as a
macro definition.

@item
Otherwise, the line is ill-formed.
@end enumerate

@node Tokenizing lines,  , Distinguishing line types, Output devices
@subsection How lines are divided into tokens

Each driver definition line is run through a simple tokenizer.  This
tokenizer recognizes two basic types of tokens.

The first type is an equals sign (@samp{=}).  Equals signs are both
delimiters between tokens and tokens in themselves.

The second type is an identifier or string token.  Identifiers and
strings are equivalent after tokenization, though they are written
differently.  An identifier is any string of characters other than
whitespace or equals sign.

A string is introduced by a single- or double-quote character (@samp{'}
or @samp{"}) and, in general, continues until the next occurrence of
that same character.  The following standard C escapes can also be
embedded within strings:

@table @code
@item \'
A single-quote (@samp{'}).

@item \"
A double-quote (@samp{"}).

@item \?
A question mark (@samp{?}).  Included for hysterical raisins.

@item \\
A backslash (@samp{\}).

@item \a
Audio bell (ASCII 7).

@item \b
Backspace (ASCII 8).

@item \f
Formfeed (ASCII 12).

@item \n
New-line (ASCII 10)

@item \r
Carriage return (ASCII 13).

@item \t
Tab (ASCII 9).

@item \v
Vertical tab (ASCII 11).

@item \@var{o}@var{o}@var{o}
Each @samp{o} must be an octal digit.  The character is the one having
the octal value specified.  Any number of octal digits is read and
interpreted; only the lower 8 bits are used.

@item \x@var{h}@var{h}
Each @samp{h} must be a hex digit.  The character is the one having the
hexadecimal value specified.  Any number of hex digits is read and
interpreted; only the lower 8 bits are used.
@end table

Tokens, outside of quoted strings, are delimited by whitespace or equals
signs.

@node PostScript driver class, ASCII driver class, Output devices, Configuration
@section The PostScript driver class

The @code{postscript} driver class is used to produce output that is
acceptable to PostScript printers and to PC-based PostScript
interpreters such as Ghostscript.  Continuing a long tradition,
PSPP's PostScript driver is configurable to the point of
absurdity.

There are actually two PostScript drivers.  The first one,
@samp{postscript}, produces ordinary DSC-compliant PostScript output.
The second one @samp{epsf}, produces an Encapsulated PostScript file.
The two drivers are otherwise identical in configuration and in
operation.

The PostScript driver is described in further detail below.

@menu
* PS output options::           Output file options.
* PS page options::             Paper, margins, scaling & rotation, more!
* PS file options::             Configuration files.
* PS font options::             Default fonts, font options.
* PS line options::             Line widths, options.
* Prologue::                    Details on the PostScript prologue.
* Encodings::                   Details on PostScript font encodings.
@end menu

@node PS output options, PS page options, PostScript driver class, PostScript driver class
@subsection PostScript output options

These options deal with the form of the output and the output file
itself:

@table @code
@item output-file=@var{filename}

File to which output should be sent.  This can be an ordinary filename
(i.e., @code{"pspp.ps"}), a pipe filename (i.e., @code{"|lpr"}), or
stdout (@code{"-"}).  Default: @code{"pspp.ps"}.

@item color=@var{boolean}

Most of the time black-and-white PostScript devices are smart enough to
map colors to shades themselves.  However, you can cause the PSPP
output driver to do an ugly simulation of this in its own driver by
turning @code{color} off.  Default: @code{on}.

This is a boolean setting, as are many settings in the PostScript
driver.  Valid positive boolean values are @samp{on}, @samp{true},
@samp{yes}, and nonzero integers.  Negative boolean values are
@samp{off}, @samp{false}, @samp{no}, and zero.

@item data=@var{data-type}

One of @code{clean7bit}, @code{clean8bit}, or @code{binary}.  This
controls what characters will be written to the output file.  PostScript
produced with @code{clean7bit} can be transmitted over 7-bit
transmission channels that use ASCII control characters for line
control.  @code{clean8bit} is similar but allows characters above 127 to
be written to the output file.  @code{binary} allows any character in
the output file.  Default: @code{clean7bit}.

@item line-ends=@var{line-end-type}

One of @code{cr}, @code{lf}, or @code{crlf}.  This controls what is used
for new-line in the output file.  Default: @code{cr}.

@item optimize-line-size=@var{level}

Either @code{0} or @code{1}.  If @var{level} is @code{1}, then short
line segments will be collected and merged into longer ones.  This
reduces output file size but requires more time and memory.  A
@var{level} of @code{0} has the advantage of being better for
interactive environments.  @code{1} is the default unless the
@code{screen} flag is set; in that case, the default is @code{0}.

@item optimize-text-size=@var{level}

One of @code{0}, @code{1}, or @code{2}, each higher level representing
correspondingly more aggressive space savings for text in the output
file and requiring correspondingly more time and memory.  Unfortunately
the levels presently are all the same.  @code{1} is the default unless
the @code{screen} flag is set; in that case, the default is @code{0}.
@end table

@node PS page options, PS file options, PS output options, PostScript driver class
@subsection PostScript page options

These options affect page setup:

@table @code
@item headers=@var{boolean}

Controls whether the standard headers showing the time and date and
title and subtitle are printed at the top of each page.  Default:
@code{on}.

@item paper-size=@var{paper-size}

Paper size, either as a symbolic name (i.e., @code{letter} or @code{a4})
or specific measurements (i.e., @code{8-1/2x11} or @code{"210 x 297"}.
@xref{papersize, , Paper sizes}.  Default: @code{letter}.

@item orientation=@var{orientation}

Either @code{portrait} or @code{landscape}.  Default: @code{portrait}.

@item left-margin=@var{dimension}
@itemx right-margin=@var{dimension}
@itemx top-margin=@var{dimension}
@itemx bottom-margin=@var{dimension}

Sets the margins around the page.  The headers, if enabled, are not
included in the margins; they are in addition to the margins.  For a
description of dimensions, see @ref{Dimensions}.  Default: @code{0.5in}.

@end table

@node PS file options, PS font options, PS page options, PostScript driver class
@subsection PostScript file options

Oh, my.  You don't really want to know about the way that the PostScript
driver deals with files, do you?  Well I suppose you're entitled, but I
warn you right now: it's not pretty.  Here goes@enddots{}

First let's look at the options that are available:

@table @code

@item font-dir=@var{font-directory}

Sets the font directory.  Default: @code{devps}.

@item prologue-file=@var{prologue-file-name}

Sets the name of the PostScript prologue file.  You can write your own
prologue, though I have no idea why you'd want to: see @ref{Prologue}.
Default: @code{ps-prologue}.

@item device-file=@var{device-file-name}

Sets the name of the Groff-format device description file.  The
PostScript driver reads this to know about the scaling of fonts
and so on.  The format of such files is described in groff_font(5),
included with Groff.  Default: @code{DESC}.

@item encoding-file=@var{encoding-file-name}

Sets the name of the encoding file.  This file contains a list of all
font encodings that will be needed so that the driver can put all of
them at the top of the prologue.  @xref{Encodings}.  Default:
@code{ps-encodings}.

If the specified encoding file cannot be found, this error will be
silently ignored, since most people do not need any encodings besides
the ones that can be found using @code{auto-encodings}, described below.

@item auto-encode=@var{boolean}

When enabled, the font encodings needed by the default proportional- and
fixed-pitch fonts will automatically be dumped to the PostScript
output.  Otherwise, it is assumed that the user has an encoding file
and knows how to use it (@pxref{Encodings}).  There is probably no good
reason to turn off this convenient feature.  Default: @code{on}.

@end table

Next I suppose it's time to describe the search algorithm.  When the
PostScript driver needs a file, whether that file be a font, a
PostScript prologue, or what you will, it searches in this manner:

@enumerate

@item
Constructs a path by taking the first of the following that is defined:

@enumerate a

@item
Environment variable @code{STAT_GROFF_FONT_PATH}.  @xref{Environment
variables}.

@item
Environment variable @code{GROFF_FONT_PATH}.

@item
The compiled-in fallback default.
@end enumerate

@item
Constructs a base name from concatenating, in order, the font directory,
a path separator (@samp{/} or @samp{\}), and the file to be found.  A
typical base name would be something like @code{devps/ps-encodings}.

@item
Searches for the base name in the path constructed above.  If the file
is found, the algorithm terminates.

@item
Searches for the base name in the standard configuration path.  See
@ref{File locations}, for more details.  If the file is found, the
algorithm terminates.

@item
At this point we remove the font directory and path separator from the
base name.  Now the base name is simply the file to be found, i.e.,
@code{ps-encodings}.

@item
Searches for the base name in the path constructed in the first step.
If the file is found, the algorithm terminates.

@item
Searches for the base name in the standard configuration path.  If the
file is found, the algorithm terminates.

@item
The algorithm terminates unsuccessfully.
@end enumerate

So, as you see, there are several ways to configure the PostScript
drivers.  Careful selection of techniques can make the configuration
very flexible indeed.

@node PS font options, PS line options, PS file options, PostScript driver class
@subsection PostScript font options

The list of available font options is short and sweet:

@table @code
@item prop-font=@var{font-name}

Sets the default proportional font.  The name should be that of a
PostScript font.  Default: @code{"Helvetica"}.

@item fixed-font=@var{font-name}

Sets the default fixed-pitch font.  The name should be that of a
PostScript font.  Default: @code{"Courier"}.

@item font-size=@var{font-size}

Sets the size of the default fonts, in thousandths of a point.  Default:
@code{10000}.

@end table

@node PS line options, Prologue, PS font options, PostScript driver class
@subsection PostScript line options

Most tables contain lines, or rules, between cells.  Some features of
the way that lines are drawn in PostScript tables are user-definable:

@table @code

@item line-style=@var{style}

Sets the style used for lines used to divide tables into sections.
@var{style} must be either @code{thick}, in which case thick lines are
used, or @var{double}, in which case double lines are used.  Default:
@code{thick}.

@item line-gutter=@var{dimension}

Sets the line gutter, which is the amount of whitespace on either side
of lines that border text or graphics objects.  @xref{Dimensions}.
Default: @code{0.5pt}.

@item line-spacing=@var{dimension}

Sets the line spacing, which is the amount of whitespace that separates
lines that are side by side, as in a double line.  Default:
@code{0.5pt}.

@item line-width=@var{dimension}

Sets the width of a typical line used in tables.  Default: @code{0.5pt}.

@item line-width-thick=@var{dimension}

Sets the width of a thick line used in tables.  Not used if
@code{line-style} is set to @code{thick}.  Default: @code{1.5pt}.

@end table

@node Prologue, Encodings, PS line options, PostScript driver class
@subsection The PostScript prologue

Most PostScript files that are generated mechanically by programs
consist of two parts: a prologue and a body.  The prologue is generally
a collection of boilerplate.  Only the body differs greatly between
two outputs from the same program.
 
This is also the strategy used in the PSPP PostScript driver.  In
general, the prologue supplied with PSPP will be more than sufficient.
In this case, you will not need to read the rest of this section.
However, hackers might want to know more.  Read on, if you fall into
this category.

The prologue is dumped into the output stream essentially unmodified.
However, two actions are performed on its lines.  First, certain lines
may be omitted as specified in the prologue file itself.  Second,
variables are substituted.

The following lines are omitted:

@enumerate
@item
All lines that contain three bangs in a row (@code{!!!}).

@item
Lines that contain @code{!eps}, if the PostScript driver is producing
ordinary PostScript output.  Otherwise an EPS file is being produced,
and the line is included in the output, although everything following
@code{!eps} is deleted.

@item
Lines that contain @code{!ps}, if the PostScript driver is producing EPS
output.  Otherwise, ordinary PostScript is being produced, and the line
is included in the output, although everything following @code{!ps} is
deleted.
@end enumerate

The following are the variables that are substituted.  Only the
variables listed are substituted; environment variables are not.
@xref{Environment substitutions}.

@table @code
@item bounding-box

The page bounding box, in points, as four space-separated numbers.  For
U.S. letter size paper, this is @samp{0 0 612 792}.

@item creator

PSPP version as a string: @samp{GNU PSPP 0.1b}, for example.

@item date

Date the file was created.  Example: @samp{Tue May 21 13:46:22 1991}.

@item data

Value of the @code{data} PostScript driver option, as one of the strings
@samp{Clean7Bit}, @samp{Clean8Bit}, or @samp{Binary}.

@item orientation

Page orientation, as one of the strings @code{Portrait} or
@code{Landscape}.

@item user

Under multiuser OSes, the user's login name, taken either from the
environment variable @code{LOGNAME} or, if that fails, the result of the
C library function @code{getlogin()}.  Defaults to @samp{nobody}.

@item host

System hostname as reported by @code{gethostname()}.  Defaults to
@samp{nowhere}.

@item prop-font

Name of the default proportional font, prefixed by the word
@samp{font} and a space.  Example: @samp{font Times-Roman}.

@item fixed-font

Name of the default fixed-pitch font, prefixed by the word @samp{font}
and a space.

@item scale-factor

The page scaling factor as a floating-point number.  Example:
@code{1.0}.  Note that this is also passed as an argument to the BP
macro.

@item paper-length
@item paper-width

The paper length and paper width, respectively, in thousandths of a
point.  Note that these are also passed as arguments to the BP macro.

@item left-margin
@item top-margin

The left margin and top margin, respectively, in thousandths of a
point.  Note that these are also passed as arguments to the BP macro.

@item title

Document title as a string.  This is not the title specified in the
PSPP syntax file.  A typical title is the word @samp{PSPP} followed
by the syntax file name in parentheses.  Example: @samp{PSPP
(<stdin>)}.

@item source-file

PSPP syntax file name.  Example: @samp{mary96/first.stat}.

@end table

Any other questions about the PostScript prologue can best be answered
by examining the default prologue or the PSPP source.

@node Encodings,  , Prologue, PostScript driver class
@subsection PostScript encodings

PostScript fonts often contain many more than 256 characters, in order
to accommodate foreign language characters and special symbols.
PostScript uses @dfn{encodings} to map these onto single-byte symbol
sets.  Each font can have many different encodings applied to it.

PSPP's PostScript driver needs to know which encoding to apply to each
font.  It can determine this from the information encapsulated in the
Groff font description that it reads.  However, there is an additional
problem---for efficiency, the PostScript driver needs to have a complete
list of all encodings that will be used in the entire session @emph{when
it opens the output file}.  For this reason, it can't use the
information built into the fonts because it doesn't know which fonts
will be used.

As a stopgap solution, there are two mechanisms for specifying which
encodings will be used.  The first mechanism is automatic and it is the
only one that most PSPP users will ever need.  The second mechanism is
manual, but it is more flexible.  Either mechanism or both may be used
at one time.

The first mechanism is activated by the @samp{auto-encode} driver option
(@pxref{PS file options}).  When enabled, @samp{auto-encode} causes the
PostScript driver to include the encodings used by the default
proportional and fixed-pitch fonts (@pxref{PS font options}).  Many
PSPP output files will only need these encodings.

The second mechanism is the file specified by the @samp{encoding-file}
option (@pxref{PS file options}).  If it exists, this file must consist
of lines in PSPP configuration-file format (@pxref{Configuration
files}).  Each line that is not a comment should name a PostScript
encoding to include in the output.

It is not an error if an encoding is included more than once, by either
mechanism.  It will appear only once in the output.  It is also not an
error if an encoding is included in the output but never used.  It
@emph{is} an error if an encoding is used but not included by one of
these mechanisms.  In this case, the built-in PostScript encoding
@samp{ISOLatin1Encoding} is substituted.

@node ASCII driver class, HTML driver class, PostScript driver class, Configuration
@section The ASCII driver class

The ASCII driver class produces output that can be displayed on a
terminal or output to printers.  All of its options are highly
configurable.  The ASCII driver has class name @samp{ascii}.

The ASCII driver is described in further detail below.

@menu
* ASCII output options::        Output file options.
* ASCII page options::          Page size, margins, more.
* ASCII font options::          Box character, bold & italics.
@end menu

@node ASCII output options, ASCII page options, ASCII driver class, ASCII driver class
@subsection ASCII output options

@table @code
@item output-file=@var{filename}

File to which output should be sent.  This can be an ordinary filename
(e.g., @code{"pspp.txt"}), a pipe filename (e.g., @code{"|lpr"}), or
stdout (@code{"-"}).  Default: @code{"pspp.list"}.

@item char-set=@var{char-set-type}

One of @samp{ascii} or @samp{latin1}.  This has no effect on output at
the present time.  Default: @code{ascii}.

@item form-feed-string=@var{form-feed-value}

The string written to the output to cause a formfeed.  See also
@code{paginate}, described below, for a related setting.  Default:
@code{"\f"}.

@item newline-string=@var{new-line-value}

The string written to the output to cause a new-line (carriage return
plus linefeed).  The default, which can be specified explicitly with
@code{newline-string=default}, is to use the system-dependent new-line
sequence by opening the output file in text mode.  This is usually the
right choice.

However, @code{newline-string} can be set to any string.  When this is
done, the output file is opened in binary mode.

@item paginate=@var{boolean}

If set, a formfeed (as set in @code{form-feed-string}, described above)
will be written to the device after every page.  Default: @code{on}.

@item tab-width=@var{tab-width-value}

The distance between tab stops for this device.  If set to 0, tabs will
not be used in the output.  Default: @code{8}.

@item init=@var{initialization-string}.

String written to the device before anything else, at the beginning of
the output.  Default: @code{""} (the empty string).

@item done=@var{finalization-string}.

String written to the device after everything else, at the end of the
output.  Default: @code{""} (the empty string).
@end table

@node ASCII page options, ASCII font options, ASCII output options, ASCII driver class
@subsection ASCII page options

These options affect page setup:

@table @code
@item headers=@var{boolean}

If enabled, two lines of header information giving title and subtitle,
page number, date and time, and PSPP version are printed at the top of
every page.  These two lines are in addition to any top margin
requested.  Default: @code{on}.

@item length=@var{line-count}

Physical length of a page, in lines.  Headers and margins are subtracted
from this value.  Default: @code{66}.

@item width=@var{character-count}

Physical width of a page, in characters.  Margins are subtracted from
this value.  Default: @code{130}.

@item lpi=@var{lines-per-inch}

Number of lines per vertical inch.  Not currently used.  Default: @code{6}.

@item cpi=@var{characters-per-inch}

Number of characters per horizontal inch.  Not currently used.  Default:
@code{10}.

@item left-margin=@var{left-margin-width}

Width of the left margin, in characters.  PSPP subtracts this value
from the page width.  Default: @code{0}.

@item right-margin=@var{right-margin-width}

Width of the right margin, in characters.  PSPP subtracts this value
from the page width.  Default: @code{0}.

@item top-margin=@var{top-margin-lines}

Length of the top margin, in lines.  PSPP subtracts this value from
the page length.  Default: @code{2}.

@item bottom-margin=@var{bottom-margin-lines}

Length of the bottom margin, in lines.  PSPP subtracts this value from
the page length.  Default: @code{2}.

@end table

@node ASCII font options,  , ASCII page options, ASCII driver class
@subsection ASCII font options

These are the ASCII font options:

@table @code
@item box[@var{line-type}]=@var{box-chars}

The characters used for lines in tables produced by the ASCII driver can
be changed using this option.  @var{line-type} is used to indicate which
type of line to change; @var{box-chars} is the character or string of
characters to use for this type of line.

@var{line-type} must be a 4-digit number in base 4.  The digits are in
the order `right', `bottom', `left', `top'.  The four possibilities for
each digit are:

@table @asis
@item 0
No line.

@item 1
Single line.

@item 2
Double line.

@item 3
Special device-defined line, if one is available; otherwise, a double
line.
@end table

Examples:

@table @code
@item box[0101]="|"

Sets @samp{|} as the character to use for a single-width line with
bottom and top components.

@item box[2222]="#"

Sets @samp{#} as the character to use for the intersection of four
double-width lines, one each from the top, bottom, left and right.

@item box[1100]="\xda"

Sets @samp{"\xda"}, which under MS-DOS is a box character suitable for
the top-left corner of a box, as the character for the intersection of
two single-width lines, one each from the right and bottom.

@end table

Defaults:

@itemize @bullet
@item
@code{box[0000]=" "}

@item
@code{box[1000]="-"}
@*@code{box[0010]="-"}
@*@code{box[1010]="-"}

@item
@code{box[0100]="|"}
@*@code{box[0001]="|"}
@*@code{box[0101]="|"}

@item
@code{box[2000]="="}
@*@code{box[0020]="="}
@*@code{box[2020]="="}

@item
@code{box[0200]="#"}
@*@code{box[0002]="#"}
@*@code{box[0202]="#"}

@item
@code{box[3000]="="}
@*@code{box[0030]="="}
@*@code{box[3030]="="}

@item
@code{box[0300]="#"}
@*@code{box[0003]="#"}
@*@code{box[0303]="#"}

@item
For all others, @samp{+} is used unless there are double lines or
special lines, in which case @samp{#} is used.
@end itemize

@item italic-on=@var{italic-on-string}

Character sequence written to turn on italics or underline printing.  If
this is set to @code{overstrike}, then the driver will simulate
underlining by overstriking with underscore characters (@samp{_}) in the
manner described by @code{overstrike-style} and
@code{carriage-return-style}.  Default: @code{overstrike}.

@item italic-off=@var{italic-off-string}

Character sequence to turn off italics or underline printing.  Default:
@code{""} (the empty string).

@item bold-on=@var{bold-on-string}

Character sequence written to turn on bold or emphasized printing.  If
set to @code{overstrike}, then the driver will simulated bold printing
by overstriking characters in the manner described by
@code{overstrike-style} and @code{carriage-return-style}.  Default:
@code{overstrike}.

@item bold-off=@var{bold-off-string}

Character sequence to turn off bold or emphasized printing.  Default:
@code{""} (the empty string).

@item bold-italic-on=@var{bold-italic-on-string}

Character sequence written to turn on bold-italic printing.  If set to
@code{overstrike}, then the driver will simulate bold-italics by
overstriking twice, once with the character, a second time with an
underscore (@samp{_}) character, in the manner described by
@code{overstrike-style} and @code{carriage-return-style}.  Default:
@code{overstrike}.

@item bold-italic-off=@var{bold-italic-off-string}

Character sequence to turn off bold-italic printing.  Default: @code{""}
(the empty string).

@item overstrike-style=@var{overstrike-option}

Either @code{single} or @code{line}:

@itemize @bullet
@item
If @code{single} is selected, then, to overstrike a line of text, the
output driver will output a character, backspace, overstrike, output a
character, backspace, overstrike, and so on along a line.

@item
If @code{line} is selected then the output driver will output an entire
line, then backspace or emit a carriage return (as indicated by
@code{carriage-return-style}), then overstrike the entire line at once.
@end itemize

@code{single} is recommended for use with ttys and programs that
understand overstriking in text files, such as the pager @code{less}.
@code{single} will also work with printer devices but results in rapid
back-and-forth motions of the printhead that can cause the printer to
physically overheat!

@code{line} is recommended for use with printer devices.  Most programs
that understand overstriking in text files will not properly deal with
@code{line} mode.  

Default: @code{single}.

@item carriage-return-style=@var{carriage-return-type}

Either @code{bs} or @code{cr}.  This option applies only when one or
more of the font commands is set to @code{overstrike} and, at the same
time, @code{overstrike-style} is set to @code{line}.

@itemize @bullet
@item
If @code{bs} is selected then the driver will return to the beginning of
a line by emitting a sequence of backspace characters (ASCII 8).

@item
If @code{cr} is selected then the driver will return to the beginning of
a line by emitting a single carriage-return character (ASCII 13).
@end itemize

Although @code{cr} is preferred as being more compact, @code{bs} is more
general since some devices do not interpret carriage returns in the
desired manner.  Default: @code{bs}.
@end table

@node HTML driver class, Miscellaneous configuring, ASCII driver class, Configuration
@section The HTML driver class

The @code{html} driver class is used to produce output for viewing in
tables-capable web browsers such as Emacs' w3-mode.  Its configuration
is very simple.  Currently, the output has a very plain format.  In the
future, further work may be done on improving the output appearance.

There are few options for use with the @code{html} driver class:

@table @code
@item output-file=@var{filename}

File to which output should be sent.  This can be an ordinary filename
(i.e., @code{"pspp.ps"}), a pipe filename (i.e., @code{"|lpr"}), or
stdout (@code{"-"}).  Default: @code{"pspp.html"}.

@item prologue-file=@var{prologue-file-name}

Sets the name of the PostScript prologue file.  You can write your own
prologue if you want to customize colors or other settings: see
@ref{HTML Prologue}.  Default: @code{html-prologue}.
@end table

@menu
* HTML Prologue::               Format of the HTML prologue file.
@end menu

@node HTML Prologue,  , HTML driver class, HTML driver class
@subsection The HTML prologue

HTML files that are generated by PSPP consist of two parts: a prologue
and a body.  The prologue is a collection of boilerplate.  Only the body
differs greatly between two outputs.  You can tune the colors and other
attributes of the output by editing the prologue.
 
The prologue is dumped into the output stream essentially unmodified.
However, two actions are performed on its lines.  First, certain lines
may be omitted as specified in the prologue file itself.  Second,
variables are substituted.

The following lines are omitted:

@enumerate
@item
All lines that contain three bangs in a row (@code{!!!}).

@item
Lines that contain @code{!title}, if no title is set for the output.  If
a title is set, then the characters @code{!title} are removed before the
line is output.

@item
Lines that contain @code{!subtitle}, if no subtitle is set for the
output.  If a subtitle is set, then the characters @code{!subtitle} are
removed before the line is output.
@end enumerate

The following are the variables that are substituted.  Only the
variables listed are substituted; environment variables are not.
@xref{Environment substitutions}.

@table @code
@item generator

PSPP version as a string: @samp{GNU PSPP 0.1b}, for example.

@item date

Date the file was created.  Example: @samp{Tue May 21 13:46:22 1991}.

@item user

Under multiuser OSes, the user's login name, taken either from the
environment variable @code{LOGNAME} or, if that fails, the result of the
C library function @code{getlogin()}.  Defaults to @samp{nobody}.

@item host

System hostname as reported by @code{gethostname()}.  Defaults to
@samp{nowhere}.

@item title

Document title as a string.  This is the title specified in the PSPP
syntax file.

@item subtitle

Document subtitle as a string.  

@item source-file

PSPP syntax file name.  Example: @samp{mary96/first.stat}.
@end table

@node Miscellaneous configuring, Improving output quality, HTML driver class, Configuration
@section Miscellaneous configuration

The following environment variables can be used to further configure
PSPP:

@table @code
@item HOME

Used to determine the user's home directory.  No default value.

@item STAT_INCLUDE_PATH

Path used to find include files in PSPP syntax files.  Defaults vary
across operating systems:

@table @asis
@item UNIX

@itemize @bullet
@item
@file{.}

@item
@file{~/.pspp/include}

@item
@file{/usr/local/lib/pspp/include}

@item
@file{/usr/lib/pspp/include}

@item
@file{/usr/local/share/pspp/include}

@item
@file{/usr/share/pspp/include}
@end itemize

@item MS-DOS

@itemize @bullet
@item
@file{.}

@item
@file{C:\PSPP\INCLUDE}

@item
@file{$PATH}
@end itemize

@item Other OSes
No default path.
@end table

@item STAT_PAGER
@itemx PAGER

When PSPP invokes an external pager, it uses the first of these that
is defined.  There is a default pager only if the person who compiled
PSPP defined one.

@item TERM

The terminal type @code{termcap} or @code{ncurses} will use, if such
support was compiled into PSPP.

@item STAT_OUTPUT_INIT_FILE

The basename used to search for the driver definition file.
@xref{Output devices}.  @xref{File locations}.  Default: @code{devices}.

@item STAT_OUTPUT_PAPERSIZE_FILE

The basename used to search for the papersize file.  @xref{papersize}.
@xref{File locations}.  Default: @code{papersize}.

@item STAT_OUTPUT_INIT_PATH

The path used to search for the driver definition file and the papersize
file.  @xref{File locations}.  Default: the standard configuration path.

@item TMPDIR

The @code{sort} procedure stores its temporary files in this directory.
Default: (UNIX) @file{/tmp}, (MS-DOS) @file{\}, (other OSes) empty string.

@item TEMP
@item TMP

Under MS-DOS only, these variables are consulted after TMPDIR, in this
order.
@end table

@node Improving output quality,  , Miscellaneous configuring, Configuration
@section Improving output quality

When its drivers are set up properly, PSPP can produce output that
looks very good indeed.  The PostScript driver, suitably configured, can
produce presentation-quality output.  Here are a few guidelines for
producing better-looking output, regardless of output driver.  Your
mileage may vary, of course, and everyone has different esthetic
preferences.

@itemize @bullet
@item
Width is important in PSPP output.  Greater output width leads to more
readable output, to a point.  Try the following to increase the output
width:

@itemize @minus
@item
If you're using the ASCII driver with a dot-matrix printer, figure out
what you need to do to put the printer into compressed mode.  Put that
string into the @code{init-string} setting.  Try to get 132 columns; 160
might be better, but you might find that print that tiny is difficult to
read.

@item
With the PostScript driver, try these ideas:

@itemize +
@item
Landscape mode.

@item
Legal-size (8.5" x 14") paper in landscape mode.

@item
Reducing font sizes.  If you're using 12-point fonts, try 10 point; if
you're using 10-point fonts, try 8 point.  Some fonts are more readable
than others at small sizes.
@end itemize
@end itemize

Try to strike a balance between character size and page width.

@item
Use high-quality fonts.  Many public domain fonts are poor in quality.
Recently, URW made some high-quality fonts available under the GPL.
These are probably suitable.

@item
Be sure you're using the proper font metrics.  The font metrics provided
with PSPP may not correspond to the fonts actually being printed.
This can cause bizarre-looking output.

@item
Make sure that you're using good ink/ribbon/toner.  Darker print is
easier to read.

@item
Use plain fonts with serifs, such as Times-Roman or Palatino.  Avoid
choosing italic or bold fonts as document base fonts.
@end itemize

@node Invocation, Language, Configuration, Top
@chapter Invoking PSPP
@cindex invocation
@cindex PSPP, invoking

@cindex command line, options
@cindex options, command-line
@example
pspp [ -B @var{dir} | --config-dir=@var{dir} ] [ -o @var{device} | --device=@var{device} ]
       [ -d @var{var}[=@var{value}] | --define=@var{var}[=@var{value}] ] [-u @var{var} | --undef=@var{var} ]
       [ -f @var{file} | --out-file=@var{file} ] [ -p | --pipe ] [ -I- | --no-include ]
       [ -I @var{dir} | --include=@var{dir} ] [ -i | --interactive ] 
       [ -n | --edit | --dry-run | --just-print | --recon ] 
       [ -r | --no-statrc ] [ -h | --help ] [ -l | --list ] 
       [ -c @var{command} | --command @var{command} ] [ -s | --safer ]
       [ --testing-mode ] [ -V | --version ] [ -v | --verbose ] 
       [ @var{key}=@var{value} ] @var{file}@enddots{}
@end example

@menu
* Non-option Arguments::        Specifying syntax files and output devices.
* Configuration Options::       Change the configuration for the current run.
* Input and output options::    Controlling input and output files.
* Language control options::    Language variants.
* Informational options::       Helpful information about PSPP.
@end menu

@node Non-option Arguments, Configuration Options, Invocation, Invocation
@section Non-option Arguments

Syntax files and output device substitutions can be specified on
PSPP's command line:

@table @code
@item @var{file}

A file by itself on the command line will be executed as a syntax file.
PSPP terminates after the syntax file runs, unless the @code{-i} or
@code{--interactive} option is given (@pxref{Language control options}).

@item @var{file1} @var{file2}

When two or more filenames are given on the command line, the first
syntax file is executed, then PSPP's dictionary is cleared, then the second
syntax file is executed.

@item @var{file1} + @var{file2}

If syntax files' names are delimited by a plus sign (@samp{+}), then the
dictionary is not cleared between their executions, as if they were
concatenated together into a single file.

@item @var{key}=@var{value}

Defines an output device macro @var{key} to expand to @var{value},
overriding any macro having the same @var{key} defined in the device
configuration file.  @xref{Macro definitions}.

@end table

There is one other way to specify a syntax file, if your operating
system supports it.  If you have a syntax file @file{foobar.stat}, put
the notation

@example
#! /usr/local/bin/pspp
@end example

at the top, and mark the file as executable with @code{chmod +x
foobar.stat}.  (If PSPP is not installed in @file{/usr/local/bin},
then insert its actual installation directory into the syntax file
instead.)  Now you should be able to invoke the syntax file just by
typing its name.  You can include any options on the command line as
usual.  PSPP entirely ignores any lines beginning with @samp{#!}.

@node Configuration Options, Input and output options, Non-option Arguments, Invocation
@section Configuration Options

Configuration options are used to change PSPP's configuration for the
current run.  The configuration options are:

@table @code
@item -a @{compatible|enhanced@}
@itemx --algorithm=@{compatible|enhanced@}

If you chose @code{compatible}, then PSPP will use the same  algorithms 
as used by some proprietary statistical analysis packages.
This is not recommended, as  these algorithms are inferior and in some cases 
compeletely broken.
The default setting is @code{enhanced}.
Certain commands have subcommands which allow you to override this setting on 
a per command basis.

@item -B @var{dir}
@itemx --config-dir=@var{dir}

Sets the configuration directory to @var{dir}.  @xref{File locations}.

@item -o @var{device}
@itemx --device=@var{device}

Selects the output device with name @var{device}.  If this option is
given more than once, then all devices mentioned are selected.  This
option disables all devices besides those mentioned on the command line.

@item -d @var{var}[=@var{value}]
@itemx --define=@var{var}[=@var{value}]

Defines an `environment variable' named @var{var} having the optional
value @var{value} specified.  @xref{Variable values}.

@item -u @var{var}
@itemx --undef=@var{var}

Undefines the `environment variable' named @var{var}.  @xref{Variable
values}.
@end table

@node Input and output options, Language control options, Configuration Options, Invocation
@section Input and output options

Input and output options affect how PSPP reads input and writes
output.  These are the input and output options:

@table @code
@item -f @var{file}
@itemx --out-file=@var{file}

This overrides the output file name for devices designated as listing
devices.  If a file named @var{file} already exists, it is overwritten.

@item -p
@itemx --pipe

Allows PSPP to be used as a filter by causing the syntax file to be
read from stdin and output to be written to stdout.  Conflicts with the
@code{-f @var{file}} and @code{--file=@var{file}} options.

@item -I-
@itemx --no-include

Clears all directories from the include path.  This includes all
directories put in the include path by default.  @xref{Miscellaneous
configuring}.

@item -I @var{dir}
@itemx --include=@var{dir}

Appends directory @var{dir} to the path that is searched for include
files in PSPP syntax files.

@item -c @var{command}
@itemx --command=@var{command}

Execute literal command @var{command}.  The command is executed before
startup syntax files, if any.

@item --testing-mode

Invoke heuristics to assist with testing PSPP.  For use by @code{make
check} and similar scripts.
@end table

@node Language control options, Informational options, Input and output options, Invocation
@section Language control options

Language control options control how PSPP syntax files are parsed and
interpreted.  The available language control options are:

@table @code
@item -i
@itemx --interactive

When a syntax file is specified on the command line, PSPP normally
terminates after processing it.  Giving this option will cause PSPP to
bring up a command prompt after processing the syntax file.

In addition, this forces syntax files to be interpreted in interactive
mode, rather than the default batch mode.  @xref{Tokenizing lines}, for
information on the differences between batch mode and interactive mode
command interpretation.

@item -n
@itemx --edit
@itemx --dry-run
@itemx --just-print
@itemx --recon

Only the syntax of any syntax file specified or of commands entered at
the command line is checked.  Transformations are not performed and
procedures are not executed.  Not yet implemented.

@item -r
@itemx --no-statrc

Prevents the execution of the PSPP startup syntax file.  Not yet
implemented, as startup syntax files aren't, either.

@item -s
@itemx --safer

Disables certain unsafe operations.  This includes the ERASE and
HOST commands, as well as use of pipes as input and output files.
@end table

@node Informational options,  , Language control options, Invocation
@section Informational options

Informational options cause information about PSPP to be written to
the terminal.  Here are the available options:

@table @code
@item -h
@item --help

Prints a message describing PSPP command-line syntax and the available
device driver classes, then terminates.

@item -l
@item --list

Lists the available device driver classes, then terminates.

@item -x @{compatible|enhanced@}
@itemx --syntax=@{compatible|enhanced@}

If you chose @code{compatible}, then PSPP will only accept command syntax that 
is compatible with the proprietary program SPSS.
If you choose @code{enhanced} then additional syntax will be available.
The default is @code{enhanced}.


@item -V
@item --version

Prints a brief message listing PSPP's version, warranties you don't
have, copying conditions and copyright, and e-mail address for bug
reports, then terminates.

@item -v
@item --verbose

Increments PSPP's verbosity level.  Higher verbosity levels cause
PSPP to display greater amounts of information about what it is
doing.  Often useful for debugging PSPP's configuration.  

This option can be given multiple times to set the verbosity level to
that value.  The default verbosity level is 0, in which no informational
messages will be displayed.

Higher verbosity levels cause messages to be displayed when the
corresponding events take place.

@table @asis
@item 1

Driver and subsystem initializations.

@item 2

Completion of driver initializations.  Beginning of driver closings.

@item 3

Completion of driver closings.

@item 4

Files searched for; success of searches.

@item 5

Individual directories included in file searches.
@end table

Each verbosity level also includes messages from lower verbosity levels.

@end table

@node Language, Expressions, Invocation, Top
@chapter The PSPP language
@cindex language, PSPP
@cindex PSPP, language

@quotation
@strong{Please note:} PSPP is not even close to completion.
Only a few actual statistical procedures are implemented.  PSPP
is a work in progress.
@end quotation

This chapter discusses elements common to many PSPP commands.
Later chapters will describe individual commands in detail.

@menu
* Tokens::                      Characters combine to form tokens.
* Commands::                    Tokens combine to form commands.
* Types of Commands::           Commands come in several flavors.
* Order of Commands::           Commands combine to form syntax files.
* Missing Observations::        Handling missing observations.
* Variables::                   The unit of data storage.
* Files::                       Files used by PSPP.
* BNF::                         How command syntax is described.
@end menu

@node Tokens, Commands, Language, Language
@section Tokens
@cindex language, lexical analysis
@cindex language, tokens
@cindex tokens
@cindex lexical analysis
@cindex lexemes

PSPP divides most syntax file lines into series of short chunks
called @dfn{tokens}, @dfn{lexical elements}, or @dfn{lexemes}.  These
tokens are then grouped to form commands, each of which tells
PSPP to take some action---read in data, write out data, perform
a statistical procedure, etc.  The process of dividing input into tokens
is @dfn{tokenization}, or @dfn{lexical analysis}.  Each type of token is
described below.

@cindex delimiters
@cindex whitespace
Tokens must be separated from each other by @dfn{delimiters}.
Delimiters include whitespace (spaces, tabs, carriage returns, line
feeds, vertical tabs), punctuation (commas, forward slashes, etc.), and
operators (plus, minus, times, divide, etc.)  Note that while whitespace
only separates tokens, other delimiters are tokens in themselves.

@table @strong
@cindex identifiers
@item Identifiers
Identifiers are names that specify variable names, commands, or command
details.

@itemize @bullet
@item
The first character in an identifier must be a letter, @samp{#}, or
@samp{@@}.  Some system identifiers begin with @samp{$}, but
user-defined variables' names may not begin with @samp{$}.

@item
The remaining characters in the identifier must be letters, digits, or
one of the following special characters: 

@example
.  _  $  #  @@
@end example

@item
@cindex variable names
@cindex names, variable
Variable names may be any length, but only the first 8 characters are
significant.

@item
@cindex case-sensitivity
Identifiers are not case-sensitive: @code{foobar}, @code{Foobar},
@code{FooBar}, @code{FOOBAR}, and @code{FoObaR} are different
representations of the same identifier.

@item
@cindex keywords
Identifiers other than variable names may be abbreviated to their first
3 characters if this abbreviation is unambiguous.  These identifiers are
often called @dfn{keywords}.  (Unique abbreviations of 3 or more
characters are also accepted: @samp{FRE}, @samp{FREQ}, and
@samp{FREQUENCIES} are equivalent when the last is a keyword.)

@item
Whether an identifier is a keyword depends on the context.

@item
@cindex keywords, reserved
@cindex reserved keywords
Some keywords are reserved.  These keywords may not be used in any
context besides those explicitly described in this manual.  The reserved
keywords are:

@example
ALL  AND  BY  EQ  GE  GT  LE  LT  NE  NOT  OR  TO  WITH
@end example

@item 
Since keywords are identifiers, all the rules for identifiers apply.
Specifically, they must be delimited as are other identifiers:
@code{WITH} is a reserved keyword, but @code{WITHOUT} is a valid
variable name.
@end itemize

@cindex @samp{.}
@cindex period
@cindex variable names, ending with period
@strong{Caution:} It is legal to end a variable name with a period, but
@emph{don't do it!}  The variable name will be misinterpreted when it is
the final token on a line: @code{FOO.} will be divided into two separate
tokens, @samp{FOO} and @samp{.}, the @dfn{terminal dot}.
@xref{Commands, , Forming commands of tokens}.

@item Numbers
@cindex numbers
@cindex integers
@cindex reals
Numbers may be specified as integers or reals.  Integers are internally
converted into reals.  Scientific notation is not supported.  Here are
some examples of valid numbers:

@example
1234  3.14159265359  .707106781185  8945.
@end example

@strong{Caution:} The last example will be interpreted as two tokens,
@samp{8945} and @samp{.}, if it is the last token on a line.

@item Strings
@cindex strings
@cindex @samp{'}
@cindex @samp{"}
@cindex case-sensitivity
Strings are literal sequences of characters enclosed in pairs of single
quotes (@samp{'}) or double quotes (@samp{"}).

@itemize @bullet
@item
Whitespace and case of letters @emph{are} significant inside strings.
@item
Whitespace characters inside a string are not delimiters.
@item
To include single-quote characters in a string, enclose the string in
double quotes.
@item
To include double-quote characters in a string, enclose the string in
single quotes.
@item
It is not possible to put both single- and double-quote characters
inside one string.
@end itemize

@item Hexstrings
@cindex hexstrings
Hexstrings are string variants that use hex digits to specify
characters.

@itemize @bullet
@item
A hexstring may be used anywhere that an ordinary string is allowed.

@item
@cindex @samp{X'}
@cindex @samp{'}
A hexstring begins with @samp{X'} or @samp{x'}, and ends with @samp{'}.

@cindex whitespace
@item
No whitespace is allowed between the initial @samp{X} and @samp{'}.

@item
Double quotes @samp{"} may be used in place of single quotes @samp{'} if
done in both places.

@item
Each pair of hex digits is internally changed into a single character
with the given value.

@item
If there is an odd number of hex digits, the missing last digit is
assumed to be @samp{0}.

@item
@cindex portability
@strong{Please note:} Use of hexstrings is nonportable because the same
numeric values are associated with different glyphs by different
operating systems.  Therefore, their use should be confined to syntax
files that will not be widely distributed.

@item
@cindex characters, reserved
@cindex 0
@cindex whitespace
@strong{Please note also:} The character with value 00 is reserved for
internal use by PSPP.  Its use in strings causes an error and
replacement with a blank space (in ASCII, hex 20, decimal 32).
@end itemize

@item Punctuation
@cindex punctuation
Punctuation separates tokens; punctuators are delimiters.  These are the
punctuation characters:

@example
,  /  =  (  )
@end example

@item Operators
@cindex operators
Operators describe mathematical operations.  Some operators are delimiters:

@example
(  )  +  -  *  /  **
@end example

Many of the above operators are also punctuators.  Punctuators are
distinguished from operators by context. 

The other operators are all reserved keywords.  None of these are
delimiters:

@example
AND  EQ  GE  GT  LE  LT  NE  OR
@end example

@item Terminal Dot
@cindex terminal dot
@cindex dot, terminal
@cindex period
@cindex @samp{.}
A period (@samp{.}) at the end of a line (except for whitespace) is one
type of a @dfn{terminal dot}, although not every terminal dot is a
period at the end of a line.  @xref{Commands, , Forming commands of
tokens}.  A period is a terminal dot @emph{only}
when it is at the end of a line; otherwise it is part of a
floating-point number.  (A period outside a number in the middle of a
line is an error.)

@quotation
@cindex terminal dot, changing
@cindex dot, terminal, changing
@strong{Please note:} The character used for the @dfn{terminal dot}
can be changed with @cmd{SET}'s ENDCMD subcommand (@pxref{SET}).  This
is strongly discouraged, and throughout all the remainder of this
manual it will be assumed that the default setting is in effect.
@end quotation

@end table

@node Commands, Types of Commands, Tokens, Language
@section Forming commands of tokens

@cindex PSPP, command structure
@cindex language, command structure
@cindex commands, structure

Most PSPP commands share a common structure, diagrammed below:

@example
@var{cmd}@dots{} [@var{sbc}[=][@var{spec} [[,]@var{spec}]@dots{}]] [[/[=][@var{spec} [[,]@var{spec}]@dots{}]]@dots{}].
@end example

@cindex @samp{[  ]}
In the above, rather daunting, expression, pairs of square brackets
(@samp{[ ]}) indicate optional elements, and names such as @var{cmd}
indicate parts of the syntax that vary from command to command.
Ellipses (@samp{...}) indicate that the preceding part may be repeated
an arbitrary number of times.  Let's pick apart what it says above:

@itemize @bullet
@cindex commands, names
@item
A command begins with a command name of one or more keywords, such as
@cmd{FREQUENCIES}, @cmd{DATA LIST}, or @cmd{N OF CASES}.  @var{cmd}
may be abbreviated to its first word if that is unambiguous; each word
in @var{cmd} may be abbreviated to a unique prefix of three or more
characters as described above.

@cindex subcommands
@item
The command name may be followed by one or more @dfn{subcommands}:

@itemize @minus
@item
Each subcommand begins with a unique keyword, indicated by @var{sbc}
above.  This is analogous to the command name.

@item
The subcommand name is optionally followed by an equals sign (@samp{=}).

@item
Some subcommands accept a series of one or more specifications
(@var{spec}), optionally separated by commas.

@item
Each subcommand must be separated from the next (if any) by a forward
slash (@samp{/}).
@end itemize

@cindex dot, terminal
@cindex terminal dot
@item
Each command must be terminated with a @dfn{terminal dot}.  
The terminal dot may be given one of three ways:

@itemize @minus
@item
(most commonly) A period character at the very end of a line, as
described above.

@item
(only if NULLINE is on: @xref{SET, , Setting user preferences}, for more
details.)  A completely blank line.

@item
(in batch mode only) Any line that is not indented from the left side of
the page causes a terminal dot to be inserted before that line.
Therefore, each command begins with a line that is flush left, followed
by zero or more lines that are indented one or more characters from the
left margin.

In batch mode, PSPP will ignore a plus sign, minus sign, or period
(@samp{+}, @samp{@minus{}}, or @samp{.}) as the first character in a
line.  Any of these characters as the first character on a line will
begin a new command.  This allows for visual indentation of a command
without that command being considered part of the previous command.

PSPP is in batch mode when it is reading input from a file, rather
than from an interactive user.  Note that the other forms of the
terminal dot may also be used in batch mode.

Sometimes, one encounters syntax files that are intended to be
interpreted in interactive mode rather than batch mode (for instance,
this can happen if a session log file is used directly as a syntax
file).  When this occurs, use the @samp{-i} command line option to force
interpretation in interactive mode (@pxref{Language control options}).
@end itemize
@end itemize

PSPP ignores empty commands when they are generated by the above
rules.  Note that, as a consequence of these rules, each command must
begin on a new line.

@node Types of Commands, Order of Commands, Commands, Language
@section Types of Commands

Commands in PSPP are divided roughly into six categories:

@table @strong
@item Utility commands
@cindex utility commands
Set or display various global options that affect PSPP operations.
May appear anywhere in a syntax file.  @xref{Utilities, , Utility
commands}.

@item File definition commands
@cindex file definition commands
Give instructions for reading data from text files or from special
binary ``system files''.  Most of these commands discard any previous
data or variables to replace it with the new data and
variables.  At least one must appear before the first command in any of
the categories below.  @xref{Data Input and Output}.

@item Input program commands
@cindex input program commands
Though rarely used, these provide powerful tools for reading data files
in arbitrary textual or binary formats.  @xref{INPUT PROGRAM}.

@item Transformations
@cindex transformations
Perform operations on data and write data to output files.  Transformations
are not carried out until a procedure is executed.  

@item Restricted transformations
@cindex restricted transformations
Same as transformations for most purposes.  @xref{Order of Commands}, for a
detailed description of the differences.

@item Procedures
@cindex procedures
Analyze data, writing results of analyses to the listing file.  Cause
transformations specified earlier in the file to be performed.  In a
more general sense, a @dfn{procedure} is any command that causes the
active file (the data) to be read.
@end table

@node Order of Commands, Missing Observations, Types of Commands, Language
@section Order of Commands
@cindex commands, ordering
@cindex order of commands

PSPP does not place many restrictions on ordering of commands.
The main restriction is that variables must be defined with one of the
file-definition commands before they are otherwise referred to.

Of course, there are specific rules, for those who are interested.
PSPP possesses five internal states, called initial, INPUT PROGRAM,
FILE TYPE, transformation, and procedure states.  (Please note the
distinction between the @cmd{INPUT PROGRAM} and @cmd{FILE TYPE}
@emph{commands} and the INPUT PROGRAM and FILE TYPE @emph{states}.)

PSPP starts up in the initial state.  Each successful completion
of a command may cause a state transition.  Each type of command has its
own rules for state transitions:

@table @strong
@item Utility commands
@itemize @bullet
@item
Legal in all states.
@item
Do not cause state transitions.  Exception: when @cmd{N OF CASES}
is executed in the procedure state, it causes a transition to the
transformation state.
@end itemize

@item @cmd{DATA LIST}
@itemize @bullet
@item
Legal in all states.
@item
When executed in the initial or procedure state, causes a transition to
the transformation state.  
@item
Clears the active file if executed in the procedure or transformation
state.
@end itemize

@item @cmd{INPUT PROGRAM}
@itemize @bullet
@item
Invalid in INPUT PROGRAM and FILE TYPE states.
@item
Causes a transition to the INPUT PROGRAM state.  
@item
Clears the active file.
@end itemize

@item @cmd{FILE TYPE}
@itemize @bullet
@item
Invalid in INPUT PROGRAM and FILE TYPE states.
@item
Causes a transition to the FILE TYPE state.
@item
Clears the active file.
@end itemize

@item Other file definition commands
@itemize @bullet
@item
Invalid in INPUT PROGRAM and FILE TYPE states.
@item
Cause a transition to the transformation state.
@item
Clear the active file, except for @cmd{ADD FILES}, @cmd{MATCH FILES},
and @cmd{UPDATE}.
@end itemize

@item Transformations
@itemize @bullet
@item
Invalid in initial and FILE TYPE states.
@item
Cause a transition to the transformation state.
@end itemize

@item Restricted transformations
@itemize @bullet
@item
Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
@item
Cause a transition to the transformation state.
@end itemize

@item Procedures
@itemize @bullet
@item
Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
@item
Cause a transition to the procedure state.
@end itemize
@end table

@node Missing Observations, Variables, Order of Commands, Language
@section Handling missing observations
@cindex missing values
@cindex values, missing

PSPP includes special support for unknown numeric data values.
Missing observations are assigned a special value, called the
@dfn{system-missing value}.  This ``value'' actually indicates the
absence of value; it means that the actual value is unknown.  Procedures
automatically exclude from analyses those observations or cases that
have missing values.  Whether single observations or entire cases are
excluded depends on the procedure.

The system-missing value exists only for numeric variables.  String
variables always have a defined value, even if it is only a string of
spaces.

Variables, whether numeric or string, can have designated
@dfn{user-missing values}.  Every user-missing value is an actual value
for that variable.  However, most of the time user-missing values are
treated in the same way as the system-missing value.  String variables
that are wider than a certain width, usually 8 characters (depending on
computer architecture), cannot have user-missing values.

For more information on missing values, see the following sections:
@ref{Variables}, @ref{MISSING VALUES}, @ref{Expressions}.  See also the
documentation on individual procedures for information on how they
handle missing values.

@node Variables, Files, Missing Observations, Language
@section Variables
@cindex variables
@cindex dictionary

Variables are the basic unit of data storage in PSPP.  All the
variables in a file taken together, apart from any associated data, are
said to form a @dfn{dictionary}.  
Some details of variables are described in the sections below.

@menu
* Attributes::                  Attributes of variables.
* System Variables::            Variables automatically defined by PSPP.
* Sets of Variables::           Lists of variable names.
* Input/Output Formats::        Input and output formats.
* Scratch Variables::           Variables deleted by procedures.
@end menu

@node Attributes, System Variables, Variables, Variables
@subsection Attributes of Variables
@cindex variables, attributes of
@cindex attributes of variables
Each variable has a number of attributes, including:

@table @strong
@item Name
This is an identifier.  Each variable must have a different name.
@xref{Tokens}.

@cindex variables, type
@cindex type of variables
@item Type
Numeric or string.

@cindex variables, width
@cindex width of variables
@item Width
(string variables only) String variables with a width of 8 characters or
fewer are called @dfn{short string variables}.  Short string variables
can be used in many procedures where @dfn{long string variables} (those
with widths greater than 8) are not allowed.

@quotation
@strong{Please note:} Certain systems may consider strings longer than 8
characters to be short strings.  Eight characters represents a minimum
figure for the maximum length of a short string.
@end quotation

@item Position
Variables in the dictionary are arranged in a specific order.
@cmd{DISPLAY} can be used to show this order: see @ref{DISPLAY}.

@item Initialization
Either reinitialized to 0 or spaces for each case, or left at its
existing value.  @xref{LEAVE}.

@cindex missing values
@cindex values, missing
@item Missing values
Optionally, up to three values, or a range of values, or a specific
value plus a range, can be specified as @dfn{user-missing values}.
There is also a @dfn{system-missing value} that is assigned to an
observation when there is no other obvious value for that observation.
Observations with missing values are automatically excluded from
analyses.  User-missing values are actual data values, while the
system-missing value is not a value at all.  @xref{Missing Observations}.

@cindex variable labels
@cindex labels, variable
@item Variable label
A string that describes the variable.  @xref{VARIABLE LABELS}.

@cindex value labels
@cindex labels, value
@item Value label
Optionally, these associate each possible value of the variable with a
string.  @xref{VALUE LABELS}.

@cindex print format
@item Print format
Display width, format, and (for numeric variables) number of decimal
places.  This attribute does not affect how data are stored, just how
they are displayed.  Example: a width of 8, with 2 decimal places.
@xref{PRINT FORMATS}.

@cindex write format
@item Write format
Similar to print format, but used by certain commands that are
designed to write to binary files.  @xref{WRITE FORMATS}.
@end table

@node System Variables, Sets of Variables, Attributes, Variables
@subsection Variables Automatically Defined by PSPP
@cindex system variables
@cindex variables, system

There are seven system variables.  These are not like ordinary
variables, as they are not stored in each case.  They can only be used
in expressions.  These system variables, whose values and output formats
cannot be modified, are described below.

@table @code
@cindex @code{$CASENUM}
@item $CASENUM
Case number of the case at the moment.  This changes as cases are
shuffled around.

@cindex @code{$DATE}
@item $DATE
Date the PSPP process was started, in format A9, following the
pattern @code{DD MMM YY}.

@cindex @code{$JDATE}
@item $JDATE
Number of days between 15 Oct 1582 and the time the PSPP process
was started.

@cindex @code{$LENGTH}
@item $LENGTH
Page length, in lines, in format F11.

@cindex @code{$SYSMIS}
@item $SYSMIS
System missing value, in format F1.

@cindex @code{$TIME}
@item $TIME
Number of seconds between midnight 14 Oct 1582 and the time the active file
was read, in format F20.

@cindex @code{$WIDTH}
@item $WIDTH
Page width, in characters, in format F3.
@end table

@node Sets of Variables, Input/Output Formats, System Variables, Variables
@subsection Lists of variable names
@cindex TO convention
@cindex convention, TO

There are several ways to specify a set of variables:

@enumerate
@item
(Most commonly.)  List the variable names one after another, optionally
separating them by commas.

@cindex @code{TO}
@item
(This method cannot be used on commands that define the dictionary, such
as @cmd{DATA LIST}.)  The syntax is the names of two existing variables,
separated by the reserved keyword @code{TO}.  The meaning is to include
every variable in the dictionary between and including the variables
specified.  For instance, if the dictionary contains six variables with
the names @code{ID}, @code{X1}, @code{X2}, @code{GOAL}, @code{MET}, and
@code{NEXTGOAL}, in that order, then @code{X2 TO MET} would include
variables @code{X2}, @code{GOAL}, and @code{MET}.

@item
(This method can be used only on commands that define the dictionary,
such as @cmd{DATA LIST}.)  It is used to define sequences of variables
that end in consecutive integers.  The syntax is two identifiers that
end in numbers.  This method is best illustrated with examples:

@itemize @bullet
@item
The syntax @code{X1 TO X5} defines 5 variables:

@itemize @minus
@item
X1
@item
X2
@item
X3
@item
X4
@item
X5
@end itemize

@item
The syntax @code{ITEM0008 TO ITEM0013} defines 6 variables:

@itemize @minus
@item
ITEM0008
@item
ITEM0009
@item
ITEM0010
@item
ITEM0011
@item
ITEM0012
@item
ITEM0013
@end itemize

@item
Each of the syntaxes @code{QUES001 TO QUES9} and @code{QUES6 TO QUES3}
are invalid, although for different reasons, which should be evident.
@end itemize

Note that after a set of variables has been defined with @cmd{DATA LIST}
or another command with this method, the same set can be referenced on
later commands using the same syntax.

@item
The above methods can be combined, either one after another or delimited
by commas.  For instance, the combined syntax @code{A Q5 TO Q8 X TO Z}
is legal as long as each part @code{A}, @code{Q5 TO Q8}, @code{X TO Z}
is individually legal.
@end enumerate

@node Input/Output Formats, Scratch Variables, Sets of Variables, Variables
@subsection Input and Output Formats

Data that PSPP inputs and outputs must have one of a number of formats.
These formats are described, in general, by a format specification of
the form @code{NAMEw.d}, where @var{name} is the
format name and @var{w} is a field width.  @var{d} is the optional
desired number of decimal places, if appropriate.  If @var{d} is not
included then it is assumed to be 0.  Some formats do not allow @var{d}
to be specified.

When an input format is specified on @cmd{DATA LIST} or another
command, then
it is converted to an output format for the purposes of @cmd{PRINT}
and other
data output commands.  For most purposes, input and output formats are
the same; the salient differences are described below.

Below are listed the input and output formats supported by PSPP.  If an
input format is mapped to a different output format by default, then
that mapping is indicated with @result{}.  Each format has the listed
bounds on input width (iw) and output width (ow).

The standard numeric input and output formats are given in the following
table:

@table @asis
@item Fw.d: 1 <= iw,ow <= 40
Standard decimal format with @var{d} decimal places.  If the number is
too large to fit within the field width, it is expressed in scientific
notation (@code{1.2+34}) if w >= 6, with always at least two digits in
the exponent.  When used as an input format, scientific notation is
allowed but an E or an F must be used to introduce the exponent.

The default output format is the same as the input format, except if
@var{d} > 1.  In that case the output @var{w} is always made to be at
least 2 + @var{d}.

@item Ew.d: 1 <= iw <= 40; 6 <= ow <= 40
For input this is equivalent to F format except that no E or F is
require to introduce the exponent.  For output, produces scientific
notation in the form @code{1.2+34}.  There are always at least two
digits given in the exponent.

The default output @var{w} is the largest of the input @var{w}, the
input @var{d} + 7, and 10.  The default output @var{d} is the input
@var{d}, but at least 3.

@item COMMAw.d: 1 <= iw,ow <= 40
Equivalent to F format, except that groups of three digits are
comma-separated on output.  If the number is too large to express in the
field width, then first commas are eliminated, then if there is still
not enough space the number is expressed in scientific notation given
that w >= 6.  Commas are allowed and ignored when this is used as an
input format.  

@item DOTw.d: 1 <= iw,ow <= 40
Equivalent to COMMA format except that the roles of comma and decimal
point are interchanged.  However: If SET /DECIMAL=DOT is in effect, then
COMMA uses @samp{,} for a decimal point and DOT uses @samp{.} for a
decimal point.

@item DOLLARw.d: 1 <= iw <= 40; 2 <= ow <= 40
Equivalent to COMMA format, except that the number is prefixed by a
dollar sign (@samp{$}) if there is room.  On input the value is allowed
to be prefixed by a dollar sign, which is ignored.

The default output @var{w} is the input @var{w}, but at least 2.

@item PCTw.d: 2 <= iw,ow <= 40
Equivalent to F format, except that the number is suffixed by a percent
sign (@samp{%}) if there is room.  On input the value is allowed to be
suffixed by a percent sign, which is ignored.

The default output @var{w} is the input @var{w}, but at least 2.

@item Nw.d: 1 <= iw,ow <= 40
Only digits are allowed within the field width.  The decimal point is
assumed to be @var{d} digits from the right margin.

The default output format is F with the same @var{w} and @var{d}, except
if @var{d} > 1.  In that case the output @var{w} is always made to be at
least 2 + @var{d}.

@item Zw.d @result{} F: 1 <= iw,ow <= 40
Zoned decimal input.  If you need to use this then you know how.

@item IBw.d @result{} F: 1 <= iw,ow <= 8
Integer binary format.  The field is interpreted as a fixed-point
positive or negative binary number in two's-complement notation.  The
location of the decimal point is implied.  Endianness is the same as the
host machine.

The default output format is F8.2 if @var{d} is 0.  Otherwise it is F,
with output @var{w} as 9 + input @var{d} and output @var{d} as input
@var{d}.

@item PIB @result{} F: 1 <= iw,ow <= 8
Positive integer binary format.  The field is interpreted as a
fixed-point positive binary number.  The location of the decimal point
is implied.  Endianness is teh same as the host machine.

The default output format follows the rules for IB format.

@item Pw.d @result{} F: 1 <= iw,ow <= 16
Binary coded decimal format.  Each byte from left to right, except the
rightmost, represents two digits.  The upper nibble of each byte is more
significant.  The upper nibble of the final byte is the least
significant digit.  The lower nibble of the final byte is the sign; a
value of D represents a negative sign and all other values are
considered positive.  The decimal point is implied.

The default output format follows the rules for IB format.

@item PKw.d @result{} F: 1 <= iw,ow <= 16
Positive binary code decimal format.  Same as P but the last byte is the
same as the others.

The default output format follows the rules for IB format.

@item RBw @result{} F: 2 <= iw,ow <= 8

Binary C architecture-dependent ``double'' format.  For a standard
IEEE754 implementation @var{w} should be 8.

The default output format follows the rules for IB format.

@item PIBHEXw.d @result{} F: 2 <= iw,ow <= 16
PIB format encoded as textual hex digit pairs.  @var{w} must be even.

The input width is mapped to a default output width as follows:
2@result{}4, 4@result{}6, 6@result{}9, 8@result{}11, 10@result{}14,
12@result{}16, 14@result{}18, 16@result{}21.  No allowances are made for
decimal places.

@item RBHEXw @result{} F: 4 <= iw,ow <= 16

RB format encoded as textual hex digits pairs.  @var{w} must be even.

The default output format is F8.2.

@item CCAw.d: 1 <= ow <= 40
@itemx CCBw.d: 1 <= ow <= 40
@itemx CCCw.d: 1 <= ow <= 40
@itemx CCDw.d: 1 <= ow <= 40
@itemx CCEw.d: 1 <= ow <= 40

User-defined custom currency formats.  May not be used as an input
format.  @xref{SET}, for more details.
@end table

The date and time numeric input and output formats accept a number of
possible formats.  Before describing the formats themselves, some
definitions of the elements that make up their formats will be helpful:

@table @dfn
@item leader
All formats accept an optional whitespace leader.

@item day
An integer between 1 and 31 representing the day of month.

@item day-count
An integer representing a number of days.

@item date-delimiter
One or more characters of whitespace or the following characters:
@code{- / . ,}

@item month
A month name in one of the following forms:
@itemize @bullet
@item
An integer between 1 and 12.
@item
Roman numerals representing an integer between 1 and 12.
@item
At least the first three characters of an English month name (January,
February, @dots{}).
@end itemize

@item year
An integer year number between 1582 and 19999, or between 1 and 199.
Years between 1 and 199 will have 1900 added.

@item julian
A single number with a year number in the first 2, 3, or 4 digits (as
above) and the day number within the year in the last 3 digits.

@item quarter
An integer between 1 and 4 representing a quarter.

@item q-delimiter
The letter @samp{Q} or @samp{q}.

@item week
An integer between 1 and 53 representing a week within a year.

@item wk-delimiter
The letters @samp{wk} in any case.

@item time-delimiter
At least one characters of whitespace or @samp{:} or @samp{.}.

@item hour
An integer greater than 0 representing an hour.

@item minute
An integer between 0 and 59 representing a minute within an hour.

@item opt-second
Optionally, a time-delimiter followed by a real number representing a
number of seconds.

@item hour24
An integer between 0 and 23 representing an hour within a day.

@item weekday
At least the first two characters of an English day word.

@item spaces
Any amount or no amount of whitespace.

@item sign
An optional positive or negative sign.

@item trailer
All formats accept an optional whitespace trailer.
@end table

The date input formats are strung together from the above pieces.  On
output, the date formats are always printed in a single canonical
manner, based on field width.  The date input and output formats are
described below:

@table @asis
@item DATEw: 9 <= iw,ow <= 40
Date format. Input format: leader + day + date-delimiter +
month + date-delimiter + year + trailer.  Output format: DD-MMM-YY for
@var{w} < 11, DD-MMM-YYYY otherwise.

@item EDATEw: 8 <= iw,ow <= 40
European date format.  Input format same as DATE.  Output format:
DD.MM.YY for @var{w} < 10, DD.MM.YYYY otherwise.

@item SDATEw: 8 <= iw,ow <= 40
Standard date format. Input format: leader + year + date-delimiter +
month + date-delimiter + day + trailer.  Output format: YY/MM/DD for
@var{w} < 10, YYYY/MM/DD otherwise.

@item ADATEw: 8 <= iw,ow <= 40
American date format.  Input format: leader + month + date-delimiter +
day + date-delimiter + year + trailer.  Output format: MM/DD/YY for
@var{w} < 10, MM/DD/YYYY otherwise.

@item JDATEw: 5 <= iw,ow <= 40
Julian date format.  Input format: leader + julian + trailer.  Output
format: YYDDD for @var{w} < 7, YYYYDDD otherwise.

@item QYRw: 4 <= iw <= 40, 6 <= ow <= 40
Quarter/year format.  Input format: leader + quarter + q-delimiter +
year + trailer.  Output format: @samp{Q Q YY}, where the first
@samp{Q} is one of the digits 1, 2, 3, 4, if @var{w} < 8, @code{Q Q
YYYY} otherwise.

@item MOYRw: 6 <= iw,ow <= 40
Month/year format.  Input format: leader + month + date-delimiter + year
+ trailer.  Output format: @samp{MMM YY} for @var{w} < 8, @samp{MMM
YYYY} otherwise.

@item WKYRw: 6 <= iw <= 40, 8 <= ow <= 40
Week/year format.  Input format: leader + week + wk-delimiter + year +
trailer.  Output format: @samp{WW WK YY} for @var{w} < 10, @samp{WW WK
YYYY} otherwise.

@item DATETIMEw.d: 17 <= iw,ow <= 40
Date and time format.  Input format: leader + day + date-delimiter +
month + date-delimiter + yaer + time-delimiter + hour24 + time-delimiter
+ minute + opt-second.  Output format: @samp{DD-MMM-YYYY HH:MM}.  If
@var{w} > 19 then seconds @samp{:SS} is added.  If @var{w} > 22 and
@var{d} > 0 then fractional seconds @samp{.SS} are added.

@item TIMEw.d: 5 <= iw,ow <= 40
Time format.  Input format: leader + sign + spaces + hour +
time-delimiter + minute + opt-second.  Output format: @samp{HH:MM}.
Seconds and fractional seconds are available with @var{w} of at least 8
and 10, respectively.

@item DTIMEw.d: 1 <= iw <= 40, 8 <= ow <= 40
Time format with day count.  Input format: leader + sign + spaces +
day-count + time-delimiter + hour + time-delimiter + minute +
opt-second.  Output format: @samp{DD HH:MM}.  Seconds and fractional
seconds are available with @var{w} of at least 8 and 10, respectively.

@item WKDAYw: 2 <= iw,ow <= 40
A weekday as a number between 1 and 7, where 1 is Sunday.  Input format:
leader + weekday + trailer.  Output format: as many characters, in all
capital letters, of the English name of the weekday as will fit in the
field width.

@item MONTHw: 3 <= iw,ow <= 40
A month as a number between 1 and 12, where 1 is January.  Input format:
leader + month + trailer.  Output format: as many character, in all
capital letters, of the English name of the month as will fit in the
field width.
@end table

There are only two formats that may be used with string variables:

@table @asis
@item Aw: 1 <= iw <= 255, 1 <= ow <= 254
The entire field is treated as a string value.

@item AHEXw @result{} A: 2 <= iw <= 254; 2 <= ow <= 510
The field is composed of characters in a string encoded as textual hex
digit pairs.

The default output @var{w} is half the input @var{w}.
@end table

@node Scratch Variables,  , Input/Output Formats, Variables
@subsection Scratch Variables

Most of the time, variables don't retain their values between cases.
Instead, either they're being read from a data file or the active file,
in which case they assume the value read, or, if created with
@cmd{COMPUTE} or
another transformation, they're initialized to the system-missing value
or to blanks, depending on type.

However, sometimes it's useful to have a variable that keeps its value
between cases.  You can do this with @cmd{LEAVE} (@pxref{LEAVE}), or you can
use a @dfn{scratch variable}.  Scratch variables are variables whose
names begin with an octothorpe (@samp{#}).  

Scratch variables have the same properties as variables left with
@cmd{LEAVE}:
they retain their values between cases, and for the first case they are
initialized to 0 or blanks.  They have the additional property that they
are deleted before the execution of any procedure.  For this reason,
scratch variables can't be used for analysis.  To obtain the same
effect, use @cmd{COMPUTE} (@pxref{COMPUTE}) to copy the scratch variable's
value into an ordinary variable, then analysis that variable.

@node Files, BNF, Variables, Language
@section Files Used by PSPP

PSPP makes use of many files each time it runs.  Some of these it
reads, some it writes, some it creates.  Here is a table listing the
most important of these files:

@table @strong
@cindex file, command
@cindex file, syntax file
@cindex command file
@cindex syntax file
@item command file
@itemx syntax file
These names (synonyms) refer to the file that contains instructions to
PSPP that tell it what to do.  The syntax file's name is specified on
the PSPP command line.  Syntax files can also be pulled in with
@cmd{INCLUDE} (@pxref{INCLUDE}).

@cindex file, data
@cindex data file
@item data file
Data files contain raw data in ASCII format suitable for being read in
by @cmd{DATA LIST}.  Data can be embedded in the syntax
file with @cmd{BEGIN DATA} and @cmd{END DATA}: this makes the
syntax file a data file too.

@cindex file, output
@cindex output file
@item listing file
One or more output files are created by PSPP each time it is
run.  The output files receive the tables and charts produced by
statistical procedures.  The output files may be in any number of formats,
depending on how PSPP is configured.

@cindex active file
@cindex file, active
@item active file
The active file is the ``file'' on which all PSPP procedures
are performed.  The active file contains variable definitions and
cases.  The active file is not necessarily a disk file: it is stored
in memory if there is room.
@end table

@node BNF,  , Files, Language
@section Backus-Naur Form
@cindex BNF
@cindex Backus-Naur Form
@cindex command syntax, description of
@cindex description of command syntax

The syntax of some parts of the PSPP language is presented in this
manual using the formalism known as @dfn{Backus-Naur Form}, or BNF. The
following table describes BNF:

@itemize @bullet
@cindex keywords
@cindex terminals
@item
Words in all-uppercase are PSPP keyword tokens.  In BNF, these are
often called @dfn{terminals}.  There are some special terminals, which
are actually written in lowercase for clarity:

@table @asis
@cindex @code{number}
@item @code{number}
A real number.

@cindex @code{integer}
@item @code{integer}
An integer number.

@cindex @code{string}
@item @code{string}
A string.

@cindex @code{var-name}
@item @code{var-name}
A single variable name.

@cindex operators
@cindex punctuators
@item @code{=}, @code{/}, @code{+}, @code{-}, etc.
Operators and punctuators.

@cindex @code{.}
@cindex terminal dot
@cindex dot, terminal
@item @code{.}
The terminal dot.  This is not necessarily an actual dot in the syntax
file: @xref{Commands}, for more details.
@end table

@item
@cindex productions
@cindex nonterminals
Other words in all lowercase refer to BNF definitions, called
@dfn{productions}.  These productions are also known as
@dfn{nonterminals}.  Some nonterminals are very common, so they are
defined here in English for clarity:

@table @code
@cindex @code{var-list}
@item var-list
A list of one or more variable names or the keyword @code{ALL}.

@cindex @code{expression}
@item expression
An expression.  @xref{Expressions}, for details.
@end table

@item
@cindex @code{::=}
@cindex ``is defined as''
@cindex productions
@samp{::=} means ``is defined as''.  The left side of @samp{::=} gives
the name of the nonterminal being defined.  The right side of @samp{::=}
gives the definition of that nonterminal.  If the right side is empty,
then one possible expansion of that nonterminal is nothing.  A BNF
definition is called a @dfn{production}.

@item
@cindex terminals and nonterminals, differences
So, the key difference between a terminal and a nonterminal is that a
terminal cannot be broken into smaller parts---in fact, every terminal
is a single token (@pxref{Tokens}).  On the other hand, nonterminals are
composed of a (possibly empty) sequence of terminals and nonterminals.
Thus, terminals indicate the deepest level of syntax description.  (In
parsing theory, terminals are the leaves of the parse tree; nonterminals
form the branches.)

@item
@cindex start symbol
@cindex symbol, start
The first nonterminal defined in a set of productions is called the
@dfn{start symbol}.  The start symbol defines the entire syntax for
that command.
@end itemize

@node Expressions, Data Input and Output, Language, Top
@chapter Mathematical Expressions
@cindex expressions, mathematical
@cindex mathematical expressions

Some PSPP commands use expressions, which share a common syntax
among all PSPP commands.  Expressions are made up of
@dfn{operands}, which can be numbers, strings, or variable names,
separated by @dfn{operators}.  There are five types of operators:
grouping, arithmetic, logical, relational, and functions.

Every operator takes one or more @dfn{arguments} as input and produces
or @dfn{returns} exactly one result as output.  Both strings and numeric
values can be used as arguments and are produced as results, but each
operator accepts only specific combinations of numeric and string values
as arguments.  With few exceptions, operator arguments may be
full-fledged expressions in themselves.

@menu
* Boolean Values::              Boolean values.
* Missing Values in Expressions::  Using missing values in expressions.
* Grouping Operators::          parentheses
* Arithmetic Operators::        add sub mul div pow
* Logical Operators::           AND NOT OR
* Relational Operators::        EQ GE GT LE LT NE
* Functions::                   More-sophisticated operators.
* Order of Operations::         Operator precedence.
@end menu

@node Boolean Values, Missing Values in Expressions, Expressions, Expressions
@section Boolean Values
@cindex Boolean
@cindex values, Boolean

Some PSPP operators and expressions work with Boolean values, which
represent true/false conditions.  Booleans have only three possible
values: 0 (false), 1 (true), and system-missing (unknown).
System-missing is neither true nor false and indicates that the true
value is unknown.

Boolean-typed operands or function arguments must take on one of these
three values.  Other values are considered false, but cause an error
when the expression is evaluated.

Strings and Booleans are not compatible, and neither may be used in
place of the other.

@node Missing Values in Expressions, Grouping Operators, Boolean Values, Expressions
@section Missing Values in Expressions

String missing values are not treated specially in expressions.  Most
numeric operators return system-missing when given system-missing
arguments.  Exceptions are listed under particular operator
descriptions.

User-missing values for numeric variables are always transformed into
the system-missing value, except inside the arguments  to the
@code{VALUE} and @code{SYSMIS} functions.

The missing-value functions can be used to precisely control how missing
values are treated in expressions.  @xref{Missing Value Functions}, for
more details.

@node Grouping Operators, Arithmetic Operators, Missing Values in Expressions, Expressions
@section Grouping Operators
@cindex parentheses
@cindex @samp{(  )}
@cindex grouping operators
@cindex operators, grouping

Parentheses (@samp{()}) are the grouping operators.  Surround an
expression with parentheses to force early evaluation.

Parentheses also surround the arguments to functions, but in that
situation they act as punctuators, not as operators.

@node Arithmetic Operators, Logical Operators, Grouping Operators, Expressions
@section Arithmetic Operators
@cindex operators, arithmetic
@cindex arithmetic operators

The arithmetic operators take numeric arguments and produce numeric
results.

@table @code
@cindex @samp{+}
@cindex addition
@item @var{a} + @var{b}
Adds @var{a} and @var{b}, returning the sum.

@cindex @samp{-}
@cindex subtraction
@item @var{a} - @var{b}
Subtracts @var{b} from @var{a}, returning the difference.

@cindex @samp{*}
@cindex multiplication
@item @var{a} * @var{b}
Multiplies @var{a} and @var{b}, returning the product.

@cindex @samp{/}
@cindex division
@item @var{a} / @var{b}
Divides @var{a} by @var{b}, returning the quotient.  If @var{b} is
zero, the result is system-missing.

@cindex @samp{**}
@cindex exponentiation
@item @var{a} ** @var{b}
Returns the result of raising @var{a} to the power @var{b}.  If
@var{a} is negative and @var{b} is not an integer, the result is
system-missing.  The result of @code{0**0} is system-missing as well.

@cindex @samp{-}
@cindex negation
@item - @var{a}
Reverses the sign of @var{a}.  
@end table

@node Logical Operators, Relational Operators, Arithmetic Operators, Expressions
@section Logical Operators
@cindex logical operators
@cindex operators, logical

@cindex true
@cindex false
@cindex Boolean
@cindex values, system-missing
@cindex system-missing
The logical operators take logical arguments and produce logical
results, meaning ``true or false''.  PSPP logical operators are
not true Boolean operators because they may also result in a
system-missing value.

@table @code
@cindex @code{AND}
@cindex @samp{&}
@cindex intersection, logical
@cindex logical intersection
@item @var{a} AND @var{b}
@itemx @var{a} & @var{b}
True if both @var{a} and @var{b} are true, false otherwise.  If one
argument is false, the result is false even if the other is missing.  If
both arguments are missing, the result is missing.

@cindex @code{OR}
@cindex @samp{|}
@cindex union, logical
@cindex logical union
@item @var{a} OR @var{b}
@itemx @var{a} | @var{b}
True if at least one of @var{a} and @var{b} is true.  If one argument is
true, the result is true even if the other argument is missing.  If both
arguments are missing, the result is missing.

@cindex @code{NOT}
@cindex @samp{~}
@cindex inversion, logical
@cindex logical inversion
@item NOT @var{a}
@itemx ~ @var{a}
True if @var{a} is false.  If the argument is missing, then the result
is missing.
@end table

@node Relational Operators, Functions, Logical Operators, Expressions
@section Relational Operators

The relational operators take numeric or string arguments and produce Boolean
results.

Strings cannot be compared to numbers.  When strings of different
lengths are compared, the shorter string is right-padded with spaces
to match the length of the longer string.

The results of string comparisons, other than tests for equality or
inequality, are dependent on the character set in use.  String
comparisons are case-sensitive.

@table @code
@cindex equality, testing
@cindex testing for equality
@cindex @code{EQ}
@cindex @samp{=}
@item @var{a} EQ @var{b}
@itemx @var{a} = @var{b}
True if @var{a} is equal to @var{b}.

@cindex less than or equal to
@cindex @code{LE}
@cindex @code{<=}
@item @var{a} LE @var{b}
@itemx @var{a} <= @var{b}
True if @var{a} is less than or equal to @var{b}.

@cindex less than
@cindex @code{LT}
@cindex @code{<}
@item @var{a} LT @var{b}
@itemx @var{a} < @var{b}
True if @var{a} is less than @var{b}.

@cindex greater than or equal to
@cindex @code{GE}
@cindex @code{>=}
@item @var{a} GE @var{b}
@itemx @var{a} >= @var{b}
True if @var{a} is greater than or equal to @var{b}.

@cindex greater than
@cindex @code{GT}
@cindex @samp{>}
@item @var{a} GT @var{b}
@itemx @var{a} > @var{b}
True if @var{a} is greater than @var{b}.

@cindex inequality, testing
@cindex testing for inequality
@cindex @code{NE}
@cindex @code{~=}
@cindex @code{<>}
@item @var{a} NE @var{b}
@itemx @var{a} ~= @var{b}
@itemx @var{a} <> @var{b}
True is @var{a} is not equal to @var{b}.
@end table

@node Functions, Order of Operations, Relational Operators, Expressions
@section Functions
@cindex functions

@cindex mathematics
@cindex operators
@cindex parentheses
@cindex @code{(}
@cindex @code{)}
@cindex names, of functions
PSPP functions provide mathematical abilities above and beyond
those possible using simple operators.  Functions have a common
syntax: each is composed of a function name followed by a left
parenthesis, one or more arguments, and a right parenthesis.  Function
names are @strong{not} reserved; their names are specially treated
only when followed by a left parenthesis: @code{EXP(10)} refers to the
constant value @code{e} raised to the 10th power, but @code{EXP} by
itself refers to the value of variable EXP.

The sections below describe each function in detail.

@menu
* Advanced Mathematics::        EXP LG10 LN SQRT
* Miscellaneous Mathematics::   ABS MOD MOD10 RND TRUNC
* Trigonometry::                ACOS ARCOS ARSIN ARTAN ASIN ATAN COS SIN TAN
* Missing Value Functions::     MISSING NMISS NVALID SYSMIS VALUE
* Pseudo-Random Numbers::       NORMAL UNIFORM
* Set Membership::              ANY RANGE
* Statistical Functions::       CFVAR MAX MEAN MIN SD SUM VARIANCE
* String Functions::            CONCAT INDEX LENGTH LOWER LPAD LTRIM NUMBER 
                                RINDEX RPAD RTRIM STRING SUBSTR UPCASE
* Time & Date::                 CTIME.xxx DATE.xxx TIME.xxx XDATE.xxx
* Miscellaneous Functions::     LAG YRMODA
* Functions Not Implemented::   CDF.xxx CDFNORM IDF.xxx NCDF.xxx PROBIT RV.xxx
@end menu

@node Advanced Mathematics, Miscellaneous Mathematics, Functions, Functions
@subsection Advanced Mathematical Functions
@cindex mathematics, advanced

Advanced mathematical functions take numeric arguments and produce
numeric results.

@deftypefn {Function} {} EXP (@var{exponent})
Returns @i{e} (approximately 2.71828) raised to power @var{exponent}.
@end deftypefn

@cindex logarithms
@deftypefn {Function} {} LG10 (@var{number})
Takes the base-10 logarithm of @var{number}.  If @var{number} is
not positive, the result is system-missing.
@end deftypefn

@deftypefn {Function} {} LN (@var{number})
Takes the base-@i{e} logarithm of @var{number}.  If @var{number} is
not positive, the result is system-missing.
@end deftypefn

@cindex square roots
@deftypefn {Function} {} SQRT (@var{number})
Takes the square root of @var{number}.  If @var{number} is negative,
the result is system-missing.
@end deftypefn

@node Miscellaneous Mathematics, Trigonometry, Advanced Mathematics, Functions
@subsection Miscellaneous Mathematical Functions
@cindex mathematics, miscellaneous

Miscellaneous mathematical functions take numeric arguments and produce
numeric results.

@cindex absolute value
@deftypefn {Function} {} ABS (@var{number})
Results in the absolute value of @var{number}.
@end deftypefn

@cindex modulus
@deftypefn {Function} {} MOD (@var{numerator}, @var{denominator})
Returns the remainder (modulus) of @var{numerator} divided by
@var{denominator}.  If @var{denominator} is 0, the result is
system-missing.  However, if @var{numerator} is 0 and
@var{denominator} is system-missing, the result is 0.
@end deftypefn

@cindex modulus, by 10
@deftypefn {Function} {} MOD10 (@var{number})
Returns the remainder when @var{number} is divided by 10.  If
@var{number} is negative, MOD10(@var{number}) is negative or zero.
@end deftypefn

@cindex rounding
@deftypefn {Function} {} RND (@var{number})
Takes the absolute value of @var{number} and rounds it to an integer.
Then, if @var{number} was negative originally, negates the result.
@end deftypefn

@cindex truncation
@deftypefn {Function} {} TRUNC (@var{number})
Discards the fractional part of @var{number}; that is, rounds
@var{number} towards zero.
@end deftypefn

@node Trigonometry, Missing Value Functions, Miscellaneous Mathematics, Functions
@subsection Trigonometric Functions
@cindex trigonometry

Trigonometric functions take numeric arguments and produce numeric
results.

@cindex arccosine
@cindex inverse cosine
@deftypefn {Function} {} ARCOS (@var{number})
Takes the arccosine, in radians, of @var{number}.  Results in
system-missing if @var{number} is not between -1 and 1.
@end deftypefn

@cindex arcsine
@cindex inverse sine
@deftypefn {Function} {} ARSIN (@var{number})
Takes the arcsine, in radians, of @var{number}.  Results in
system-missing if @var{number} is not between -1 and 1 inclusive.
@end deftypefn

@cindex arctangent
@cindex inverse tangent
@deftypefn {Function} {} ARTAN (@var{number})
Takes the arctangent, in radians, of @var{number}.
@end deftypefn

@cindex cosine
@deftypefn {Function} {} COS (@var{angle})
Takes the cosine of @var{angle} which should be in radians.
@end deftypefn

@cindex sine
@deftypefn {Function} {} SIN (@var{angle})
Takes the sine of @var{angle} which should be in radians.
@end deftypefn

@cindex tangent
@deftypefn {Function} {} TAN (@var{angle})
Takes the tangent of @var{angle} which should be in radians.
Results in system-missing at values
of @var{angle} that are too close to odd multiples of pi/2.
Portability: none.
@end deftypefn

@node Missing Value Functions, Pseudo-Random Numbers, Trigonometry, Functions
@subsection Missing-Value Functions
@cindex missing values
@cindex values, missing
@cindex functions, missing-value

Missing-value functions take various numeric arguments and yield
various types of results.  Note that the normal rules of evaluation
apply within expression arguments to these functions.  In particular,
user-missing values for numeric variables are converted to
system-missing values.

@deftypefn {Function} {} MISSING (@var{expr})
Returns 1 if @var{expr} has the system-missing value, 0 otherwise.
@end deftypefn

@deftypefn {Function} {} NMISS (@var{expr} [, @var{expr}]@dots{})
Each argument must be a numeric expression.  Returns the number of
system-missing values in the list.  As a special extension,
the syntax @code{@var{var1} TO @var{var2}} may be used to refer to a
range of variables; see @ref{Sets of Variables}, for more details.
@end deftypefn

@deftypefn {Function} {} NVALID (@var{expr} [, @var{expr}]@dots{})
Each argument must be a numeric expression.  Returns the number of
values in the list that are not system-missing.  As a special extension,
the syntax @code{@var{var1} TO @var{var2}} may be used to refer to a
range of variables; see @ref{Sets of Variables}, for more details.
@end deftypefn

@deftypefn {Function} {} SYSMIS (@var{expr})
When @var{expr} is simply the name of a numeric variable, returns 1 if
the variable has the system-missing value, 0 if it is user-missing or
not missing.  If given @var{expr} takes another form, results in 1 if
the value is system-missing, 0 otherwise.
@end deftypefn

@deftypefn {Function} {} VALUE (@var{variable})
Prevents the user-missing values of @var{variable} from being
transformed into system-missing values, and always results in the
actual value of @var{variable}, whether it is user-missing,
system-missing or not missing at all.
@end deftypefn

@node Pseudo-Random Numbers, Set Membership, Missing Value Functions, Functions
@subsection Pseudo-Random Number Generation Functions
@cindex random numbers
@cindex pseudo-random numbers (see random numbers)

Pseudo-random number generation functions take numeric arguments and
produce numeric results.

PSPP uses the alleged RC4 cipher as a pseudo-random number generator
(PRNG).  The bytes output by this PRNG are system-independent for a
given random seed, but differences in endianness and floating-point
formats will make PRNG results differ from system to system.  RC4
should produce high-quality random numbers for simulation purposes.
(If you're concerned about the quality of the random number generator,
well, you're using a statistical processing package---analyze it!)

PSPP's implementation of RC4 has not undergone any security auditing.
Furthermore, various precautions that would be necessary for secure
operation, such as secure seeding and discarding the first several
bytes of output, have not been taken.  Therefore, PSPP's
implementation of RC4 should not be used for security purposes.

@cindex random numbers, normally-distributed
@deftypefn {Function} {} NORMAL (@var{number})
Results in a random number.  Results from @code{NORMAL} are normally
distributed with a mean of 0 and a standard deviation of @var{number}.
@end deftypefn

@cindex random numbers, uniformly-distributed
@deftypefn {Function} {} UNIFORM (@var{number})
Results in a random number between 0 and @var{number}.  Results from
@code{UNIFORM} are evenly distributed across its entire range.  There
may be a maximum on the largest random number ever generated---this is
often 
@ifinfo 
2**31-1 
@end ifinfo
@tex
$2^{31}-1$
@end tex
(2,147,483,647), but it may be orders of magnitude
higher or lower.
@end deftypefn

@node Set Membership, Statistical Functions, Pseudo-Random Numbers, Functions
@subsection Set-Membership Functions
@cindex set membership
@cindex membership, of set

Set membership functions determine whether a value is a member of a set.
They take a set of numeric arguments or a set of string arguments, and
produce Boolean results.

String comparisons are performed according to the rules given in
@ref{Relational Operators}.

@deftypefn {Function} {} ANY (@var{value}, @var{set} [, @var{set}]@dots{})
Results in true if @var{value} is equal to any of the @var{set}
values.  Otherwise, results in false.  If @var{value} is
system-missing, returns system-missing.  System-missing values in
@var{set} do not cause ANY to return system-missing.
@end deftypefn

@deftypefn {Function} {} RANGE (@var{value}, @var{low}, @var{high} [, @var{low}, @var{high}]@dots{})
Results in true if @var{value} is in any of the intervals bounded by
@var{low} and @var{high} inclusive.  Otherwise, results in false.
Each @var{low} must be less than or equal to its corresponding
@var{high} value.  @var{low} and @var{high} must be given in pairs.
If @var{value} is system-missing, returns system-missing.
System-missing values in @var{set} do not cause RANGE to return
system-missing.
@end deftypefn

@node Statistical Functions, String Functions, Set Membership, Functions
@subsection Statistical Functions
@cindex functions, statistical
@cindex statistics

Statistical functions compute descriptive statistics on a list of
values.  Some statistics can be computed on numeric or string values;
other can only be computed on numeric values.  Their results have the
same type as their arguments.  The current case's weighting factor
(@pxref{WEIGHT}) has no effect on statistical functions.

@cindex arguments, minimum valid
@cindex minimum valid number of arguments
With statistical functions it is possible to specify a minimum number of
non-missing arguments for the function to be evaluated.  To do so,
append a dot and the number to the function name.  For instance, to
specify a minimum of three valid arguments to the MEAN function, use the
name @code{MEAN.3}.

@cindex coefficient of variation
@cindex variation, coefficient of
@deftypefn {Function} {} CFVAR (@var{number}, @var{number}[, @dots{}])
Results in the coefficient of variation of the values of @var{number}.
This function requires at least two valid arguments to give a
non-missing result.  (The coefficient of variation is the standard
deviation divided by the mean.)
@end deftypefn

@cindex maximum
@deftypefn {Function} {} MAX (@var{value}, @var{value}[, @dots{}])
Results in the value of the greatest @var{value}.  The @var{value}s may
be numeric or string.  Although at least two arguments must be given,
only one need be valid for MAX to give a non-missing result.
@end deftypefn

@cindex mean
@deftypefn {Function} {} MEAN (@var{number}, @var{number}[, @dots{}])
Results in the mean of the values of @var{number}.  Although at least
two arguments must be given, only one need be valid for MEAN to give a
non-missing result.
@end deftypefn

@cindex minimum
@deftypefn {Function} {} MIN (@var{number}, @var{number}[, @dots{}])
Results in the value of the least @var{value}.  The @var{value}s may
be numeric or string.  Although at least two arguments must be given,
only one need be valid for MAX to give a non-missing result.
@end deftypefn

@cindex standard deviation
@cindex deviation, standard
@deftypefn {Function} {} SD (@var{number}, @var{number}[, @dots{}])
Results in the standard deviation of the values of @var{number}.
This function requires at least two valid arguments to give a
non-missing result.
@end deftypefn

@cindex sum
@deftypefn {Function} {} SUM (@var{number}, @var{number}[, @dots{}])
Results in the sum of the values of @var{number}.  Although at least two
arguments must be given, only one need by valid for SUM to give a
non-missing result.
@end deftypefn

@cindex variance
@deftypefn {Function} {} VARIANCE (@var{number}, @var{number}[, @dots{}])
Results in the variance of the values of @var{number}.  This function
requires at least two valid arguments to give a non-missing result.
@end deftypefn

@node String Functions, Time & Date, Statistical Functions, Functions
@subsection String Functions
@cindex functions, string
@cindex string functions

String functions take various arguments and return various results.

@cindex concatenation
@cindex strings, concatenation of
@deftypefn {Function} {} CONCAT (@var{string}, @var{string}[, @dots{}])
Returns a string consisting of each @var{string} in sequence.
@code{CONCAT("abc", "def", "ghi")} has a value of @code{"abcdefghi"}.
The resultant string is truncated to a maximum of 255 characters.
@end deftypefn

@cindex searching strings
@deftypefn {Function} {} INDEX (@var{haystack}, @var{needle})
Returns a positive integer indicating the position of the first
occurrence @var{needle} in @var{haystack}.  Returns 0 if @var{haystack}
does not contain @var{needle}.  Returns system-missing if @var{needle}
is an empty string.
@end deftypefn

@deftypefn {Function} {} INDEX (@var{haystack}, @var{needle}, @var{divisor})
Divides @var{needle} into parts, each with length @var{divisor}.
Searches @var{haystack} for the first occurrence of each part, and
returns the smallest value.  Returns 0 if @var{haystack} does not
contain any part in @var{needle}.  It is an error if @var{divisor}
cannot be evenly divided into the length of @var{needle}.  Returns
system-missing if @var{needle} is an empty string.
@end deftypefn

@cindex strings, finding length of
@deftypefn {Function} {} LENGTH (@var{string})
Returns the number of characters in @var{string}.
@end deftypefn

@cindex strings, case of
@deftypefn {Function} {} LOWER (@var{string})
Returns a string identical to @var{string} except that all uppercase
letters are changed to lowercase letters.  The definitions of
``uppercase'' and ``lowercase'' are system-dependent.
@end deftypefn

@cindex strings, padding
@deftypefn {Function} {} LPAD (@var{string}, @var{length})
If @var{string} is at least @var{length} characters in length, returns
@var{string} unchanged.  Otherwise, returns @var{string} padded with
spaces on the left side to length @var{length}.  Returns an empty string
if @var{length} is system-missing, negative, or greater than 255.
@end deftypefn

@deftypefn {Function} {} LPAD (@var{string}, @var{length}, @var{padding})
If @var{string} is at least @var{length} characters in length, returns
@var{string} unchanged.  Otherwise, returns @var{string} padded with
@var{padding} on the left side to length @var{length}.  Returns an empty
string if @var{length} is system-missing, negative, or greater than 255, or
if @var{padding} does not contain exactly one character.
@end deftypefn

@cindex strings, trimming
@cindex whitespace, trimming
@deftypefn {Function} {} LTRIM (@var{string})
Returns @var{string}, after removing leading spaces.  Other whitespace,
such as tabs, carriage returns, line feeds, and vertical tabs, is not
removed.
@end deftypefn

@deftypefn {Function} {} LTRIM (@var{string}, @var{padding})
Returns @var{string}, after removing leading @var{padding} characters.
If @var{padding} does not contain exactly one character, returns an
empty string.
@end deftypefn

@cindex numbers, converting from strings
@cindex strings, converting to numbers
@deftypefn {Function} {} NUMBER (@var{string}, @var{format})
Returns the number produced when @var{string} is interpreted according
to format specifier @var{format}.  If the format width @var{w} is less
than the length of @var{string}, then only the first @var{w}
characters in @var{string} are used, e.g.@: @code{NUMBER("123", F3.0)}
and @code{NUMBER("1234", F3.0)} both have value 123.  If @var{w} is
greater than @var{string}'s length, then it is treated as if it were
right-padded with spaces.  If @var{string} is not in the correct
format for @var{format}, system-missing is returned.
@end deftypefn

@cindex strings, searching backwards
@deftypefn {Function} {} RINDEX (@var{string}, @var{format})
Returns a positive integer indicating the position of the last
occurrence of @var{needle} in @var{haystack}.  Returns 0 if
@var{haystack} does not contain @var{needle}.  Returns system-missing if
@var{needle} is an empty string.
@end deftypefn

@deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle}, @var{divisor})
Divides @var{needle} into parts, each with length @var{divisor}.
Searches @var{haystack} for the last occurrence of each part, and
returns the largest value.  Returns 0 if @var{haystack} does not contain
any part in @var{needle}.  It is an error if @var{divisor} cannot be
evenly divided into the length of @var{needle}.  Returns system-missing
if @var{needle} is an empty string.
@end deftypefn

@cindex padding strings
@cindex strings, padding
@deftypefn {Function} {} RPAD (@var{string}, @var{length})
If @var{string} is at least @var{length} characters in length, returns
@var{string} unchanged.  Otherwise, returns @var{string} padded with
spaces on the right to length @var{length}.  Returns an empty string if
@var{length} is system-missing, negative, or greater than 255.
@end deftypefn

@deftypefn {Function} {} RPAD (@var{string}, @var{length}, @var{padding})
If @var{string} is at least @var{length} characters in length, returns
@var{string} unchanged.  Otherwise, returns @var{string} padded with
@var{padding} on the right to length @var{length}.  Returns an empty
string if @var{length} is system-missing, negative, or greater than 255,
or if @var{padding} does not contain exactly one character.
@end deftypefn

@cindex strings, trimming
@cindex whitespace, trimming
@deftypefn {Function} {} RTRIM (@var{string})
Returns @var{string}, after removing trailing spaces.  Other types of
whitespace are not removed.
@end deftypefn

@deftypefn {Function} {} RTRIM (@var{string}, @var{padding})
Returns @var{string}, after removing trailing @var{padding} characters.
If @var{padding} does not contain exactly one character, returns an
empty string.
@end deftypefn

@cindex strings, converting from numbers
@cindex numbers, converting to strings
@deftypefn {Function} {} STRING (@var{number}, @var{format})
Returns a string corresponding to @var{number} in the format given by
format specifier @var{format}.  For example, @code{STRING(123.56, F5.1)}
has the value @code{"123.6"}.
@end deftypefn

@cindex substrings
@cindex strings, taking substrings of
@deftypefn {Function} {} SUBSTR (@var{string}, @var{start})
Returns a string consisting of the value of @var{string} from position
@var{start} onward.  Returns an empty string if @var{start} is system-missing
or has a value less than 1 or greater than the number of characters in
@var{string}.
@end deftypefn

@deftypefn {Function} {} SUBSTR (@var{string}, @var{start}, @var{count})
Returns a string consisting of the first @var{count} characters from
@var{string} beginning at position @var{start}.  Returns an empty string
if @var{start} or @var{count} is system-missing, if @var{start} is less
than 1 or greater than the number of characters in @var{string}, or if
@var{count} is less than 1.  Returns a string shorter than @var{count}
characters if @var{start} + @var{count} - 1 is greater than the number
of characters in @var{string}.  Examples: @code{SUBSTR("abcdefg", 3, 2)}
has value @code{"cd"}; @code{SUBSTR("Ben Pfaff", 5, 10)} has the value
@code{"Pfaff"}.
@end deftypefn

@cindex case conversion
@cindex strings, case of
@deftypefn {Function} {} UPCASE (@var{string})
Returns @var{string}, changing lowercase letters to uppercase letters.
@end deftypefn

@node Time & Date, Miscellaneous Functions, String Functions, Functions
@subsection Time & Date Functions
@cindex functions, time & date
@cindex times
@cindex dates

@cindex dates, legal range of
The legal range of dates for use in PSPP is 15 Oct 1582
through 31 Dec 19999.

@cindex arguments, invalid
@cindex invalid arguments
@quotation
@strong{Please note:} Most time & date extraction functions will accept
invalid arguments:

@itemize @bullet
@item
Negative numbers in PSPP time format.
@item
Numbers less than 86,400 in PSPP date format.
@end itemize

However, sensible results are not guaranteed for these invalid values.
The given equivalents for these functions are definitely not guaranteed
for invalid values.
@end quotation

@quotation
@strong{Please note also:} The time & date construction
functions @strong{do} produce reasonable and useful results for
out-of-range values; these are not considered invalid.
@end quotation

@menu
* Time & Date Concepts::        How times & dates are defined and represented
* Time Construction::           TIME.@{DAYS HMS@}
* Time Extraction::             CTIME.@{DAYS HOURS MINUTES SECONDS@}
* Date Construction::           DATE.@{DMY MDY MOYR QYR WKYR YRDAY@}
* Date Extraction::             XDATE.@{DATE HOUR JDAY MDAY MINUTE MONTH
                                       QUARTER SECOND TDAY TIME WEEK
                                       WKDAY YEAR@}
@end menu

@node Time & Date Concepts, Time Construction, Time & Date, Time & Date
@subsubsection How times & dates are defined and represented

@cindex time, concepts
@cindex time, intervals
Times and dates are handled by PSPP as single numbers.  A
@dfn{time} is an interval.  PSPP measures times in seconds.
Thus, the following intervals correspond with the numeric values given:
                
@example
          10 minutes                        600
          1 hour                          3,600
          1 day, 3 hours, 10 seconds     97,210
          40 days                     3,456,000
          10010 d, 14 min, 24 s     864,864,864
@end example

@cindex dates, concepts
@cindex time, instants of
A @dfn{date}, on the other hand, is a particular instant in the past or
the future.  PSPP represents a date as a number of seconds after the
midnight that separated 8 Oct 1582 and 9 Oct 1582.  (Please note that 15
Oct 1582 immediately followed 9 Oct 1582.)  Thus, the midnights before
the dates given below correspond with the numeric PSPP dates given:

@example
              15 Oct 1582                86,400
               4 Jul 1776         6,113,318,400
               1 Jan 1900        10,010,390,400
               1 Oct 1978        12,495,427,200
              24 Aug 1995        13,028,601,600
@end example

@cindex time, mathematical properties of
@cindex mathematics, applied to times & dates
@cindex dates, mathematical properties of
@noindent
Please note: 

@itemize @bullet
@item
A time may be added to, or subtracted from, a date, resulting in a date.

@item
The difference of two dates may be taken, resulting in a time.  

@item 
Two times may be added to, or subtracted from, each other, resulting in
a time.
@end itemize

(Adding two dates does not produce a useful result.)

Since times and dates are merely numbers, the ordinary addition and
subtraction operators are employed for these purposes.

@quotation
@strong{Please note:} Many dates and times have extremely large
values---just look at the values above.  Thus, it is not a good idea to
take powers of these values; also, the accuracy of some procedures may
be affected.  If necessary, convert times or dates in seconds to some
other unit, like days or years, before performing analysis.
@end quotation

@node Time Construction, Time Extraction, Time & Date Concepts, Time & Date
@subsubsection Functions that Produce Times
@cindex times, constructing
@cindex constructing times

These functions take numeric arguments and produce numeric results in
PSPP time format.

@cindex days
@cindex time, in days
@deftypefn {Function} {} TIME.DAYS (@var{ndays})
Results in a time value corresponding to @var{ndays} days.
(@code{TIME.DAYS(@var{x})} is equivalent to @code{@var{x} * 60 * 60 *
24}.)
@end deftypefn

@cindex hours-minutes-seconds
@cindex time, in hours-minutes-seconds
@deftypefn {Function} {} TIME.HMS (@var{nhours}, @var{nmins}, @var{nsecs})
Results in a time value corresponding to @var{nhours} hours, @var{nmins}
minutes, and @var{nsecs} seconds.  (@code{TIME.HMS(@var{h}, @var{m},
@var{s})} is equivalent to @code{@var{h}*60*60 + @var{m}*60 +
@var{s}}.)
@end deftypefn

@node Time Extraction, Date Construction, Time Construction, Time & Date
@subsubsection Functions that Examine Times
@cindex extraction, of time
@cindex time examination
@cindex examination, of times
@cindex time, lengths of

These functions take numeric arguments in PSPP time format and
give numeric results.

@cindex days
@cindex time, in days
@deftypefn {Function} {} CTIME.DAYS (@var{time})
Results in the number of days and fractional days in @var{time}.
(@code{CTIME.DAYS(@var{x})} is equivalent to @code{@var{x}/60/60/24}.)
@end deftypefn

@cindex hours
@cindex time, in hours
@deftypefn {Function} {} CTIME.HOURS (@var{time})
Results in the number of hours and fractional hours in @var{time}.
(@code{CTIME.HOURS(@var{x})} is equivalent to @code{@var{x}/60/60}.)
@end deftypefn

@cindex minutes
@cindex time, in minutes
@deftypefn {Function} {} CTIME.MINUTES (@var{time})
Results in the number of minutes and fractional minutes in @var{time}.
(@code{CTIME.MINUTES(@var{x})} is equivalent to @code{@var{x}/60}.)
@end deftypefn

@cindex seconds
@cindex time, in seconds
@deftypefn {Function} {} CTIME.SECONDS (@var{time})
Results in the number of seconds and fractional seconds in @var{time}.
(@code{CTIME.SECONDS} does nothing; @code{CTIME.SECONDS(@var{x})} is
equivalent to @code{@var{x}}.)
@end deftypefn

@node Date Construction, Date Extraction, Time Extraction, Time & Date
@subsubsection Functions that Produce Dates
@cindex dates, constructing
@cindex constructing dates

@cindex arguments, of date construction functions
These functions take numeric arguments and give numeric results in the
PSPP date format.  Arguments taken by these functions are:

@table @var
@item day
Refers to a day of the month between 1 and 31.

@item month
Refers to a month of the year between 1 and 12.

@item quarter
Refers to a quarter of the year between 1 and 4.  The quarters of the
year begin on the first days of months 1, 4, 7, and 10.

@item week
Refers to a week of the year between 1 and 53.

@item yday
Refers to a day of the year between 1 and 366.

@item year
Refers to a year between 1582 and 19999.
@end table

@cindex arguments, invalid
If these functions' arguments are out-of-range, they are correctly
normalized before conversion to date format.  Non-integers are rounded
toward zero.

@cindex day-month-year
@cindex dates, day-month-year
@deftypefn {Function} {} DATE.DMY (@var{day}, @var{month}, @var{year})
@deftypefnx {Function} {} DATE.MDY (@var{month}, @var{day}, @var{year})
Results in a date value corresponding to the midnight before day
@var{day} of month @var{month} of year @var{year}.
@end deftypefn

@cindex month-year
@cindex dates, month-year
@deftypefn {Function} {} DATE.MOYR (@var{month}, @var{year})
Results in a date value corresponding to the midnight before the first
day of month @var{month} of year @var{year}.
@end deftypefn

@cindex quarter-year
@cindex dates, quarter-year
@deftypefn {Function} {} DATE.QYR (@var{quarter}, @var{year})
Results in a date value corresponding to the midnight before the first
day of quarter @var{quarter} of year @var{year}.
@end deftypefn

@cindex week-year
@cindex dates, week-year
@deftypefn {Function} {} DATE.WKYR (@var{week}, @var{year})
Results in a date value corresponding to the midnight before the first
day of week @var{week} of year @var{year}.
@end deftypefn

@cindex year-day
@cindex dates, year-day
@deftypefn {Function} {} DATE.YRDAY (@var{year}, @var{yday})
Results in a date value corresponding to the midnight before day
@var{yday} of year @var{year}.
@end deftypefn

@node Date Extraction,  , Date Construction, Time & Date
@subsubsection Functions that Examine Dates
@cindex extraction, of dates
@cindex date examination

@cindex arguments, of date extraction functions
These functions take numeric arguments in PSPP date or time
format and give numeric results.  These names are used for arguments:

@table @var
@item date
A numeric value in PSPP date format.

@item time
A numeric value in PSPP time format.

@item time-or-date
A numeric value in PSPP time or date format.
@end table

@cindex days
@cindex dates, in days
@cindex time, in days
@deftypefn {Function} {} XDATE.DATE (@var{time-or-date})
For a time, results in the time corresponding to the number of whole
days @var{date-or-time} includes.  For a date, results in the date
corresponding to the latest midnight at or before @var{date-or-time};
that is, gives the date that @var{date-or-time} is in.
(XDATE.DATE(@var{x}) is equivalent to TRUNC(@var{x}/86400)*86400.)
Applying this function to a time is a non-portable feature.
@end deftypefn

@cindex hours
@cindex dates, in hours
@cindex time, in hours
@deftypefn {Function} {} XDATE.HOUR (@var{time-or-date})
For a time, results in the number of whole hours beyond the number of
whole days represented by @var{date-or-time}.  For a date, results in
the hour (as an integer between 0 and 23) corresponding to
@var{date-or-time}.  (XDATE.HOUR(@var{x}) is equivalent to
MOD(TRUNC(@var{x}/3600),24))  Applying this function to a time is a
non-portable feature.
@end deftypefn

@cindex day of the year
@cindex dates, day of the year
@deftypefn {Function} {} XDATE.JDAY (@var{date})
Results in the day of the year (as an integer between 1 and 366)
corresponding to @var{date}.
@end deftypefn

@cindex day of the month
@cindex dates, day of the month
@deftypefn {Function} {} XDATE.MDAY (@var{date})
Results in the day of the month (as an integer between 1 and 31)
corresponding to @var{date}.
@end deftypefn

@cindex minutes
@cindex dates, in minutes
@cindex time, in minutes
@deftypefn {Function} {} XDATE.MINUTE (@var{time-or-date})
Results in the number of minutes (as an integer between 0 and 59) after
the last hour in @var{time-or-date}.  (XDATE.MINUTE(@var{x}) is
equivalent to MOD(TRUNC(@var{x}/60),60)) Applying this function to a
time is a non-portable feature.
@end deftypefn

@cindex months
@cindex dates, in months
@deftypefn {Function} {} XDATE.MONTH (@var{date})
Results in the month of the year (as an integer between 1 and 12)
corresponding to @var{date}.
@end deftypefn

@cindex quarters
@cindex dates, in quarters
@deftypefn {Function} {} XDATE.QUARTER (@var{date})
Results in the quarter of the year (as an integer between 1 and 4)
corresponding to @var{date}.
@end deftypefn

@cindex seconds
@cindex dates, in seconds
@cindex time, in seconds
@deftypefn {Function} {} XDATE.SECOND (@var{time-or-date})
Results in the number of whole seconds after the last whole minute (as
an integer between 0 and 59) in @var{time-or-date}.
(XDATE.SECOND(@var{x}) is equivalent to MOD(@var{x}, 60).)  Applying
this function to a time is a non-portable feature.
@end deftypefn

@cindex days
@cindex times, in days
@deftypefn {Function} {} XDATE.TDAY (@var{time})
Results in the number of whole days (as an integer) in @var{time}.
(XDATE.TDAY(@var{x}) is equivalent to TRUNC(@var{x}/86400).)
@end deftypefn

@cindex time
@cindex dates, time of day
@deftypefn {Function} {} XDATE.TIME (@var{date})
Results in the time of day at the instant corresponding to @var{date},
in PSPP time format.  This is the number of seconds since
midnight on the day corresponding to @var{date}.  (XDATE.TIME(@var{x}) is
equivalent to TRUNC(@var{x}/86400)*86400.)
@end deftypefn

@cindex week
@cindex dates, in weeks
@deftypefn {Function} {} XDATE.WEEK (@var{date})
Results in the week of the year (as an integer between 1 and 53)
corresponding to @var{date}.
@end deftypefn

@cindex day of the week
@cindex weekday
@cindex dates, day of the week
@cindex dates, in weekdays
@deftypefn {Function} {} XDATE.WKDAY (@var{date})
Results in the day of week (as an integer between 1 and 7) corresponding
to @var{date}.  The days of the week are:

@table @asis
@item 1
Sunday
@item 2
Monday
@item 3
Tuesday
@item 4
Wednesday
@item 5
Thursday
@item 6
Friday
@item 7
Saturday
@end table
@end deftypefn

@cindex years
@cindex dates, in years
@deftypefn {Function} {} XDATE.YEAR (@var{date})
Returns the year (as an integer between 1582 and 19999) corresponding to
@var{date}.
@end deftypefn

@node Miscellaneous Functions, Functions Not Implemented, Time & Date, Functions
@subsection Miscellaneous Functions
@cindex functions, miscellaneous

Miscellaneous functions take various arguments and produce various
results.

@cindex cross-case function
@cindex function, cross-case
@deftypefn {Function} {} LAG (@var{variable})
@anchor{LAG}
@var{variable} must be a numeric or string variable name.  @code{LAG}
results in the value of that variable for the case before the current
one.  In case-selection procedures, @code{LAG} results in the value of
the variable for the last case selected.  Results in system-missing (for
numeric variables) or blanks (for string variables) for the first case
or before any cases are selected.
@end deftypefn

@deftypefn {Function} {} LAG (@var{variable}, @var{ncases})
@var{variable} must be a numeric or string variable name.  @var{ncases}
must be a small positive constant integer, although there is no explicit
limit.  (Use of a large value for @var{ncases} will increase memory
consumption, since PSPP must keep @var{ncases} cases in memory.)
@code{LAG (@var{variable}, @var{ncases}} results in the value of
@var{variable} that is @var{ncases} before the case currently being
processed.  See @code{LAG (@var{variable})} above for more details.
@end deftypefn

@cindex date, Julian
@cindex Julian date
@deftypefn {Function} {} YRMODA (@var{year}, @var{month}, @var{day})
@var{year} is a year between 0 and 199 or 1582 and 19999.  @var{month} is
a month between 1 and 12.  @var{day} is a day between 1 and 31.  If
@var{month} or @var{day} is out-of-range, it changes the next higher
unit.  For instance, a @var{day} of 0 refers to the last day of the
previous month, and a @var{month} of 13 refers to the first month of the
next year.  @var{year} must be in range.  If @var{year} is between 0 and
199, 1900 is added.  @var{year}, @var{month}, and @var{day} must all be
integers.

@code{YRMODA} results in the number of days between 15 Oct 1582 and
the date specified, plus one.  The date passed to @code{YRMODA} must be
on or after 15 Oct 1582.  15 Oct 1582 has a value of 1.
@end deftypefn

@node Functions Not Implemented,  , Miscellaneous Functions, Functions
@subsection Functions Not Implemented
@cindex functions, not implemented
@cindex not implemented
@cindex features, not implemented

These functions are not yet implemented and thus not yet documented,
since it's a hassle.

@findex CDF.xxx
@findex CDFNORM
@findex IDF.xxx
@findex NCDF.xxx
@findex PROBIT
@findex RV.xxx

@itemize @bullet
@item
@code{CDF.xxx}
@item
@code{CDFNORM}
@item
@code{IDF.xxx}
@item
@code{NCDF.xxx}
@item
@code{PROBIT}
@item
@code{RV.xxx}
@end itemize

@node Order of Operations,  , Functions, Expressions
@section Operator Precedence
@cindex operator precedence
@cindex precedence, operator
@cindex order of operations
@cindex operations, order of

The following table describes operator precedence.  Smaller-numbered
levels in the table have higher precedence.  Within a level, operations
are performed from left to right, except for level 2 (exponentiation),
where operations are performed from right to left.  If an operator
appears in the table in two places (@code{-}), the first occurrence is
unary, the second is binary.

@enumerate
@item
@code{(  )}
@item
@code{**}
@item
@code{-}
@item
@code{*  /}
@item
@code{+  -}
@item
@code{EQ  GE  GT  LE  LT  NE}
@item
@code{AND  NOT  OR}
@end enumerate

@node Data Input and Output, System and Portable Files, Expressions, Top
@chapter Data Input and Output
@cindex input
@cindex output
@cindex data
@cindex cases
@cindex observations

Data are the focus of the PSPP language.  
Each datum  belongs to a @dfn{case} (also called an @dfn{observation}).
Each case represents an individual or `experimental unit'.
For example, in the results of a survey, the names of the respondents,
their sex, age @i{etc}. and their responses are all data and the data
pertaining to single respondent is a case.
This chapter examines
the PSPP commands for defining variables and reading and writing data.

@quotation
@strong{Please note:} Data is not actually read until a procedure is
executed.  These commands tell PSPP how to read data, but they
do not @emph{cause} PSPP to read data.
@end quotation

@menu
* BEGIN DATA::                  Embed data within a syntax file.
* CLEAR TRANSFORMATIONS::       Clear pending transformations.
* DATA LIST::                   Fundamental data reading command.
* END CASE::                    Output the current case.
* END FILE::                    Terminate the current input program.
* FILE HANDLE::                 Support for fixed-length records.
* INPUT PROGRAM::               Support for complex input programs.
* LIST::                        List cases in the active file.
* MATRIX DATA::                 Read matrices in text format.
* NEW FILE::                    Clear the active file and dictionary.
* PRINT::                       Display values in print formats.
* PRINT EJECT::                 Eject the current page then print.
* PRINT SPACE::                 Print blank lines.
* REREAD::                      Take another look at the previous input line.
* REPEATING DATA::              Multiple cases on a single line.
* WRITE::                       Display values in write formats.
@end menu

@node BEGIN DATA, CLEAR TRANSFORMATIONS, Data Input and Output, Data Input and Output
@section BEGIN DATA
@vindex BEGIN DATA
@vindex END DATA
@cindex Embedding data in syntax files
@cindex Data, embedding in syntax files

@display
BEGIN DATA.
@dots{}
END DATA.
@end display

@cmd{BEGIN DATA} and @cmd{END DATA} can be used to embed raw ASCII
data in a PSPP syntax file.  @cmd{DATA LIST} or another input
procedure must be used before @cmd{BEGIN DATA} (@pxref{DATA LIST}).
@cmd{BEGIN DATA} and @cmd{END DATA} must be used together.  @cmd{END
DATA} must appear by itself on a single line, with no leading
whitespace and exactly one space between the words @code{END} and
@code{DATA}, followed immediately by the terminal dot, like this:

@example
END DATA.
@end example

@node CLEAR TRANSFORMATIONS, DATA LIST, BEGIN DATA, Data Input and Output
@section CLEAR TRANSFORMATIONS
@vindex CLEAR TRANSFORMATIONS

@display
CLEAR TRANSFORMATIONS.
@end display

@cmd{CLEAR TRANSFORMATIONS} clears out all pending
transformations.  It does not cancel the current input program.  It is
valid only when PSPP is interactive, not in syntax files.

@node DATA LIST, END CASE, CLEAR TRANSFORMATIONS, Data Input and Output
@section DATA LIST
@vindex DATA LIST
@cindex reading data from a file
@cindex data, reading from a file
@cindex data, embedding in syntax files
@cindex embedding data in syntax files

Used to read text or binary data, @cmd{DATA LIST} is the most
fundamental data-reading command.  Even the more sophisticated input
methods use @cmd{DATA LIST} commands as a building block.
Understanding @cmd{DATA LIST} is important to understanding how to use
PSPP to read your data files.

There are two major variants of @cmd{DATA LIST}, which are fixed
format and free format.  In addition, free format has a minor variant,
list format, which is discussed in terms of its differences from vanilla
free format.

Each form of @cmd{DATA LIST} is described in detail below.

@menu
* DATA LIST FIXED::             Fixed columnar locations for data.
* DATA LIST FREE::              Any spacing you like.
* DATA LIST LIST::              Each case must be on a single line.
@end menu

@node DATA LIST FIXED, DATA LIST FREE, DATA LIST, DATA LIST
@subsection DATA LIST FIXED
@vindex DATA LIST FIXED
@cindex reading fixed-format data
@cindex fixed-format data, reading
@cindex data, fixed-format, reading
@cindex embedding fixed-format data

@display
DATA LIST [FIXED]
        @{TABLE,NOTABLE@}
        FILE='filename'
        RECORDS=record_count
        END=end_var
        /[line_no] var_spec@dots{}

where each var_spec takes one of the forms
        var_list start-end [type_spec]
        var_list (fortran_spec)
@end display

@cmd{DATA LIST FIXED} is used to read data files that have values at fixed
positions on each line of single-line or multiline records.  The
keyword FIXED is optional.

The FILE subcommand must be used if input is to be taken from an
external file.  It may be used to specify a filename as a string or a
file handle (@pxref{FILE HANDLE}).  If the FILE subcommand is not used,
then input is assumed to be specified within the command file using
@cmd{BEGIN DATA}@dots{}@cmd{END DATA} (@pxref{BEGIN DATA}).

The optional RECORDS subcommand, which takes a single integer as an
argument, is used to specify the number of lines per record.  If RECORDS
is not specified, then the number of lines per record is calculated from
the list of variable specifications later in @cmd{DATA LIST}.

The END subcommand is only useful in conjunction with @cmd{INPUT
PROGRAM}.  @xref{INPUT PROGRAM}, for details.

@cmd{DATA LIST} can optionally output a table describing how the data file
will be read.  The TABLE subcommand enables this output, and NOTABLE
disables it.  The default is to output the table.

The list of variables to be read from the data list must come last.
Each line in the data record is introduced by a slash (@samp{/}).
Optionally, a line number may follow the slash.  Following, any number
of variable specifications may be present.

Each variable specification consists of a list of variable names
followed by a description of their location on the input line.  Sets of
variables may specified using the @code{DATA LIST} TO convention
(@pxref{Sets of
Variables}).  There are two ways to specify the location of the variable
on the line: PSPP style and FORTRAN style.

With PSPP style, the starting column and ending column for the field
are specified after the variable name, separated by a dash (@samp{-}).
For instance, the third through fifth columns on a line would be
specified @samp{3-5}.  By default, variables are considered to be in
@samp{F} format (@pxref{Input/Output Formats}).  (This default can be
changed; see @ref{SET} for more information.)

When using PSPP style, to use a variable format other than the default,
specify the format type in parentheses after the column numbers.  For
instance, for alphanumeric @samp{A} format, use @samp{(A)}.  

In addition, implied decimal places can be specified in parentheses
after the column numbers.  As an example, suppose that a data file has a
field in which the characters @samp{1234} should be interpreted as
having the value 12.34.  Then this field has two implied decimal places,
and the corresponding specification would be @samp{(2)}.  If a field
that has implied decimal places contains a decimal point, then the
implied decimal places are not applied.

Changing the variable format and adding implied decimal places can be
done together; for instance, @samp{(N,5)}.

When using PSPP style, the input and output width of each variable is
computed from the field width.  The field width must be evenly divisible
into the number of variables specified.

FORTRAN style is an altogether different approach to specifying field
locations.  With this approach, a list of variable input format
specifications, separated by commas, are placed after the variable names
inside parentheses.  Each format specifier advances as many characters
into the input line as it uses.

In addition to the standard format specifiers (@pxref{Input/Output
Formats}), FORTRAN style defines some extensions:

@table @asis
@item @code{X}
Advance the current column on this line by one character position.

@item @code{T}@var{x}
Set the current column on this line to column @var{x}, with column
numbers considered to begin with 1 at the left margin.

@item @code{NEWREC}@var{x}
Skip forward @var{x} lines in the current record, resetting the active
column to the left margin.

@item Repeat count
Any format specifier may be preceded by a number.  This causes the
action of that format specifier to be repeated the specified number of
times.

@item (@var{spec1}, @dots{}, @var{specN})
Group the given specifiers together.  This is most useful when preceded
by a repeat count.  Groups may be nested arbitrarily.
@end table

FORTRAN and PSPP styles may be freely intermixed.  PSPP style leaves the
active column immediately after the ending column specified.  Record
motion using @code{NEWREC} in FORTRAN style also applies to later
FORTRAN and PSPP specifiers.
 
@menu
* DATA LIST FIXED Examples::    Examples of DATA LIST FIXED.
@end menu

@node DATA LIST FIXED Examples,  , DATA LIST FIXED, DATA LIST FIXED
@unnumberedsubsubsec Examples

@enumerate
@item
@example
DATA LIST TABLE /NAME 1-10 (A) INFO1 TO INFO3 12-17 (1).

BEGIN DATA.
John Smith 102311
Bob Arnold 122015
Bill Yates  918 6
END DATA.
@end example

Defines the following variables:

@itemize @bullet
@item
@code{NAME}, a 10-character-wide long string variable, in columns 1
through 10.

@item
@code{INFO1}, a numeric variable, in columns 12 through 13.

@item
@code{INFO2}, a numeric variable, in columns 14 through 15.

@item
@code{INFO3}, a numeric variable, in columns 16 through 17.
@end itemize

The @code{BEGIN DATA}/@code{END DATA} commands cause three cases to be
defined:

@example
Case   NAME         INFO1   INFO2   INFO3
   1   John Smith     10      23      11
   2   Bob Arnold     12      20      15
   3   Bill Yates      9      18       6
@end example

The @code{TABLE} keyword causes PSPP to print out a table
describing the four variables defined.

@item
@example
DAT LIS FIL="survey.dat"
        /ID 1-5 NAME 7-36 (A) SURNAME 38-67 (A) MINITIAL 69 (A)
        /Q01 TO Q50 7-56
        /.
@end example

Defines the following variables:

@itemize @bullet
@item
@code{ID}, a numeric variable, in columns 1-5 of the first record.

@item
@code{NAME}, a 30-character long string variable, in columns 7-36 of the
first record.

@item
@code{SURNAME}, a 30-character long string variable, in columns 38-67 of
the first record.

@item
@code{MINITIAL}, a 1-character short string variable, in column 69 of
the first record.

@item
Fifty variables @code{Q01}, @code{Q02}, @code{Q03}, @dots{}, @code{Q49},
@code{Q50}, all numeric, @code{Q01} in column 7, @code{Q02} in column 8,
@dots{}, @code{Q49} in column 55, @code{Q50} in column 56, all in the second
record.
@end itemize

Cases are separated by a blank record.

Data is read from file @file{survey.dat} in the current directory.

This example shows keywords abbreviated to their first 3 letters.

@end enumerate

@node DATA LIST FREE, DATA LIST LIST, DATA LIST FIXED, DATA LIST
@subsection DATA LIST FREE
@vindex DATA LIST FREE

@display
DATA LIST FREE
        [@{NOTABLE,TABLE@}]
        FILE='filename'
        END=end_var
        /var_spec@dots{}

where each var_spec takes one of the forms
        var_list [(type_spec)]
        var_list *
@end display

In free format, the input data is structured as a series of comma- or
whitespace-delimited fields (end of line is one form of whitespace; it
is not treated specially).  Field contents may be surrounded by matched
pairs of apostrophes (@samp{'}) or quotes (@samp{"}), or they may be
unenclosed.  For any type of field leading white space (up to the
apostrophe or quote, if any) is not included in the field.

Multiple consecutive delimiters are equivalent to a single delimiter.
To specify an empty field, write an empty set of single or double
quotes; for instance, @samp{""}.

The NOTABLE and TABLE subcommands are as in @cmd{DATA LIST FIXED} above.
NOTABLE is the default.

The FILE and END subcommands are as in @cmd{DATA LIST FIXED} above.

The variables to be parsed are given as a single list of variable names.
This list must be introduced by a single slash (@samp{/}).  The set of
variable names may contain format specifications in parentheses
(@pxref{Input/Output Formats}).  Format specifications apply to all
variables back to the previous parenthesized format specification.  

In addition, an asterisk may be used to indicate that all variables
preceding it are to have input/output format @samp{F8.0}.

Specified field widths are ignored on input, although all normal limits
on field width apply, but they are honored on output.

@node DATA LIST LIST,  , DATA LIST FREE, DATA LIST
@subsection DATA LIST LIST
@vindex DATA LIST LIST

@display
DATA LIST LIST
        [@{NOTABLE,TABLE@}]
        FILE='filename'
        END=end_var
        /var_spec@dots{}

where each var_spec takes one of the forms
        var_list [(type_spec)]
        var_list *
@end display

With one exception, @cmd{DATA LIST LIST} is syntactically and
semantically equivalent to @cmd{DATA LIST FREE}.  The exception is
that each input line is expected to correspond to exactly one input
record.  If more or fewer fields are found on an input line than
expected, an appropriate diagnostic is issued.

@node END CASE, END FILE, DATA LIST, Data Input and Output
@section END CASE
@vindex END CASE

@display
END CASE.
@end display

@cmd{END CASE} is used only within @cmd{INPUT PROGRAM} to output the
current case.  @xref{INPUT PROGRAM}, for details.

@node END FILE, FILE HANDLE, END CASE, Data Input and Output
@section END FILE
@vindex END FILE

@display
END FILE.
@end display

@cmd{END FILE} is used only within @cmd{INPUT PROGRAM} to terminate
the current input program.  @xref{INPUT PROGRAM}.

@node FILE HANDLE, INPUT PROGRAM, END FILE, Data Input and Output
@section FILE HANDLE
@vindex FILE HANDLE

@display
FILE HANDLE handle_name
        /NAME='filename'
        /RECFORM=@{VARIABLE,FIXED,SPANNED@}
        /LRECL=rec_len
        /MODE=@{CHARACTER,IMAGE,BINARY,MULTIPUNCH,360@}
@end display

Use @cmd{FILE HANDLE} to define the attributes of a file that does
not use conventional variable-length records terminated by new-line
characters.

Specify the file handle name as an identifier.  Any given identifier may
only appear once in a PSPP run.  File handles may not be reassigned to a
different file.  The file handle name must immediately follow the @cmd{FILE
HANDLE} command name.

The NAME subcommand specifies the name of the file associated with the
handle.  It is the only required subcommand.

The RECFORM subcommand specifies how the file is laid out.  VARIABLE
specifies variable-length lines terminated with new-lines, and it is the
default.  FIXED specifies fixed-length records.  SPANNED is not
supported.

LRECL specifies the length of fixed-length records.  It is required if
@code{/RECFORM FIXED} is specified.  

MODE specifies a file mode.  CHARACTER, the default, causes the data
file to be opened in ANSI C text mode.  BINARY causes the data file to
be opened in ANSI C binary mode.  The other possibilities are not
supported.

@node INPUT PROGRAM, LIST, FILE HANDLE, Data Input and Output
@section INPUT PROGRAM
@vindex INPUT PROGRAM

@display
INPUT PROGRAM.
@dots{} input commands @dots{}
END INPUT PROGRAM.
@end display

@cmd{INPUT PROGRAM}@dots{}@cmd{END INPUT PROGRAM} specifies a
complex input program.  By placing data input commands within @cmd{INPUT
PROGRAM}, PSPP programs can take advantage of more complex file
structures than available with only @cmd{DATA LIST}.

The first sort of extended input program is to simply put multiple @cmd{DATA
LIST} commands within the @cmd{INPUT PROGRAM}.  This will cause all of
the data
files to be read in parallel.  Input will stop when end of file is
reached on any of the data files.

Transformations, such as conditional and looping constructs, can also be
included within @cmd{INPUT PROGRAM}.  These can be used to combine input
from several data files in more complex ways.  However, input will still
stop when end of file is reached on any of the data files.

To prevent @cmd{INPUT PROGRAM} from terminating at the first end of
file, use
the END subcommand on @cmd{DATA LIST}.  This subcommand takes a
variable name,
which should be a numeric scratch variable (@pxref{Scratch Variables}).
(It need not be a scratch variable but otherwise the results can be
surprising.)  The value of this variable is set to 0 when reading the
data file, or 1 when end of file is encountered.

Two additional commands are useful in conjunction with @cmd{INPUT PROGRAM}.
@cmd{END CASE} is the first.  Normally each loop through the
@cmd{INPUT PROGRAM}
structure produces one case.  @cmd{END CASE} controls exactly
when cases are output.  When @cmd{END CASE} is used, looping from the end of
@cmd{INPUT PROGRAM} to the beginning does not cause a case to be output.

@cmd{END FILE} is the second.  When the END subcommand is used on @cmd{DATA
LIST}, there is no way for the @cmd{INPUT PROGRAM} construct to stop
looping,
so an infinite loop results.  @cmd{END FILE}, when executed,
stops the flow of input data and passes out of the @cmd{INPUT PROGRAM}
structure.

All this is very confusing.  A few examples should help to clarify.

@example
INPUT PROGRAM.
        DATA LIST NOTABLE FILE='a.data'/X 1-10.
        DATA LIST NOTABLE FILE='b.data'/Y 1-10.
END INPUT PROGRAM.
LIST.
@end example

The example above reads variable X from file @file{a.data} and variable
Y from file @file{b.data}.  If one file is shorter than the other then
the extra data in the longer file is ignored.

@example
INPUT PROGRAM.
        NUMERIC #A #B.
        
        DO IF NOT #A.
                DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
        END IF.
        DO IF NOT #B.
                DATA LIST NOTABLE END=#B FILE='b.data'/Y 1-10.
        END IF.
        DO IF #A AND #B.
                END FILE.
        END IF.
        END CASE.
END INPUT PROGRAM.
LIST.
@end example

The above example reads variable X from @file{a.data} and variable Y from
@file{b.data}.  If one file is shorter than the other then the missing
field is set to the system-missing value alongside the present value for
the remaining length of the longer file.

@example
INPUT PROGRAM.
        NUMERIC #A #B.

        DO IF #A.
                DATA LIST NOTABLE END=#B FILE='b.data'/X 1-10.
                DO IF #B.
                        END FILE.
                ELSE.
                        END CASE.
                END IF.
        ELSE.
                DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
                DO IF NOT #A.
                        END CASE.
                END IF.
        END IF.
END INPUT PROGRAM.
LIST.
@end example

The above example reads data from file @file{a.data}, then from
@file{b.data}, and concatenates them into a single active file.

@example
INPUT PROGRAM.
        NUMERIC #EOF.

        LOOP IF NOT #EOF.
                DATA LIST NOTABLE END=#EOF FILE='a.data'/X 1-10.
                DO IF NOT #EOF.
                        END CASE.
                END IF.
        END LOOP.

        COMPUTE #EOF = 0.
        LOOP IF NOT #EOF.
                DATA LIST NOTABLE END=#EOF FILE='b.data'/X 1-10.
                DO IF NOT #EOF.
                        END CASE.
                END IF.
        END LOOP.

        END FILE.
END INPUT PROGRAM.
LIST.
@end example

The above example does the same thing as the previous example, in a
different way.

@example
INPUT PROGRAM.
        LOOP #I=1 TO 50.
                COMPUTE X=UNIFORM(10).
                END CASE.
        END LOOP.
        END FILE.
END INPUT PROGRAM.
LIST/FORMAT=NUMBERED.
@end example

The above example causes an active file to be created consisting of 50
random variates between 0 and 10.

@node LIST, MATRIX DATA, INPUT PROGRAM, Data Input and Output
@section LIST
@vindex LIST

@display
LIST
        /VARIABLES=var_list
        /CASES=FROM start_index TO end_index BY incr_index
        /FORMAT=@{UNNUMBERED,NUMBERED@} @{WRAP,SINGLE@} 
                @{NOWEIGHT,WEIGHT@}
@end display

The @cmd{LIST} procedure prints the values of specified variables to the
listing file.

The VARIABLES subcommand specifies the variables whose values are to be
printed.  Keyword VARIABLES is optional.  If VARIABLES subcommand is not
specified then all variables in the active file are printed.

The CASES subcommand can be used to specify a subset of cases to be
printed.  Specify FROM and the case number of the first case to print,
TO and the case number of the last case to print, and BY and the number
of cases to advance between printing cases, or any subset of those
settings.  If CASES is not specified then all cases are printed.

The FORMAT subcommand can be used to change the output format.  NUMBERED
will print case numbers along with each case; UNNUMBERED, the default,
causes the case numbers to be omitted.  The WRAP and SINGLE settings are
currently not used.  WEIGHT will cause case weights to be printed along
with variable values; NOWEIGHT, the default, causes case weights to be
omitted from the output.

Case numbers start from 1.  They are counted after all transformations
have been considered.

@cmd{LIST} attempts to fit all the values on a single line.  If needed
to make them fit, variable names are displayed vertically.  If values
cannot fit on a single line, then a multi-line format will be used.

@cmd{LIST} is a procedure.  It causes the data to be read.

@node MATRIX DATA, NEW FILE, LIST, Data Input and Output
@section MATRIX DATA
@vindex MATRIX DATA

@display
MATRIX DATA
        /VARIABLES=var_list
        /FILE='filename'
        /FORMAT=@{LIST,FREE@} @{LOWER,UPPER,FULL@} @{DIAGONAL,NODIAGONAL@}
        /SPLIT=@{new_var,var_list@}
        /FACTORS=var_list
        /CELLS=n_cells
        /N=n
        /CONTENTS=@{N_VECTOR,N_SCALAR,N_MATRIX,MEAN,STDDEV,COUNT,MSE,
                   DFE,MAT,COV,CORR,PROX@}
@end display

@cmd{MATRIX DATA} command reads square matrices in one of several textual
formats.  @cmd{MATRIX DATA} clears the dictionary and replaces it and
reads a
data file.

Use VARIABLES to specify the variables that form the rows and columns of
the matrices.  You may not specify a variable named @code{VARNAME_}.  You
should specify VARIABLES first.

Specify the file to read on FILE, either as a file name string or a file
handle (@pxref{FILE HANDLE}).  If FILE is not specified then matrix data
must immediately follow @cmd{MATRIX DATA} with a @cmd{BEGIN
DATA}@dots{}@cmd{END DATA}
construct (@pxref{BEGIN DATA}).

The FORMAT subcommand specifies how the matrices are formatted.  LIST,
the default, indicates that there is one line per row of matrix data;
FREE allows single matrix rows to be broken across multiple lines.  This
is analogous to the difference between @cmd{DATA LIST FREE} and
@cmd{DATA LIST LIST}
(@pxref{DATA LIST}).  LOWER, the default, indicates that the lower
triangle of the matrix is given; UPPER indicates the upper triangle; and
FULL indicates that the entire matrix is given.  DIAGONAL, the default,
indicates that the diagonal is part of the data; NODIAGONAL indicates
that it is omitted.  DIAGONAL/NODIAGONAL have no effect when FULL is
specified.

The SPLIT subcommand is used to specify @cmd{SPLIT FILE} variables for the
input matrices (@pxref{SPLIT FILE}).  Specify either a single variable
not specified on VARIABLES, or one or more variables that are specified
on VARIABLES.  In the former case, the SPLIT values are not present in
the data and ROWTYPE_ may not be specified on VARIABLES.  In the latter
case, the SPLIT values are present in the data.

Specify a list of factor variables on FACTORS.  Factor variables must
also be listed on VARIABLES.  Factor variables are used when there are
some variables where, for each possible combination of their values,
statistics on the matrix variables are included in the data.

If FACTORS is specified and ROWTYPE_ is not specified on VARIABLES, the
CELLS subcommand is required.  Specify the number of factor variable
combinations that are given.  For instance, if factor variable A has 2
values and factor variable B has 3 values, specify 6.

The N subcommand specifies a population number of observations.  When N
is specified, one N record is output for each @cmd{SPLIT FILE}.

Use CONTENTS to specify what sort of information the matrices include.
Each possible option is described in more detail below.  When ROWTYPE_
is specified on VARIABLES, CONTENTS is optional; otherwise, if CONTENTS
is not specified then /CONTENTS=CORR is assumed.

@table @asis
@item N
@item N_VECTOR
Number of observations as a vector, one value for each variable.
@item N_SCALAR
Number of observations as a single value.
@item N_MATRIX
Matrix of counts.
@item MEAN
Vector of means.
@item STDDEV
Vector of standard deviations.
@item COUNT
Vector of counts.
@item MSE
Vector of mean squared errors.
@item DFE
Vector of degrees of freedom.
@item MAT
Generic matrix.
@item COV
Covariance matrix.
@item CORR
Correlation matrix.
@item PROX
Proximities matrix.
@end table

The exact semantics of the matrices read by @cmd{MATRIX DATA} are complex.
Right now @cmd{MATRIX DATA} isn't too useful due to a lack of procedures
accepting or producing related data, so these semantics aren't
documented.  Later, they'll be described here in detail.

@node NEW FILE, PRINT, MATRIX DATA, Data Input and Output
@section NEW FILE
@vindex NEW FILE

@display
NEW FILE.
@end display

@cmd{NEW FILE} command clears the current active file.

@node PRINT, PRINT EJECT, NEW FILE, Data Input and Output
@section PRINT
@vindex PRINT

@display
PRINT 
        OUTFILE='filename'
        RECORDS=n_lines
        @{NOTABLE,TABLE@}
        /[line_no] arg@dots{}

arg takes one of the following forms:
        'string' [start-end]
        var_list start-end [type_spec]
        var_list (fortran_spec)
        var_list *
@end display

The @cmd{PRINT} transformation writes variable data to an output file.
@cmd{PRINT} is executed when a procedure causes the data to be read.
Follow @cmd{PRINT} by @cmd{EXECUTE} to print variable data without
invoking a procedure (@pxref{EXECUTE}).

All @cmd{PRINT} subcommands are optional.

The OUTFILE subcommand specifies the file to receive the output.  The
file may be a file name as a string or a file handle (@pxref{FILE
HANDLE}).  If OUTFILE is not present then output will be sent to PSPP's
output listing file.

The RECORDS subcommand specifies the number of lines to be output.  The
number of lines may optionally be surrounded by parentheses.

TABLE will cause the PRINT command to output a table to the listing file
that describes what it will print to the output file.  NOTABLE, the
default, suppresses this output table.

Introduce the strings and variables to be printed with a slash
(@samp{/}).  Optionally, the slash may be followed by a number
indicating which output line will be specified.  In the absence of this
line number, the next line number will be specified.  Multiple lines may
be specified using multiple slashes with the intended output for a line
following its respective slash.

Literal strings may be printed.  Specify the string itself.  Optionally
the string may be followed by a column number or range of column
numbers, specifying the location on the line for the string to be
printed.  Otherwise, the string will be printed at the current position
on the line.

Variables to be printed can be specified in the same ways as available
for @cmd{DATA LIST FIXED} (@pxref{DATA LIST FIXED}).  In addition, a
variable
list may be followed by an asterisk (@samp{*}), which indicates that the
variables should be printed in their dictionary print formats, separated
by spaces.  A variable list followed by a slash or the end of command
will be interpreted the same way.

If a FORTRAN type specification is used to move backwards on the current
line, then text is written at that point on the line, the line will be
truncated to that length, although additional text being added will
again extend the line to that length.

@node PRINT EJECT, PRINT SPACE, PRINT, Data Input and Output
@section PRINT EJECT
@vindex PRINT EJECT

@display
PRINT EJECT 
        OUTFILE='filename'
        RECORDS=n_lines
        @{NOTABLE,TABLE@}
        /[line_no] arg@dots{}

arg takes one of the following forms:
        'string' [start-end]
        var_list start-end [type_spec]
        var_list (fortran_spec)
        var_list *
@end display

@cmd{PRINT EJECT} writes data to an output file.  Before the data is
written, the current page in the listing file is ejected.

@xref{PRINT}, for more information on syntax and usage.

@node PRINT SPACE, REREAD, PRINT EJECT, Data Input and Output
@section PRINT SPACE
@vindex PRINT SPACE

@display
PRINT SPACE OUTFILE='filename' n_lines.
@end display

@cmd{PRINT SPACE} prints one or more blank lines to an output file.

The OUTFILE subcommand is optional.  It may be used to direct output to
a file specified by file name as a string or file handle (@pxref{FILE
HANDLE}).  If OUTFILE is not specified then output will be directed to
the listing file.

n_lines is also optional.  If present, it is an expression
(@pxref{Expressions}) specifying the number of blank lines to be
printed.  The expression must evaluate to a nonnegative value.

@node REREAD, REPEATING DATA, PRINT SPACE, Data Input and Output
@section REREAD
@vindex REREAD

@display
REREAD FILE=handle COLUMN=column.
@end display

The @cmd{REREAD} transformation allows the previous input line in a
data file
already processed by @cmd{DATA LIST} or another input command to be re-read
for further processing.

The FILE subcommand, which is optional, is used to specify the file to
have its line re-read.  The file must be specified in the form of a file
handle (@pxref{FILE HANDLE}).  If FILE is not specified then the last
file specified on @cmd{DATA LIST} will be assumed (last file specified
lexically, not in terms of flow-of-control).

By default, the line re-read is re-read in its entirety.  With the
COLUMN subcommand, a prefix of the line can be exempted from
re-reading.  Specify an expression (@pxref{Expressions}) evaluating to
the first column that should be included in the re-read line.  Columns
are numbered from 1 at the left margin.

Issuing @code{REREAD} multiple times will not back up in the data
file.  Instead, it will re-read the same line multiple times.

@node REPEATING DATA, WRITE, REREAD, Data Input and Output
@section REPEATING DATA
@vindex REPEATING DATA

@display
REPEATING DATA
        /STARTS=start-end
        /OCCURS=n_occurs
        /FILE='filename'
        /LENGTH=length
        /CONTINUED[=cont_start-cont_end]
        /ID=id_start-id_end=id_var
        /@{TABLE,NOTABLE@}
        /DATA=var_spec@dots{}

where each var_spec takes one of the forms
        var_list start-end [type_spec]
        var_list (fortran_spec)
@end display

@cmd{REPEATING DATA} parses groups of data repeating in
a uniform format, possibly with several groups on a single line.  Each
group of data corresponds with one case.  @cmd{REPEATING DATA} may only be
used within an @cmd{INPUT PROGRAM} structure (@pxref{INPUT PROGRAM}).
When used with @cmd{DATA LIST}, it
can be used to parse groups of cases that share a subset of variables
but differ in their other data.

The STARTS subcommand is required.  Specify a range of columns, using
literal numbers or numeric variable names.  This range specifies the
columns on the first line that are used to contain groups of data.  The
ending column is optional.  If it is not specified, then the record
width of the input file is used.  For the inline file (@pxref{BEGIN
DATA}) this is 80 columns; for a file with fixed record widths it is the
record width; for other files it is 1024 characters by default.

The OCCURS subcommand is required.  It must be a number or the name of a
numeric variable.  Its value is the number of groups present in the
current record.

The DATA subcommand is required.  It must be the last subcommand
specified.  It is used to specify the data present within each repeating
group.  Column numbers are specified relative to the beginning of a
group at column 1.  Data is specified in the same way as with @cmd{DATA LIST
FIXED} (@pxref{DATA LIST FIXED}).

All other subcommands are optional.

FILE specifies the file to read, either a file name as a string or a
file handle (@pxref{FILE HANDLE}).  If FILE is not present then the
default is the last file handle used on @cmd{DATA LIST} (lexically, not in
terms of flow of control).

By default @cmd{REPEATING DATA} will output a table describing how it will
parse the input data.  Specifying NOTABLE will disable this behavior;
specifying TABLE will explicitly enable it.

The LENGTH subcommand specifies the length in characters of each group.
If it is not present then length is inferred from the DATA subcommand.
LENGTH can be a number or a variable name.

Normally all the data groups are expected to be present on a single
line.  Use the CONTINUED command to indicate that data can be continued
onto additional lines.  If data on continuation lines starts at the left
margin and continues through the entire field width, no column
specifications are necessary on CONTINUED.  Otherwise, specify the
possible range of columns in the same way as on STARTS.

When data groups are continued from line to line, it is easy
for cases to get out of sync through careless hand editing.  The
ID subcommand allows a case identifier to be present on each line of
repeating data groups.  @cmd{REPEATING DATA} will check for the same
identifier on each line and report mismatches.  Specify the range of
columns that the identifier will occupy, followed by an equals sign
(@samp{=}) and the identifier variable name.  The variable must already
have been declared with @cmd{NUMERIC} or another command.

@cmd{REPEATING DATA} should be the last command given within an
@cmd{INPUT PROGRAM}.  It should not be enclosed within a @cmd{LOOP}
structure (@pxref{LOOP}).  Use @cmd{DATA LIST} before, not after,
@cmd{REPEATING DATA}.

@node WRITE,  , REPEATING DATA, Data Input and Output
@section WRITE
@vindex WRITE

@display
WRITE 
        OUTFILE='filename'
        RECORDS=n_lines
        @{NOTABLE,TABLE@}
        /[line_no] arg@dots{}

arg takes one of the following forms:
        'string' [start-end]
        var_list start-end [type_spec]
        var_list (fortran_spec)
        var_list *
@end display

@code{WRITE} writes text or binary data to an output file.  

@xref{PRINT}, for more information on syntax and usage.  The main
difference between @code{PRINT} and @code{WRITE} is that @cmd{WRITE}
uses write formats by default, where PRINT uses print formats.

The sole additional difference is that if @cmd{WRITE} is used to send output
to a binary file, carriage control characters will not be output.
@xref{FILE HANDLE}, for information on how to declare a file as binary.

@node System and Portable Files, Variable Attributes, Data Input and Output, Top
@chapter System Files and Portable Files

The commands in this chapter read, write, and examine system files and
portable files.

@menu
* APPLY DICTIONARY::            Apply system file dictionary to active file.
* EXPORT::                      Write to a portable file.
* GET::                         Read from a system file.
* IMPORT::                      Read from a portable file.
* MATCH FILES::                 Merge system files.
* SAVE::                        Write to a system file.
* SYSFILE INFO::                Display system file dictionary.
* XSAVE::                       Write to a system file, as a transform.
@end menu

@node APPLY DICTIONARY, EXPORT, System and Portable Files, System and Portable Files
@section APPLY DICTIONARY
@vindex APPLY DICTIONARY

@display
APPLY DICTIONARY FROM='filename'.
@end display

@cmd{APPLY DICTIONARY} applies the variable labels, value labels,
and missing values from variables in a system file to corresponding
variables in the active file.  In some cases it also updates the
weighting variable.

Specify a system file with a file name string or as a file handle
(@pxref{FILE HANDLE}).  The dictionary in the system file will be read,
but it will not replace the active file dictionary.  The system file's
data will not be read.

Only variables with names that exist in both the active file and the
system file are considered.  Variables with the same name but different
types (numeric, string) will cause an error message.  Otherwise, the
system file variables' attributes will replace those in their matching
active file variables, as described below.

If a system file variable has a variable label, then it will replace the
active file variable's variable label.  If the system file variable does
not have a variable label, then the active file variable's variable
label, if any, will be retained.

If the active file variable is numeric or short string, then value
labels and missing values, if any, will be copied to the active file
variable.  If the system file variable does not have value labels or
missing values, then those in the active file variable, if any, will not
be disturbed.

Finally, weighting of the active file is updated (@pxref{WEIGHT}).  If
the active file has a weighting variable, and the system file does not,
or if the weighting variable in the system file does not exist in the
active file, then the active file weighting variable, if any, is
retained.  Otherwise, the weighting variable in the system file becomes
the active file weighting variable.

@cmd{APPLY DICTIONARY} takes effect immediately.  It does not read the
active
file.  The system file is not modified.

@node EXPORT, GET, APPLY DICTIONARY, System and Portable Files
@section EXPORT
@vindex EXPORT

@display
EXPORT
        /OUTFILE='filename'
        /DROP=var_list
        /KEEP=var_list
        /RENAME=(src_names=target_names)@dots{}
@end display

The @cmd{EXPORT} procedure writes the active file dictionary and data to a
specified portable file.

The OUTFILE subcommand, which is the only required subcommand, specifies
the portable file to be written as a file name string or a file handle
(@pxref{FILE HANDLE}).

DROP, KEEP, and RENAME follow the same format as the SAVE procedure
(@pxref{SAVE}).

@cmd{EXPORT} is a procedure.  It causes the active file to be read.

@node GET, IMPORT, EXPORT, System and Portable Files
@section GET
@vindex GET

@display
GET
        /FILE='filename'
        /DROP=var_list
        /KEEP=var_list
        /RENAME=(src_names=target_names)@dots{}
@end display

@cmd{GET} clears the current dictionary and active file and
replaces them with the dictionary and data from a specified system file.

The FILE subcommand is the only required subcommand.  Specify the system
file to be read as a string file name or a file handle (@pxref{FILE
HANDLE}).

By default, all the variables in a system file are read.  The DROP
subcommand can be used to specify a list of variables that are not to be
read.  By contrast, the KEEP subcommand can be used to specify variable
that are to be read, with all other variables not read.

Normally variables in a system file retain the names that they were
saved under.  Use the RENAME subcommand to change these names.  Specify,
within parentheses, a list of variable names followed by an equals sign
(@samp{=}) and the names that they should be renamed to.  Multiple
parenthesized groups of variable names can be included on a single
RENAME subcommand.  Variables' names may be swapped using a RENAME
subcommand of the form @samp{/RENAME=(A B=B A)}.

Alternate syntax for the RENAME subcommand allows the parentheses to be
eliminated.  When this is done, only a single variable may be renamed at
once.  For instance, @samp{/RENAME=A=B}.  This alternate syntax is
deprecated.

DROP, KEEP, and RENAME are performed in left-to-right order.  They
each may be present any number of times.  @cmd{GET} never modifies a
system file on disk.  Only the active file read from the system file
is affected by these subcommands.

@cmd{GET} does not cause the data to be read, only the dictionary.  The data
is read later, when a procedure is executed.

@node IMPORT, MATCH FILES, GET, System and Portable Files
@section IMPORT
@vindex IMPORT

@display
IMPORT
        /FILE='filename'
        /TYPE=@{COMM,TAPE@}
        /DROP=var_list
        /KEEP=var_list
        /RENAME=(src_names=target_names)@dots{}
@end display

The @cmd{IMPORT} transformation clears the active file dictionary and
data and
replaces them with a dictionary and data from a portable file on disk.

The FILE subcommand, which is the only required subcommand, specifies
the portable file to be read as a file name string or a file handle
(@pxref{FILE HANDLE}).

The TYPE subcommand is currently not used.

DROP, KEEP, and RENAME follow the syntax used by @cmd{GET} (@pxref{GET}).

@cmd{IMPORT} does not cause the data to be read, only the dictionary.  The
data is read later, when a procedure is executed.

@node MATCH FILES, SAVE, IMPORT, System and Portable Files
@section MATCH FILES
@vindex MATCH FILES

@display
MATCH FILES
        /BY var_list
        /@{FILE,TABLE@}=@{*,'filename'@}
        /DROP=var_list
        /KEEP=var_list
        /RENAME=(src_names=target_names)@dots{}
        /IN=var_name
        /FIRST=var_name
        /LAST=var_name
        /MAP
@end display

@cmd{MATCH FILES} merges one or more system files, optionally
including the active file.  Records with the same values for BY
variables are combined into a single record.  Records with different
values are output in order.  Thus, multiple sorted system files are
combined into a single sorted system file based on the value of the BY
variables.  The results of the merge become the new active file.

The BY subcommand specifies a list of variables that are used to match
records from each of the system files.  Variables specified must exist
in all the files specified on FILE and TABLE.  BY should usually be
specified.  If TABLE is used then BY is required.

Specify FILE with a system file as a file name string or file handle
(@pxref{FILE HANDLE}), or with an asterisk (@samp{*}) to
indicate the current active file.  The files specified on FILE are
merged together based on the BY variables, or combined case-by-case if
BY is not specified.  Normally at least two FILE subcommands should be
specified.

Specify TABLE with a system file to use it as a @dfn{table
lookup file}.  Records in table lookup files are not used up after
they've been used once.  This means that data in table lookup files can
correspond to any number of records in FILE files.  Table lookup files
correspond to lookup tables in traditional relational database systems.
It is incorrect to have records with duplicate BY values in table lookup
files.

Any number of FILE and TABLE subcommands may be specified.  Each
instance of FILE or TABLE can be followed by DROP, KEEP, and/or RENAME
subcommands.  These take the same form as the corresponding subcommands
of @cmd{GET} (@pxref{GET}), and perform the same functions.

Variables belonging to files that are not present for the current case
are set to the system-missing value for numeric variables or spaces for
string variables.

IN, FIRST, LAST, and MAP are currently not used.

@cmd{MATCH FILES} may not be specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}) if the active file is used as an input source.

@node SAVE, SYSFILE INFO, MATCH FILES, System and Portable Files
@section SAVE
@vindex SAVE

@display
SAVE
        /OUTFILE='filename'
        /@{COMPRESSED,UNCOMPRESSED@}
        /DROP=var_list
        /KEEP=var_list
        /RENAME=(src_names=target_names)@dots{}
@end display

The @cmd{SAVE} procedure causes the dictionary and data in the active
file to
be written to a system file.

FILE is the only required subcommand.  Specify the system
file to be written as a string file name or a file handle (@pxref{FILE
HANDLE}).

The COMPRESS and UNCOMPRESS subcommand determine whether the saved
system file is compressed.  By default, system files are compressed.
This default can be changed with the SET command (@pxref{SET}).

By default, all the variables in the active file dictionary are written
to the system file.  The DROP subcommand can be used to specify a list
of variables not to be written.  In contrast, KEEP specifies variables
to be written, with all variables not specified not written.

Normally variables are saved to a system file under the same names they
have in the active file.  Use the RENAME subcommand to change these names.
Specify, within parentheses, a list of variable names followed by an
equals sign (@samp{=}) and the names that they should be renamed to.
Multiple parenthesized groups of variable names can be included on a
single RENAME subcommand.  Variables' names may be swapped using a
RENAME subcommand of the form @samp{/RENAME=(A B=B A)}.

Alternate syntax for the RENAME subcommand allows the parentheses to be
eliminated.  When this is done, only a single variable may be renamed at
once.  For instance, @samp{/RENAME=A=B}.  This alternate syntax is
deprecated.

DROP, KEEP, and RENAME are performed in left-to-right order.  They
each may be present any number of times.  @cmd{SAVE} never modifies
the active file.  DROP, KEEP, and RENAME only affect the system file
written to disk.

@cmd{SAVE} causes the data to be read.  It is a procedure.

@node SYSFILE INFO, XSAVE, SAVE, System and Portable Files
@section SYSFILE INFO
@vindex SYSFILE INFO

@display 
SYSFILE INFO FILE='filename'.
@end display

@cmd{SYSFILE INFO} reads the dictionary in a system file and
displays the information in its dictionary.

Specify a file name or file handle.  @cmd{SYSFILE INFO} reads that file as
a system file and displays information on its dictionary.

@cmd{SYSFILE INFO} does not affect the current active file.

@node XSAVE,  , SYSFILE INFO, System and Portable Files
@section XSAVE
@vindex XSAVE

@display
XSAVE
        /FILE='filename'
        /@{COMPRESSED,UNCOMPRESSED@}
        /DROP=var_list
        /KEEP=var_list
        /RENAME=(src_names=target_names)@dots{}
@end display

The @cmd{XSAVE} transformation writes the active file dictionary and
data to a
system file stored on disk.

@cmd{XSAVE} is a transformation, not a procedure.  It is executed when the
data is read by a procedure or procedure-like command.  In all other
respects, @cmd{XSAVE} is identical to @cmd{SAVE}.  @xref{SAVE}, for
more information
on syntax and usage.

@node Variable Attributes, Data Manipulation, System and Portable Files, Top
@chapter Manipulating variables

The variables in the active file dictionary are important.  There are
several utility functions for examining and adjusting them.

@menu
* ADD VALUE LABELS::            Add value labels to variables.
* DISPLAY::                     Display variable names & descriptions.
* DISPLAY VECTORS::             Display a list of vectors.
* FORMATS::                     Set print and write formats.
* LEAVE::                       Don't clear variables between cases.
* MISSING VALUES::              Set missing values for variables.
* MODIFY VARS::                 Rename, reorder, and drop variables.
* NUMERIC::                     Create new numeric variables.
* PRINT FORMATS::               Set variable print formats.
* RENAME VARIABLES::            Rename variables.
* VALUE LABELS::                Set value labels for variables.
* STRING::                      Create new string variables.
* VARIABLE LABELS::             Set variable labels for variables.
* VECTOR::                      Declare an array of variables.
* WRITE FORMATS::               Set variable write formats.
@end menu

@node ADD VALUE LABELS, DISPLAY, Variable Attributes, Variable Attributes
@section ADD VALUE LABELS
@vindex ADD VALUE LABELS

@display 
ADD VALUE LABELS
        /var_list value 'label' [value 'label']@dots{}
@end display

@cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
LABELS} (@pxref{VALUE LABELS}), but it does not clear value
labels from the variables before adding the ones specified.

@node DISPLAY, DISPLAY VECTORS, ADD VALUE LABELS, Variable Attributes
@section DISPLAY
@vindex DISPLAY

@display
DISPLAY @{NAMES,INDEX,LABELS,VARIABLES,DICTIONARY,SCRATCH@}
        [SORTED] [var_list]
@end display

@cmd{DISPLAY} displays requested information on variables.  Variables can
optionally be sorted alphabetically.  The entire dictionary or just
specified variables can be described.

One of the following keywords can be present:

@table @asis
@item NAMES
The variables' names are displayed.

@item INDEX
The variables' names are displayed along with a value describing their
position within the active file dictionary.

@item LABELS
Variable names, positions, and variable labels are displayed.

@item VARIABLES
Variable names, positions, print and write formats, and missing values
are displayed.

@item DICTIONARY
Variable names, positions, print and write formats, missing values,
variable labels, and value labels are displayed.

@item SCRATCH
Varible names are displayed, for scratch variables only (@pxref{Scratch
Variables}).
@end table

If SORTED is specified, then the variables are displayed in ascending
order based on their names; otherwise, they are displayed in the order
that they occur in the active file dictionary.

@node DISPLAY VECTORS, FORMATS, DISPLAY, Variable Attributes
@section DISPLAY VECTORS
@vindex DISPLAY VECTORS

@display
DISPLAY VECTORS.
@end display

@cmd{DISPLAY VECTORS} lists all the currently declared vectors.

@node FORMATS, LEAVE, DISPLAY VECTORS, Variable Attributes
@section FORMATS
@vindex FORMATS

@display
FORMATS var_list (fmt_spec).
@end display

@cmd{FORMATS} set both print and write formats for the specified
variables to the specified format specification.  @xref{Input/Output
Formats}.

Specify a list of variables followed by a format specification in
parentheses.  The print and write formats of the specified variables
will be changed.

Additional lists of variables and formats may be included if they are
delimited by a slash (@samp{/}).

@cmd{FORMATS} takes effect immediately.  It is not affected by
conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.

@node LEAVE, MISSING VALUES, FORMATS, Variable Attributes
@section LEAVE
@vindex LEAVE

@display
LEAVE var_list.
@end display

@cmd{LEAVE} prevents the specified variables from being
reinitialized whenever a new case is processed.

Normally, when a data file is processed, every variable in the active
file is initialized to the system-missing value or spaces at the
beginning of processing for each case.  When a variable has been
specified on @cmd{LEAVE}, this is not the case.  Instead, that variable is
initialized to 0 (not system-missing) or spaces for the first case.
After that, it retains its value between cases.

This becomes useful for counters.  For instance, in the example below
the variable SUM maintains a running total of the values in the ITEM
variable.

@example
DATA LIST /ITEM 1-3.
COMPUTE SUM=SUM+ITEM.
PRINT /ITEM SUM.
LEAVE SUM
BEGIN DATA.
123
404
555
999
END DATA.
@end example

@noindent Partial output from this example:

@example
123   123.00
404   527.00
555  1082.00
999  2081.00
@end example

It is best to use @cmd{LEAVE} command immediately before invoking a
procedure command, because the left status of variables is reset by
certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
Left status is also reset by all procedure invocations.

@node MISSING VALUES, MODIFY VARS, LEAVE, Variable Attributes
@section MISSING VALUES
@vindex MISSING VALUES

@display
MISSING VALUES var_list (missing_values).

missing_values takes one of the following forms:
        num1
        num1, num2
        num1, num2, num3
        num1 THRU num2
        num1 THRU num2, num3
        string1
        string1, string2
        string1, string2, string3
As part of a range, LO or LOWEST may take the place of num1;
HI or HIGHEST may take the place of num2.
@end display

@cmd{MISSING VALUES} sets user-missing values for numeric and
short string variables.  Long string variables may not have missing
values.

Specify a list of variables, followed by a list of their user-missing
values in parentheses.  Up to three discrete values may be given, or,
for numeric variables only, a range of values optionally accompanied by
a single discrete value.  Ranges may be open-ended on one end, indicated
through the use of the keyword LO or LOWEST or HI or HIGHEST.

The @cmd{MISSING VALUES} command takes effect immediately.  It is not
affected by conditional and looping constructs such as @cmd{DO IF} or
@cmd{LOOP}.

@node MODIFY VARS, NUMERIC, MISSING VALUES, Variable Attributes
@section MODIFY VARS
@vindex MODIFY VARS

@display 
MODIFY VARS
        /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
        /RENAME=(old_names=new_names)@dots{}
        /@{DROP,KEEP@}=var_list
        /MAP    
@end display

@cmd{MODIFY VARS} reorders, renames, and deletes variables in the
active file.

At least one subcommand must be specified, and no subcommand may be
specified more than once.  DROP and KEEP may not both be specified.

The REORDER subcommand changes the order of variables in the active
file.  Specify one or more lists of variable names in parentheses.  By
default, each list of variables is rearranged into the specified order.
To put the variables into the reverse of the specified order, put
keyword BACKWARD before the parentheses.  To put them into alphabetical
order in the dictionary, specify keyword ALPHA before the parentheses.
BACKWARD and ALPHA may also be combined.

To rename variables in the active file, specify RENAME, an equals sign
(@samp{=}), and lists of the old variable names and new variable names
separated by another equals sign within parentheses.  There must be the
same number of old and new variable names.  Each old variable is renamed to
the corresponding new variable name.  Multiple parenthesized groups of
variables may be specified.

The DROP subcommand deletes a specified list of variables from the
active file.

The KEEP subcommand keeps the specified list of variables in the active
file.  Any unlisted variables are deleted from the active file.

MAP is currently ignored.

If either DROP or KEEP is specified, the data is read; otherwise it is
not.

@cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}).

@node NUMERIC, PRINT FORMATS, MODIFY VARS, Variable Attributes
@section NUMERIC
@vindex NUMERIC

@display
NUMERIC /var_list [(fmt_spec)].
@end display

@cmd{NUMERIC} explicitly declares new numeric variables, optionally
setting their output formats.

Specify a slash (@samp{/}), followed by the names of the new numeric
variables.  If you wish to set their output formats, follow their names
by an output format specification in parentheses (@pxref{Input/Output
Formats}); otherwise, the default is F8.2.

Variables created with @cmd{NUMERIC} are initialized to the
system-missing value.

@node PRINT FORMATS, RENAME VARIABLES, NUMERIC, Variable Attributes
@section PRINT FORMATS
@vindex PRINT FORMATS

@display
PRINT FORMATS var_list (fmt_spec).
@end display

@cmd{PRINT FORMATS} sets the print formats for the specified
variables to the specified format specification.

Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
but @cmd{PRINT FORMATS} sets only print formats, not write formats.

@node RENAME VARIABLES, VALUE LABELS, PRINT FORMATS, Variable Attributes
@section RENAME VARIABLES
@vindex RENAME VARIABLES

@display
RENAME VARIABLES (old_names=new_names)@dots{} .
@end display

@cmd{RENAME VARIABLES} changes the names of variables in the active
file.  Specify lists of the old variable names and new
variable names, separated by an equals sign (@samp{=}), within
parentheses.  There must be the same number of old and new variable
names.  Each old variable is renamed to the corresponding new variable
name.  Multiple parenthesized groups of variables may be specified.

@cmd{RENAME VARIABLES} takes effect immediately.  It does not cause the data
to be read.

@cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}).

@node VALUE LABELS, STRING, RENAME VARIABLES, Variable Attributes
@section VALUE LABELS
@vindex VALUE LABELS

@display 
VALUE LABELS
        /var_list value 'label' [value 'label']@dots{}
@end display

@cmd{VALUE LABELS} allows values of numeric and short string
variables to be associated with labels.  In this way, a short value can
stand for a long value.

To set up value labels for a set of variables, specify the
variable names after a slash (@samp{/}), followed by a list of values
and their associated labels, separated by spaces.  Long string
variables may not be specified.

Before @cmd{VALUE LABELS} is executed, any existing value labels
are cleared from the variables specified.  Use @cmd{ADD VALUE LABELS}
(@pxref{ADD VALUE LABELS}) to add value labels without clearing those
already present.

@node STRING, VARIABLE LABELS, VALUE LABELS, Variable Attributes
@section STRING
@vindex STRING

@display
STRING /var_list (fmt_spec).
@end display

@cmd{STRING} creates new string variables for use in
transformations.

Specify a slash (@samp{/}), followed by the names of the string
variables to create and the desired output format specification in
parentheses (@pxref{Input/Output Formats}).  Variable widths are
implicitly derived from the specified output formats.

Created variables are initialized to spaces.

@node VARIABLE LABELS, VECTOR, STRING, Variable Attributes
@section VARIABLE LABELS
@vindex VARIABLE LABELS

@display
VARIABLE LABELS
        /var_list 'var_label'.
@end display

@cmd{VARIABLE LABELS} associates explanatory names
with variables.  This name, called a @dfn{variable label}, is displayed by
statistical procedures.

To assign a variable label to a group of variables, specify a slash
(@samp{/}), followed by the list of variable names and the variable
label as a string.

@node VECTOR, WRITE FORMATS, VARIABLE LABELS, Variable Attributes
@section VECTOR
@vindex VECTOR

@display
Two possible syntaxes:
        VECTOR vec_name=var_list.
        VECTOR vec_name_list(count).
@end display

@cmd{VECTOR} allows a group of variables to be accessed as if they
were consecutive members of an array with a vector(index) notation.

To make a vector out of a set of existing variables, specify a name for
the vector followed by an equals sign (@samp{=}) and the variables that
belong in the vector.

To make a vector and create variables at the same time, specify one or
more vector names followed by a count in parentheses.  This will cause
variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
to be created as numeric variables with print and write format F8.2.
Variable names including numeric suffixes may not exceed 8 characters
in length, and none of the variables may exist prior to @cmd{VECTOR}.

All the variables in a vector must be the same type.

Vectors created with @cmd{VECTOR} disappear after any procedure or
procedure-like command is executed.  The variables contained in the
vectors remain, unless they are scratch variables (@pxref{Scratch
Variables}).

Variables within a vector may be references in expressions using
@code{vector(index)} syntax.

@node WRITE FORMATS,  , VECTOR, Variable Attributes
@section WRITE FORMATS
@vindex WRITE FORMATS

@display
WRITE FORMATS var_list (fmt_spec).
@end display

@cmd{WRITE FORMATS} sets the write formats for the specified variables
to the specified format specification.  Its syntax is identical to
that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
write formats, not print formats.

@node Data Manipulation, Data Selection, Variable Attributes, Top
@chapter Data transformations
@cindex transformations

The PSPP procedures examined in this chapter manipulate data and
prepare the active file for later analyses.  They do not produce output,
as a rule.

@menu
* AGGREGATE::                   Summarize multiple cases into a single case.
* AUTORECODE::                  Automatic recoding of variables.
* COMPUTE::                     Assigning a variable a calculated value.
* COUNT::                       Counting variables with particular values.
* FLIP::                        Exchange variables with cases.
* IF::                          Conditionally assigning a calculated value.
* RECODE::                      Mapping values from one set to another.
* SORT CASES::                  Sort the active file.
@end menu

@node AGGREGATE, AUTORECODE, Data Manipulation, Data Manipulation
@section AGGREGATE
@vindex AGGREGATE

@display
AGGREGATE
        /BREAK=var_list
        /PRESORTED
        /OUTFILE=@{*,'filename'@}
        /DOCUMENT
        /MISSING=COLUMNWISE
        /dest_vars=agr_func(src_vars, args@dots{})@dots{}
@end display

@cmd{AGGREGATE} summarizes groups of cases into single cases.
Cases are divided into groups that have the same values for one or more
variables called @dfn{break variables}.  Several functions are available
for summarizing case contents.

At least one break variable must be specified on BREAK, the only
required subcommand.  The values of these variables are used to divide
the active file into groups to be summarized.  In addition, at least
one @var{dest_var} must be specified.

By default, the active file is sorted based on the break variables
before aggregation takes place.  If the active file is already sorted
or otherwise grouped in terms of the break variables, specify
PRESORTED to save time.

The OUTFILE subcommand specifies a system file by file name string or
file handle (@pxref{FILE HANDLE}).  The aggregated cases are written to
this file.  If OUTFILE is not specified, or if @samp{*} is specified,
then the aggregated cases replace the active file.

Specify DOCUMENT to copy the documents from the active file into the
aggregate file (@pxref{DOCUMENT}).  Otherwise, the aggregate file will
not contain any documents, even if the aggregate file replaces the
active file.

One or more sets of aggregation variables must be specified.  Each set
comprises a list of aggregation variables, an equals sign (@samp{=}),
the name of an aggregation function (see the list below), and a list
of source variables in parentheses.  Some aggregation functions expect
additional arguments following the source variable names.

Each set must have exactly as many source variables as aggregation
variables.  Each aggregation variable receives the results of applying
the specified aggregation function to the corresponding source
variable.  Most aggregation functions may be applied to numeric and
short and long string variables.  Others, marked below, are restricted
to numeric values.

The available aggregation functions are as follows:

@table @asis
@item SUM(var_name)
Sum.  Limited to numeric values.
@item MEAN(var_name)
Arithmetic mean.  Limited to numeric values.
@item SD(var_name)
Standard deviation of the mean.  Limited to numeric values.
@item MAX(var_name)
Maximum value.
@item MIN(var_name)
Minimum value.
@item FGT(var_name, value)
@itemx PGT(var_name, value)
Fraction between 0 and 1, or percentage between 0 and 100, respectively,
of values greater than the specified constant.
@item FLT(var_name, value)
@itemx PLT(var_name, value)
Fraction or percentage, respectively, of values less than the specified
constant.
@item FIN(var_name, low, high)
@itemx PIN(var_name, low, high)
Fraction or percentage, respectively, of values within the specified
inclusive range of constants.
@item FOUT(var_name, low, high)
@itemx POUT(var_name, low, high)
Fraction or percentage, respectively, of values strictly outside the
specified range of constants.
@item N(var_name)
Number of non-missing values.
@item N
Number of cases aggregated to form this group.  Don't supply a source
variable for this aggregation function.
@item NU(var_name)
Number of non-missing values.  Each case is considered to have a weight
of 1, regardless of the current weighting variable (@pxref{WEIGHT}).
@item NU
Number of cases aggregated to form this group.  Each case is considered
to have a weight of 1, regardless of the current weighting variable.
@item NMISS(var_name)
Number of missing values.
@item NUMISS(var_name)
Number of missing values.  Each case is considered to have a weight of
1, regardless of the current weighting variable.
@item FIRST(var_name)
First value in this group.
@item LAST(var_name)
Last value in this group.
@end table

Aggregation functions compare string values in terms of internal
character codes.  On most modern computers, this is a form of ASCII.

The aggregation functions listed above exclude all user-missing values
from calculations.  To include user-missing values, insert a period
(@samp{.}) between the function name and left parenthesis
(e.g.~@samp{SUM.}).

Normally, only a single case (for SD and SD., two cases) need be
non-missing in each group for the aggregate variable to be
non-missing.  Specifying /MISSING=COLUMNWISE inverts this behavior, so
that the aggregate variable becomes missing if any aggregated value is
missing.

@cmd{AGGREGATE} both ignores and cancels the current @cmd{SPLIT FILE}
settings (@pxref{SPLIT FILE}).

@node AUTORECODE, COMPUTE, AGGREGATE, Data Manipulation
@section AUTORECODE
@vindex AUTORECODE

@display
AUTORECODE VARIABLES=src_vars INTO dest_vars
        /DESCENDING
        /PRINT
@end display

The @cmd{AUTORECODE} procedure considers the @var{n} values that a variable
takes on and maps them onto values 1@dots{}@var{n} on a new numeric
variable.

Subcommand VARIABLES is the only required subcommand and must come
first.  Specify VARIABLES, an equals sign (@samp{=}), a list of source
variables, INTO, and a list of target variables.  There must the same
number of source and target variables.  The target variables must not
already exist.

By default, increasing values of a source variable (for a string, this
is based on character code comparisons) are recoded to increasing values
of its target variable.  To cause increasing values of a source variable
to be recoded to decreasing values of its target variable (@var{n} down
to 1), specify DESCENDING.

PRINT is currently ignored.

@cmd{AUTORECODE} is a procedure.  It causes the data to be read.

@node COMPUTE, COUNT, AUTORECODE, Data Manipulation
@section COMPUTE
@vindex COMPUTE

@display
COMPUTE variable = expression.
  or
COMPUTE vector(index) = expression.
@end display

@cmd{COMPUTE} assigns the value of an expression to a target
variable.  For each case, the expression is evaluated and its value
assigned to the target variable.  Numeric and short and long string
variables may be assigned.  When a string expression's width differs
from the target variable's width, the string result of the expression
is truncated or padded with spaces on the right as necessary.  The
expression and variable types must match.

For numeric variables only, the target variable need not already
exist.  Numeric variables created by @cmd{COMPUTE} are assigned an
@code{F8.2} output format.  String variables must be declared before
they can be used as targets for @cmd{COMPUTE}.

The target variable may be specified as an element of a vector
(@pxref{VECTOR}).  In this case, a vector index expression must be
specified in parentheses following the vector name.  The index
expression must evaluate to a numeric value that, after rounding down
to the nearest integer, is a valid index for the named vector.

Using @cmd{COMPUTE} to assign to a variable specified on @cmd{LEAVE}
(@pxref{LEAVE}) resets the variable's left state.  Therefore,
@code{LEAVE} should be specified following @cmd{COMPUTE}, not before.

@cmd{COMPUTE} is a transformation.  It does not cause the active file to be
read.

When @cmd{COMPUTE} is specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
(@pxref{LAG}).

@node COUNT, FLIP, COMPUTE, Data Manipulation
@section COUNT
@vindex COUNT

@display
COUNT var_name = var@dots{} (value@dots{}).

Each value takes one of the following forms:
        number
        string
        num1 THRU num2
        MISSING
        SYSMIS
In addition, num1 and num2 can be LO or LOWEST, or HI or HIGHEST,
respectively.
@end display

@cmd{COUNT} creates or replaces a numeric @dfn{target} variable that
counts the occurrence of a @dfn{criterion} value or set of values over
one or more @dfn{test} variables for each case.

The target variable values are always nonnegative integers.  They are
never missing.  The target variable is assigned an F8.2 output format.
@xref{Input/Output Formats}.  Any variables, including long and short
string variables, may be test variables.

User-missing values of test variables are treated just like any other
values.  They are @strong{not} treated as system-missing values.
User-missing values that are criterion values or inside ranges of
criterion values are counted as any other values.  However (for numeric
variables), keyword MISSING may be used to refer to all system-
and user-missing values.

@cmd{COUNT} target variables are assigned values in the order
specified.  In the command @code{COUNT A=A B(1) /B=A B(2).}, the
following actions occur:

@itemize @minus
@item
The number of occurrences of 1 between @code{A} and @code{B} is counted.

@item
@code{A} is assigned this value.

@item
The number of occurrences of 1 between @code{B} and the @strong{new}
value of @code{A} is counted.

@item
@code{B} is assigned this value.
@end itemize

Despite this ordering, all @cmd{COUNT} criterion variables must exist
before the procedure is executed---they may not be created as target
variables earlier in the command!  Break such a command into two
separate commands.

The examples below may help to clarify.

@enumerate A
@item
Assuming @code{Q0}, @code{Q2}, @dots{}, @code{Q9} are numeric variables,
the following commands:

@enumerate
@item
Count the number of times the value 1 occurs through these variables
for each case and assigns the count to variable @code{QCOUNT}.  

@item
Print out the total number of times the value 1 occurs throughout
@emph{all} cases using @cmd{DESCRIPTIVES}.  @xref{DESCRIPTIVES}, for
details.
@end enumerate

@example
COUNT QCOUNT=Q0 TO Q9(1).
DESCRIPTIVES QCOUNT /STATISTICS=SUM.
@end example

@item
Given these same variables, the following commands:

@enumerate
@item
Count the number of valid values of these variables for each case and
assigns the count to variable @code{QVALID}.

@item
Multiplies each value of @code{QVALID} by 10 to obtain a percentage of
valid values, using @cmd{COMPUTE}.  @xref{COMPUTE}, for details.

@item
Print out the percentage of valid values across all cases, using
@cmd{DESCRIPTIVES}.  @xref{DESCRIPTIVES}, for details.
@end enumerate

@example
COUNT QVALID=Q0 TO Q9 (LO THRU HI).
COMPUTE QVALID=QVALID*10.
DESCRIPTIVES QVALID /STATISTICS=MEAN.
@end example
@end enumerate

@node FLIP, IF, COUNT, Data Manipulation
@section FLIP
@vindex FLIP

@display
FLIP /VARIABLES=var_list /NEWNAMES=var_name.
@end display

@cmd{FLIP} transposes rows and columns in the active file.  It
causes cases to be swapped with variables, and vice versa.

All variables in the transposed active file are numeric.  String
variables take on the system-missing value in the transposed file.

No subcommands are required.  The VARIABLES subcommand specifies
variables that will be transformed into cases.  Variables not specified
are discarded.  By default, all variables are selected for
transposition.

The variables specified by NEWNAMES, which must be a string variable, is
used to give names to the variables created by @cmd{FLIP}.  If
NEWNAMES is not
specified then the default is a variable named CASE_LBL, if it exists.
If it does not then the variables created by FLIP are named VAR000
through VAR999, then VAR1000, VAR1001, and so on.

When a NEWNAMES variable is available, the names must be canonicalized
before becoming variable names.  Invalid characters are replaced by
letter @samp{V} in the first position, or by @samp{_} in subsequent
positions.  If the name thus generated is not unique, then numeric
extensions are added, starting with 1, until a unique name is found or
there are no remaining possibilities.  If the latter occurs then the
FLIP operation aborts.

The resultant dictionary contains a CASE_LBL variable, which stores the
names of the variables in the dictionary before the transposition.  If
the active file is subsequently transposed using @cmd{FLIP}, this
variable can
be used to recreate the original variable names.

FLIP honors N OF CASES.  It ignores TEMPORARY, so that ``temporary''
transformations become permanent.

@node IF, RECODE, FLIP, Data Manipulation
@section IF
@vindex IF

@display
IF condition variable=expression.
  or
IF condition vector(index)=expression.
@end display

The @cmd{IF} transformation conditionally assigns the value of a target
expression to a target variable, based on the truth of a test
expression.

Specify a boolean-valued expression (@pxref{Expressions}) to be tested
following the IF keyword.  This expression is evaluated for each case.
If the value is true, then the value of the expression is computed and
assigned to the specified variable.  If the value is false or missing,
nothing is done.  Numeric and short and long string variables may be
assigned.  When a string expression's width differs from the target
variable's width, the string result of the expression is truncated or
padded with spaces on the right as necessary.  The expression and
variable types must match.

The target variable may be specified as an element of a vector
(@pxref{VECTOR}).  In this case, a vector index expression must be
specified in parentheses following the vector name.  The index
expression must evaluate to a numeric value that, after rounding down
to the nearest integer, is a valid index for the named vector.

Using @cmd{IF} to assign to a variable specified on @cmd{LEAVE}
(@pxref{LEAVE}) resets the variable's left state.  Therefore,
@code{LEAVE} should be specified following @cmd{IF}, not before.

When @cmd{IF} is specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
(@pxref{LAG}).

@node RECODE, SORT CASES, IF, Data Manipulation
@section RECODE
@vindex RECODE

@display
RECODE var_list (src_value@dots{}=dest_value)@dots{} [INTO var_list].

src_value may take the following forms:
        number
        string
        num1 THRU num2
        MISSING
        SYSMIS
        ELSE
Open-ended ranges may be specified using LO or LOWEST for num1
or HI or HIGHEST for num2.

dest_value may take the following forms:
        num
        string
        SYSMIS
        COPY
@end display

@cmd{RECODE} translates data from one range of values to
another, via flexible user-specified mappings.  Data may be remapped
in-place or copied to new variables.  Numeric, short string, and long
string data can be recoded.

Specify the list of source variables, followed by one or more mapping
specifications each enclosed in parentheses.  If the data is to be
copied to new variables, specify INTO, then the list of target
variables.  String target variables must already have been declared
using @cmd{STRING} or another transformation, but numeric target
variables can
be created on the fly.  There must be exactly as many target variables
as source variables.  Each source variable is remapped into its
corresponding target variable.

When INTO is not used, the input and output variables must be of the
same type.  Otherwise, string values can be recoded into numeric values,
and vice versa.  When this is done and there is no mapping for a
particular value, either a value consisting of all spaces or the
system-missing value is assigned, depending on variable type.

Mappings are considered from left to right.  The first src_value that
matches the value of the source variable causes the target variable to
receive the value indicated by the dest_value.  Literal number, string,
and range src_value's should be self-explanatory.  MISSING as a
src_value matches any user- or system-missing value.  SYSMIS matches the
system missing value only.  ELSE is a catch-all that matches anything.
It should be the last src_value specified.

Numeric and string dest_value's should also be self-explanatory.  COPY
causes the input values to be copied to the output.  This is only value
if the source and target variables are of the same type.  SYSMIS
indicates the system-missing value.

If the source variables are strings and the target variables are
numeric, then there is one additional mapping available: (CONVERT),
which must be the last specified mapping.  CONVERT causes a number
specified as a string to be converted to a numeric value.  If the string
cannot be parsed as a number, then the system-missing value is assigned.

Multiple recodings can be specified on a single @cmd{RECODE} invocation.
Introduce additional recodings with a slash (@samp{/}) to
separate them from the previous recodings.

@node SORT CASES,  , RECODE, Data Manipulation
@section SORT CASES
@vindex SORT CASES

@display
SORT CASES BY var_list.
@end display

@cmd{SORT CASES} sorts the active file by the values of one or more
variables.

Specify BY and a list of variables to sort by.  By default, variables
are sorted in ascending order.  To override sort order, specify (D) or
(DOWN) after a list of variables to get descending order, or (A) or (UP)
for ascending order.  These apply to the entire list of variables
preceding them.

@cmd{SORT CASES} is a procedure.  It causes the data to be read.

@cmd{SORT CASES} attempts to sort the entire active file in main memory.
If main memory is exhausted, it falls back to a merge sort algorithm that
involves writing and reading numerous temporary files.

@cmd{SORT CASES} may not be specified following TEMPORARY.  

@node Data Selection, Conditionals and Looping, Data Manipulation, Top
@chapter Selecting data for analysis

This chapter documents PSPP commands that temporarily or permanently
select data records from the active file for analysis.

@menu
* FILTER::                      Exclude cases based on a variable.
* N OF CASES::                  Limit the size of the active file.
* PROCESS IF::                  Temporarily excluding cases.
* SAMPLE::                      Select a specified proportion of cases.
* SELECT IF::                   Permanently delete selected cases.
* SPLIT FILE::                  Do multiple analyses with one command.
* TEMPORARY::                   Make transformations' effects temporary.
* WEIGHT::                      Weight cases by a variable.
@end menu

@node FILTER, N OF CASES, Data Selection, Data Selection
@section FILTER
@vindex FILTER

@display
FILTER BY var_name.
FILTER OFF.
@end display

@cmd{FILTER} allows a boolean-valued variable to be used to select
cases from the data stream for processing.

To set up filtering, specify BY and a variable name.  Keyword
BY is optional but recommended.  Cases which have a zero or system- or
user-missing value are excluded from analysis, but not deleted from the
data stream.  Cases with other values are analyzed.
To filter based on a different condition, use
transformations such as @cmd{COMPUTE} or @cmd{RECODE} to compute a
filter variable of the required form, then specify that variable on
@cmd{FILTER}.

@code{FILTER OFF} turns off case filtering.

Filtering takes place immediately before cases pass to a procedure for
analysis.  Only one filter variable may be active at a time.  Normally,
case filtering continues until it is explicitly turned off with @code{FILTER
OFF}.  However, if @cmd{FILTER} is placed after TEMPORARY, it filters only
the next procedure or procedure-like command.

@node N OF CASES, PROCESS IF, FILTER, Data Selection
@section N OF CASES
@vindex N OF CASES

@display
N [OF CASES] num_of_cases [ESTIMATED].
@end display

Sometimes you may want to disregard cases of your input.  @cmd{N} can
do this.  @code{N 100} tells PSPP to disregard all cases after the
first 100.

If the value specified for @cmd{N} is greater than the number of cases
read in, the value is ignored.

@cmd{N} does not discard cases or prevent them from being read.  It
just causes cases beyond the last one specified to be ignored by data
analysis commands.

A later @cmd{N} command can increase or decrease the number of cases
selected.  (To select all the cases without knowing how many there are,
specify a very high number: 100000 or whatever you think is large enough.)

Transformation procedures performed after @cmd{N} is executed
@emph{do} cause cases to be discarded.

@cmd{SAMPLE}, @cmd{PROCESS IF}, and @cmd{SELECT IF} have
precedence over @cmd{N}---the same results are obtained by both of the
following fragments, given the same random number seeds:

@example
@i{@dots{}set up, read in data@dots{}}
N 100.
SAMPLE .5.
@i{@dots{}analyze data@dots{}}

@i{@dots{}set up, read in data@dots{}}  
SAMPLE .5.
N 100.
@i{@dots{}analyze data@dots{}}
@end example

Both fragments above first randomly sample approximately half of the
cases, then select the first 100 of those sampled.

@cmd{N} with the @code{ESTIMATED} keyword gives an
estimated number of cases before @cmd{DATA LIST} or another command to
read in data.  @code{ESTIMATED} never limits the number of cases
processed by procedures.  PSPP currently does not make use of
case count estimates.

When @cmd{N} is specified after @cmd{TEMPORARY}, it affects only
the next procedure (@pxref{TEMPORARY}).

@node PROCESS IF, SAMPLE, N OF CASES, Data Selection
@section PROCESS IF
@vindex PROCESS IF

@example
PROCESS IF expression.
@end example

@cmd{PROCESS IF} temporarily eliminates cases from the
data stream.  Its effects are active only through the execution of the
next procedure or procedure-like command.

Specify a boolean expression (@pxref{Expressions}).  If the value of the
expression is true for a particular case, the case will be analyzed.  If
the expression has a false or missing value, then the case will be
deleted from the data stream for this procedure only.

Regardless of its placement relative to other commands, @cmd{PROCESS IF}
always takes effect immediately before data passes to the procedure.
Only one @cmd{PROCESS IF} command may be in effect at any given time.

The effects of @cmd{PROCESS IF} are similar, but not identical, to the
effects of executing @cmd{TEMPORARY}, then @cmd{SELECT IF}
(@pxref{SELECT IF}).

The filtering performed by @cmd{PROCESS IF} takes place immediately
before cases pass to a procedure for analysis.  Because @cmd{PROCESS
IF} affects only a single procedure, its placement relative to
@cmd{TEMPORARY} is unimportant.

@cmd{PROCESS IF} is deprecated.  It is included for compatibility with
old command files.  New syntax files should use @cmd{SELECT IF} or
@cmd{FILTER} instead.

@node SAMPLE, SELECT IF, PROCESS IF, Data Selection
@section SAMPLE
@vindex SAMPLE

@display
SAMPLE num1 [FROM num2].
@end display

@cmd{SAMPLE} randomly samples a proportion of the cases in the active
file.  Unless it follows @cmd{TEMPORARY}, it operates as a
transformation, permanently removing cases from the active file.

The proportion to sample can be expressed as a single number between 0
and 1.  If @code{k} is the number specified, and @code{N} is the number
of currently-selected cases in the active file, then after
@code{SAMPLE @var{k}.}, approximately @code{k*N} cases will be
selected.

The proportion to sample can also be specified in the style @code{SAMPLE
@var{m} FROM @var{N}}.  With this style, cases are selected as follows:

@enumerate
@item
If @var{N} is equal to the number of currently-selected cases in the
active file, exactly @var{m} cases will be selected.

@item
If @var{N} is greater than the number of currently-selected cases in the
active file, an equivalent proportion of cases will be selected.

@item
If @var{N} is less than the number of currently-selected cases in the
active, exactly @var{m} cases will be selected @emph{from the first
@var{N} cases in the active file.}
@end enumerate

@cmd{SAMPLE} and @cmd{SELECT IF} are performed in
the order specified by the syntax file.

@cmd{SAMPLE} is always performed before @code{N OF CASES}, regardless
of ordering in the syntax file (@pxref{N OF CASES}).

The same values for @cmd{SAMPLE} may result in different samples.  To
obtain the same sample, use the @code{SET} command to set the random
number seed to the same value before each @cmd{SAMPLE}.  Different
samples may still result when the file is processed on systems with
differing endianness or floating-point formats.  By default, the
random number seed is based on the system time.

@node SELECT IF, SPLIT FILE, SAMPLE, Data Selection
@section SELECT IF
@vindex SELECT IF

@display
SELECT IF expression.
@end display

@cmd{SELECT IF} selects cases for analysis based on the value of a
boolean expression.  Cases not selected are permanently eliminated
from the active file, unless @cmd{TEMPORARY} is in effect
(@pxref{TEMPORARY}).

Specify a boolean expression (@pxref{Expressions}).  If the value of the
expression is true for a particular case, the case will be analyzed.  If
the expression has a false or missing value, then the case will be
deleted from the data stream.

Place @cmd{SELECT IF} as early in the command file as
possible.  Cases that are deleted early can be processed more
efficiently in time and space.

When @cmd{SELECT IF} is specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
(@pxref{LAG}).

@node SPLIT FILE, TEMPORARY, SELECT IF, Data Selection
@section SPLIT FILE
@vindex SPLIT FILE

@display
Two possible syntaxes:
        SPLIT FILE BY var_list.
        SPLIT FILE OFF.
@end display

@cmd{SPLIT FILE} allows multiple sets of data present in one data
file to be analyzed separately using single statistical procedure
commands.

Specify a list of variable names to analyze multiple sets of
data separately.  Groups of cases having the same values for these
variables are analyzed by statistical procedure commands as one group.
An independent analysis is carried out for each group of cases, and the
variable values for the group are printed along with the analysis.

Specify OFF to disable @cmd{SPLIT FILE} and resume analysis of the
entire active file as a single group of data.

When @cmd{SPLIT FILE} is specified after @cmd{TEMPORARY}, it affects only
the next procedure (@pxref{TEMPORARY}).

@node TEMPORARY, WEIGHT, SPLIT FILE, Data Selection
@section TEMPORARY
@vindex TEMPORARY

@display
TEMPORARY.
@end display

@cmd{TEMPORARY} is used to make the effects of transformations
following its execution temporary.  These transformations will
affect only the execution of the next procedure or procedure-like
command.  Their effects will not be saved to the active file.

The only specification on @cmd{TEMPORARY} is the command name.

@cmd{TEMPORARY} may not appear within a @cmd{DO IF} or @cmd{LOOP}
construct.  It may appear only once between procedures and
procedure-like commands.

Scratch variables cannot be used following @cmd{TEMPORARY}.

An example may help to clarify:

@example
DATA LIST /X 1-2.
BEGIN DATA.
 2
 4
10
15
20
24
END DATA.
COMPUTE X=X/2.
TEMPORARY.
COMPUTE X=X+3.
DESCRIPTIVES X.
DESCRIPTIVES X.
@end example

The data read by the first @cmd{DESCRIPTIVES} are 4, 5, 8,
10.5, 13, 15.  The data read by the first @cmd{DESCRIPTIVES} are 1, 2,
5, 7.5, 10, 12.

@node WEIGHT,  , TEMPORARY, Data Selection
@section WEIGHT
@vindex WEIGHT

@display
WEIGHT BY var_name.
WEIGHT OFF.
@end display

@cmd{WEIGHT} assigns cases varying weights,
changing the frequency distribution of the active file.  Execution of
@cmd{WEIGHT} is delayed until data have been read.

If a variable name is specified, @cmd{WEIGHT} causes the values of that
variable to be used as weighting factors for subsequent statistical
procedures.  Use of keyword BY is optional but recommended.  Weighting
variables must be numeric.  Scratch variables may not be used for
weighting (@pxref{Scratch Variables}).

When OFF is specified, subsequent statistical procedures will weight all
cases equally.

A positive integer weighting factor @var{w} on a case will yield the
same statistical output as would replicating the case @var{w} times.
A weighting factor of 0 is treated for statistical purposes as if the
case did not exist in the input.  Weighting values need not be
integers, but negative and system-missing values for the weighting
variable are interpreted as weighting factors of 0.  User-missing
values are not treated specially.

When @cmd{WEIGHT} is specified after @cmd{TEMPORARY}, it affects only
the next procedure (@pxref{TEMPORARY}).

@cmd{WEIGHT} does not cause cases in the active file to be replicated in
memory.

@node Conditionals and Looping, Statistics, Data Selection, Top
@chapter Conditional and Looping Constructs
@cindex conditionals
@cindex loops
@cindex flow of control
@cindex control flow

This chapter documents PSPP commands used for conditional execution,
looping, and flow of control.

@menu
* BREAK::                       Exit a loop.
* DO IF::                       Conditionally execute a block of code.
* DO REPEAT::                   Textually repeat a code block.
* LOOP::                        Repeat a block of code.
@end menu

@node BREAK, DO IF, Conditionals and Looping, Conditionals and Looping
@section BREAK
@vindex BREAK

@display
BREAK.
@end display

@cmd{BREAK} terminates execution of the innermost currently executing
@cmd{LOOP} construct.

@cmd{BREAK} is allowed only inside @cmd{LOOP}@dots{}@cmd{END LOOP}.
@xref{LOOP}, for more details.

@node DO IF, DO REPEAT, BREAK, Conditionals and Looping
@section DO IF
@vindex DO IF

@display
DO IF condition.
        @dots{}
[ELSE IF condition.
        @dots{}
]@dots{}
[ELSE.
        @dots{}]
END IF.
@end display

@cmd{DO IF} allows one of several sets of transformations to be
executed, depending on user-specified conditions.

If the specified boolean expression evaluates as true, then the block
of code following @cmd{DO IF} is executed.  If it evaluates as
missing, then
none of the code blocks is executed.  If it is false, then
the boolean expression on the first @cmd{ELSE IF}, if present, is tested in
turn, with the same rules applied.  If all expressions evaluate to
false, then the @cmd{ELSE} code block is executed, if it is present.

When @cmd{DO IF} or @cmd{ELSE IF} is specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
(@pxref{LAG}).

@node DO REPEAT, LOOP, DO IF, Conditionals and Looping
@section DO REPEAT
@vindex DO REPEAT

@display
DO REPEAT repvar_name=expansion@dots{}.
        @dots{}
END REPEAT [PRINT].

expansion takes one of the following forms:
        var_list
        num_or_range@dots{}
        'string'@dots{}

num_or_range takes one of the following forms:
        number
        num1 TO num2
@end display

@cmd{DO REPEAT} repeats a block of code, textually substituting
different variables, numbers, or strings into the block with each
repetition.

Specify a repeat variable name followed by an equals sign (@samp{=}) and
the list of replacements.  Replacements can be a list of variables
(which may be existing variables or new variables or a combination
thereof), of numbers, or of strings.  When new variable names are
specified, @cmd{DO REPEAT} creates them as numeric variables.  When numbers
are specified, runs of integers may be indicated with TO notation, for
instance @samp{1 TO 5} and @samp{1 2 3 4 5} would be equivalent.  There
is no equivalent notation for string values.

Multiple repeat variables can be specified.  When this is done, each
variable must have the same number of replacements.

The code within @cmd{DO REPEAT} is repeated as many times as there are
replacements for each variable.  The first time, the first value for
each repeat variable is substituted; the second time, the second value
for each repeat variable is substituted; and so on.

Repeat variable substitutions work like macros.  They take place
anywhere in a line that the repeat variable name occurs as a token,
including command and subcommand names.  For this reason it is not a
good idea to select words commonly used in command and subcommand names
as repeat variable identifiers.

If PRINT is specified on @cmd{END REPEAT}, the commands after substitutions
are made are printed to the listing file, prefixed by a plus sign
(@samp{+}).

@node LOOP,  , DO REPEAT, Conditionals and Looping
@section LOOP
@vindex LOOP

@display
LOOP [index_var=start TO end [BY incr]] [IF condition].
        @dots{}
END LOOP [IF condition].
@end display

@cmd{LOOP} iterates a group of commands.  A number of
termination options are offered.

Specify index_var to make that variable count from one value to
another by a particular increment.  index_var must be a pre-existing
numeric variable.  start, end, and incr are numeric expressions
(@pxref{Expressions}.)  

During the first iteration, index_var is set to the value of start.
During each successive iteration, index_var is increased by the value of
incr.  If end > start, then the loop terminates when index_var > end;
otherwise it terminates when index_var < end.  If incr is not specified
then it defaults to +1 or -1 as appropriate.

If end > start and incr < 0, or if end < start and incr > 0, then the
loop is never executed.  index_var is nevertheless set to the value of
start.

Modifying index_var within the loop is allowed, but it has no effect on
the value of index_var in the next iteration.

Specify a boolean expression for the condition on @cmd{LOOP} to
cause the loop to be executed only if the condition is true.  If the
condition is false or missing before the loop contents are executed the
first time, the loop contents are not executed at all.

If index and condition clauses are both present on @cmd{LOOP}, the index
clause is always evaluated first.

Specify a boolean expression for the condition on @cmd{END LOOP} to cause
the loop to terminate if the condition is not true after the enclosed
code block is executed.  The condition is evaluated at the end of the
loop, not at the beginning.

If the index clause and both condition clauses are not present, then the
loop is executed MXLOOPS (@pxref{SET}) times.

@cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).

When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
(@pxref{LAG}).

@node Statistics, Utilities, Conditionals and Looping, Top
@chapter Statistics

This chapter documents the statistical procedures that PSPP supports so
far.

@menu
* DESCRIPTIVES::                Descriptive statistics.
* FREQUENCIES::                 Frequency tables.
* CROSSTABS::                   Crosstabulation tables.
* T-TEST::                      Test Hypotheses about means.
@end menu

@node DESCRIPTIVES, FREQUENCIES, Statistics, Statistics
@section DESCRIPTIVES

@vindex DESCRIPTIVES
@display
DESCRIPTIVES
        /VARIABLES=var_list
        /MISSING=@{VARIABLE,LISTWISE@} @{INCLUDE,NOINCLUDE@}
        /FORMAT=@{LABELS,NOLABELS@} @{NOINDEX,INDEX@} @{LINE,SERIAL@}
        /SAVE
        /STATISTICS=@{ALL,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,
                     SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,DEFAULT,
                     SESKEWNESS,SEKURTOSIS@}
        /SORT=@{NONE,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,SKEWNESS,
               RANGE,MINIMUM,MAXIMUM,SUM,SESKEWNESS,SEKURTOSIS,NAME@}
              @{A,D@}
@end display

The @cmd{DESCRIPTIVES} procedure reads the active file and outputs
descriptive
statistics requested by the user.  In addition, it can optionally
compute Z-scores.

The VARIABLES subcommand, which is required, specifies the list of
variables to be analyzed.  Keyword VARIABLES is optional.

All other subcommands are optional:

The MISSING subcommand determines the handling of missing variables.  If
INCLUDE is set, then user-missing values are included in the
calculations.  If NOINCLUDE is set, which is the default, user-missing
values are excluded.  If VARIABLE is set, then missing values are
excluded on a variable by variable basis; if LISTWISE is set, then
the entire case is excluded whenever any value in that case has a
system-missing or, if INCLUDE is set, user-missing value.

The FORMAT subcommand affects the output format.  Currently the
LABELS/NOLABELS and NOINDEX/INDEX settings are not used.  When SERIAL is
set, both valid and missing number of cases are listed in the output;
when NOSERIAL is set, only valid cases are listed.

The SAVE subcommand causes @cmd{DESCRIPTIVES} to calculate Z scores for all
the specified variables.  The Z scores are saved to new variables.
Variable names are generated by trying first the original variable name
with Z prepended and truncated to a maximum of 8 characters, then the
names ZSC000 through ZSC999, STDZ00 through STDZ09, ZZZZ00 through
ZZZZ09, ZQZQ00 through ZQZQ09, in that sequence.  In addition, Z score
variable names can be specified explicitly on VARIABLES in the variable
list by enclosing them in parentheses after each variable.

The STATISTICS subcommand specifies the statistics to be displayed:

@table @code
@item ALL
All of the statistics below.
@item MEAN
Arithmetic mean.
@item SEMEAN
Standard error of the mean.
@item STDDEV
Standard deviation.
@item VARIANCE
Variance.
@item KURTOSIS
Kurtosis and standard error of the kurtosis.
@item SKEWNESS
Skewness and standard error of the skewness.
@item RANGE
Range.
@item MINIMUM
Minimum value.
@item MAXIMUM
Maximum value.
@item SUM
Sum.
@item DEFAULT
Mean, standard deviation of the mean, minimum, maximum.
@item SEKURTOSIS
Standard error of the kurtosis.
@item SESKEWNESS
Standard error of the skewness.
@end table

The SORT subcommand specifies how the statistics should be sorted.  Most
of the possible values should be self-explanatory.  NAME causes the
statistics to be sorted by name.  By default, the statistics are listed
in the order that they are specified on the VARIABLES subcommand.  The A
and D settings request an ascending or descending sort order,
respectively.

@node FREQUENCIES, CROSSTABS, DESCRIPTIVES, Statistics
@section FREQUENCIES

@vindex FREQUENCIES
@display
FREQUENCIES
        /VARIABLES=var_list
        /FORMAT=@{TABLE,NOTABLE,LIMIT(limit)@}
                @{STANDARD,CONDENSE,ONEPAGE[(onepage_limit)]@}
                @{LABELS,NOLABELS@}
                @{AVALUE,DVALUE,AFREQ,DFREQ@}
                @{SINGLE,DOUBLE@}
                @{OLDPAGE,NEWPAGE@}
        /MISSING=@{EXCLUDE,INCLUDE@}
        /STATISTICS=@{DEFAULT,MEAN,SEMEAN,MEDIAN,MODE,STDDEV,VARIANCE,
                     KURTOSIS,SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,
                     SESKEWNESS,SEKURTOSIS,ALL,NONE@}
        /NTILES=ntiles
        /PERCENTILES=percent@dots{}

(These options are not currently implemented.)
        /BARCHART=@dots{}
        /HISTOGRAM=@dots{}
        /HBAR=@dots{}
        /GROUPED=@dots{}

(Integer mode.)
        /VARIABLES=var_list (low,high)@dots{}
@end display

The @cmd{FREQUENCIES} procedure outputs frequency tables for specified
variables.
@cmd{FREQUENCIES} can also calculate and display descriptive statistics
(including median and mode) and percentiles.

In the future, @cmd{FREQUENCIES} will also support graphical output in the
form of bar charts and histograms.  In addition, it will be able to
support percentiles for grouped data.

The VARIABLES subcommand is the only required subcommand.  Specify the
variables to be analyzed.  In most cases, this is all that is required.
This is known as @dfn{general mode}.

Occasionally, one may want to invoke a special mode called @dfn{integer
mode}.  Normally, in general mode, PSPP will automatically determine
what values occur in the data.  In integer mode, the user specifies the
range of values that the data assumes.  To invoke this mode, specify a
range of data values in parentheses, separated by a comma.  Data values
inside the range are truncated to the nearest integer, then assigned to
that value.  If values occur outside this range, they are discarded.

The FORMAT subcommand controls the output format.  It has several
possible settings:  

@itemize @bullet
@item
TABLE, the default, causes a frequency table to be output for every
variable specified.  NOTABLE prevents them from being output.  LIMIT
with a numeric argument causes them to be output except when there are
more than the specified number of values in the table.

@item
STANDARD frequency tables contain more complete information, but also to
take up more space on the printed page.  CONDENSE frequency tables are
less informative but take up less space.  ONEPAGE with a numeric
argument will output standard frequency tables if there are the
specified number of values or less, condensed tables otherwise.  ONEPAGE
without an argument defaults to a threshold of 50 values.

@item
LABELS causes value labels to be displayed in STANDARD frequency
tables.  NOLABLES prevents this.

@item
Normally frequency tables are sorted in ascending order by value.  This
is AVALUE.  DVALUE tables are sorted in descending order by value.
AFREQ and DFREQ tables are sorted in ascending and descending order,
respectively, by frequency count.

@item
SINGLE spaced frequency tables are closely spaced.  DOUBLE spaced
frequency tables have wider spacing.

@item
OLDPAGE and NEWPAGE are not currently used.
@end itemize

The MISSING subcommand controls the handling of user-missing values.
When EXCLUDE, the default, is set, user-missing values are not included
in frequency tables or statistics.  When INCLUDE is set, user-missing
are included.  System-missing values are never included in statistics,
but are listed in frequency tables.

The available STATISTICS are the same as available in @cmd{DESCRIPTIVES}
(@pxref{DESCRIPTIVES}), with the addition of MEDIAN, the data's median
value, and MODE, the mode.  (If there are multiple modes, the smallest
value is reported.)  By default, the mean, standard deviation of the
mean, minimum, and maximum are reported for each variable.

PERCENTILES causes the specified percentiles to be reported.
The percentiles should  be presented at a list of numbers between 0
and 100 inclusive.  
The NTILES subcommand causes the percentiles to be reported at the
boundaries of the data set divided into the specified number of ranges.
For instance, @code{/NTILES=4} would cause quartiles to be reported.


@node CROSSTABS, T-TEST, FREQUENCIES, Statistics
@section CROSSTABS

@vindex CROSSTABS
@display
CROSSTABS
        /TABLES=var_list BY var_list [BY var_list]@dots{}
        /MISSING=@{TABLE,INCLUDE,REPORT@}
        /WRITE=@{NONE,CELLS,ALL@}
        /FORMAT=@{TABLES,NOTABLES@}
                @{LABELS,NOLABELS,NOVALLABS@}
                @{PIVOT,NOPIVOT@}
                @{AVALUE,DVALUE@}
                @{NOINDEX,INDEX@}
                @{BOX,NOBOX@}
        /CELLS=@{COUNT,ROW,COLUMN,TOTAL,EXPECTED,RESIDUAL,SRESIDUAL,
                ASRESIDUAL,ALL,NONE@}
        /STATISTICS=@{CHISQ,PHI,CC,LAMBDA,UC,BTAU,CTAU,RISK,GAMMA,D,
                     KAPPA,ETA,CORR,ALL,NONE@}
        
(Integer mode.)
        /VARIABLES=var_list (low,high)@dots{}
@end display

The @cmd{CROSSTABS} procedure displays crosstabulation
tables requested by the user.  It can calculate several statistics for
each cell in the crosstabulation tables.  In addition, a number of
statistics can be calculated for each table itself.

The TABLES subcommand is used to specify the tables to be reported.  Any
number of dimensions is permitted, and any number of variables per
dimension is allowed.  The TABLES subcommand may be repeated as many
times as needed.  This is the only required subcommand in @dfn{general
mode}.  

Occasionally, one may want to invoke a special mode called @dfn{integer
mode}.  Normally, in general mode, PSPP automatically determines
what values occur in the data.  In integer mode, the user specifies the
range of values that the data assumes.  To invoke this mode, specify the
VARIABLES subcommand, giving a range of data values in parentheses for
each variable to be used on the TABLES subcommand.  Data values inside
the range are truncated to the nearest integer, then assigned to that
value.  If values occur outside this range, they are discarded.  When it
is present, the VARIABLES subcommand must precede the TABLES
subcommand.

In general mode, numeric and string variables may be specified on
TABLES.  Although long string variables are allowed, only their
initial short-string parts are used.  In integer mode, only numeric
variables are allowed.

The MISSING subcommand determines the handling of user-missing values.
When set to TABLE, the default, missing values are dropped on a table by
table basis.  When set to INCLUDE, user-missing values are included in
tables and statistics.  When set to REPORT, which is allowed only in
integer mode, user-missing values are included in tables but marked with
an @samp{M} (for ``missing'') and excluded from statistical
calculations.

Currently the WRITE subcommand is ignored.

The FORMAT subcommand controls the characteristics of the
crosstabulation tables to be displayed.  It has a number of possible
settings:

@itemize @bullet
@item
TABLES, the default, causes crosstabulation tables to be output.
NOTABLES suppresses them.

@item
LABELS, the default, allows variable labels and value labels to appear
in the output.  NOLABELS suppresses them.  NOVALLABS displays variable
labels but suppresses value labels.

@item
PIVOT, the default, causes each TABLES subcommand to be displayed in a
pivot table format.  NOPIVOT causes the old-style crosstabulation format
to be used.

@item
AVALUE, the default, causes values to be sorted in ascending order.
DVALUE asserts a descending sort order.

@item
INDEX/NOINDEX is currently ignored.

@item
BOX/NOBOX is currently ignored.
@end itemize

The CELLS subcommand controls the contents of each cell in the displayed
crosstabulation table.  The possible settings are:

@table @asis
@item COUNT
Frequency count.
@item ROW
Row percent.
@item COLUMN
Column percent.
@item TOTAL
Table percent.
@item EXPECTED
Expected value.
@item RESIDUAL 
Residual.
@item SRESIDUAL
Standardized residual.
@item ASRESIDUAL
Adjusted standardized residual.
@item ALL
All of the above.
@item NONE
Suppress cells entirely.
@end table

@samp{/CELLS} without any settings specified requests COUNT, ROW,
COLUMN, and TOTAL.  If CELLS is not specified at all then only COUNT
will be selected.

The STATISTICS subcommand selects statistics for computation:

@table @asis
@item CHISQ
Pearson chi-square, likelihood ratio, Fisher's exact test, continuity
correction, linear-by-linear association.
@item PHI
Phi.
@item CC
Contingency coefficient.
@item LAMBDA
Lambda.
@item UC
Uncertainty coefficient.
@item BTAU
Tau-b.
@item CTAU
Tau-c.
@item RISK
Risk estimate.
@item GAMMA
Gamma.
@item D
Somers' D.
@item KAPPA
Cohen's Kappa.
@item ETA
Eta.
@item CORR
Spearman correlation, Pearson's r.
@item ALL
All of the above.
@item NONE
No statistics.
@end table

Selected statistics are only calculated when appropriate for the
statistic.  Certain statistics require tables of a particular size, and
some statistics are calculated only in integer mode.

@samp{/STATISTICS} without any settings selects CHISQ.  If the
STATISTICS subcommand is not given, no statistics are calculated.

@strong{Please note:} Currently the implementation of CROSSTABS has the
followings bugs:

@itemize @bullet
@item
Pearson's R (but not Spearman) is off a little.
@item
T values for Spearman's R and Pearson's R are wrong.
@item
Significance of symmetric and directional measures is not calculated.
@item
Asymmetric ASEs and T values for lambda are wrong.
@item
ASE of Goodman and Kruskal's tau is not calculated.
@item
ASE of symmetric somers' d is wrong.
@item
Approximate T of uncertainty coefficient is wrong.
@end itemize

Fixes for any of these deficiencies would be welcomed.

@node T-TEST,  , CROSSTABS, Statistics
@comment  node-name,  next,  previous,  up
@section T-TEST

@vindex T-TEST
@display
T-TEST
        /MISSING=@{ANALYSIS,LISTWISE@} @{EXCLUDE,INCLUDE@}
        /CRITERIA=CIN(confidence)


(One Sample mode.)
        TESTVAL=test_value
        /VARIABLES=var_list


(Independent Samples mode.)
        GROUPS=var(value1 [, value2])
        /VARIABLES=var_list


(Paired Samples mode.)
        PAIRS=var_list [WITH var_list [(PAIRED)] ]

@end display


The @cmd{T-TEST} procedure outputs tables used in testing hypotheses about 
means.  
It operates in one of three modes:
@itemize
@item One Sample mode.
@item Independent Groups mode.
@item Paired mode.
@end itemize

@noindent
Each of these modes are described in more detail below.
There are two optional subcommands which are common to all modes.

The @cmd{/CRITERIA} subcommand tells PSPP the confidence interval used
in the tests.  The default value is 0.95.


The @cmd{MISSING} subcommand determines the handling of missing
variables.  
If INCLUDE is set, then user-missing values are included in the
calculations, but system-missing values are not.
If EXCLUDE is set, which is the default, user-missing
values are excluded as well as system-missing values. 
This is the default.

If LISTWISE is set, then the entire case is excluded from analysis
whenever any variable  specified in the @cmd{/VARIABLES}, @cmd{/PAIRS} or 
@cmd{/GROUPS} subcommands contains a missing value.   
If ANALYSIS is set, then missing values are excluded only in the analysis for
which they would be needed. This is the default.


@menu
* One Sample Mode::             Testing against a hypothesised mean
* Independent Samples Mode::    Testing two independent groups for equal mean
* Paired Samples Mode::         Testing two interdependent groups for equal mean
@end menu

@node One Sample Mode, Independent Samples Mode, T-TEST, T-TEST
@subsection One Sample Mode

The @cmd{TESTVAL} subcommand invokes the One Sample mode.
This mode is used to test a population mean against a hypothesised
mean. 
The value given to the @cmd{TESTVAL} subcommand is the value against
which you wish to test.
In this mode, you must also use the @cmd{/VARIABLES} subcommand to
tell PSPP which variables you wish to test.

@node Independent Samples Mode, Paired Samples Mode, One Sample Mode, T-TEST
@comment  node-name,  next,  previous,  up
@subsection Independent Samples Mode

The @cmd{GROUPS} subcommand invokes Independent Samples mode or
`Groups' mode. 
This mode is used to test whether two groups of values have the
same population mean.
In this mode, you must also use the @cmd{/VARIABLES} subcommand to
tell PSPP the dependent variables you wish to test.

The variable given in the @cmd{GROUPS} subcommand is the independent
variable which determines to which group the samples belong.
The values in parentheses are the specific values of the independent
variable for each group.
If the parentheses are omitted and no values are given, the default values 
of 1.0 and 2.0 are assumed.

If the independent variable is numeric, 
it is acceptable to specify only one value inside the parentheses.
If you do this, cases where the independent variable is
less than  or equal to this value belong to the first group, and cases
greater than this value belong to the second group.
When using this form of the @cmd{GROUPS} subcommand, missing values in
the independent variable are excluded on a listwise basis, regardless
of whether @cmd{/MISSING=LISTWISE} was specified.


@node Paired Samples Mode,  , Independent Samples Mode, T-TEST
@comment  node-name,  next,  previous,  up
@subsection Paired Samples Mode

The @cmd{PAIRS} subcommand introduces Paired Samples mode.
Use this mode when repeated measures have been taken from the same
samples.
If the the @code{WITH} keyword is omitted, then tables for all
combinations of variables given in the @cmd{PAIRS} subcommand are
generated. 
If the @code{WITH} keyword is given, and the @code{(PAIRED)} keyword
is also given, then the number of variables preceding @code{WITH}
must be the same as the number following it.
In this case, tables for each respective pair of variables are
generated.
In the event that the @code{WITH} keyword is given, but the
@code{(PAIRED)} keyword is omitted, then tables for each combination
of variable preceding @code{WITH} against variable following
@code{WITH} are generated.


@node Utilities, Not Implemented, Statistics, Top
@chapter Utilities

Commands that don't fit any other category are placed here.

Most of these commands are not affected by commands like @cmd{IF} and
@cmd{LOOP}:
they take effect only once, unconditionally, at the time that they are
encountered in the input.

@menu
* COMMENT::                     Document your syntax file.
* DOCUMENT::                    Document the active file.
* DISPLAY DOCUMENTS::           Display active file documents.
* DISPLAY FILE LABEL::          Display the active file label.
* DROP DOCUMENTS::              Remove documents from the active file.
* ERASE::                       Erase a file.
* EXECUTE::                     Execute pending transformations.
* FILE LABEL::                  Set the active file's label.
* FINISH::                      Terminate the PSPP session.
* HOST::                        Temporarily return to the operating system.
* INCLUDE::                     Include a file within the current one.
* QUIT::                        Terminate the PSPP session.
* SET::                         Adjust PSPP runtime parameters.
* SHOW::                        Display runtime parameters.
* SUBTITLE::                    Provide a document subtitle.
* TITLE::                       Provide a document title.
@end menu

@node COMMENT, DOCUMENT, Utilities, Utilities
@section COMMENT
@vindex COMMENT
@vindex *

@display 
Two possibles syntaxes:
        COMMENT comment text @dots{} .
        *comment text @dots{} .
@end display

@cmd{COMMENT} is ignored.  It is used to provide information to
the author and other readers of the PSPP syntax file.  

@cmd{COMMENT} can extend over any number of lines.  Don't forget to
terminate it with a dot or a blank line.

@node DOCUMENT, DISPLAY DOCUMENTS, COMMENT, Utilities
@section DOCUMENT
@vindex DOCUMENT

@display
DOCUMENT documentary_text.
@end display

@cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
active file.  Documents added in this way are saved to system files.
They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
DOCUMENTS}.  They can be removed from the active file with @cmd{DROP
DOCUMENTS}.

Specify the documentary text following the DOCUMENT keyword.  You can
extend the documentary text over as many lines as necessary.  Lines are
truncated at 80 characters width.  Don't forget to terminate
the command with a dot or a blank line.

@node DISPLAY DOCUMENTS, DISPLAY FILE LABEL, DOCUMENT, Utilities
@section DISPLAY DOCUMENTS
@vindex DISPLAY DOCUMENTS

@display
DISPLAY DOCUMENTS.
@end display

@cmd{DISPLAY DOCUMENTS} displays the documents in the active file.  Each
document is preceded by a line giving the time and date that it was
added.  @xref{DOCUMENT}.

@node DISPLAY FILE LABEL, DROP DOCUMENTS, DISPLAY DOCUMENTS, Utilities
@section DISPLAY FILE LABEL
@vindex DISPLAY FILE LABEL

@display
DISPLAY FILE LABEL.
@end display

@cmd{DISPLAY FILE LABEL} displays the file label contained in the
active file,
if any.  @xref{FILE LABEL}.

@node DROP DOCUMENTS, ERASE, DISPLAY FILE LABEL, Utilities
@section DROP DOCUMENTS
@vindex DROP DOCUMENTS

@display
DROP DOCUMENTS.
@end display

@cmd{DROP DOCUMENTS} removes all documents from the active file.
New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).

@cmd{DROP DOCUMENTS} changes only the active file.  It does not modify any
system files stored on disk.


@node ERASE, EXECUTE, DROP DOCUMENTS, Utilities
@comment  node-name,  next,  previous,  up
@section ERASE
@vindex ERASE

@display
ERASE FILE file_name.
@end display

@cmd{ERASE FILE} deletes a file from the local filesystem.
file_name must be quoted.
This command cannot be used if the SAFER setting is active.


@node EXECUTE, FILE LABEL, ERASE, Utilities
@section EXECUTE
@vindex EXECUTE

@display
EXECUTE.
@end display

@cmd{EXECUTE} causes the active file to be read and all pending
transformations to be executed.

@node FILE LABEL, FINISH, EXECUTE, Utilities
@section FILE LABEL
@vindex FILE LABEL

@display
FILE LABEL file_label.
@end display

@cmd{FILE LABEL} provides a title for the active file.  This
title will be saved into system files and portable files that are
created during this PSPP run.

file_label need not be quoted.  If quotes are
included, they become part of the file label.

@node FINISH, HOST, FILE LABEL, Utilities
@section FINISH
@vindex FINISH

@display
FINISH.
@end display

@cmd{FINISH} terminates the current PSPP session and returns
control to the operating system.

This command is not valid in interactive mode.

@node HOST, INCLUDE, FINISH, Utilities
@comment  node-name,  next,  previous,  up
@section HOST
@vindex HOST

@display
HOST.
@end display

@cmd{HOST} suspends the current PSPP session and temporarily returns control 
to the operating system.
This command cannot be used if the SAFER setting is active.


@node INCLUDE, QUIT, HOST, Utilities
@section INCLUDE
@vindex INCLUDE
@vindex @@

@display
Two possible syntaxes:
        INCLUDE 'filename'.
        @@filename.
@end display

@cmd{INCLUDE} causes the PSPP command processor to read an
additional command file as if it were included bodily in the current
command file.

Include files may be nested to any depth, up to the limit of available
memory.

@node QUIT, SET, INCLUDE, Utilities
@section QUIT
@vindex QUIT

@display
Two possible syntaxes:
        QUIT.
        EXIT.
@end display

@cmd{QUIT} terminates the current PSPP session and returns control
to the operating system.  

This command is not valid within a command file.

@node SET, SHOW, QUIT, Utilities
@section SET
@vindex SET

@display
SET

(data input)
        /BLANKS=@{SYSMIS,'.',number@}
        /DECIMAL=@{DOT,COMMA@}
        /FORMAT=fmt_spec

(program input)
        /ENDCMD='.'
        /NULLINE=@{ON,OFF@}

(interaction)
        /CPROMPT='cprompt_string'
        /DPROMPT='dprompt_string'
        /ERRORBREAK=@{OFF,ON@}
        /MXERRS=max_errs
        /MXWARNS=max_warnings
        /PROMPT='prompt'
        /VIEWLENGTH=@{MINIMUM,MEDIAN,MAXIMUM,n_lines@}
        /VIEWWIDTH=n_characters

(program execution)
        /MEXPAND=@{ON,OFF@}
        /MITERATE=max_iterations
        /MNEST=max_nest
        /MPRINT=@{ON,OFF@}
        /MXLOOPS=max_loops
        /SEED=@{RANDOM,seed_value@}
        /UNDEFINED=@{WARN,NOWARN@}

(data output)
        /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
        /DECIMAL=@{DOT,COMMA@}
        /FORMAT=fmt_spec

(output routing)
        /ECHO=@{ON,OFF@}
        /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
        /INCLUDE=@{ON,OFF@}
        /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
        /PRINTBACK=@{ON,OFF@}
        /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}

(output activation)
        /LISTING=@{ON,OFF@}
        /PRINTER=@{ON,OFF@}
        /SCREEN=@{ON,OFF@}

(output driver options)
        /HEADERS=@{NO,YES,BLANK@}
        /LENGTH=@{NONE,length_in_lines@}
        /LISTING=filename
        /MORE=@{ON,OFF@}
        /PAGER=@{OFF,"pager_name"@}
        /WIDTH=@{NARROW,WIDTH,n_characters@}

(logging)
        /JOURNAL=@{ON,OFF@} [filename]
        /LOG=@{ON,OFF@} [filename]

(system files)
        /COMPRESSION=@{ON,OFF@}
        /SCOMPRESSION=@{ON,OFF@}

(security)
        /SAFER=ON

(obsolete settings accepted for compatibility, but ignored)
        /AUTOMENU=@{ON,OFF@}
        /BEEP=@{ON,OFF@}
        /BLOCK='c'
        /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
        /CASE=@{UPPER,UPLOW@}
        /COLOR=@dots{}
        /CPI=cpi_value
        /DISK=@{ON,OFF@}
        /EJECT=@{ON,OFF@}
        /HELPWINDOWS=@{ON,OFF@}
        /HIGHRES=@{ON,OFF@}
        /HISTOGRAM='c'
        /LOWRES=@{AUTO,ON,OFF@}
        /LPI=lpi_value
        /MENUS=@{STANDARD,EXTENDED@}
        /MXMEMORY=max_memory
        /PTRANSLATE=@{ON,OFF@}
        /RCOLORS=@dots{}
        /RUNREVIEW=@{AUTO,MANUAL@}
        /SCRIPTTAB='c'
        /TB1=@{'xxx','xxxxxxxxxxx'@}
        /TBFONTS='string'
        /WORKDEV=drive_letter
        /WORKSPACE=workspace_size
        /XSORT=@{YES,NO@}
@end display

@cmd{SET} allows the user to adjust several parameters relating to
PSPP's execution.  Since there are many subcommands to this command, its
subcommands will be examined in groups.

On subcommands that take boolean values, ON and YES are synonym, and
as are OFF and NO, when used as subcommand values.

The data input subcommands affect the way that data is read from data
files.  The data input subcommands are

@table @asis
@item BLANKS
This is the value assigned to an item data item that is empty or
contains only whitespace.  An argument of SYSMIS or '.' will cause the
system-missing value to be assigned to null items.  This is the
default.  Any real value may be assigned.

@item DECIMAL
The default DOT setting causes the decimal point character to be
@samp{.}.  A setting of COMMA causes the decimal point character to be
@samp{,}.

@item FORMAT
Allows the default numeric input/output format to be specified.  The
default is F8.2.  @xref{Input/Output Formats}.
@end table

Program input subcommands affect the way that programs are parsed when
they are typed interactively or run from a script.  They are

@table @asis
@item ENDCMD
This is a single character indicating the end of a command.  The default
is @samp{.}.  Don't change this.

@item NULLINE
Whether a blank line is interpreted as ending the current command.  The
default is ON.
@end table

Interaction subcommands affect the way that PSPP interacts with an
online user.  The interaction subcommands are

@table @asis
@item CPROMPT
The command continuation prompt.  The default is @samp{    > }.

@item DPROMPT
Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
DATA}).  The default is @samp{data> }.

@item ERRORBREAK
Whether an error causes PSPP to stop processing the current command
file after finishing the current command.  The default is OFF.

@item MXERRS
The maximum number of errors before PSPP halts processing of the current
command file.  The default is 50.

@item MXWARNS
The maximum number of warnings + errors before PSPP halts processing the
current command file.  The default is 100.

@item PROMPT
The command prompt.  The default is @samp{PSPP> }.

@item VIEWLENGTH
The length of the screen in lines.  MINIMUM means 25 lines, MEDIAN and
MAXIMUM mean 43 lines.  Otherwise specify the number of lines.  Normally
PSPP should auto-detect your screen size so this shouldn't have to be
used.

@item VIEWWIDTH
The width of the screen in characters.  Normally 80 or 132.
@end table

Program execution subcommands control the way that PSPP commands
execute.  The program execution subcommands are

@table @asis
@item MEXPAND
@itemx MITERATE
@itemx MNEST
@itemx MPRINT
Currently not used.

@item MXLOOPS
The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).

@item SEED
The initial pseudo-random number seed.  Set to a real number or to
RANDOM, which will obtain an initial seed from the current time of day.

@item UNDEFINED
Currently not used.
@end table

Data output subcommands affect the format of output data.  These
subcommands are

@table @asis
@item CCA
@itemx CCB
@itemx CCC
@itemx CCD
@itemx CCE
Set up custom currency formats.  The argument is a string which must
contain exactly three commas or exactly three periods.  If commas, then
the grouping character for the currency format is @samp{,}, and the
decimal point character is @samp{.}; if periods, then the situation is
reversed.  

The commas or periods divide the string into four fields, which are, in
order, the negative prefix, prefix, suffix, and negative suffix.  When a
value is formatted using the custom currency format, the prefix precedes
the value formatted and the suffix follows it.  In addition, if the
value is negative, the negative prefix precedes the prefix and the
negative suffix follows the suffix.

@item DECIMAL
The default DOT setting causes the decimal point character to be
@samp{.}.  A setting of COMMA causes the decimal point character to be
@samp{,}.

@item FORMAT
Allows the default numeric input/output format to be specified.  The
default is F8.2.  @xref{Input/Output Formats}.
@end table

Output routing subcommands affect where the output of transformations
and procedures is sent.  These subcommands are

@table @asis
@item ECHO

If turned on, commands are written to the listing file as they are read
from command files.  The default is OFF.

@itemx ERRORS
@itemx INCLUDE
@itemx MESSAGES
@item PRINTBACK
@item RESULTS
Currently not used.
@end table

Output activation subcommands affect whether output devices of
particular types are enabled.  These subcommands are

@table @asis
@item LISTING
Enable or disable listing devices.

@item PRINTER
Enable or disable printer devices.

@item SCREEN
Enable or disable screen devices.
@end table

Output driver option subcommands affect output drivers' settings.  These
subcommands are

@table @asis
@item HEADERS
@itemx LENGTH
@itemx LISTING
@itemx MORE
@itemx PAGER 
@itemx WIDTH
Currently not used.
@end table

Logging subcommands affect logging of commands executed to external
files.  These subcommands are

@table @asis
@item JOURNAL
@item LOG
Not currently used.
@end table

System file subcommands affect the default format of system files
produced by PSPP.  These subcommands are

@table @asis
@item COMPRESSION
Not currently used.

@item SCOMPRESSION
Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
compressed by default.  The default is ON.
@end table

Security subcommands affect the operations that commands are allowed to
perform.  The security subcommands are

@table @asis
@item SAFER
When set, this setting cannot ever be reset, for obvious security
reasons.  Setting this option disables the following operations:

@itemize @bullet
@item
The ERASE command.
@item
The HOST command.
@item
Pipe filenames (filenames beginning or ending with @samp{|}).
@end itemize

Be aware that this setting does not guarantee safety (commands can still
overwrite files, for instance) but it is an improvement.
@end table

@node SHOW, SUBTITLE, SET, Utilities
@comment  node-name,  next,  previous,  up
@section SHOW
@vindex SHOW

@display
SHOW
        /@var{subcommand}
        
@end display

@cmd{SHOW} can be used to display the current state of PSPP's
execution parameters.  All of the parameters which can be changed 
using  @code{SET} @xref{SET}, can be examined using @cmd{SHOW}, by
using a subcommand with the same name.
In addition, @code{SHOW} supports the following subcommands:

@table @code
@item WARRANTY
Show details of the lack of warranty for PSPP.
@item COPYING
Display the terms of PSPP's copyright licence @ref{License}.
@end table



@node SUBTITLE, TITLE, SHOW, Utilities
@section SUBTITLE
@vindex SUBTITLE

@display
SUBTITLE 'subtitle_string'.
  or
SUBTITLE subtitle_string.
@end display

@cmd{SUBTITLE} provides a subtitle to a particular PSPP
run.  This subtitle appears at the top of each output page below the
title, if headers are enabled on the output device.

Specify a subtitle as a string in quotes.  The alternate syntax that did
not require quotes is now obsolete.  If it is used then the subtitle is
converted to all uppercase.

@node TITLE,  , SUBTITLE, Utilities
@section TITLE
@vindex TITLE

@display
TITLE 'title_string'.
  or
TITLE title_string.
@end display

@cmd{TITLE} provides a title to a particular PSPP run.
This title appears at the top of each output page, if headers are enabled
on the output device.

Specify a title as a string in quotes.  The alternate syntax that did
not require quotes is now obsolete.  If it is used then the title is
converted to all uppercase.

@node Not Implemented, Data File Format, Utilities, Top
@chapter Not Implemented

This chapter lists parts of the PSPP language that are not yet
implemented.

The following transformations and utilities are not yet implemented, but
they will be supported in a later release.

@itemize @bullet
@item
ADD FILES
@item
ANOVA
@item
DEFINE
@item
FILE TYPE
@item
GET SAS
@item
GET TRANSLATE
@item
MCONVERT
@item
PLOT
@item
PRESERVE
@item
PROCEDURE OUTPUT
@item
RESTORE
@item
SAVE TRANSLATE
@item
SHOW
@item
UPDATE
@end itemize

The following transformations and utilities are not implemented.  There
are no plans to support them in future releases.  Contributions to
implement them will still be accepted.

@itemize @bullet
@item
EDIT
@item
GET DATABASE
@item
GET OSIRIS
@item
GET SCSS
@item
GSET
@item
HELP
@item
INFO
@item
INPUT MATRIX
@item
KEYED DATA LIST
@item
NUMBERED and UNNUMBERED
@item
OPTIONS
@item
REVIEW
@item
SAVE SCSS
@item
SPSS MANAGER
@item
STATISTICS
@end itemize

@node Data File Format, Portable File Format, Not Implemented, Top
@chapter Data File Format

PSPP necessarily uses the same format for system files as do the
products with which it is compatible.  This chapter is a description of
that format.

There are three data types used in system files: 32-bit integers, 64-bit
floating points, and 1-byte characters.  In this document these will
simply be referred to as @code{int32}, @code{flt64}, and @code{char},
the names that are used in the PSPP source code.  Every field of type
@code{int32} or @code{flt64} is aligned on a 32-bit boundary.

The endianness of data in PSPP system files is not specified.  System
files output on a computer of a particular endianness will have the
endianness of that computer.  However, PSPP can read files of either
endianness, regardless of its host computer's endianness.  PSPP
translates endianness for both integer and floating point numbers.

Floating point formats are also not specified.  PSPP does not
translate between floating point formats.  This is unlikely to be a
problem as all modern computer architectures use IEEE 754 format for
floating point representation.

The PSPP system-missing value is represented by the largest possible
negative number in the floating point format; in C, this is most likely
@code{-DBL_MAX}.  There are two other important values used in missing
values: @code{HIGHEST} and @code{LOWEST}.  These are represented by the
largest possible positive number (probably @code{DBL_MAX}) and the
second-largest negative number.  The latter must be determined in a
system-dependent manner; in IEEE 754 format it is represented by value
@code{0xffeffffffffffffe}.

System files are divided into records.  Each record begins with an
@code{int32} giving a numeric record type.  Individual record types are
described below:

@menu
* File Header Record::          
* Variable Record::             
* Value Label Record::          
* Value Label Variable Record::  
* Document Record::             
* Machine int32 Info Record::   
* Machine flt64 Info Record::   
* Miscellaneous Informational Records::  
* Dictionary Termination Record::  
* Data Record::                 
@end menu

@node File Header Record, Variable Record, Data File Format, Data File Format
@section File Header Record

The file header is always the first record in the file.

@example
struct sysfile_header
  @{
    char                rec_type[4];
    char                prod_name[60];
    int32               layout_code;
    int32               case_size;
    int32               compressed;
    int32               weight_index;
    int32               ncases;
    flt64               bias;
    char                creation_date[9];
    char                creation_time[8];
    char                file_label[64];
    char                padding[3];
  @};
@end example

@table @code
@item char rec_type[4];
Record type code.  Always set to @samp{$FL2}.  This is the only record
for which the record type is not of type @code{int32}.

@item char prod_name[60];
Product identification string.  This always begins with the characters
@samp{@@(#) SPSS DATA FILE}.  PSPP uses the remaining characters to
give its version and the operating system name; for example, @samp{GNU
pspp 0.1.4 - sparc-sun-solaris2.5.2}.  The string is truncated if it
would be longer than 60 characters; otherwise it is padded on the right
with spaces.

@item int32 layout_code;
Always set to 2.  PSPP reads this value to determine the
file's endianness.

@item int32 case_size;
Number of data elements per case.  This is the number of variables,
except that long string variables add extra data elements (one for every
8 characters after the first 8).

@item int32 compressed;
Set to 1 if the data in the file is compressed, 0 otherwise.

@item int32 weight_index;
If one of the variables in the data set is used as a weighting variable,
set to the index of that variable.  Otherwise, set to 0.

@item int32 ncases;
Set to the number of cases in the file if it is known, or -1 otherwise.

In the general case it is not possible to determine the number of cases
that will be output to a system file at the time that the header is
written.  The way that this is dealt with is by writing the entire
system file, including the header, then seeking back to the beginning of
the file and writing just the @code{ncases} field.  For `files' in which
this is not valid, the seek operation fails.  In this case,
@code{ncases} remains -1.

@item flt64 bias;
Compression bias.  Always set to 100.  The significance of this value is
that only numbers between @code{(1 - bias)} and @code{(251 - bias)} can
be compressed.

@item char creation_date[9];
Set to the date of creation of the system file, in @samp{dd mmm yy}
format, with the month as standard English abbreviations, using an
initial capital letter and following with lowercase.  If the date is not
available then this field is arbitrarily set to @samp{01 Jan 70}.

@item char creation_time[8];
Set to the time of creation of the system file, in @samp{hh:mm:ss}
format and using 24-hour time.  If the time is not available then this
field is arbitrarily set to @samp{00:00:00}.

@item char file_label[64];
Set the the file label declared by the user, if any.  Padded on the
right with spaces.

@item char padding[3];
Ignored padding bytes to make the structure a multiple of 32 bits in
length.  Set to zeros.
@end table

@node Variable Record, Value Label Record, File Header Record, Data File Format
@section Variable Record

Immediately following the header must come the variable records.  There
must be one variable record for every variable and every 8 characters in
a long string beyond the first 8; i.e., there must be exactly as many
variable records as the value specified for @code{case_size} in the file
header record.

@example
struct sysfile_variable
  @{
    int32               rec_type;
    int32               type;
    int32               has_var_label;
    int32               n_missing_values;
    int32               print;
    int32               write;
    char                name[8];

    /* The following two fields are present 
       only if has_var_label is 1. */
    int32               label_len;
    char                label[/* variable length */];

    /* The following field is present only
       if n_missing_values is not 0. */
    flt64               missing_values[/* variable length*/];
  @};
@end example

@table @code
@item int32 rec_type;
Record type code.  Always set to 2.

@item int32 type;
Variable type code.  Set to 0 for a numeric variable.  For a short
string variable or the first part of a long string variable, this is set
to the width of the string.  For the second and subsequent parts of a
long string variable, set to -1, and the remaining fields in the
structure are ignored.

@item int32 has_var_label;
If this variable has a variable label, set to 1; otherwise, set to 0.

@item int32 n_missing_values;
If the variable has no missing values, set to 0.  If the variable has
one, two, or three discrete missing values, set to 1, 2, or 3,
respectively.  If the variable has a range for missing variables, set to
-2; if the variable has a range for missing variables plus a single
discrete value, set to -3.

@item int32 print;
Print format for this variable.  See below.

@item int32 write;
Write format for this variable.  See below.

@item char name[8];
Variable name.  The variable name must begin with a capital letter or
the at-sign (@samp{@@}).  Subsequent characters may also be octothorpes
(@samp{#}), dollar signs (@samp{$}), underscores (@samp{_}), or full
stops (@samp{.}).  The variable name is padded on the right with spaces.

@item int32 label_len;
This field is present only if @code{has_var_label} is set to 1.  It is
set to the length, in characters, of the variable label, which must be a
number between 0 and 120.

@item char label[/* variable length */];
This field is present only if @code{has_var_label} is set to 1.  It has
length @code{label_len}, rounded up to the nearest multiple of 32 bits.
The first @code{label_len} characters are the variable's variable label.

@item flt64 missing_values[/* variable length */];
This field is present only if @code{n_missing_values} is not 0.  It has
the same number of elements as the absolute value of
@code{n_missing_values}.  For discrete missing values, each element
represents one missing value.  When a range is present, the first
element denotes the minimum value in the range, and the second element
denotes the maximum value in the range.  When a range plus a value are
present, the third element denotes the additional discrete missing
value.  HIGHEST and LOWEST are indicated as described in the chapter
introduction.
@end table

The @code{print} and @code{write} members of sysfile_variable are output
formats coded into @code{int32} types.  The LSB (least-significant byte)
of the @code{int32} represents the number of decimal places, and the
next two bytes in order of increasing significance represent field width
and format type, respectively.  The MSB (most-significant byte) is not
used and should be set to zero.

Format types are defined as follows:
@table @asis
@item 0
Not used.
@item 1
@code{A}
@item 2
@code{AHEX}
@item 3
@code{COMMA}
@item 4
@code{DOLLAR}
@item 5
@code{F}
@item 6
@code{IB}
@item 7
@code{PIBHEX}
@item 8
@code{P}
@item 9
@code{PIB}
@item 10
@code{PK}
@item 11
@code{RB}
@item 12
@code{RBHEX}
@item 13
Not used.
@item 14
Not used.
@item 15
@code{Z}
@item 16
@code{N}
@item 17
@code{E}
@item 18
Not used.
@item 19
Not used.
@item 20
@code{DATE}
@item 21
@code{TIME}
@item 22
@code{DATETIME}
@item 23
@code{ADATE}
@item 24
@code{JDATE}
@item 25
@code{DTIME}
@item 26
@code{WKDAY}
@item 27
@code{MONTH}
@item 28
@code{MOYR}
@item 29
@code{QYR}
@item 30
@code{WKYR}
@item 31
@code{PCT}
@item 32
@code{DOT}
@item 33
@code{CCA}
@item 34
@code{CCB}
@item 35
@code{CCC}
@item 36
@code{CCD}
@item 37
@code{CCE}
@item 38
@code{EDATE}
@item 39
@code{SDATE}
@end table

@node Value Label Record, Value Label Variable Record, Variable Record, Data File Format
@section Value Label Record

Value label records must follow the variable records and must precede
the header termination record.  Other than this, they may appear
anywhere in the system file.  Every value label record must be
immediately followed by a label variable record, described below.

Value label records begin with @code{rec_type}, an @code{int32} value
set to the record type of 3.  This is followed by @code{count}, an
@code{int32} value set to the number of value labels present in this
record.

These two fields are followed by a series of @code{count} tuples.  Each
tuple is divided into two fields, the value and the label.  The first of
these, the value, is composed of a 64-bit value, which is either a
@code{flt64} value or up to 8 characters (padded on the right to 8
bytes) denoting a short string value.  Whether the value is a
@code{flt64} or a character string is not defined inside the value label
record.

The second field in the tuple, the label, has variable length.  The
first @code{char} is a count of the number of characters in the value
label.  The remainder of the field is the label itself.  The field is
padded on the right to a multiple of 64 bits in length.

@node Value Label Variable Record, Document Record, Value Label Record, Data File Format
@section Value Label Variable Record

Every value label variable record must be immediately preceded by a
value label record, described above.

@example
struct sysfile_value_label_variable
  @{
     int32              rec_type;
     int32              count;
     int32              vars[/* variable length */];
  @};
@end example

@table @code
@item int32 rec_type;
Record type.  Always set to 4.

@item int32 count;
Number of variables that the associated value labels from the value
label record are to be applied.

@item int32 vars[/* variable length];
A list of variables to which to apply the value labels.  There are
@code{count} elements.
@end table

@node Document Record, Machine int32 Info Record, Value Label Variable Record, Data File Format
@section Document Record

There must be no more than one document record per system file.
Document records must follow the variable records and precede the
dictionary termination record.

@example
struct sysfile_document
  @{
    int32               rec_type;
    int32               n_lines;
    char                lines[/* variable length */][80];
  @};
@end example

@table @code
@item int32 rec_type;
Record type.  Always set to 6.

@item int32 n_lines;
Number of lines of documents present.

@item char lines[/* variable length */][80];
Document lines.  The number of elements is defined by @code{n_lines}.
Lines shorter than 80 characters are padded on the right with spaces.
@end table

@node Machine int32 Info Record, Machine flt64 Info Record, Document Record, Data File Format
@section Machine @code{int32} Info Record

There must be no more than one machine @code{int32} info record per
system file.  Machine @code{int32} info records must follow the variable
records and precede the dictionary termination record.

@example
struct sysfile_machine_int32_info
  @{
    /* Header. */
    int32               rec_type;
    int32               subtype;
    int32               size;
    int32               count;

    /* Data. */
    int32               version_major;
    int32               version_minor;
    int32               version_revision;
    int32               machine_code;
    int32               floating_point_rep;
    int32               compression_code;
    int32               endianness;
    int32               character_code;
  @};
@end example

@table @code
@item int32 rec_type;
Record type.  Always set to 7.

@item int32 subtype;
Record subtype.  Always set to 3.

@item int32 size;
Size of each piece of data in the data part, in bytes.  Always set to 4.

@item int32 count;
Number of pieces of data in the data part.  Always set to 8.

@item int32 version_major;
PSPP major version number.  In version @var{x}.@var{y}.@var{z}, this
is @var{x}.

@item int32 version_minor;
PSPP minor version number.  In version @var{x}.@var{y}.@var{z}, this
is @var{y}.

@item int32 version_revision;
PSPP version revision number.  In version @var{x}.@var{y}.@var{z},
this is @var{z}.

@item int32 machine_code;
Machine code.  PSPP always set this field to value to -1, but other
values may appear.

@item int32 floating_point_rep;
Floating point representation code.  For IEEE 754 systems this is 1.
IBM 370 sets this to 2, and DEC VAX E to 3.

@item int32 compression_code;
Compression code.  Always set to 1.

@item int32 endianness;
Machine endianness.  1 indicates big-endian, 2 indicates little-endian.

@item int32 character_code;
Character code.  1 indicates EBCDIC, 2 indicates 7-bit ASCII, 3
indicates 8-bit ASCII, 4 indicates DEC Kanji.
@end table

@node Machine flt64 Info Record, Miscellaneous Informational Records, Machine int32 Info Record, Data File Format
@section Machine @code{flt64} Info Record

There must be no more than one machine @code{flt64} info record per
system file.  Machine @code{flt64} info records must follow the variable
records and precede the dictionary termination record.

@example
struct sysfile_machine_flt64_info
  @{
    /* Header. */
    int32               rec_type;
    int32               subtype;
    int32               size;
    int32               count;

    /* Data. */
    flt64               sysmis;
    flt64               highest;
    flt64               lowest;
  @};
@end example

@table @code
@item int32 rec_type;
Record type.  Always set to 7.

@item int32 subtype;
Record subtype.  Always set to 4.

@item int32 size;
Size of each piece of data in the data part, in bytes.  Always set to 4.

@item int32 count;
Number of pieces of data in the data part.  Always set to 3.

@item flt64 sysmis;
The system missing value.

@item flt64 highest;
The value used for HIGHEST in missing values.

@item flt64 lowest;
The value used for LOWEST in missing values.
@end table

@node Miscellaneous Informational Records, Dictionary Termination Record, Machine flt64 Info Record, Data File Format
@section Miscellaneous Informational Records

Miscellaneous informational records must follow the variable records and
precede the dictionary termination record.

Miscellaneous informational records are ignored by PSPP when reading
system files.  They are not written by PSPP when writing system files.

@example
struct sysfile_misc_info
  @{
    /* Header. */
    int32               rec_type;
    int32               subtype;
    int32               size;
    int32               count;

    /* Data. */
    char                data[/* variable length */];
  @};
@end example

@table @code
@item int32 rec_type;
Record type.  Always set to 7.

@item int32 subtype;
Record subtype.  May take any value.  According to Aapi
H@"am@"al@"ainen, value 5 indicates a set of grouped variables and 6
indicates date info (probably related to USE).

@item int32 size;
Size of each piece of data in the data part.  Should have the value 4 or
8, for @code{int32} and @code{flt64}, respectively.

@item int32 count;
Number of pieces of data in the data part.

@item char data[/* variable length */];
Arbitrary data.  There must be @code{size} times @code{count} bytes of
data.
@end table

@node Dictionary Termination Record, Data Record, Miscellaneous Informational Records, Data File Format
@section Dictionary Termination Record

The dictionary termination record must follow all other records, except
for the actual cases, which it must precede.  There must be exactly one
dictionary termination record in every system file.

@example
struct sysfile_dict_term
  @{
    int32               rec_type;
    int32               filler;
  @};
@end example

@table @code
@item int32 rec_type;
Record type.  Always set to 999.

@item int32 filler;
Ignored padding.  Should be set to 0.
@end table

@node Data Record,  , Dictionary Termination Record, Data File Format
@section Data Record

Data records must follow all other records in the data file.  There must
be at least one data record in every system file.

The format of data records varies depending on whether the data is
compressed.  Regardless, the data is arranged in a series of 8-byte
elements.

When data is not compressed, Every case is composed of @code{case_size}
of these 8-byte elements, where @code{case_size} comes from the file
header record (@pxref{File Header Record}).  Each element corresponds to
the variable declared in the respective variable record (@pxref{Variable
Record}).  Numeric values are given in @code{flt64} format; string
values are literal characters string, padded on the right when
necessary.

Compressed data is arranged in the following manner: the first 8-byte
element in the data section is divided into a series of 1-byte command
codes.  These codes have meanings as described below:

@table @asis
@item 0
Ignored.  If the program writing the system file accumulates compressed
data in blocks of fixed length, 0 bytes can be used to pad out extra
bytes remaining at the end of a fixed-size block.

@item 1 through 251
These values indicate that the corresponding numeric variable has the
value @code{(@var{code} - @var{bias})} for the case being read, where
@var{code} is the value of the compression code and @var{bias} is the
variable @code{compression_bias} from the file header.  For example,
code 105 with bias 100.0 (the normal value) indicates a numeric variable
of value 5.

@item 252
End of file.  This code may or may not appear at the end of the data
stream.  PSPP always outputs this code but its use is not required.

@item 253
This value indicates that the numeric or string value is not
compressible.  The value is stored in the 8-byte element following the
current block of command bytes.  If this value appears twice in a block
of command bytes, then it indicates the second element following the
command bytes, and so on.

@item 254
Used to indicate a string value that is all spaces.

@item 255
Used to indicate the system-missing value.
@end table

When the end of the first 8-byte element of command bytes is reached,
any blocks of non-compressible values are skipped, and the next element
of command bytes is read and interpreted, until the end of the file is
reached.

@node Portable File Format, q2c Input Format, Data File Format, Top
@chapter Portable File Format

These days, most computers use the same internal data formats for
integer and floating-point data, if one ignores little differences like
big- versus little-endian byte ordering.  However, occasionally it is
necessary to exchange data between systems with incompatible data
formats.  This is what portable files are designed to do.

@strong{Please note:} Although all of the following information is
correct, as far as the author has been able to ascertain, it is gleaned
from examination of ASCII-formatted portable files only, so some of it
may be incorrect in the general case.

@menu
* Portable File Characters::    
* Portable File Structure::     
* Portable File Header::        
* Version and Date Info Record::  
* Identification Records::      
* Variable Count Record::       
* Case Weight Variable Record::  
* Variable Records::            
* Value Label Records::         
* Portable File Data::          
@end menu

@node Portable File Characters, Portable File Structure, Portable File Format, Portable File Format
@section Portable File Characters

Portable files are arranged as a series of lines of exactly 80
characters each.  Each line is terminated by a carriage-return,
line-feed sequence ``new-lines'').  New-lines are only used to avoid
line length limits imposed by some OSes; they are not meaningful.

The file must be terminated with a @samp{Z} character.  In addition, if
the final line in the file does not have exactly 80 characters, then it
is padded on the right with @samp{Z} characters.  (The file contents may
be in any character set; the file contains a description of its own
character set, as explained in the next section.  Therefore, the
@samp{Z} character is not necessarily an ASCII @samp{Z}.)

For the rest of the description of the portable file format, new-lines
and the trailing @samp{Z}s will be ignored, as if they did not exist,
because they are not an important part of understanding the file
contents.

@node Portable File Structure, Portable File Header, Portable File Characters, Portable File Format
@section Portable File Structure

Every portable file consists of the following records, in sequence:

@itemize @bullet

@item
File header.

@item
Version and date info.

@item
Product identification.

@item
Subproduct identification (optional).

@item
Variable count.

@item
Case weight variable (optional).

@item
Variables.  Each variable record may optionally be followed by a
missing value record and a variable label record.

@item
Value labels (optional).

@item
Data.
@end itemize

Most records are identified by a single-character tag code.  The file
header and version info record do not have a tag.

Other than these single-character codes, there are three types of fields
in a portable file: floating-point, integer, and string.  Floating-point
fields have the following format:

@itemize @bullet

@item
Zero or more leading spaces.

@item
Optional asterisk (@samp{*}), which indicates a missing value.  The
asterisk must be followed by a single character, generally a period
(@samp{.}), but it appears that other characters may also be possible.
This completes the specification of a missing value.

@item
Optional minus sign (@samp{-}) to indicate a negative number.

@item
A whole number, consisting of one or more base-30 digits: @samp{0}
through @samp{9} plus capital letters @samp{A} through @samp{T}.

@item
Optional fraction, consisting of a radix point (@samp{.}) followed by
one or more base-30 digits.

@item
Optional exponent, consisting of a plus or minus sign (@samp{+} or
@samp{-}) followed by one or more base-30 digits.

@item
A forward slash (@samp{/}).
@end itemize

Integer fields take a form identical to floating-point fields, but they
may not contain a fraction.

String fields take the form of a integer field having value @var{n},
followed by exactly @var{n} characters, which are the string content.

@node Portable File Header, Version and Date Info Record, Portable File Structure, Portable File Format
@section Portable File Header

Every portable file begins with a 464-byte header, consisting of a
200-byte collection of vanity splash strings, followed by a 256-byte
character set translation table, followed by an 8-byte tag string.

The 200-byte segment is divided into five 40-byte sections, each of
which represents the string @code{@var{charset} SPSS PORT FILE} in a
different character set encoding, where @var{charset} is the name of
the character set used in the file, e.g. @code{ASCII} or
@code{EBCDIC}.  Each string is padded on the right with spaces in its
respective character set.

It appears that these strings exist only to inform those who might view
the file on a screen, and that they are not parsed by SPSS products.
Thus, they can be safely ignored.  For those interested, the strings are
supposed to be in the following character sets, in the specified order:
EBCDIC, 7-bit ASCII, CDC 6-bit ASCII, 6-bit ASCII, Honeywell 6-bit
ASCII.

The 256-byte segment describes a mapping from the character set used in
the portable file to an arbitrary character set having characters at the
following positions:

@table @asis
@item 0--60

Control characters.  Not important enough to describe in full here.

@item 61--63

Reserved.

@item 64--73

Digits @samp{0} through @samp{9}.

@item 74--99

Capital letters @samp{A} through @samp{Z}. 

@item 100--125

Lowercase letters @samp{a} through @samp{z}.

@item 126

Space.

@item 127--130

Symbols @code{.<(+}

@item 131

Solid vertical pipe.

@item 132--142

Symbols @code{&[]!$*);^-/}

@item 143

Broken vertical pipe.

@item 144--150

Symbols @code{,%_>}?@code{`:}   @c @code{?} is an inverted question mark

@item 151

British pound symbol.

@item 152--155

Symbols @code{@@'="}.

@item 156

Less than or equal symbol.

@item 157

Empty box.

@item 158

Plus or minus.

@item 159

Filled box.

@item 160

Degree symbol.

@item 161

Dagger.

@item 162

Symbol @samp{~}.

@item 163

En dash.

@item 164

Lower left corner box draw.

@item 165

Upper left corner box draw.

@item 166

Greater than or equal symbol.

@item 167--176

Superscript @samp{0} through @samp{9}.

@item 177

Lower right corner box draw.

@item 178

Upper right corner box draw.

@item 179

Not equal symbol.

@item 180

Em dash.

@item 181

Superscript @samp{(}.

@item 182

Superscript @samp{)}.

@item 183

Horizontal dagger (?).

@item 184--186

Symbols @samp{@{@}\}.
@item 187

Cents symbol.

@item 188

Centered dot, or bullet.

@item 189--255

Reserved.
@end table

Symbols that are not defined in a particular character set are set to
the same value as symbol 64; i.e., to @samp{0}.

The 8-byte tag string consists of the exact characters @code{SPSSPORT}
in the portable file's character set, which can be used to verify that
the file is indeed a portable file.

@node Version and Date Info Record, Identification Records, Portable File Header, Portable File Format
@section Version and Date Info Record

This record does not have a tag code.  It has the following structure:

@itemize @bullet
@item
A single character identifying the file format version.  The letter A
represents version 0, and so on.

@item
An 8-character string field giving the file creation date in the format
YYYYMMDD.

@item
A 6-character string field giving the file creation time in the format
HHMMSS.
@end itemize

@node Identification Records, Variable Count Record, Version and Date Info Record, Portable File Format
@section Identification Records

The product identification record has tag code @samp{1}.  It consists of
a single string field giving the name of the product that wrote the
portable file.

The subproduct identification record has tag code @samp{3}.  It
consists of a single string field giving additional information on the
product that wrote the portable file.

@node Variable Count Record, Case Weight Variable Record, Identification Records, Portable File Format
@section Variable Count Record

The variable count record has tag code @samp{4}.  It consists of two
integer fields.  The first contains the number of variables in the file
dictionary.  The purpose of the second is unknown; it contains the value
161 in all portable files examined so far.

@node Case Weight Variable Record, Variable Records, Variable Count Record, Portable File Format
@section Case Weight Variable Record

The case weight variable record is optional.  If it is present, it
indicates the variable used for weighting cases; if it is absent,
cases are unweighted.  It has tag code @samp{6}.  It consists of a
single string field that names the weighting variable.

@node Variable Records, Value Label Records, Case Weight Variable Record, Portable File Format
@section Variable Records

Each variable record represents a single variable.  Variable records
have tag code @samp{7}.  They have the following structure:

@itemize @bullet

@item
Width (integer).  This is 0 for a numeric variable, and a number between 1
and 255 for a string variable.

@item
Name (string).  1--8 characters long.  Must be in all capitals.

@item
Print format.  This is a set of three integer fields:

@itemize @minus

@item
Format type (@pxref{Variable Record}).

@item
Format width.  1--40.

@item
Number of decimal places.  1--40.
@end itemize

@item
Write format.  Same structure as the print format described above.
@end itemize

Each variable record can optionally be followed by a missing value
record, which has tag code @samp{8}.  A missing value record has one
field, the missing value itself (a floating-point or string, as
appropriate).  Up to three of these missing value records can be used.

There is also a record for missing value ranges, which has tag code
@samp{B}.  It is followed by two fields representing the range, which
are floating-point or string as appropriate.  If a missing value range
is present, it may be followed by a single missing value record.

Tag codes @samp{9} and @samp{A} represent @code{LO THRU @var{x}} and
@code{@var{x} THRU HI} ranges, respectively.  Each is followed by a
single field representing @var{x}.  If one of the ranges is present, it
may be followed by a single missing value record.

In addition, each variable record can optionally be followed by a
variable label record, which has tag code @samp{C}.  A variable label
record has one field, the variable label itself (string).

@node Value Label Records, Portable File Data, Variable Records, Portable File Format
@section Value Label Records

Value label records have tag code @samp{D}.  They have the following
format:

@itemize @bullet
@item
Variable count (integer).

@item
List of variables (strings).  The variable count specifies the number in
the list.  Variables are specified by their names.  All variables must
be of the same type (numeric or string).

@item
Label count (integer).

@item
List of (value, label) tuples.  The label count specifies the number of
tuples.  Each tuple consists of a value, which is numeric or string as
appropriate to the variables, followed by a label (string).
@end itemize

@node Portable File Data,  , Value Label Records, Portable File Format
@section Portable File Data

The data record has tag code @samp{F}.  There is only one tag for all
the data; thus, all the data must follow the dictionary.  The data is
terminated by the end-of-file marker @samp{Z}, which is not valid as the
beginning of a data element.

Data elements are output in the same order as the variable records
describing them.  String variables are output as string fields, and
numeric variables are output as floating-point fields.

@node q2c Input Format, Bugs, Portable File Format, Top
@chapter @code{q2c} Input Format

PSPP statistical procedures have a bizarre and somewhat irregular
syntax.  Despite this, a parser generator has been written that
adequately addresses many of the possibilities and tries to provide
hooks for the exceptional cases.  This parser generator is named
@code{q2c}.

@menu
* Invoking q2c::                q2c command-line syntax.
* q2c Input Structure::         High-level layout of the input file.
* Grammar Rules::               Syntax of the grammar rules.
@end menu

@node Invoking q2c, q2c Input Structure, q2c Input Format, q2c Input Format
@section Invoking q2c

@example
q2c @var{input.q} @var{output.c}
@end example

@code{q2c} translates a @samp{.q} file into a @samp{.c} file.  It takes
exactly two command-line arguments, which are the input file name and
output file name, respectively.  @code{q2c} does not accept any
command-line options.

@node q2c Input Structure, Grammar Rules, Invoking q2c, q2c Input Format
@section @code{q2c} Input Structure

@code{q2c} input files are divided into two sections: the grammar rules
and the supporting code.  The @dfn{grammar rules}, which make up the
first part of the input, are used to define the syntax of the
statistical procedure to be parsed.  The @dfn{supporting code},
following the grammar rules, are copied largely unchanged to the output
file, except for certain escapes.

The most important lines in the grammar rules are used for defining
procedure syntax.  These lines can be prefixed with a dollar sign
(@samp{$}), which prevents Emacs' CC-mode from munging them.  Besides
this, a bang (@samp{!}) at the beginning of a line causes the line,
minus the bang, to be written verbatim to the output file (useful for
comments).  As a third special case, any line that begins with the exact
characters @code{/* *INDENT} is ignored and not written to the output.
This allows @code{.q} files to be processed through @code{indent}
without being munged.

The syntax of the grammar rules themselves is given in the following
sections.

The supporting code is passed into the output file largely unchanged.
However, the following escapes are supported.  Each escape must appear
on a line by itself.

@table @code
@item /* (header) */

Expands to a series of C @code{#include} directives which include the
headers that are required for the parser generated by @code{q2c}.

@item /* (decls @var{scope}) */

Expands to C variable and data type declarations for the variables and
@code{enum}s input and output by the @code{q2c} parser.  @var{scope}
must be either @code{local} or @code{global}.  @code{local} causes the
declarations to be output as function locals.  @code{global} causes them
to be declared as @code{static} module variables; thus, @code{global} is
a bit of a misnomer.

@item /* (parser) */

Expands to the entire parser.  Must be enclosed within a C function.

@item /* (free) */

Expands to a set of calls to the @code{free} function for variables
declared by the parser.  Only needs to be invoked if subcommands of type
@code{string} are used in the grammar rules.
@end table

@node Grammar Rules,  , q2c Input Structure, q2c Input Format
@section Grammar Rules

The grammar rules describe the format of the syntax that the parser
generated by @code{q2c} will understand.  The way that the grammar rules
are included in @code{q2c} input file are described above.

The grammar rules are divided into tokens of the following types:

@table @asis
@item Identifier (@code{ID})

An identifier token is a sequence of letters, digits, and underscores
(@samp{_}).  Identifiers are @emph{not} case-sensitive.

@item String (@code{STRING})

String tokens are initiated by a double-quote character (@samp{"}) and
consist of all the characters between that double quote and the next
double quote, which must be on the same line as the first.  Within a
string, a backslash can be used as a ``literal escape''.  The only
reasons to use a literal escape are to include a double quote or a
backslash within a string.

@item Special character

Other characters, other than whitespace, constitute tokens in
themselves.

@end table

The syntax of the grammar rules is as follows:

@example
grammar-rules ::= ID : subcommands .
subcommands ::= subcommand
            ::= subcommands ; subcommand
@end example

The syntax begins with an ID or STRING token that gives the name of the
procedure to be parsed.  The rest of the syntax consists of subcommands
separated by semicolons (@samp{;}) and terminated with a full stop
(@samp{.}).

@example
subcommand ::= sbc-options ID sbc-defn
sbc-options ::= 
            ::= sbc-option
            ::= sbc-options sbc-options
sbc-option ::= *
           ::= +
sbc-defn ::= opt-prefix = specifiers
         ::= [ ID ] = array-sbc
         ::= opt-prefix = sbc-special-form
opt-prefix ::=
           ::= ( ID )
@end example

Each subcommand can be prefixed with one or more option characters.  An
asterisk (@samp{*}) is used to indicate the default subcommand; the
keyword used for the default subcommand can be omitted in the PSPP
syntax file.  A plus sign (@samp{+}) is used to indicate that a
subcommand can appear more than once; if it is not present then that
subcommand can appear no more than once.

The subcommand name appears after the option characters.

There are three forms of subcommands.  The first and most common form
simply gives an equals sign (@samp{=}) and a list of specifiers, which
can each be set to a single setting.  The second form declares an array,
which is a set of flags that can be individually turned on by the user.
There are also several special forms that do not take a list of
specifiers.

Arrays require an additional @code{ID} argument.  This is used as a
prefix, prepended to the variable names constructed from the
specifiers.  The other forms also allow an optional prefix to be
specified.

@example
array-sbc ::= alternatives
          ::= array-sbc , alternatives
alternatives ::= ID
             ::= alternatives | ID
@end example

An array subcommand is a set of Boolean values that can independently be
turned on by the user, listed separated by commas (@samp{,}).  If an value has more
than one name then these names are separated by pipes (@samp{|}).

@example
specifiers ::= specifier
           ::= specifiers , specifier
specifier ::= opt-id : settings
opt-id ::=
       ::= ID
@end example

Ordinary subcommands (other than arrays and special forms) require a
list of specifiers.  Each specifier has an optional name and a list of
settings.  If the name is given then a correspondingly named variable
will be used to store the user's choice of setting.  If no name is given
then there is no way to tell which setting the user picked; in this case
the settings should probably have values attached.

@example
settings ::= setting
         ::= settings / setting
setting ::= setting-options ID setting-value
setting-options ::=
                ::= *
                ::= !
                ::= * !
@end example

Individual settings are separated by forward slashes (@samp{/}).  Each
setting can be as little as an @code{ID} token, but options and values
can optionally be included.  The @samp{*} option means that, for this
setting, the @code{ID} can be omitted.  The @samp{!} option means that
this option is the default for its specifier.

@example
setting-value ::=
              ::= ( setting-value-2 )
              ::= setting-value-2
setting-value-2 ::= setting-value-options setting-value-type : ID 
                    setting-value-restriction
setting-value-options ::=
                      ::= *
setting-value-type ::= N
                   ::= D
setting-value-restriction ::= 
                          ::= , STRING
@end example

Settings may have values.  If the value must be enclosed in parentheses,
then enclose the value declaration in parentheses.  Declare the setting
type as @samp{n} or @samp{d} for integer or floating point type,
respectively.  The given @code{ID} is used to construct a variable name.
If option @samp{*} is given, then the value is optional; otherwise it
must be specified whenever the corresponding setting is specified.  A
``restriction'' can also be specified which is a string giving a C
expression limiting the valid range of the value.  The special escape
@code{%s} should be used within the restriction to refer to the
setting's value variable.

@example
sbc-special-form ::= VAR
                 ::= VARLIST varlist-options
                 ::= INTEGER opt-list
                 ::= DOUBLE opt-list
                 ::= PINT
                 ::= STRING @r{(the literal word STRING)} string-options
                 ::= CUSTOM
varlist-options ::= 
                ::= ( STRING )
opt-list ::=
         ::= LIST
string-options ::= 
               ::= ( STRING STRING )
@end example

The special forms are of the following types:

@table @code
@item VAR

A single variable name.

@item VARLIST

A list of variables.  If given, the string can be used to provide
@code{PV_@var{*}} options to the call to @code{parse_variables}. 

@item INTEGER

A single integer value.

@item INTEGER LIST

A list of integers separated by spaces or commas.

@item DOUBLE

A single floating-point value.

@item DOUBLE LIST

A list of floating-point values.

@item PINT

A single positive integer value.

@item STRING

A string value.  If the options are given then the first string is an
expression giving a restriction on the value of the string; the second
string is an error message to display when the restriction is violated.

@item CUSTOM

A custom function is used to parse this subcommand.  The function must
have prototype @code{int custom_@var{name} (void)}.  It should return 0
on failure (when it has already issued an appropriate diagnostic), 1 on
success, or 2 if it fails and the calling function should issue a syntax
error on behalf of the custom handler.

@end table

@node Bugs, Function Index, q2c Input Format, Top
@chapter Bugs

@menu
* Known bugs::                  Pointers to other files.
* Contacting the Author::       Where to send the bug reports.
@end menu

@node Known bugs, Contacting the Author, Bugs, Bugs
@section Known bugs

This is the list of known bugs in PSPP.  In addition, @xref{Not
Implemented}, and @xref{Functions Not Implemented}, for lists of bugs
due to features not implemented.  For known bugs in individual language
features, see the documentation for that feature.

@itemize @bullet
@item
Nothing has yet been tested exhaustively. Be cautious using PSPP to
make important decisions.

@item
@code{make check} fails on some systems that don't like the syntax.  I'm
not sure why.  If someone could make an attempt to track this down, it
would be appreciated.

@item
PostScript driver bugs:

@itemize @minus
@item
Does not support driver arguments `max-fonts-simult' or
`optimize-text-size'.

@item
Minor problems with font-encodings.

@item
Fails to align fonts along their baselines.

@item
Does not support certain bizarre line intersections--should
never crop up in practice.

@item
Does not gracefully substitute for existing fonts whose
encodings are missing.

@item
Does not perform italic correction or left italic correction
on font changes.

@item
Encapsulated PostScript is unimplemented.
@end itemize

@item
ASCII driver bugs:

@itemize @minus
Does not support `infinite length' or `infinite width' paper.
@end itemize
@end itemize

See below for information on reporting bugs not listed here.

@node Contacting the Author,  , Known bugs, Bugs
@section Contacting the Author

The author can be contacted at e-mail address
@ifinfo
<blp@@gnu.org>.
@end ifinfo
@iftex
@code{<blp@@gnu.org>}.
@end iftex

PSPP bug reports should be sent to 
@ifinfo
<bug-gnu-pspp@@gnu.org>.
@end ifinfo
@iftex
@code{<bug-gnu-pspp@@gnu.org>}.
@end iftex

@node Function Index, Concept Index, Bugs, Top
@chapter Function Index
@printindex fn

@node Concept Index, Command Index, Function Index, Top
@chapter Concept Index
@printindex cp

@node Command Index,  , Concept Index, Top
@chapter Command Index
@printindex vr

@contents
@bye

@c Local Variables:
@c compile-command: "makeinfo pspp.texi"
@c End: