pspp 0.10.2-1+b1 / usr / share / doc / pspp / pspp.xml

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
  <!ENTITY tex "TeX">
  <!ENTITY latex "LaTeX">
]>
<book id="-" lang="en">
<title>PSPP</title>
<!-- For double-sided printing, uncomment: -->
<!-- @setchapternewpage odd -->
<!-- %**end of header -->




<!-- This macro should be used for marking command names.  For the purposes of markup,  -->
<!--  no distinction is made between ``commands'' and ``procedures''. -->

<!-- This macro is used for fragments of command syntax that are not in themselves command names. -->
<!-- It does not necessarily have to be a subcommand. -->

<!-- Use this macro to refer to PSPP itself .  Not when giving a shell command line example. -->





<bookinfo><legalnotice><para>This manual is for GNU PSPP version 0.10.2,
software for statistical analysis.
</para>
<para>Copyright &#169; 1997, 1998, 2004, 2005, 2009, 2012, 2013, 2014, 2016 Free Software Foundation, Inc.
</para>
<blockquote><para>Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled &quot;GNU
Free Documentation License&quot;.
</para></blockquote></legalnotice></bookinfo>
<para>This manual is for GNU PSPP version 0.10.2,
software for statistical analysis.
</para>
<para>Copyright &#169; 1997, 1998, 2004, 2005, 2009, 2012, 2013, 2014, 2016 Free Software Foundation, Inc.
</para>
<blockquote><para>Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled &quot;GNU
Free Documentation License&quot;.
</para></blockquote>

<!-- @chapheading Acknowledgements -->
<para>The authors wish to thank Network Theory Ltd 
<ulink url="http://www.network-theory.co.uk">http://www.network-theory.co.uk</ulink>
for their financial support 
in the production of this manual.
</para>



<chapter label="" id="Top">
<title>GNU PSPP</title>

<para>This manual is for GNU PSPP version 0.10.2,
software for statistical analysis.
</para>
<para>Copyright &#169; 1997, 1998, 2004, 2005, 2009, 2012, 2013, 2014, 2016 Free Software Foundation, Inc.
</para>
<blockquote><para>Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled &quot;GNU
Free Documentation License&quot;.
</para></blockquote>


</chapter>
<chapter label="1" id="Introduction">
<title>Introduction</title>
<indexterm role="cp"><primary>introduction</primary></indexterm>

<indexterm role="cp"><primary>pspp language</primary></indexterm>
<indexterm role="cp"><primary>language, pspp</primary></indexterm>
<para>pspp is a tool for statistical analysis of sampled data.  
It reads the data, analyzes the data according to commands provided, and writes the results
to a listing file,  to the standard output or to a window of the graphical display.
</para>
<para>The language accepted by pspp is similar to those accepted by SPSS
statistical products.  
The details of pspp&#8217;s language are given later in this manual.
</para>
<indexterm role="cp"><primary>PostScript</primary></indexterm>
<indexterm role="cp"><primary>PDF</primary></indexterm>
<indexterm role="cp"><primary>HTML</primary></indexterm>
<indexterm role="cp"><primary>DocBook</primary></indexterm>
<para>pspp produces tables and charts as output, which it can produce in
several formats; currently, ASCII, PostScript, PDF, HTML, and DocBook are
supported.
</para>
<para>The current version of pspp, 0.10.2, is incomplete in
terms of its statistical procedure support.  pspp is a work in progress.
The authors hope to fully support all features in the products
that pspp replaces, eventually.  The authors welcome questions,
comments, donations, and code submissions.  See <link linkend="Bugs">Submitting Bug
Reports</link>, for instructions on contacting the authors.
</para></chapter>
<chapter label="2" id="License">
<title>Your rights and obligations</title>
<indexterm role="cp"><primary>license</primary></indexterm>
<indexterm role="cp"><primary>licence</primary></indexterm>
<indexterm role="cp"><primary>your rights and obligations</primary></indexterm>
<indexterm role="cp"><primary>rights, your</primary></indexterm>
<indexterm role="cp"><primary>copyright</primary></indexterm>
<indexterm role="cp"><primary>obligations, your</primary></indexterm>

<para>pspp is not in the public domain. It is copyrighted and there are
restrictions on its distribution, but these restrictions are designed
to permit everything that a good cooperating citizen would want to do.
What is not allowed is to try to prevent others from further sharing
any version of this program that they might get from you.
</para>
<para>Specifically, we want to make sure that you have the right to give
away copies of pspp, that you receive source code or else can get it
if you want it, that you can change these programs or use pieces of
them in new free programs, and that you know you can do these things.
</para>
<para>To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of pspp, you must give the recipients all the rights that you
have.  You must make sure that they, too, receive or can get the
source code.  And you must tell them their rights.
</para>
<para>Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for pspp.  If these programs are
modified by someone else and passed on, we want their recipients to
know that what they have is not what we distributed, so that any
problems introduced by others will not reflect on our reputation.
</para>
<para>Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone&#8217;s free use or not licensed at all.
</para>
<para>The precise conditions of the license for pspp are found in the
GNU General Public License.  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., 51 Franklin Street, Fifth
Floor, Boston, MA 02110-1301 USA. This manual specifically
is covered by the GNU Free Documentation License (see <link linkend="GNU-Free-Documentation-License">GNU Free
Documentation License</link>).
</para>
</chapter>
<chapter label="3" id="Invoking-PSPP">
<title>Invoking <command>pspp</command></title>
<indexterm role="cp"><primary>invocation</primary></indexterm>
<indexterm role="cp"><primary>pspp, invoking</primary></indexterm>

<para>pspp has two separate user interfaces.  This chapter describes
<command>pspp</command>, pspp&#8217;s command-line driven text-based user interface.
The following chapter briefly describes PSPPIRE, the graphical user
interface to pspp.
</para>
<para>The sections below describe the <command>pspp</command> program&#8217;s command-line
interface.
</para>

<sect1 label="3.1" id="Main-Options">
<title>Main Options</title>

<para>Here is a summary of all the options, grouped by type, followed by
explanations in the same order.
</para>
<para>In the table, arguments to long options also apply to any
corresponding short options.
</para>
<variablelist><varlistentry><term><emphasis>Non-option arguments</emphasis>
</term><listitem><screen><replaceable>syntax-file</replaceable>
</screen>
</listitem></varlistentry><varlistentry><term><emphasis>Output options</emphasis>
</term><listitem><screen>-o, --output=<replaceable>output-file</replaceable>
-O <replaceable>option</replaceable>=<replaceable>value</replaceable>
-O format=<replaceable>format</replaceable>
-O device={terminal|listing}
--no-output
-e, --error-file=<replaceable>error-file</replaceable>
</screen>
</listitem></varlistentry><varlistentry><term><emphasis>Language options</emphasis>
</term><listitem><screen>-I, --include=<replaceable>dir</replaceable>
-I-, --no-include
-b, --batch
-i, --interactive
-r, --no-statrc
-a, --algorithm={compatible|enhanced}
-x, --syntax={compatible|enhanced}
--syntax-encoding=<replaceable>encoding</replaceable>
</screen>
</listitem></varlistentry><varlistentry><term><emphasis>Informational options</emphasis>
</term><listitem><screen>-h, --help
-V, --version
</screen>
</listitem></varlistentry><varlistentry><term><emphasis>Other options</emphasis>
</term><listitem><screen>-s, --safer
--testing-mode
</screen></listitem></varlistentry></variablelist>
<variablelist><varlistentry><term><replaceable>syntax-file</replaceable>
</term><listitem><para>Read and execute the named syntax file.  If no syntax files are
specified, pspp prompts for commands.  If any syntax files are
specified, pspp by default exits after it runs them, but you may make
it prompt for commands by specifying &#8216;<literal>-</literal>&#8217; as an additional syntax
file.
</para>
</listitem></varlistentry><varlistentry><term><option>-o <replaceable>output-file</replaceable></option>
</term><listitem><para>Write output to <replaceable>output-file</replaceable>.  pspp has several different output
drivers that support output in various formats (use <option>--help</option> to
list the available formats).  Specify this option more than once to
produce multiple output files, presumably in different formats.
</para>
<para>Use &#8216;<literal>-</literal>&#8217; as <replaceable>output-file</replaceable> to write output to standard output.
</para>
<para>If no <option>-o</option> option is used, then pspp writes text and CSV
output to standard output and other kinds of output to whose name is
based on the format, e.g. <filename>pspp.pdf</filename> for PDF output.
</para>
</listitem></varlistentry><varlistentry><term><option>-O <replaceable>option</replaceable>=<replaceable>value</replaceable></option>
</term><listitem><para>Sets an option for the output file configured by a preceding
<option>-o</option>.  Most options are specific to particular output formats.
A few options that apply generically are listed below.
</para>
</listitem></varlistentry><varlistentry><term><option>-O format=<replaceable>format</replaceable></option>
</term><listitem><para>pspp uses the extension of the file name given on <option>-o</option> to
select an output format.  Use this option to override this choice by
specifying an alternate format, e.g. <option>-o pspp.out -O html</option> to
write HTML to a file named <filename>pspp.out</filename>.  Use <option>--help</option> to
list the available formats.
</para>
</listitem></varlistentry><varlistentry><term><option>-O device={terminal|listing}</option>
</term><listitem><para>Sets whether pspp considers the output device configured by the
preceding <option>-o</option> to be a terminal or a listing device.  This
affects what output will be sent to the device, as configured by the
SET command&#8217;s output routing subcommands (see <link linkend="SET">SET</link>).  By default,
output written to standard output is considered a terminal device and
other output is considered a listing device.
</para>
</listitem></varlistentry><varlistentry><term><option>--no-output</option>
</term><listitem><para>Disables output entirely, if neither <option>-o</option> nor <option>-O</option> is
also used.  If one of those options is used, <option>--no-output</option> has
no effect.
</para>
</listitem></varlistentry><varlistentry><term><option>-e <replaceable>error-file</replaceable></option>
</term><term><option>--error-file=<replaceable>error-file</replaceable></option>
</term><listitem><para>Configures a file to receive pspp error, warning, and note messages in
plain text format.  Use &#8216;<literal>-</literal>&#8217; as <replaceable>error-file</replaceable> to write messages
to standard output.  The default error file is standard output in the
absence of these options, but this is suppressed if an output device
writes to standard output (or another terminal), to avoid printing
every message twice.  Use &#8216;<literal>none</literal>&#8217; as <replaceable>error-file</replaceable> to
explicitly suppress the default.
</para>
</listitem></varlistentry><varlistentry><term><option>-I <replaceable>dir</replaceable></option>
</term><term><option>--include=<replaceable>dir</replaceable></option>
</term><listitem><para>Appends <replaceable>dir</replaceable> to the set of directories searched by the <literal>INCLUDE</literal>
(see <link linkend="INCLUDE">INCLUDE</link>) and <literal>INSERT</literal> (see <link linkend="INSERT">INSERT</link>) commands.
</para>
</listitem></varlistentry><varlistentry><term><option>-I-</option>
</term><term><option>--no-include</option>
</term><listitem><para>Clears all directories from the include path, including directories
inserted in the include path by default.  The default include path is
<filename>.</filename> (the current directory), followed by <filename>.pspp</filename> in the
user&#8217;s home directory, followed by pspp&#8217;s system configuration
directory (usually <filename>/etc/pspp</filename> or <filename>/usr/local/etc/pspp</filename>).
</para>
</listitem></varlistentry><varlistentry><term><option>-b</option>
</term></varlistentry><varlistentry><term><option>--batch</option>
</term></varlistentry><varlistentry><term><option>-i</option>
</term><term><option>--interactive</option>
</term><listitem><para>These options forces syntax files to be interpreted in batch mode or
interactive mode, respectively, rather than the default &#8220;auto&#8221; mode.
See <link linkend="Syntax-Variants">Syntax Variants</link>, for a description of the differences.
</para>
</listitem></varlistentry><varlistentry><term><option>-r</option>
</term><term><option>--no-statrc</option>
</term><listitem><para>Disables running <filename>rc</filename> at pspp startup time.
</para>
</listitem></varlistentry><varlistentry><term><option>-a {enhanced|compatible}</option>
</term><term><option>--algorithm={enhanced|compatible}</option>
</term><listitem><para>With <literal>enhanced</literal>, the default, pspp uses the best implemented
algorithms for statistical procedures.  With <literal>compatible</literal>,
however, pspp will in some cases use inferior algorithms to produce
the same results as the proprietary program SPSS.
</para>
<para>Some commands have subcommands that override this setting on a per
command basis.
</para>
</listitem></varlistentry><varlistentry><term><option>-x {enhanced|compatible}</option>
</term><term><option>--syntax={enhanced|compatible}</option>
</term><listitem><para>With <literal>enhanced</literal>, the default, pspp accepts its own extensions
beyond those compatible with the proprietary program SPSS.  With
<literal>compatible</literal>, pspp rejects syntax that uses these extensions.
</para>
</listitem></varlistentry><varlistentry><term><option>--syntax-encoding=<replaceable>encoding</replaceable></option>
</term><listitem><para>Specifies <replaceable>encoding</replaceable> as the encoding for syntax files named on the
command line.  The <replaceable>encoding</replaceable> also becomes the default encoding
for other syntax files read during the pspp session by the
<literal>INCLUDE</literal> and <literal>INSERT</literal> commands.  See <link linkend="INSERT">INSERT</link>, for the
accepted forms of <replaceable>encoding</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><option>--help</option>
</term><listitem><para>Prints a message describing pspp command-line syntax and the available
device formats, then exits.
</para>
</listitem></varlistentry><varlistentry><term><option>-V</option>
</term><term><option>--version</option>
</term><listitem><para>Prints a brief message listing pspp&#8217;s version, warranties you don&#8217;t
have, copying conditions and copyright, and e-mail address for bug
reports, then exits.
</para>
</listitem></varlistentry><varlistentry><term><option>-s</option>
</term><term><option>--safer</option>
</term><listitem><para>Disables certain unsafe operations.  This includes the <literal>ERASE</literal> and
<literal>HOST</literal> commands, as well as use of pipes as input and output files.
</para>
</listitem></varlistentry><varlistentry><term><option>--testing-mode</option>
</term><listitem><para>Invoke heuristics to assist with testing pspp.  For use
by <command>make check</command> and similar scripts.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="3.2" id="PDF-PostScript-and-SVG-Output-Options">
<title>PDF, PostScript, and SVG Output Options</title>
<indexterm role="cp"><primary>PDF</primary></indexterm>
<indexterm role="cp"><primary>Postscript</primary></indexterm>
<indexterm role="cp"><primary>SVG</primary></indexterm>

<para>To produce output in PDF, PostScript, and SVG formats, specify
<option>-o <replaceable>file</replaceable></option> on the pspp command line, optionally followed
by any of the options shown in the table below to customize the output
format.
</para>
<para>PDF, PostScript, and SVG output is only available if your installation
of pspp was compiled with the Cairo library.
</para>
<variablelist><varlistentry><term><option>-O format={pdf|ps|svg}</option>
</term><listitem><para>Specify the output format.  This is only necessary if the file name
given on <option>-o</option> does not end in <filename>.pdf</filename>, <filename>.ps</filename>, or
<filename>.svg</filename>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O paper-size=<replaceable>paper-size</replaceable></option>
</term><listitem><para>Paper size, as a name (e.g. <literal>a4</literal>, <literal>letter</literal>) or
measurements (e.g. <literal>210x297</literal>, <literal>8.5x11in</literal>).
</para>
<para>The default paper size is taken from the <envar>PAPERSIZE</envar> environment
variable or the file indicated by the <envar>PAPERCONF</envar> environment
variable, if either variable is set.  If not, and your system supports
the <literal>LC_PAPER</literal> locale category, then the default paper size is
taken from the locale.  Otherwise, if <filename>/etc/papersize</filename> exists,
the default paper size is read from it.  As a last resort, A4 paper is
assumed.
</para>
</listitem></varlistentry><varlistentry><term><option>-O foreground-color=<replaceable>color</replaceable></option>
</term><term><option>-O background-color=<replaceable>color</replaceable></option>
</term><listitem><para>Sets <replaceable>color</replaceable> as the color to be used for the background or foreground.
Color should be given in the format <literal>#<replaceable>RRRR</replaceable><replaceable>GGGG</replaceable><replaceable>BBBB</replaceable></literal>,
where <replaceable>RRRR</replaceable>, <replaceable>GGGG</replaceable> and <replaceable>BBBB</replaceable> are 4 character hexadecimal
representations of the red, green and blue components respectively.
</para>
</listitem></varlistentry><varlistentry><term><option>-O orientation=<replaceable>orientation</replaceable></option>
</term><listitem><para>Either <literal>portrait</literal> or <literal>landscape</literal>.  Default: <literal>portrait</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O left-margin=<replaceable>dimension</replaceable></option>
</term><term><option>-O right-margin=<replaceable>dimension</replaceable></option>
</term><term><option>-O top-margin=<replaceable>dimension</replaceable></option>
</term><term><option>-O bottom-margin=<replaceable>dimension</replaceable></option>
</term><listitem><para>Sets the margins around the page.  See
below for the allowed forms of <replaceable>dimension</replaceable> Default: <literal>0.5in</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O prop-font=<replaceable>font-name</replaceable></option>
</term><term><option>-O emph-font=<replaceable>font-name</replaceable></option>
</term><term><option>-O fixed-font=<replaceable>font-name</replaceable></option>
</term><listitem><para>Sets the font used for proportional, emphasized, or fixed-pitch text.
Most systems support CSS-like font names such as &#8220;serif&#8221; and
&#8220;monospace&#8221;, but a wide range of system-specific font are likely to
be supported as well.
</para>
<para>Default: proportional font <literal>serif</literal>, emphasis font <literal>serif
italic</literal>, fixed-pitch font <literal>monospace</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O font-size=<replaceable>font-size</replaceable></option>
</term><listitem><para>Sets the size of the default fonts, in thousandths of a point.  Default:
10000 (10 point).
</para>
</listitem></varlistentry><varlistentry><term><option>-O line-gutter=<replaceable>dimension</replaceable></option>
</term><listitem><para>Sets the width of white space on either side of lines that border text
or graphics objects.  Default: <literal>1pt</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O line-spacing=<replaceable>dimension</replaceable></option>
</term><listitem><para>Sets the spacing between the lines in a double line in a table.
Default: <literal>1pt</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O line-width=<replaceable>dimension</replaceable></option>
</term><listitem><para>Sets the width of the lines used in tables.  Default: <literal>0.5pt</literal>.
</para></listitem></varlistentry></variablelist>
<para>Each <replaceable>dimension</replaceable> value above may be specified in various units
based on its suffix: &#8216;<literal>mm</literal>&#8217; for millimeters, &#8216;<literal>in</literal>&#8217; for inches,
or &#8216;<literal>pt</literal>&#8217; for points.  Lacking a suffix, numbers below 50 are
assumed to be in inches and those about 50 are assumed to be in
millimeters.
</para>
</sect1>
<sect1 label="3.3" id="Plain-Text-Output-Options">
<title>Plain Text Output Options</title>

<para>pspp can produce plain text output, drawing boxes using ASCII or
Unicode line drawing characters.  To produce plain text output,
specify <option>-o <replaceable>file</replaceable></option> on the pspp command line, optionally
followed by options from the table below to customize the output
format.
</para>
<para>Plain text output is encoded in UTF-8.
</para>
<variablelist><varlistentry><term><option>-O format=txt</option>
</term><listitem><para>Specify the output format.  This is only necessary if the file name
given on <option>-o</option> does not end in <filename>.txt</filename> or <filename>.list</filename>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O charts={<replaceable>template</replaceable>.png|none}</option>
</term><listitem><para>Name for chart files included in output.  The value should be a file
name that includes a single &#8216;<literal>#</literal>&#8217; and ends in <filename>png</filename>.  When a
chart is output, the &#8216;<literal>#</literal>&#8217; is replaced by the chart number.  The
default is the file name specified on <option>-o</option> with the extension
stripped off and replaced by <filename>-#.png</filename>.
</para>
<para>Specify <literal>none</literal> to disable chart output.  Charts are always
disabled if your installation of pspp was compiled without the
Cairo library.
</para>
</listitem></varlistentry><varlistentry><term><option>-O foreground-color=<replaceable>color</replaceable></option>
</term><term><option>-O background-color=<replaceable>color</replaceable></option>
</term><listitem><para>Sets <replaceable>color</replaceable> as the color to be used for the background or foreground to 
be used for charts.
Color should be given in the format <literal>#<replaceable>RRRR</replaceable><replaceable>GGGG</replaceable><replaceable>BBBB</replaceable></literal>,
where <replaceable>RRRR</replaceable>, <replaceable>GGGG</replaceable> and <replaceable>BBBB</replaceable> are 4 character hexadecimal
representations of the red, green and blue components respectively.
If charts are disabled, this option has no effect.
</para>

</listitem></varlistentry><varlistentry><term><option>-O paginate=<replaceable>boolean</replaceable></option>
</term><listitem><para>If set, pspp writes an ASCII formfeed the end of every page.  Default:
<literal>off</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O headers=<replaceable>boolean</replaceable></option>
</term><listitem><para>If enabled, pspp prints 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: <literal>off</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O length=<replaceable>line-count</replaceable></option>
</term><listitem><para>Physical length of a page.  Headers and margins are subtracted from
this value.  You may specify the number of lines as a number, or for
screen output you may specify <literal>auto</literal> to track the height of the
terminal as it changes.  Default: <literal>66</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O width=<replaceable>character-count</replaceable></option>
</term><listitem><para>Width of a page, in characters.  Margins are subtracted from this
value.  For screen output you may specify <literal>auto</literal> in place of a
number to track the width of the terminal as it changes.  Default:
<literal>79</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O top-margin=<replaceable>top-margin-lines</replaceable></option>
</term><listitem><para>Length of the top margin, in lines.  pspp subtracts this value from
the page length.  Default: <literal>0</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O bottom-margin=<replaceable>bottom-margin-lines</replaceable></option>
</term><listitem><para>Length of the bottom margin, in lines.  pspp subtracts this value from
the page length.  Default: <literal>0</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O box={ascii|unicode}</option>
</term><listitem><para>Sets the characters used for lines in tables.  
If set to 
<literal>ascii</literal> the characters &#8216;<literal>-</literal>&#8217;, &#8216;<literal>|</literal>&#8217;, and &#8216;<literal>+</literal>&#8217; for single-width
lines and &#8216;<literal>=</literal>&#8217; and &#8216;<literal>#</literal>&#8217; for double-width lines are used.
If set to <literal>unicode</literal> then  Unicode box drawing characters will be used.
The default is <literal>unicode</literal> if the locale&#8217;s character encoding is &quot;UTF-8&quot;
or <literal>ascii</literal> otherwise.
</para>
</listitem></varlistentry><varlistentry><term><option>-O emphasis={none|bold|underline}</option>
</term><listitem><para>How to emphasize text.  Bold and underline emphasis are achieved with
overstriking, which may not be supported by all the software to which
you might pass the output.  Default: <literal>none</literal>.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="3.4" id="HTML-Output-Options">
<title>HTML Output Options</title>
<indexterm role="cp"><primary>HTML</primary></indexterm>
<para>To produce output in HTML format, specify <option>-o <replaceable>file</replaceable></option> on
the pspp command line, optionally followed by any of the options shown
in the table below to customize the output format.
</para>
<variablelist><varlistentry><term><option>-O format=html</option>
</term><listitem><para>Specify the output format.  This is only necessary if the file name
given on <option>-o</option> does not end in <filename>.html</filename>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O charts={<replaceable>template</replaceable>.png|none}</option>
</term><listitem><para>Sets the name used for chart files.  See <link linkend="Plain-Text-Output-Options">Plain Text Output Options</link>,
for details.
</para>
</listitem></varlistentry><varlistentry><term><option>-O borders=<replaceable>boolean</replaceable></option>
</term><listitem><para>Decorate the tables with borders.  If set to false, the tables produced
will have no borders.  The default value is true.
</para>
</listitem></varlistentry><varlistentry><term><option>-O css=<replaceable>boolean</replaceable></option>
</term><listitem><para>Use cascading style sheets.  Cascading style sheets give an improved appearance
and can be used to produce pages which fit a certain web site&#8217;s style.
The default value is true.
</para>
</listitem></varlistentry></variablelist>
</sect1>
<sect1 label="3.5" id="OpenDocument-Output-Options">
<title>OpenDocument Output Options</title>

<para>To produce output as an OpenDocument text (ODT) document, specify
<option>-o <replaceable>file</replaceable></option> on the pspp command line.  If <replaceable>file</replaceable> does
not end in <filename>.odt</filename>, you must also specify <option>-O format=odt</option>.
</para>
<para>ODT support is only available if your installation of pspp was
compiled with the libxml2 library.
</para>
<para>The OpenDocument output format does not have any configurable options.
</para>
</sect1>
<sect1 label="3.6" id="Comma_002dSeparated-Value-Output-Options">
<title>Comma-Separated Value Output Options</title>

<para>To produce output in comma-separated value (CSV) format, specify
<option>-o <replaceable>file</replaceable></option> on the pspp command line, optionally followed
by any of the options shown in the table below to customize the output
format.
</para>
<variablelist><varlistentry><term><option>-O format=csv</option>
</term><listitem><para>Specify the output format.  This is only necessary if the file name
given on <option>-o</option> does not end in <filename>.csv</filename>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O separator=<replaceable>field-separator</replaceable></option>
</term><listitem><para>Sets the character used to separate fields.  Default: a comma
(&#8216;<literal>,</literal>&#8217;).
</para>
</listitem></varlistentry><varlistentry><term><option>-O quote=<replaceable>qualifier</replaceable></option>
</term><listitem><para>Sets <replaceable>qualifier</replaceable> as the character used to quote fields that
contain white space, the separator (or any of the characters in the
separator, if it contains more than one character), or the quote
character itself.  If <replaceable>qualifier</replaceable> is longer than one character,
only the first character is used; if <replaceable>qualifier</replaceable> is the empty
string, then fields are never quoted.
</para>
</listitem></varlistentry><varlistentry><term><option>-O titles=<replaceable>boolean</replaceable></option>
</term><listitem><para>Whether table titles (brief descriptions) should be printed.  Default:
<literal>on</literal>.
</para>
</listitem></varlistentry><varlistentry><term><option>-O captions=<replaceable>boolean</replaceable></option>
</term><listitem><para>Whether table captions (more extensive descriptions) should be
printed.  Default: on.
</para></listitem></varlistentry></variablelist>
<para>The CSV format used is an extension to that specified in RFC 4180:
</para>
<variablelist><varlistentry><term>Tables
</term><listitem><para>Each table row is output on a separate line, and each column is output
as a field.  The contents of a cell that spans multiple rows or
columns is output only for the top-left row and column; the rest are
output as empty fields.
</para>
</listitem></varlistentry><varlistentry><term>Titles
</term><listitem><para>When a table has a title and titles are enabled, the title is output
just above the table as a single field prefixed by &#8216;<literal>Table:</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term>Captions
</term><listitem><para>When a table has a caption and captions are enabled, the caption is
output just below the table as a single field prefixed by
&#8216;<literal>Caption:</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term>Footnotes
</term><listitem><para>Within a table, footnote markers are output as bracketed letters
following the cell&#8217;s contents, e.g.&#160;&#8216;<literal>[a]</literal>&#8217;, &#8216;<literal>[b]</literal>&#8217;,
...  The footnotes themselves are output following the body of
the table, as a separate two-column table introduced with a line that
says &#8216;<literal>Footnotes:</literal>&#8217;.  Each row in the table represent one footnote:
the first column is the marker, the second column is the text.
</para>
</listitem></varlistentry><varlistentry><term>Text
</term><listitem><para>Text in output is printed as a field on a line by itself.  The TITLE
and SUBTITLE produce similar output, prefixed by &#8216;<literal>Title:</literal>&#8217; or
&#8216;<literal>Subtitle:</literal>&#8217;, respectively.
</para>
</listitem></varlistentry><varlistentry><term>Messages
</term><listitem><para>Errors, warnings, and notes are printed the same way as text.
</para>
</listitem></varlistentry><varlistentry><term>Charts
</term><listitem><para>Charts are not included in CSV output.
</para></listitem></varlistentry></variablelist>
<para>Successive output items are separated by a blank line.
</para>
</sect1>
</chapter>
<chapter label="4" id="Invoking-PSPPIRE">
<title>Invoking <command>psppire</command></title>
<sect1 label="4.1">
<title>The graphic user interface</title>
<indexterm role="cp"><primary>Graphic user interface</primary></indexterm>
<indexterm role="cp"><primary>PSPPIRE</primary></indexterm>

<para>The PSPPIRE graphic user interface for pspp can perform all
functionality of the command line interface.  In addition it gives an
instantaneous view of the data, variables and statistical output.
</para>
<para>The graphic user interface can be started by typing <command>psppire</command> at a 
command prompt.
Alternatively many systems have a system of interactive menus or buttons 
from which <command>psppire</command> can be started by a series of mouse clicks.
</para>
<para>Once the principles of the pspp system are understood, 
the graphic user interface is designed to be largely intuitive, and
for this reason is covered only very briefly by this manual.
</para>

</sect1>
</chapter>
<chapter label="5" id="Using-PSPP">
<title>Using pspp</title>

<para>pspp is a tool for the statistical analysis of sampled data.
You can use it to discover patterns in the data,
to explain differences in one subset of data in terms of another subset
and to find out
whether certain beliefs about the data are justified.
This chapter does not attempt to introduce the theory behind the 
statistical analysis,
but it shows how such analysis can be performed using pspp.
</para>
<para>For the purposes of this tutorial, it is assumed that you are using pspp in its 
interactive mode from the command line.
However, the example commands can also be typed into a file and executed in 
a post-hoc mode by typing &#8216;<literal>pspp <replaceable>filename</replaceable></literal>&#8217; at a shell prompt,
where <replaceable>filename</replaceable> is the name of the file containing the commands.
Alternatively, from the graphical interface, you can select
File &#8594; New &#8594; Syntax to open a new syntax window
and use the Run menu when a syntax fragment is ready to be 
executed.
Whichever method you choose, the syntax is identical.
</para>
<para>When using the interactive method, pspp tells you that it&#8217;s waiting for your
data with a string like PSPP&gt; or data&gt;.
In the examples of this chapter, whenever you see text like this, it
indicates the prompt displayed by pspp, <emphasis>not</emphasis> something that you 
should type.
</para>
<para>Throughout this chapter reference is made to a number of sample data files.
So that you can try the examples for yourself,
you should have received these files along with your copy of pspp.<!-- -->
<footnote><para>These files contain purely fictitious data.  They should not be used
for research purposes.</para></footnote>
</para><blockquote><para><emphasis role="bold">Please note:</emphasis> Normally these files are installed in the directory
<filename>/usr/local/share/pspp/examples</filename>.
If however your system administrator or operating system vendor has
chosen to install them in a different location, you will have to adjust
the examples accordingly.
</para></blockquote>


<sect1 label="5.1" id="Preparation-of-Data-Files">
<title>Preparation of Data Files</title>


<para>Before analysis can commence,  the data must be loaded into pspp and
arranged such that both pspp and humans can understand what
the data represents.
There are two aspects of data:
</para>
<itemizedlist><listitem><para>The variables &#8212; these are the parameters of a quantity
 which has been measured or estimated in some way.
 For example height, weight and geographic location are all variables.
</para></listitem><listitem><para>The observations (also called &#8216;cases&#8217;) of the variables &#8212;
 each observation represents an instance when the variables were measured
 or observed. 
</para></listitem></itemizedlist>
<para>For example, a data set which has the variables <replaceable>height</replaceable>, <replaceable>weight</replaceable>, and
<replaceable>name</replaceable>, might have the observations:
</para><screen>1881 89.2 Ahmed
1192 107.01 Frank
1230 67 Julie
</screen><para>The following sections explain how to define a dataset.
</para>

<sect2 label="5.1.1" id="Defining-Variables">
<title>Defining Variables</title>
<indexterm role="cp"><primary>variables</primary></indexterm>

<para>Variables come in two basic types, <emphasis>viz</emphasis>: <firstterm>numeric</firstterm> and <firstterm>string</firstterm>.
Variables such as age, height and satisfaction are numeric,
whereas name is a string variable.
String variables are best reserved for commentary data to assist the 
human observer.
However they can also be used for nominal or categorical data.
</para>

<para><link linkend="data_002dlist">data-list</link> defines two variables <replaceable>forename</replaceable> and <replaceable>height</replaceable>,
and reads data into them by manual input. 
</para>
<anchor id="data_002dlist"/>
<screen>PSPP&gt; data list list /forename (A12) height.
PSPP&gt; begin data.
data&gt; Ahmed 188
data&gt; Bertram 167
data&gt; Catherine 134.231
data&gt; David 109.1
data&gt; end data
PSPP&gt;
</screen>

<para>There are several things to note about this example.
</para>
<itemizedlist><listitem><para>The words &#8216;<literal>data list list</literal>&#8217; are an example of the <literal>DATA LIST</literal>
command. See <link linkend="DATA-LIST">DATA LIST</link>.
It tells pspp to prepare for reading data.
The word &#8216;<literal>list</literal>&#8217; intentionally appears twice.
The first occurrence is part of the <literal>DATA LIST</literal> call,
whilst the second
tells pspp that the data is to be read as free format data with
one record per line.
</para>
</listitem><listitem><para>The &#8216;<literal>/</literal>&#8217; character is important. It marks the start of the list of
variables which you wish to define.
</para>
</listitem><listitem><para>The text &#8216;<literal>forename</literal>&#8217; is the name of the first variable,
and &#8216;<literal>(A12)</literal>&#8217; says that the variable <replaceable>forename</replaceable> is a string
variable and that its maximum length is 12 bytes.
The second variable&#8217;s name is specified by the text &#8216;<literal>height</literal>&#8217;.
Since no format is given, this variable has the default format.
Normally the default format expects numeric data, which should be
entered in the locale of the operating system.
Thus, the example is correct for English locales and other
locales which use a period (&#8216;<literal>.</literal>&#8217;) as the decimal separator.
However if you are using a system with a locale which uses the comma (&#8216;<literal>,</literal>&#8217;)
as the decimal separator, then you should in the subsequent lines substitute
&#8216;<literal>.</literal>&#8217; with &#8216;<literal>,</literal>&#8217;.  
Alternatively, you could explicitly tell pspp that the <replaceable>height</replaceable> 
variable is to be read using a period as its decimal separator by appending the
text &#8216;<literal>DOT8.3</literal>&#8217; after the word &#8216;<literal>height</literal>&#8217;.
For more information on data formats, see <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.
</para>

</listitem><listitem><para>Normally, pspp displays the  prompt PSPP&gt; whenever it&#8217;s
expecting a command.
However, when it&#8217;s expecting data, the prompt changes to data&gt;
so that you know to enter data and not a command.
</para>
</listitem><listitem><para>At the end of every command there is a terminating &#8216;<literal>.</literal>&#8217; which tells
pspp that the end of a command has been encountered.
You should not enter &#8216;<literal>.</literal>&#8217; when data is expected (<emphasis>ie.</emphasis> when 
the data&gt; prompt is current) since it is appropriate only for
terminating commands.
</para></listitem></itemizedlist>
</sect2>
<sect2 label="5.1.2" id="Listing-the-data">
<title>Listing the data</title>
<indexterm role="vr"><primary>LIST</primary></indexterm>

<para>Once the data has been entered,
you could type
</para><screen>PSPP&gt; list /format=numbered.
</screen><para>to list the data.
The optional text &#8216;<literal>/format=numbered</literal>&#8217; requests the case numbers to be 
shown along with the data.
It should show the following output:
</para><screen>Case#     forename   height
----- ------------ --------
    1 Ahmed          188.00 
    2 Bertram        167.00 
    3 Catherine      134.23 
    4 David          109.10 
</screen><para>Note that the numeric variable <replaceable>height</replaceable> is displayed to 2 decimal 
places, because the format for that variable is &#8216;<literal>F8.2</literal>&#8217;.
For a complete description of the <literal>LIST</literal> command, see <link linkend="LIST">LIST</link>.
</para>
</sect2>
<sect2 label="5.1.3" id="Reading-data-from-a-text-file">
<title>Reading data from a text file</title>
<indexterm role="cp"><primary>reading data</primary></indexterm>

<para>The previous example showed how to define a set of variables and to 
manually enter the data for those variables.
Manual entering of data is tedious work, and often
a file containing the data will be have been previously 
prepared.
Let us assume that you have a file called <filename>mydata.dat</filename> containing the
ascii encoded data:
</para><screen>Ahmed          188.00 
Bertram        167.00 
Catherine      134.23 
David          109.10 
&#160;             .
&#160;             .
&#160;             .
Zachariah      113.02
</screen><para>You can can tell the <literal>DATA LIST</literal> command to read the data directly from
this file instead of by manual entry, with a command like:
</para><screen>PSPP&gt; data list file='mydata.dat' list /forename (A12) height.
</screen><para>Notice however, that it is still necessary to specify the names of the
variables and their formats, since this information is not contained
in the file.
It is also possible to specify the file&#8217;s character encoding and other 
parameters.
For full details refer to see <link linkend="DATA-LIST">DATA LIST</link>.
</para>
</sect2>
<sect2 label="5.1.4" id="Reading-data-from-a-pre_002dprepared-PSPP-file">
<title>Reading data from a pre-prepared pspp file</title>
<indexterm role="cp"><primary>system files</primary></indexterm>
<indexterm role="vr"><primary>GET</primary></indexterm>

<para>When working with other pspp users, or users of other software which
uses the pspp data format, you may be given the data in
a pre-prepared pspp file.
Such files contain not only the data, but the variable definitions,
along with their formats, labels and other meta-data.
Conventionally, these files (sometimes called &#8220;system&#8221; files) 
have the suffix <filename>.sav</filename>, but that is
not mandatory.
The following syntax loads a file called <filename>my-file.sav</filename>.
</para><screen>PSPP&gt; get file='my-file.sav'.
</screen><para>You will encounter several instances of this in future examples.
</para>

</sect2>
<sect2 label="5.1.5" id="Saving-data-to-a-PSPP-file_002e">
<title>Saving data to a pspp file.</title>
<indexterm role="cp"><primary>saving</primary></indexterm>
<indexterm role="vr"><primary>SAVE</primary></indexterm>

<para>If you want to save your data, along with the variable definitions so
that you or other pspp users can use it later, you can do this with
the <literal>SAVE</literal> command.
</para>
<para>The following syntax will save the existing data and variables to a
file called <filename>my-new-file.sav</filename>.
</para><screen>PSPP&gt; save outfile='my-new-file.sav'.
</screen><para>If <filename>my-new-file.sav</filename> already exists, then it will be overwritten.
Otherwise it will be created.
</para>

</sect2>
<sect2 label="5.1.6" id="Reading-data-from-other-sources">
<title>Reading data from other sources</title>
<indexterm role="cp"><primary>comma separated values</primary></indexterm>
<indexterm role="cp"><primary>spreadsheets</primary></indexterm>
<indexterm role="cp"><primary>databases</primary></indexterm>

<para>Sometimes it&#8217;s useful to be able to read data from comma 
separated text, from spreadsheets, databases or other sources.
In these instances you should
use the <literal>GET DATA</literal> command (see <link linkend="GET-DATA">GET DATA</link>).
</para>
</sect2>
<sect2 label="5.1.7" id="Exiting-PSPP">
<title>Exiting PSPP</title>

<para>Use the <literal>FINISH</literal> command to exit PSPP:
</para><screen>PSPP&gt; finish.
</screen>  
</sect2>
</sect1>
<sect1 label="5.2" id="Data-Screening-and-Transformation">
<title>Data Screening and Transformation</title>

<indexterm role="cp"><primary>screening</primary></indexterm>
<indexterm role="cp"><primary>transformation</primary></indexterm>

<para>Once data has been entered, it is often desirable, or even necessary,
to transform it in some way before performing analysis upon it.
At the very least, it&#8217;s good practice to check for errors.
</para>

<sect2 label="5.2.1" id="Identifying-incorrect-data">
<title>Identifying incorrect data</title>
<indexterm role="cp"><primary>erroneous data</primary></indexterm>
<indexterm role="cp"><primary>errors, in data</primary></indexterm>

<para>Data from real sources is rarely error free.
pspp has a number of procedures which can be used to help 
identify data which might be incorrect.
</para>
<para>The <literal>DESCRIPTIVES</literal> command (see <link linkend="DESCRIPTIVES">DESCRIPTIVES</link>) is used to generate
simple linear statistics for a dataset.  It is also useful for
identifying potential problems in the data.
The example file <filename>physiology.sav</filename> contains a number of physiological
measurements of a sample of healthy adults selected at random.
However, the data entry clerk made a number of mistakes when entering
the data.
<link linkend="descriptives">descriptives</link> illustrates the use of <literal>DESCRIPTIVES</literal> to screen this
data and identify the erroneous values.
</para>
<anchor id="descriptives"/>
<screen>PSPP&gt; get file='/usr/local/share/pspp/examples/physiology.sav'.
PSPP&gt; descriptives sex, weight, height.
</screen>
<para>Output:
</para><screen>DESCRIPTIVES.  Valid cases = 40; cases with missing value(s) = 0.
+--------#--+-------+-------+-------+-------+
|Variable# N|  Mean |Std Dev|Minimum|Maximum|
#========#==#=======#=======#=======#=======#
|sex     #40|    .45|    .50|    .00|   1.00|
|height  #40|1677.12| 262.87| 179.00|1903.00|
|weight  #40|  72.12|  26.70| -55.60|  92.07|
+--------#--+-------+-------+-------+-------+
</screen>

<para>In the output of <link linkend="descriptives">descriptives</link>,
the most interesting column is the minimum value.
The <replaceable>weight</replaceable> variable has a minimum value of less than zero,
which is clearly erroneous.
Similarly, the <replaceable>height</replaceable> variable&#8217;s minimum value seems to be very low.
In fact, it is more than 5 standard deviations from the mean, and is a 
seemingly bizarre height for an adult person.
We can examine the data in more detail with the <literal>EXAMINE</literal>
command (see <link linkend="EXAMINE">EXAMINE</link>):
</para>
<para>In <link linkend="examine">examine</link> you can see that the lowest value of <replaceable>height</replaceable> is
179 (which we suspect to be erroneous), but the second lowest is 1598
which
we know from the <literal>DESCRIPTIVES</literal> command 
is within 1 standard deviation from the mean.
Similarly the <replaceable>weight</replaceable> variable has a lowest value which is
negative but a plausible value for the second lowest value.
This suggests that the two extreme values are outliers and probably 
represent data entry errors. 
</para>
<anchor id="examine"/>
<para>[&#8230; continue from <link linkend="descriptives">descriptives</link>]
</para><screen>PSPP&gt; examine height, weight /statistics=extreme(3).    
</screen>
<para>Output:
</para><screen>#===============================#===========#=======#
#                               #Case Number| Value #
#===============================#===========#=======#
#Height in millimetres Highest 1#         14|1903.00#
#                              2#         15|1884.00#
#                              3#         12|1801.65#
#                     ----------#-----------+-------#
#                       Lowest 1#         30| 179.00#
#                              2#         31|1598.00#
#                              3#         28|1601.00#
#                     ----------#-----------+-------#
#Weight in kilograms   Highest 1#         13|  92.07#
#                              2#          5|  92.07#
#                              3#         17|  91.74#
#                     ----------#-----------+-------#
#                       Lowest 1#         38| -55.60#
#                              2#         39|  54.48#
#                              3#         33|  55.45#
#===============================#===========#=======#
</screen>

</sect2>
<sect2 label="5.2.2" id="Dealing-with-suspicious-data">
<title>Dealing with suspicious data</title>

<indexterm role="cp"><primary>SYSMIS</primary></indexterm>
<indexterm role="cp"><primary>recoding data</primary></indexterm>
<para>If possible, suspect data should be checked and re-measured.
However, this may not always be feasible, in which case the researcher may
decide to disregard these values.
pspp has a feature whereby data can assume the special value &#8216;SYSMIS&#8217;, and
will be disregarded in future analysis. See <link linkend="Missing-Observations">Missing Observations</link>.
You can set the two suspect values to the &#8216;SYSMIS&#8217; value using the <literal>RECODE</literal>
command.
</para><screen>pspp&gt; recode height (179 = SYSMIS).
pspp&gt; recode weight (LOWEST THRU 0 = SYSMIS).
</screen><para>The first command says that for any observation which has a
<replaceable>height</replaceable> value of 179, that value should be changed to the SYSMIS
value.
The second command says that any <replaceable>weight</replaceable> values of zero or less
should be changed to SYSMIS.
From now on, they will be ignored in analysis.
For detailed information about the <literal>RECODE</literal> command see <link linkend="RECODE">RECODE</link>.
</para>
<para>If you now re-run the <literal>DESCRIPTIVES</literal> or <literal>EXAMINE</literal> commands in
<link linkend="descriptives">descriptives</link> and <link linkend="examine">examine</link> you
will see a data summary with more plausible parameters.
You will also notice that the data summaries indicate the two missing values.
</para>
</sect2>
<sect2 label="5.2.3" id="Inverting-negatively-coded-variables">
<title>Inverting negatively coded variables</title>

<indexterm role="cp"><primary>Likert scale</primary></indexterm>
<indexterm role="cp"><primary>Inverting data</primary></indexterm>
<para>Data entry errors are not the only reason for wanting to recode data.
The sample file <filename>hotel.sav</filename> comprises data gathered from a 
customer satisfaction survey of clients at a particular hotel.
In <link linkend="reliability">reliability</link>, this file is loaded for analysis.
The line <literal>display dictionary.</literal> tells pspp to display the
variables and associated data.
The output from this command has been omitted from the example for the sake of clarity, but
you will notice that each of the variables
<replaceable>v1</replaceable>, <replaceable>v2</replaceable> &#8230; <replaceable>v5</replaceable>  are measured on a 5 point Likert scale,
with 1 meaning &#8220;Strongly disagree&#8221; and 5 meaning &#8220;Strongly agree&#8221;.
Whilst variables <replaceable>v1</replaceable>, <replaceable>v2</replaceable> and <replaceable>v4</replaceable> record responses
to a positively posed question, variables <replaceable>v3</replaceable> and <replaceable>v5</replaceable> are 
responses to negatively worded questions.
In order to perform meaningful analysis, we need to recode the variables so
that they all measure in the same direction.
We could use the <literal>RECODE</literal> command, with syntax such as:
</para><screen>recode v3 (1 = 5) (2 = 4) (4 = 2) (5 = 1).
</screen><para>However an easier and more elegant way uses the <literal>COMPUTE</literal>
command (see <link linkend="COMPUTE">COMPUTE</link>).
Since the variables are Likert variables in the range (1 &#8230; 5),
subtracting their value  from 6 has the effect of inverting them:
</para><screen>compute <replaceable>var</replaceable> = 6 - <replaceable>var</replaceable>.
</screen><para><link linkend="reliability">reliability</link> uses this technique to recode the variables 
<replaceable>v3</replaceable> and <replaceable>v5</replaceable>.
After applying  <literal>COMPUTE</literal> for both variables,
all subsequent commands will use the inverted values.
</para>

</sect2>
<sect2 label="5.2.4" id="Testing-data-consistency">
<title>Testing data consistency</title>

<indexterm role="cp"><primary>reliability</primary></indexterm>
<indexterm role="cp"><primary>consistency</primary></indexterm>

<para>A sensible check to perform on survey data is the calculation of
reliability.
This gives the statistician some confidence that the questionnaires have been 
completed thoughtfully.
If you examine the labels of variables <replaceable>v1</replaceable>,  <replaceable>v3</replaceable> and <replaceable>v4</replaceable>,
you will notice that they ask very similar questions.
One would therefore expect the values of these variables (after recoding) 
to closely follow one another, and we can test that with the <literal>RELIABILITY</literal> 
command (see <link linkend="RELIABILITY">RELIABILITY</link>).
<link linkend="reliability">reliability</link> shows a pspp session where the user (after recoding
negatively scaled variables) requests reliability statistics for
<replaceable>v1</replaceable>, <replaceable>v3</replaceable> and <replaceable>v4</replaceable>.
</para>
<anchor id="reliability"/>
<screen>PSPP&gt; get file='/usr/local/share/pspp/examples/hotel.sav'.
PSPP&gt; display dictionary.
PSPP&gt; * recode negatively worded questions.
PSPP&gt; compute v3 = 6 - v3.
PSPP&gt; compute v5 = 6 - v5.
PSPP&gt; reliability v1, v3, v4.
</screen>
<para>Output (dictionary information omitted for clarity):
</para><screen>1.1 RELIABILITY.  Case Processing Summary
#==============#==#======#
#              # N|   %  #
#==============#==#======#
#Cases Valid   #17|100.00#
#      Excluded# 0|   .00#
#      Total   #17|100.00#
#==============#==#======#

1.2 RELIABILITY.  Reliability Statistics
#================#==========#
#Cronbach's Alpha#N of Items#
#================#==========#
#             .81#         3#
#================#==========#
</screen>

<para>As a rule of thumb, many statisticians consider a value of Cronbach&#8217;s Alpha of 
0.7 or higher to indicate reliable data.
Here, the value is 0.81 so the data and the recoding that we performed 
are vindicated.
</para>

</sect2>
<sect2 label="5.2.5" id="Testing-for-normality">
<title>Testing for normality</title>
<indexterm role="cp"><primary>normality, testing</primary></indexterm>

<para>Many statistical tests rely upon certain properties of the data.
One common property, upon which many linear tests depend, is that of
normality &#8212; the data must have been drawn from a normal distribution.
It is necessary then to ensure normality before deciding upon the
test procedure to use.  One way to do this uses the <literal>EXAMINE</literal> command.
</para>
<para>In <link linkend="normality">normality</link>, a researcher was examining the failure rates
of equipment produced by an engineering company.
The file <filename>repairs.sav</filename> contains the mean time between
failures (<replaceable>mtbf</replaceable>) of some items of equipment subject to the study.
Before performing linear analysis on the data, 
the researcher wanted to ascertain that the data is normally distributed.
</para>
<para>A normal distribution has a skewness and kurtosis of zero.
Looking at the skewness of <replaceable>mtbf</replaceable> in <link linkend="normality">normality</link> it is clear
that the mtbf figures have a lot of positive skew and are therefore
not drawn from a normally distributed variable.
Positive skew can often be compensated for by applying a logarithmic 
transformation.
This is done with the <literal>COMPUTE</literal> command in the line
</para><screen>compute mtbf_ln = ln (mtbf).
</screen><para>Rather than redefining the existing variable, this use of <literal>COMPUTE</literal>
defines a new variable <replaceable>mtbf_ln</replaceable> which is
the natural logarithm of <replaceable>mtbf</replaceable>.
The final command in this example calls <literal>EXAMINE</literal> on this new variable,
and it can be seen from the results that both the skewness and
kurtosis for <replaceable>mtbf_ln</replaceable> are very close to zero.
This provides some confidence that the <replaceable>mtbf_ln</replaceable> variable is 
normally distributed and thus safe for linear analysis.
In the event that no suitable transformation can be found,
then it would be worth considering 
an appropriate non-parametric test instead of a linear one.
See <link linkend="NPAR-TESTS">NPAR TESTS</link>, for information about non-parametric tests.
</para>
<anchor id="normality"/>
<screen>PSPP&gt; get file='/usr/local/share/pspp/examples/repairs.sav'.
PSPP&gt; examine mtbf 
                /statistics=descriptives.
PSPP&gt; compute mtbf_ln = ln (mtbf).
PSPP&gt; examine mtbf_ln
                /statistics=descriptives.
</screen>
<para>Output:
</para><screen>1.2 EXAMINE.  Descriptives
#====================================================#=========#==========#
#                                                    #Statistic|Std. Error#
#====================================================#=========#==========#
#mtbf    Mean                                        #   8.32  |   1.62   #
#        95% Confidence Interval for Mean Lower Bound#   4.85  |          #
#                                         Upper Bound#  11.79  |          #
#        5% Trimmed Mean                             #   7.69  |          #
#        Median                                      #   8.12  |          #
#        Variance                                    #  39.21  |          #
#        Std. Deviation                              #   6.26  |          #
#        Minimum                                     #   1.63  |          #
#        Maximum                                     #  26.47  |          #
#        Range                                       #  24.84  |          #
#        Interquartile Range                         #   5.83  |          #
#        Skewness                                    #   1.85  |    .58   #
#        Kurtosis                                    #   4.49  |   1.12   #
#====================================================#=========#==========#

2.2 EXAMINE.  Descriptives
#====================================================#=========#==========#
#                                                    #Statistic|Std. Error#
#====================================================#=========#==========#
#mtbf_ln Mean                                        #   1.88  |    .19   #
#        95% Confidence Interval for Mean Lower Bound#   1.47  |          #
#                                         Upper Bound#   2.29  |          #
#        5% Trimmed Mean                             #   1.88  |          #
#        Median                                      #   2.09  |          #
#        Variance                                    #   .54   |          #
#        Std. Deviation                              #   .74   |          #
#        Minimum                                     #   .49   |          #
#        Maximum                                     #   3.28  |          #
#        Range                                       #   2.79  |          #
#        Interquartile Range                         #   .92   |          #
#        Skewness                                    #   -.16  |    .58   #
#        Kurtosis                                    #   -.09  |   1.12   #
#====================================================#=========#==========#
</screen>


</sect2>
</sect1>
<sect1 label="5.3" id="Hypothesis-Testing">
<title>Hypothesis Testing</title>

<indexterm role="cp"><primary>Hypothesis testing</primary></indexterm>
<indexterm role="cp"><primary>p-value</primary></indexterm>
<indexterm role="cp"><primary>null hypothesis</primary></indexterm>

<para>One of the most fundamental purposes of statistical analysis
is hypothesis testing.
Researchers commonly need to test hypotheses about a set of data.
For example, she might want to test whether one set of data comes from
the same distribution as another,
or
whether the mean of a dataset significantly differs from a particular
value.
This section presents just some of the possible tests that pspp offers.
</para>
<para>The researcher starts by making a <firstterm>null hypothesis</firstterm>.
Often this is a hypothesis which he suspects to be false.
For example, if he suspects that <replaceable>A</replaceable> is greater than <replaceable>B</replaceable> he will 
state the null hypothesis as <inlineequation><mathphrase><replaceable>A</replaceable> = <replaceable>B</replaceable></mathphrase></inlineequation>.<!-- -->
<footnote><para>This example assumes that it is already proven that <replaceable>B</replaceable> is
not greater than <replaceable>A</replaceable>.</para></footnote>
</para>
<para>The <firstterm>p-value</firstterm> is a recurring concept in hypothesis testing.
It is the highest acceptable probability that the evidence implying a
null hypothesis is false, could have been obtained when the null
hypothesis is in fact true.
Note that this is not the same as &#8220;the probability of making an
error&#8221; nor is it the same as &#8220;the probability of rejecting a
hypothesis when it is true&#8221;.
</para>



<sect2 label="5.3.1" id="Testing-for-differences-of-means">
<title>Testing for differences of means</title>

<indexterm role="cp"><primary>T-test</primary></indexterm>
<indexterm role="vr"><primary>T-TEST</primary></indexterm>

<para>A common statistical test involves hypotheses about means.
The <literal>T-TEST</literal> command is used to find out whether or not two separate 
subsets have the same mean.
</para>
<para><link linkend="t_002dtest">t-test</link> uses the file <filename>physiology.sav</filename> previously
encountered.
A researcher suspected that the heights and core body 
temperature of persons might be different depending upon their sex.
To investigate this, he posed two null hypotheses: 
</para><itemizedlist><listitem><para>The mean heights of males and females in the population are equal.
</para></listitem><listitem><para>The mean body temperature of males and
      females in the population are equal.
</para></listitem></itemizedlist><para>For the purposes of the investigation the researcher
decided to use a  p-value of 0.05.
</para>
<para>In addition to the T-test, the <literal>T-TEST</literal> command also performs the 
Levene test for equal variances.
If the variances are equal, then a more powerful form of the T-test can be used.
However if it is unsafe to assume equal variances,
then an alternative calculation is necessary.
pspp performs both calculations.
</para>
<para>For the <replaceable>height</replaceable> variable, the output shows the significance of the 
Levene test to be 0.33 which means there is a 
33% probability that the  
Levene test produces this outcome when the variances are equal.
Had the significance been less than 0.05, then it would have been unsafe to assume that
the variances were equal.
However, because the value is higher than 0.05 the homogeneity of variances assumption
is safe and the &#8220;Equal Variances&#8221; row (the more powerful test) can be used.
Examining this row, the two tailed significance for the <replaceable>height</replaceable> t-test 
is less than 0.05, so it is safe to reject the null hypothesis and conclude
that the mean heights of males and females are unequal.
</para>
<para>For the <replaceable>temperature</replaceable> variable, the significance of the Levene test 
is 0.58 so again, it is safe to use the row for equal variances.
The equal variances row indicates that the two tailed significance for
<replaceable>temperature</replaceable> is 0.20.  Since this is greater than 0.05 we must reject
the null hypothesis and conclude that there is insufficient evidence to 
suggest that the body temperature of male and female persons are different.
</para>
<anchor id="t_002dtest"/>
<screen>PSPP&gt; get file='/usr/local/share/pspp/examples/physiology.sav'.
PSPP&gt; recode height (179 = SYSMIS).
PSPP&gt; t-test group=sex(0,1) /variables = height temperature.
</screen><para>Output:
</para><screen>1.1 T-TEST.  Group Statistics
#==================#==#=======#==============#========#
#              sex | N|  Mean |Std. Deviation|SE. Mean#
#==================#==#=======#==============#========#
#height      Male  |22|1796.49|         49.71|   10.60#
#            Female|17|1610.77|         25.43|    6.17#
#temperature Male  |22|  36.68|          1.95|     .42#
#            Female|18|  37.43|          1.61|     .38#
#==================#==#=======#==============#========#
1.2 T-TEST.  Independent Samples Test
#===========================#=========#===============================   =#
#                           # Levene's| t-test for Equality of Means      #
#                           #----+----+------+-----+------+---------+-   -#
#                           #    |    |      |     |      |         |     #
#                           #    |    |      |     |Sig. 2|         |     #
#                           #  F |Sig.|   t  |  df |tailed|Mean Diff|     #
#===========================#====#====#======#=====#======#=========#=   =#
#height      Equal variances# .97| .33| 14.02|37.00|   .00|   185.72| ... #
#          Unequal variances#    |    | 15.15|32.71|   .00|   185.72| ... #
#temperature Equal variances# .31| .58| -1.31|38.00|   .20|     -.75| ... #
#          Unequal variances#    |    | -1.33|37.99|   .19|     -.75| ... #
#===========================#====#====#======#=====#======#=========#=   =#
</screen>

</sect2>
<sect2 label="5.3.2" id="Linear-Regression">
<title>Linear Regression</title>
<indexterm role="cp"><primary>linear regression</primary></indexterm>
<indexterm role="vr"><primary>REGRESSION</primary></indexterm>

<para>Linear regression is a technique used to investigate if and how a variable 
is linearly related to others.
If a variable is found to be linearly related, then this can be used to 
predict future values of that variable.
</para>
<para>In example <link linkend="regression">regression</link>, the service department of the company wanted to
be able to predict the time to repair equipment, in order to improve
the accuracy of their quotations.
It was suggested that the time to repair might be related to the time
between failures and the duty cycle of the equipment.
The p-value of 0.1 was chosen for this investigation.
In order to investigate this hypothesis, the <literal>REGRESSION</literal> command
was used.
This command not only tests if the variables are related, but also
identifies the potential linear relationship. See <link linkend="REGRESSION">REGRESSION</link>.
</para>

<anchor id="regression"/>
<screen>PSPP&gt; get file='/usr/local/share/pspp/examples/repairs.sav'.
PSPP&gt; regression /variables = mtbf duty_cycle /dependent = mttr.
PSPP&gt; regression /variables = mtbf /dependent = mttr.
</screen><para>Output:
</para><screen>1.3(1) REGRESSION.  Coefficients
#=============================================#====#==========#====#=====#
#                                             #  B |Std. Error|Beta|  t  #
#========#====================================#====#==========#====#=====#
#        |(Constant)                          #9.81|      1.50| .00| 6.54#
#        |Mean time between failures (months) #3.10|       .10| .99|32.43#
#        |Ratio of working to non-working time#1.09|      1.78| .02|  .61#
#        |                                    #    |          |    |     #
#========#====================================#====#==========#====#=====#

1.3(2) REGRESSION.  Coefficients
#=============================================#============#
#                                             #Significance#
#========#====================================#============#
#        |(Constant)                          #         .10#
#        |Mean time between failures (months) #         .00#
#        |Ratio of working to non-working time#         .55#
#        |                                    #            #
#========#====================================#============#
2.3(1) REGRESSION.  Coefficients
#============================================#=====#==========#====#=====#
#                                            #  B  |Std. Error|Beta|  t  #
#========#===================================#=====#==========#====#=====#
#        |(Constant)                         #10.50|       .96| .00|10.96#
#        |Mean time between failures (months)# 3.11|       .09| .99|33.39#
#        |                                   #     |          |    |     #
#========#===================================#=====#==========#====#=====#

2.3(2) REGRESSION.  Coefficients
#============================================#============#
#                                            #Significance#
#========#===================================#============#
#        |(Constant)                         #         .06#
#        |Mean time between failures (months)#         .00#
#        |                                   #            #
#========#===================================#============#
</screen>

<para>The coefficients in the first table suggest that the formula
<inlineequation><mathphrase><replaceable>mttr</replaceable> = 9.81 + 3.1 \times <replaceable>mtbf</replaceable> + 1.09 \times <replaceable>duty_cycle</replaceable></mathphrase></inlineequation>
can be used to predict the time to repair.
However, the significance value for the <replaceable>duty_cycle</replaceable> coefficient
is very high, which would make this an unsafe predictor.
For this reason, the test was repeated, but omitting the
<replaceable>duty_cycle</replaceable> variable.
This time, the significance of all coefficients no higher than 0.06,
suggesting that at the 0.06 level, the formula
<inlineequation><mathphrase><replaceable>mttr</replaceable> = 10.5 + 3.11 \times <replaceable>mtbf</replaceable></mathphrase></inlineequation> is a reliable
predictor of the time to repair.
</para>

<!--  LocalWords:  PSPP dir itemize noindent var cindex dfn cartouche samp xref -->
<!--  LocalWords:  pxref ie sav Std Dev kilograms SYSMIS sansserif pre pspp emph -->
<!--  LocalWords:  Likert Cronbach's Cronbach mtbf npplot ln myfile cmd NPAR Sig -->
<!--  LocalWords:  vindex Levene Levene's df Diff clicksequence mydata dat ascii -->
<!--  LocalWords:  mttr outfile -->
</sect2>
</sect1>
</chapter>
<chapter label="6" id="Language">
<title>The pspp language</title>
<indexterm role="cp"><primary>language, pspp</primary></indexterm>
<indexterm role="cp"><primary>pspp, language</primary></indexterm>

<para>This chapter discusses elements common to many pspp commands.
Later chapters will describe individual commands in detail.
</para>


<sect1 label="6.1" id="Tokens">
<title>Tokens</title>
<indexterm role="cp"><primary>language, lexical analysis</primary></indexterm>
<indexterm role="cp"><primary>language, tokens</primary></indexterm>
<indexterm role="cp"><primary>tokens</primary></indexterm>
<indexterm role="cp"><primary>lexical analysis</primary></indexterm>

<para>pspp divides most syntax file lines into series of short chunks
called <firstterm>tokens</firstterm>.
Tokens are then grouped to form commands, each of which tells
pspp to take some action&#8212;read in data, write out data, perform
a statistical procedure, etc.  Each type of token is
described below.
</para>
<variablelist><indexterm role="cp"><primary>identifiers</primary></indexterm>
<varlistentry><term><emphasis role="bold">Identifiers</emphasis>
</term><listitem><para>Identifiers are names that typically specify variables, commands, or
subcommands.  The first character in an identifier must be a letter,
&#8216;<literal>#</literal>&#8217;, or &#8216;<literal>@</literal>&#8217;.  The remaining characters in the identifier
must be letters, digits, or one of the following special characters:
</para>
.  _  $  #  @

<indexterm role="cp"><primary>case-sensitivity</primary></indexterm>
<para>Identifiers may be any length, but only the first 64 bytes are
significant.  Identifiers are not case-sensitive: <literal>foobar</literal>,
<literal>Foobar</literal>, <literal>FooBar</literal>, <literal>FOOBAR</literal>, and <literal>FoObaR</literal> are
different representations of the same identifier.
</para>
<indexterm role="cp"><primary>identifiers, reserved</primary></indexterm>
<indexterm role="cp"><primary>reserved identifiers</primary></indexterm>
<para>Some identifiers are reserved.  Reserved identifiers may not be used
in any context besides those explicitly described in this manual.  The
reserved identifiers are:
</para>
ALL  AND  BY  EQ  GE  GT  LE  LT  NE  NOT  OR  TO  WITH

</listitem></varlistentry><varlistentry><term><emphasis role="bold">Keywords</emphasis>
</term><listitem><para>Keywords are a subclass of identifiers that form a fixed part of
command syntax.  For example, command and subcommand names are
keywords.  Keywords may be abbreviated to their first 3 characters if
this abbreviation is unambiguous.  (Unique abbreviations of 3 or more
characters are also accepted: &#8216;<literal>FRE</literal>&#8217;, &#8216;<literal>FREQ</literal>&#8217;, and
&#8216;<literal>FREQUENCIES</literal>&#8217; are equivalent when the last is a keyword.)
</para>
<para>Reserved identifiers are always used as keywords.  Other identifiers
may be used both as keywords and as user-defined identifiers, such as
variable names.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Numbers</emphasis>
</term><listitem><indexterm role="cp"><primary>numbers</primary></indexterm>
<indexterm role="cp"><primary>integers</primary></indexterm>
<indexterm role="cp"><primary>reals</primary></indexterm>
<para>Numbers are expressed in decimal.  A decimal point is optional.
Numbers may be expressed in scientific notation by adding &#8216;<literal>e</literal>&#8217; and
a base-10 exponent, so that &#8216;<literal>1.234e3</literal>&#8217; has the value 1234.  Here
are some more examples of valid numbers:
</para>
<screen>-5  3.14159265359  1e100  -.707  8945.
</screen>
<para>Negative numbers are expressed with a &#8216;<literal>-</literal>&#8217; prefix.  However, in
situations where a literal &#8216;<literal>-</literal>&#8217; token is expected, what appears to
be a negative number is treated as &#8216;<literal>-</literal>&#8217; followed by a positive
number.
</para>
<para>No white space is allowed within a number token, except for horizontal
white space between &#8216;<literal>-</literal>&#8217; and the rest of the number.
</para>
<para>The last example above, &#8216;<literal>8945.</literal>&#8217; will be interpreted as two
tokens, &#8216;<literal>8945</literal>&#8217; and &#8216;<literal>.</literal>&#8217;, if it is the last token on a line.
See <link linkend="Commands">Forming commands of tokens</link>.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Strings</emphasis>
</term><listitem><indexterm role="cp"><primary>strings</primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>'</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>&quot;</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>case-sensitivity</primary></indexterm>
<para>Strings are literal sequences of characters enclosed in pairs of
single quotes (&#8216;<literal>'</literal>&#8217;) or double quotes (&#8216;<literal>&quot;</literal>&#8217;).  To include the
character used for quoting in the string, double it, e.g.
&#8216;<literal>'it''s an apostrophe'</literal>&#8217;.  White space and case of letters are
significant inside strings.
</para>
<para>Strings can be concatenated using &#8216;<literal>+</literal>&#8217;, so that &#8216;<literal>&quot;a&quot; + 'b' +
'c'</literal>&#8217; is equivalent to &#8216;<literal>'abc'</literal>&#8217;.  So that a long string may be
broken across lines, a line break may precede or follow, or both
precede and follow, the &#8216;<literal>+</literal>&#8217;.  (However, an entirely blank line
preceding or following the &#8216;<literal>+</literal>&#8217; is interpreted as ending the
current command.)
</para>
<para>Strings may also be expressed as hexadecimal character values by
prefixing the initial quote character by &#8216;<literal>x</literal>&#8217; or &#8216;<literal>X</literal>&#8217;.
Regardless of the syntax file or active dataset&#8217;s encoding, the
hexadecimal digits in the string are interpreted as Unicode characters
in UTF-8 encoding.
</para>
<para>Individual Unicode code points may also be expressed by specifying the
hexadecimal code point number in single or double quotes preceded by
&#8216;<literal>u</literal>&#8217; or &#8216;<literal>U</literal>&#8217;.  For example, Unicode code point U+1D11E, the
musical G clef character, could be expressed as <literal>U'1D11E'</literal>.
Invalid Unicode code points (above U+10FFFF or in between U+D800 and
U+DFFF) are not allowed.
</para>
<para>When strings are concatenated with &#8216;<literal>+</literal>&#8217;, each segment&#8217;s prefix is
considered individually.  For example, <literal>'The G clef symbol is:' +
u&quot;1d11e&quot; + &quot;.&quot;</literal> inserts a G clef symbol in the middle of an otherwise
plain text string.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Punctuators and Operators</emphasis>
</term><listitem><indexterm role="cp"><primary>punctuators</primary></indexterm>
<indexterm role="cp"><primary>operators</primary></indexterm>
<para>These tokens are the punctuators and operators:
</para>
,  /  =  (  )  +  -  *  /  **  &lt;  &lt;=  &lt;&gt;  &gt;  &gt;=  ~=  &amp;  |  .

<para>Most of these appear within the syntax of commands, but the period
(&#8216;<literal>.</literal>&#8217;) punctuator is used only at the end of a command.  It is a
punctuator only as the last character on a line (except white space).
When it is the last non-space character on a line, a period is not
treated as part of another token, even if it would otherwise be part
of, e.g., an identifier or a floating-point number.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="6.2" id="Commands">
<title>Forming commands of tokens</title>

<indexterm role="cp"><primary>pspp, command structure</primary></indexterm>
<indexterm role="cp"><primary>language, command structure</primary></indexterm>
<indexterm role="cp"><primary>commands, structure</primary></indexterm>

<para>Most pspp commands share a common structure.  A command begins with a
command name, such as <literal>FREQUENCIES</literal>, <literal>DATA LIST</literal>, or <literal>N OF
CASES</literal>.  The command name may be abbreviated to its first word, and
each word in the command name may be abbreviated to its first three
or more characters, where these abbreviations are unambiguous.
</para>
<para>The command name may be followed by one or more <firstterm>subcommands</firstterm>.
Each subcommand begins with a subcommand name, which may be
abbreviated to its first three letters.  Some subcommands accept a
series of one or more specifications, which follow the subcommand
name, optionally separated from it by an equals sign
(&#8216;<literal>=</literal>&#8217;). Specifications may be separated from each other
by commas or spaces.  Each subcommand must be separated from the next (if any)
by a forward slash (&#8216;<literal>/</literal>&#8217;).
</para>
<para>There are multiple ways to mark the end of a command.  The most common
way is to end the last line of the command with a period (&#8216;<literal>.</literal>&#8217;) as
described in the previous section (see <link linkend="Tokens">Tokens</link>).  A blank line, or
one that consists only of white space or comments, also ends a command.
</para>
</sect1>
<sect1 label="6.3" id="Syntax-Variants">
<title>Syntax Variants</title>

<indexterm role="cp"><primary>Batch syntax</primary></indexterm>
<indexterm role="cp"><primary>Interactive syntax</primary></indexterm>

<para>There are three variants of command syntax, which vary only in how
they detect the end of one command and the start of the next.
</para>
<para>In <firstterm>interactive mode</firstterm>, which is the default for syntax typed at a
command prompt, a period as the last non-blank character on a line
ends a command.  A blank line also ends a command.
</para>
<para>In <firstterm>batch mode</firstterm>, an end-of-line period or a blank line also ends a
command.  Additionally, it treats any line that has a non-blank
character in the leftmost column as beginning a new command.  Thus, in
batch mode the second and subsequent lines in a command must be
indented.
</para>
<para>Regardless of the syntax mode, a plus sign, minus sign, or period in
the leftmost column of a line is ignored and causes that line to begin
a new command.  This is most useful in batch mode, in which the first
line of a new command could not otherwise be indented, but it is
accepted regardless of syntax mode.
</para>
<para>The default mode for reading commands from a file is <firstterm>auto mode</firstterm>.
It is the same as batch mode, except that a line with a non-blank in
the leftmost column only starts a new command if that line begins with
the name of a pspp command.  This correctly interprets most valid pspp
syntax files regardless of the syntax mode for which they are
intended.
</para>
<para>The <option>--interactive</option> (or <option>-i</option>) or <option>--batch</option> (or
<option>-b</option>) options set the syntax mode for files listed on the pspp
command line.  See <link linkend="Main-Options">Main Options</link>, for more details.
</para>
</sect1>
<sect1 label="6.4" id="Types-of-Commands">
<title>Types of Commands</title>

<para>Commands in pspp are divided roughly into six categories:
</para>
<variablelist><varlistentry><term><emphasis role="bold">Utility commands</emphasis>
</term><listitem><indexterm role="cp"><primary>utility commands</primary></indexterm>
<para>Set or display various global options that affect pspp operations.
May appear anywhere in a syntax file.  See <link linkend="Utilities">Utility
commands</link>.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">File definition commands</emphasis>
</term><listitem><indexterm role="cp"><primary>file definition commands</primary></indexterm>
<para>Give instructions for reading data from text files or from special
binary &#8220;system files&#8221;.  Most of these commands replace any previous
data or variables with new data or
variables.  At least one file definition command must appear before the first command in any of
the categories below.  See <link linkend="Data-Input-and-Output">Data Input and Output</link>.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Input program commands</emphasis>
</term><listitem><indexterm role="cp"><primary>input program commands</primary></indexterm>
<para>Though rarely used, these provide tools for reading data files
in arbitrary textual or binary formats.  See <link linkend="INPUT-PROGRAM">INPUT PROGRAM</link>.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Transformations</emphasis>
</term><listitem><indexterm role="cp"><primary>transformations</primary></indexterm>
<para>Perform operations on data and write data to output files.  Transformations
are not carried out until a procedure is executed.  
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Restricted transformations</emphasis>
</term><listitem><indexterm role="cp"><primary>restricted transformations</primary></indexterm>
<para>Transformations that cannot appear in certain contexts.  See <link linkend="Order-of-Commands">Order
of Commands</link>, for details.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Procedures</emphasis>
</term><listitem><indexterm role="cp"><primary>procedures</primary></indexterm>
<para>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 <firstterm>procedure</firstterm> is any command that causes the
active dataset (the data) to be read.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="6.5" id="Order-of-Commands">
<title>Order of Commands</title>
<indexterm role="cp"><primary>commands, ordering</primary></indexterm>
<indexterm role="cp"><primary>order of commands</primary></indexterm>

<para>pspp does not place many restrictions on ordering of commands.  The
main restriction is that variables must be defined before they are otherwise
referenced.  This section describes the details of command ordering,
but most users will have no need to refer to them.
</para>
<para>pspp possesses five internal states, called <firstterm>initial</firstterm>, <firstterm>input-program</firstterm>
<firstterm>file-type</firstterm>, <firstterm>transformation</firstterm>, and <firstterm>procedure</firstterm> states.  (Please note the
distinction between the <literal>INPUT PROGRAM</literal> and <literal>FILE TYPE</literal>
<emphasis>commands</emphasis> and the <firstterm>input-program</firstterm> and <firstterm>file-type</firstterm> <emphasis>states</emphasis>.)
</para>
<para>pspp starts 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:
</para>
<variablelist><varlistentry><term><emphasis role="bold">Utility commands</emphasis>
</term><listitem><itemizedlist><listitem><para>Valid in any state.
</para></listitem><listitem><para>Do not cause state transitions.  Exception: when <literal>N OF CASES</literal>
is executed in the procedure state, it causes a transition to the
transformation state.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold"><literal>DATA LIST</literal></emphasis>
</term><listitem><itemizedlist><listitem><para>Valid in any state.
</para></listitem><listitem><para>When executed in the initial or procedure state, causes a transition to
the transformation state.  
</para></listitem><listitem><para>Clears the active dataset if executed in the procedure or transformation
state.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold"><literal>INPUT PROGRAM</literal></emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in input-program and file-type states.
</para></listitem><listitem><para>Causes a transition to the intput-program state.  
</para></listitem><listitem><para>Clears the active dataset.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold"><literal>FILE TYPE</literal></emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in intput-program and file-type states.
</para></listitem><listitem><para>Causes a transition to the file-type state.
</para></listitem><listitem><para>Clears the active dataset.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Other file definition commands</emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in input-program and file-type states.
</para></listitem><listitem><para>Cause a transition to the transformation state.
</para></listitem><listitem><para>Clear the active dataset, except for <literal>ADD FILES</literal>, <literal>MATCH FILES</literal>,
and <literal>UPDATE</literal>.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Transformations</emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in initial and file-type states.
</para></listitem><listitem><para>Cause a transition to the transformation state.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Restricted transformations</emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in initial, input-program, and file-type states.
</para></listitem><listitem><para>Cause a transition to the transformation state.
</para></listitem></itemizedlist>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Procedures</emphasis>
</term><listitem><itemizedlist><listitem><para>Invalid in initial, input-program, and file-type states.
</para></listitem><listitem><para>Cause a transition to the procedure state.
</para></listitem></itemizedlist></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="6.6" id="Missing-Observations">
<title>Handling missing observations</title>
<indexterm role="cp"><primary>missing values</primary></indexterm>
<indexterm role="cp"><primary>values, missing</primary></indexterm>

<para>pspp includes special support for unknown numeric data values.
Missing observations are assigned a special value, called the
<firstterm>system-missing value</firstterm>.  This &#8220;value&#8221; actually indicates the
absence of a value; it means that the actual value is unknown.  Procedures
automatically exclude from analyses those observations or cases that
have missing values.  Details of missing value exclusion depend on the
procedure and can often be controlled by the user; refer to
descriptions of individual procedures for details.
</para>
<para>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.
</para>
<para>Variables, whether numeric or string, can have designated
<firstterm>user-missing values</firstterm>.  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.
</para>
<para>For more information on missing values, see the following sections:
<link linkend="Datasets">Datasets</link>, <link linkend="MISSING-VALUES">MISSING VALUES</link>, <link linkend="Expressions">Expressions</link>.  See also the
documentation on individual procedures for information on how they
handle missing values.
</para>
</sect1>
<sect1 label="6.7" id="Datasets">
<title>Datasets</title>
<indexterm role="cp"><primary>dataset</primary></indexterm>
<indexterm role="cp"><primary>variable</primary></indexterm>
<indexterm role="cp"><primary>dictionary</primary></indexterm>

<para>pspp works with data organized into <firstterm>datasets</firstterm>.  A dataset
consists of a set of <firstterm>variables</firstterm>, which taken together are said to
form a <firstterm>dictionary</firstterm>, and one or more <firstterm>cases</firstterm>, each of which
has one value for each variable.
</para>
<para>At any given time pspp has exactly one distinguished dataset, called
the <firstterm>active dataset</firstterm>.  Most pspp commands work only with the
active dataset.  In addition to the active dataset, pspp also supports
any number of additional open datasets.  The <literal>DATASET</literal> commands
can choose a new active dataset from among those that are open, as
well as create and destroy datasets (see <link linkend="DATASET">DATASET</link>).
</para>
<para>The sections below describe variables in more detail.
</para>

<sect2 label="6.7.1" id="Attributes">
<title>Attributes of Variables</title>
<indexterm role="cp"><primary>variables, attributes of</primary></indexterm>
<indexterm role="cp"><primary>attributes of variables</primary></indexterm>
<para>Each variable has a number of attributes, including:
</para>
<variablelist><varlistentry><term><emphasis role="bold">Name</emphasis>
</term><listitem><para>An identifier, up to 64 bytes long.  Each variable must have a different name.
See <link linkend="Tokens">Tokens</link>.
</para>
<para>Some system variable names begin with &#8216;<literal>$</literal>&#8217;, but user-defined
variables&#8217; names may not begin with &#8216;<literal>$</literal>&#8217;.
</para>
<indexterm role="cp"><primary>&#8216;<literal>.</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>period</primary></indexterm>
<indexterm role="cp"><primary>variable names, ending with period</primary></indexterm>
<para>The final character in a variable name should not be &#8216;<literal>.</literal>&#8217;, because
such an identifier will be misinterpreted when it is the final token
on a line: <literal>FOO.</literal> will be divided into two separate tokens,
&#8216;<literal>FOO</literal>&#8217; and &#8216;<literal>.</literal>&#8217;, indicating end-of-command.  See <link linkend="Tokens">Tokens</link>.
</para>
<indexterm role="cp"><primary>&#8216;<literal>_</literal>&#8217;</primary></indexterm>
<para>The final character in a variable name should not be &#8216;<literal>_</literal>&#8217;, because
some such identifiers are used for special purposes by pspp
procedures.
</para>
<para>As with all pspp identifiers, variable names are not case-sensitive.
pspp capitalizes variable names on output the same way they were
capitalized at their point of definition in the input.
</para>
<indexterm role="cp"><primary>variables, type</primary></indexterm>
<indexterm role="cp"><primary>type of variables</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Type</emphasis>
</term><listitem><para>Numeric or string.
</para>
<indexterm role="cp"><primary>variables, width</primary></indexterm>
<indexterm role="cp"><primary>width of variables</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Width</emphasis>
</term><listitem><para>(string variables only) String variables with a width of 8 characters or
fewer are called <firstterm>short string variables</firstterm>.  Short string variables
may be used in a few contexts where <firstterm>long string variables</firstterm> (those
with widths greater than 8) are not allowed.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Position</emphasis>
</term><listitem><para>Variables in the dictionary are arranged in a specific order.
<literal>DISPLAY</literal> can be used to show this order: see <link linkend="DISPLAY">DISPLAY</link>.
</para>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Initialization</emphasis>
</term><listitem><para>Either reinitialized to 0 or spaces for each case, or left at its
existing value.  See <link linkend="LEAVE">LEAVE</link>.
</para>
<indexterm role="cp"><primary>missing values</primary></indexterm>
<indexterm role="cp"><primary>values, missing</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Missing values</emphasis>
</term><listitem><para>Optionally, up to three values, or a range of values, or a specific
value plus a range, can be specified as <firstterm>user-missing values</firstterm>.
There is also a <firstterm>system-missing value</firstterm> 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.  See <link linkend="Missing-Observations">Missing Observations</link>.
</para>
<indexterm role="cp"><primary>variable labels</primary></indexterm>
<indexterm role="cp"><primary>labels, variable</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Variable label</emphasis>
</term><listitem><para>A string that describes the variable.  See <link linkend="VARIABLE-LABELS">VARIABLE LABELS</link>.
</para>
<indexterm role="cp"><primary>value labels</primary></indexterm>
<indexterm role="cp"><primary>labels, value</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Value label</emphasis>
</term><listitem><para>Optionally, these associate each possible value of the variable with a
string.  See <link linkend="VALUE-LABELS">VALUE LABELS</link>.
</para>
<indexterm role="cp"><primary>print format</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Print format</emphasis>
</term><listitem><para>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.
See <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.
</para>
<indexterm role="cp"><primary>write format</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Write format</emphasis>
</term><listitem><para>Similar to print format, but used by the <literal>WRITE</literal> command
(see <link linkend="WRITE">WRITE</link>).
</para>
<indexterm role="cp"><primary>custom attributes</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Custom attributes</emphasis>
</term><listitem><para>User-defined associations between names and values.  See <link linkend="VARIABLE-ATTRIBUTE">VARIABLE
ATTRIBUTE</link>.
</para>
<indexterm role="cp"><primary>variable role</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">Role</emphasis>
</term><listitem><para>The intended role of a variable for use in dialog boxes in graphical
user interfaces.  See <link linkend="VARIABLE-ROLE">VARIABLE ROLE</link>.
</para></listitem></varlistentry></variablelist>
</sect2>
<sect2 label="6.7.2" id="System-Variables">
<title>Variables Automatically Defined by pspp</title>
<indexterm role="cp"><primary>system variables</primary></indexterm>
<indexterm role="cp"><primary>variables, system</primary></indexterm>

<para>There are seven system variables.  These are not like ordinary
variables because system variables are not always stored.  They can be used only
in expressions.  These system variables, whose values and output formats
cannot be modified, are described below.
</para>
<variablelist><indexterm role="cp"><primary><literal>$CASENUM</literal></primary></indexterm>
<varlistentry><term><literal>$CASENUM</literal>
</term><listitem><para>Case number of the case at the moment.  This changes as cases are
shuffled around.
</para>
<indexterm role="cp"><primary><literal>$DATE</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>$DATE</literal>
</term><listitem><para>Date the pspp process was started, in format A9, following the
pattern <literal>DD MMM YY</literal>.
</para>
<indexterm role="cp"><primary><literal>$JDATE</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>$JDATE</literal>
</term><listitem><para>Number of days between 15 Oct 1582 and the time the pspp process
was started.
</para>
<indexterm role="cp"><primary><literal>$LENGTH</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>$LENGTH</literal>
</term><listitem><para>Page length, in lines, in format F11.
</para>
<indexterm role="cp"><primary><literal>$SYSMIS</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>$SYSMIS</literal>
</term><listitem><para>System missing value, in format F1.
</para>
<indexterm role="cp"><primary><literal>$TIME</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>$TIME</literal>
</term><listitem><para>Number of seconds between midnight 14 Oct 1582 and the time the active dataset
was read, in format F20.
</para>
<indexterm role="cp"><primary><literal>$WIDTH</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>$WIDTH</literal>
</term><listitem><para>Page width, in characters, in format F3.
</para></listitem></varlistentry></variablelist>
</sect2>
<sect2 label="6.7.3" id="Sets-of-Variables">
<title>Lists of variable names</title>
<indexterm role="cp"><primary><literal>TO</literal> convention</primary></indexterm>
<indexterm role="cp"><primary>convention, <literal>TO</literal></primary></indexterm>

<para>To refer to a set of variables, list their names one after another.
Optionally, their names may be separated by commas.  To include a
range of variables from the dictionary in the list, write the name of
the first and last variable in the range, separated by <literal>TO</literal>.  For
instance, if the dictionary contains six variables with the names
<literal>ID</literal>, <literal>X1</literal>, <literal>X2</literal>, <literal>GOAL</literal>, <literal>MET</literal>, and
<literal>NEXTGOAL</literal>, in that order, then <literal>X2 TO MET</literal> would include
variables <literal>X2</literal>, <literal>GOAL</literal>, and <literal>MET</literal>.
</para>
<para>Commands that define variables, such as <literal>DATA LIST</literal>, give
<literal>TO</literal> an alternate meaning.  With these commands, <literal>TO</literal> define
sequences of variables whose names end in consecutive integers.  The
syntax is two identifiers that begin with the same root and end with
numbers, separated by <literal>TO</literal>.  The syntax <literal>X1 TO X5</literal> defines 5
variables, named <literal>X1</literal>, <literal>X2</literal>, <literal>X3</literal>, <literal>X4</literal>, and
<literal>X5</literal>.  The syntax <literal>ITEM0008 TO ITEM0013</literal> defines 6
variables, named <literal>ITEM0008</literal>, <literal>ITEM0009</literal>, <literal>ITEM0010</literal>,
<literal>ITEM0011</literal>, <literal>ITEM0012</literal>, and <literal>ITEM00013</literal>.  The syntaxes
<literal>QUES001 TO QUES9</literal> and <literal>QUES6 TO QUES3</literal> are invalid.
</para>
<para>After a set of variables has been defined with <literal>DATA LIST</literal> or
another command with this method, the same set can be referenced on
later commands using the same syntax.
</para>
</sect2>
<sect2 label="6.7.4" id="Input-and-Output-Formats">
<title>Input and Output Formats</title>

<indexterm role="cp"><primary>formats</primary></indexterm>
<para>An <firstterm>input format</firstterm> describes how to interpret the contents of an
input field as a number or a string.  It might specify that the field
contains an ordinary decimal number, a time or date, a number in binary
or hexadecimal notation, or one of several other notations.  Input
formats are used by commands such as <literal>DATA LIST</literal> that read data or
syntax files into the pspp active dataset.
</para>
<para>Every input format corresponds to a default <firstterm>output format</firstterm> that
specifies the formatting used when the value is output later.  It is
always possible to explicitly specify an output format that resembles
the input format.  Usually, this is the default, but in cases where the
input format is unfriendly to human readability, such as binary or
hexadecimal formats, the default output format is an easier-to-read
decimal format.
</para>
<para>Every variable has two output formats, called its <firstterm>print format</firstterm> and
<firstterm>write format</firstterm>.  Print formats are used in most output contexts;
write formats are used only by <literal>WRITE</literal> (see <link linkend="WRITE">WRITE</link>).  Newly
created variables have identical print and write formats, and
<literal>FORMATS</literal>, the most commonly used command for changing formats
(see <link linkend="FORMATS">FORMATS</link>), sets both of them to the same value as well.  Thus,
most of the time, the distinction between print and write formats is
unimportant.
</para>
<para>Input and output formats are specified to pspp with 
a <firstterm>format specification</firstterm> of the
form <literal><replaceable>TYPE</replaceable><replaceable>w</replaceable></literal> or <literal>TYPE<replaceable>w</replaceable>.<replaceable>d</replaceable></literal>, where
<replaceable>TYPE</replaceable> is one of the format types described later, <replaceable>w</replaceable> is a
field width measured in columns, and <replaceable>d</replaceable> is an optional number of
decimal places.  If <replaceable>d</replaceable> is omitted, a value of 0 is assumed.  Some
formats do not allow a nonzero <replaceable>d</replaceable> to be specified.
</para>
<para>The following sections describe the input and output formats supported
by pspp.
</para>

<sect3 label="6.7.4.1" id="Basic-Numeric-Formats">
<title>Basic Numeric Formats</title>

<indexterm role="cp"><primary>numeric formats</primary></indexterm>
<para>The basic numeric formats are used for input and output of real numbers
in standard or scientific notation.  The following table shows an
example of how each format displays positive and negative numbers with
the default decimal point setting:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="10*"></colspec><colspec colwidth="10*"></colspec><colspec colwidth="10*"></colspec><thead><row><entry><para>Format </para></entry><entry><para><literal>&#160;3141.59</literal>   </para></entry><entry><para><literal>-3141.59</literal>
</para></entry></row></thead><tbody><row><entry><para>F8.2       </para></entry><entry><para><literal>&#160;3141.59</literal>   </para></entry><entry><para><literal>-3141.59</literal>
</para></entry></row><row><entry><para>COMMA9.2   </para></entry><entry><para><literal>&#160;3,141.59</literal>  </para></entry><entry><para><literal>-3,141.59</literal>
</para></entry></row><row><entry><para>DOT9.2     </para></entry><entry><para><literal>&#160;3.141,59</literal>  </para></entry><entry><para><literal>-3.141,59</literal>
</para></entry></row><row><entry><para>DOLLAR10.2 </para></entry><entry><para><literal>&#160;$3,141.59</literal> </para></entry><entry><para><literal>-$3,141.59</literal>
</para></entry></row><row><entry><para>PCT9.2     </para></entry><entry><para><literal>&#160;3141.59%</literal>  </para></entry><entry><para><literal>-3141.59%</literal>
</para></entry></row><row><entry><para>E8.1       </para></entry><entry><para><literal>&#160;3.1E+003</literal>  </para></entry><entry><para><literal>-3.1E+003</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>On output, numbers in F format are expressed in standard decimal
notation with the requested number of decimal places.  The other formats
output some variation on this style:
</para>
<itemizedlist><listitem><para>Numbers in COMMA format are additionally grouped every three digits by
inserting a grouping character.  The grouping character is ordinarily a
comma, but it can be changed to a period (see <link linkend="SET-DECIMAL">SET DECIMAL</link>).
</para>
</listitem><listitem><para>DOT format is like COMMA format, but it interchanges the role of the
decimal point and grouping characters.  That is, the current grouping
character is used as a decimal point and vice versa.
</para>
</listitem><listitem><para>DOLLAR format is like COMMA format, but it prefixes the number with
&#8216;<literal>$</literal>&#8217;.
</para>
</listitem><listitem><para>PCT format is like F format, but adds &#8216;<literal>%</literal>&#8217; after the number.
</para>
</listitem><listitem><para>The E format always produces output in scientific notation.
</para></listitem></itemizedlist>
<para>On input, the basic numeric formats accept positive and numbers in
standard decimal notation or scientific notation.  Leading and trailing
spaces are allowed.  An empty or all-spaces field, or one that contains
only a single period, is treated as the system missing value.
</para>
<para>In scientific notation, the exponent may be introduced by a sign
(&#8216;<literal>+</literal>&#8217; or &#8216;<literal>-</literal>&#8217;), or by one of the letters &#8216;<literal>e</literal>&#8217; or &#8216;<literal>d</literal>&#8217;
(in uppercase or lowercase), or by a letter followed by a sign.  A
single space may follow the letter or the sign or both.
</para>
<para>On fixed-format <literal>DATA LIST</literal> (see <link linkend="DATA-LIST-FIXED">DATA LIST FIXED</link>) and in a few
other contexts, decimals are implied when the field does not contain a
decimal point.  In F6.5 format, for example, the field <literal>314159</literal> is
taken as the value 3.14159 with implied decimals.  Decimals are never
implied if an explicit decimal point is present or if scientific
notation is used.
</para>
<para>E and F formats accept the basic syntax already described.  The other
formats allow some additional variations:
</para>
<itemizedlist><listitem><para>COMMA, DOLLAR, and DOT formats ignore grouping characters within the
integer part of the input field.  The identity of the grouping
character depends on the format.
</para>
</listitem><listitem><para>DOLLAR format allows a dollar sign to precede the number.  In a negative
number, the dollar sign may precede or follow the minus sign.
</para>
</listitem><listitem><para>PCT format allows a percent sign to follow the number.
</para></listitem></itemizedlist>
<para>All of the basic number formats have a maximum field width of 40 and
accept no more than 16 decimal places, on both input and output.  Some
additional restrictions apply:
</para>
<itemizedlist><listitem><para>As input formats, the basic numeric formats allow no more decimal places
than the field width.  As output formats, the field width must be
greater than the number of decimal places; that is, large enough to
allow for a decimal point and the number of requested decimal places.
DOLLAR and PCT formats must allow an additional column for &#8216;<literal>$</literal>&#8217; or
&#8216;<literal>%</literal>&#8217;.
</para>
</listitem><listitem><para>The default output format for a given input format increases the field
width enough to make room for optional input characters.  If an input
format calls for decimal places, the width is increased by 1 to make
room for an implied decimal point.  COMMA, DOT, and DOLLAR formats also
increase the output width to make room for grouping characters.  DOLLAR
and PCT further increase the output field width by 1 to make room for
&#8216;<literal>$</literal>&#8217; or &#8216;<literal>%</literal>&#8217;.  The increased output width is capped at 40, the
maximum field width.
</para>
</listitem><listitem><para>The E format is exceptional.  For output, E format has a minimum width
of 7 plus the number of decimal places.  The default output format for
an E input format is an E format with at least 3 decimal places and
thus a minimum width of 10.
</para></listitem></itemizedlist>
<para>More details of basic numeric output formatting are given below:
</para>
<itemizedlist><listitem><para>Output rounds to nearest, with ties rounded away from zero.  Thus, 2.5
is output as <literal>3</literal> in F1.0 format, and -1.125 as <literal>-1.13</literal> in F5.1
format.
</para>
</listitem><listitem><para>The system-missing value is output as a period in a field of spaces,
placed in the decimal point&#8217;s position, or in the rightmost column if no
decimal places are requested.  A period is used even if the decimal
point character is a comma.
</para>
</listitem><listitem><para>A number that does not fill its field is right-justified within the
field.
</para>
</listitem><listitem><para>A number is too large for its field causes decimal places to be dropped
to make room.  If dropping decimals does not make enough room,
scientific notation is used if the field is wide enough.  If a number
does not fit in the field, even in scientific notation, the overflow is
indicated by filling the field with asterisks (&#8216;<literal>*</literal>&#8217;).
</para>
</listitem><listitem><para>COMMA, DOT, and DOLLAR formats insert grouping characters only if space
is available for all of them.  Grouping characters are never inserted
when all decimal places must be dropped.  Thus, 1234.56 in COMMA5.2
format is output as &#8216;<literal>&#160;1235</literal>&#8217; without a comma, even though there
is room for one, because all decimal places were dropped.
</para>
</listitem><listitem><para>DOLLAR or PCT format drop the &#8216;<literal>$</literal>&#8217; or &#8216;<literal>%</literal>&#8217; only if the number
would not fit at all without it.  Scientific notation with &#8216;<literal>$</literal>&#8217; or
&#8216;<literal>%</literal>&#8217; is preferred to ordinary decimal notation without it.
</para>
</listitem><listitem><para>Except in scientific notation, a decimal point is included only when
it is followed by a digit.  If the integer part of the number being
output is 0, and a decimal point is included, then the zero before the
decimal point is dropped.
</para>
<para>In scientific notation, the number always includes a decimal point,
even if it is not followed by a digit.
</para>
</listitem><listitem><para>A negative number includes a minus sign only in the presence of a
nonzero digit: -0.01 is output as &#8216;<literal>-.01</literal>&#8217; in F4.2 format but as
&#8216;<literal>&#160;&#160;.0</literal>&#8217; in F4.1 format.  Thus, a &#8220;negative zero&#8221; never
includes a minus sign.
</para>
</listitem><listitem><para>In negative numbers output in DOLLAR format, the dollar sign follows the
negative sign.  Thus, -9.99 in DOLLAR6.2 format is output as
<literal>-$9.99</literal>.
</para>
</listitem><listitem><para>In scientific notation, the exponent is output as &#8216;<literal>E</literal>&#8217; followed by
&#8216;<literal>+</literal>&#8217; or &#8216;<literal>-</literal>&#8217; and exactly three digits.  Numbers with magnitude
less than 10**-999 or larger than 10**999 are not supported by most
computers, but if they are supported then their output is considered
to overflow the field and will be output as asterisks.
</para>
</listitem><listitem><para>On most computers, no more than 15 decimal digits are significant in
output, even if more are printed.  In any case, output precision cannot
be any higher than input precision; few data sets are accurate to 15
digits of precision.  Unavoidable loss of precision in intermediate
calculations may also reduce precision of output.
</para>
</listitem><listitem><para>Special values such as infinities and &#8220;not a number&#8221; values are
usually converted to the system-missing value before printing.  In a few
circumstances, these values are output directly.  In fields of width 3
or greater, special values are output as however many characters will
fit from <literal>+Infinity</literal> or <literal>-Infinity</literal> for infinities, from
<literal>NaN</literal> for &#8220;not a number,&#8221; or from <literal>Unknown</literal> for other values
(if any are supported by the system).  In fields under 3 columns wide,
special values are output as asterisks.
</para></listitem></itemizedlist>
</sect3>
<sect3 label="6.7.4.2" id="Custom-Currency-Formats">
<title>Custom Currency Formats</title>

<indexterm role="cp"><primary>currency formats</primary></indexterm>
<para>The custom currency formats are closely related to the basic numeric
formats, but they allow users to customize the output format.  The
SET command configures custom currency formats, using the syntax
</para><literallayout>SET CC<replaceable>x</replaceable>=<literal>&quot;</literal><replaceable>string</replaceable><literal>&quot;</literal>.
</literallayout><para>where <replaceable>x</replaceable> is A, B, C, D, or E, and <replaceable>string</replaceable> is no more than 16
characters long.
</para>
<para><replaceable>string</replaceable> must contain exactly three commas or exactly three periods
(but not both), except that a single quote character may be used to
&#8220;escape&#8221; a following comma, period, or single quote.  If three commas
are used, commas will be used for grouping in output, and a period will
be used as the decimal point.  Uses of periods reverses these roles.
</para>
<para>The commas or periods divide <replaceable>string</replaceable> into four fields, called the
<firstterm>negative prefix</firstterm>, <firstterm>prefix</firstterm>, <firstterm>suffix</firstterm>, and <firstterm>negative
suffix</firstterm>, respectively.  The prefix and suffix are added to output
whenever space is available.  The negative prefix and negative suffix
are always added to a negative number when the output includes a nonzero
digit.
</para>
<para>The following syntax shows how custom currency formats could be used to
reproduce basic numeric formats:
</para>
<screen>SET CCA=&quot;-,,,&quot;.  /* Same as COMMA.
SET CCB=&quot;-...&quot;.  /* Same as DOT.
SET CCC=&quot;-,$,,&quot;. /* Same as DOLLAR.
SET CCD=&quot;-,,%,&quot;. /* Like PCT, but groups with commas.
</screen>
<para>Here are some more examples of custom currency formats.  The final
example shows how to use a single quote to escape a delimiter:
</para>
<screen>SET CCA=&quot;,EUR,,-&quot;.   /* Euro.
SET CCB=&quot;(,USD ,,)&quot;. /* US dollar.
SET CCC=&quot;-.R$..&quot;.    /* Brazilian real.
SET CCD=&quot;-,, NIS,&quot;.  /* Israel shekel.
SET CCE=&quot;-.Rp'. ..&quot;. /* Indonesia Rupiah.
</screen>
<para>These formats would yield the following output:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="7*"></colspec><colspec colwidth="14*"></colspec><colspec colwidth="14*"></colspec><thead><row><entry><para>Format </para></entry><entry><para><literal>&#160;3145.59</literal>         </para></entry><entry><para><literal>-3145.59</literal>
</para></entry></row></thead><tbody><row><entry><para>CCA12.2 </para></entry><entry><para><literal>&#160;EUR3,145.59</literal>        </para></entry><entry><para><literal>EUR3,145.59-</literal>
</para></entry></row><row><entry><para>CCB14.2 </para></entry><entry><para><literal>&#160;&#160;USD 3,145.59</literal> </para></entry><entry><para><literal>(USD 3,145.59)</literal>
</para></entry></row><row><entry><para>CCC11.2 </para></entry><entry><para><literal>&#160;R$3.145,59</literal>         </para></entry><entry><para><literal>-R$3.145,59</literal>
</para></entry></row><row><entry><para>CCD13.2 </para></entry><entry><para><literal>&#160;3,145.59 NIS</literal>       </para></entry><entry><para><literal>-3,145.59 NIS</literal>
</para></entry></row><row><entry><para>CCE10.0 </para></entry><entry><para><literal>&#160;Rp. 3.146</literal>          </para></entry><entry><para><literal>-Rp. 3.146</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>The default for all the custom currency formats is &#8216;<literal>-,,,</literal>&#8217;,
equivalent to COMMA format.
</para>
</sect3>
<sect3 label="6.7.4.3" id="Legacy-Numeric-Formats">
<title>Legacy Numeric Formats</title>

<para>The N and Z numeric formats provide compatibility with legacy file
formats.  They have much in common:
</para>
<itemizedlist><listitem><para>Output is rounded to the nearest representable value, with ties rounded
away from zero.
</para>
</listitem><listitem><para>Numbers too large to display are output as a field filled with asterisks
(&#8216;<literal>*</literal>&#8217;).
</para>
</listitem><listitem><para>The decimal point is always implicitly the specified number of digits
from the right edge of the field, except that Z format input allows an
explicit decimal point.
</para>
</listitem><listitem><para>Scientific notation may not be used.
</para>
</listitem><listitem><para>The system-missing value is output as a period in a field of spaces.
The period is placed just to the right of the implied decimal point in
Z format, or at the right end in N format or in Z format if no decimal
places are requested.  A period is used even if the decimal point
character is a comma.
</para>
</listitem><listitem><para>Field width may range from 1 to 40.  Decimal places may range from 0 up
to the field width, to a maximum of 16.
</para>
</listitem><listitem><para>When a legacy numeric format used for input is converted to an output
format, it is changed into the equivalent F format.  The field width is
increased by 1 if any decimal places are specified, to make room for a
decimal point.  For Z format, the field width is increased by 1 more
column, to make room for a negative sign.  The output field width is
capped at 40 columns.
</para></listitem></itemizedlist>
<bridgehead renderas="sect3">N Format</bridgehead>

<para>The N format supports input and output of fields that contain only
digits.  On input, leading or trailing spaces, a decimal point, or any
other non-digit character causes the field to be read as the
system-missing value.  As a special exception, an N format used on
<literal>DATA LIST FREE</literal> or <literal>DATA LIST LIST</literal> is treated as the
equivalent F format.
</para>
<para>On output, N pads the field on the left with zeros.  Negative numbers
are output like the system-missing value.
</para>
<bridgehead renderas="sect3">Z Format</bridgehead>

<para>The Z format is a &#8220;zoned decimal&#8221; format used on IBM mainframes.  Z
format encodes the sign as part of the final digit, which must be one of
the following:
</para><screen>0123456789
{ABCDEFGHI
}JKLMNOPQR
</screen><para>where the characters in each row represent digits 0 through 9 in order.
Characters in the first two rows indicate a positive sign; those in the
third indicate a negative sign.
</para>
<para>On output, Z fields are padded on the left with spaces.  On input,
leading and trailing spaces are ignored.  Any character in an input
field other than spaces, the digit characters above, and &#8216;<literal>.</literal>&#8217; causes
the field to be read as system-missing.
</para>
<para>The decimal point character for input and output is always &#8216;<literal>.</literal>&#8217;,
even if the decimal point character is a comma (see <link linkend="SET-DECIMAL">SET DECIMAL</link>).
</para>
<para>Nonzero, negative values output in Z format are marked as negative even
when no nonzero digits are output.  For example, -0.2 is output in Z1.0
format as &#8216;<literal>J</literal>&#8217;.  The &#8220;negative zero&#8221; value supported by most
machines is output as positive.
</para>
</sect3>
<sect3 label="6.7.4.4" id="Binary-and-Hexadecimal-Numeric-Formats">
<title>Binary and Hexadecimal Numeric Formats</title>

<indexterm role="cp"><primary>binary formats</primary></indexterm>
<indexterm role="cp"><primary>hexadecimal formats</primary></indexterm>
<para>The binary and hexadecimal formats are primarily designed for
compatibility with existing machine formats, not for human readability.
All of them therefore have a F format as default output format.  Some of
these formats are only portable between machines with compatible byte
ordering (endianness) or floating-point format.
</para>
<para>Binary formats use byte values that in text files are interpreted as
special control functions, such as carriage return and line feed.  Thus,
data in binary formats should not be included in syntax files or read
from data files with variable-length records, such as ordinary text
files.  They may be read from or written to data files with fixed-length
records.  See <link linkend="FILE-HANDLE">FILE HANDLE</link>, for information on working with
fixed-length records.
</para>
<bridgehead renderas="sect3">P and PK Formats</bridgehead>

<para>These are binary-coded decimal formats, in which every byte (except the
last, in P format) represents two decimal digits.  The most-significant
4 bits of the first byte is the most-significant decimal digit, the
least-significant 4 bits of the first byte is the next decimal digit,
and so on.
</para>
<para>In P format, the most-significant 4 bits of the last byte are the
least-significant decimal digit.  The least-significant 4 bits represent
the sign: decimal 15 indicates a negative value, decimal 13 indicates a
positive value.
</para>
<para>Numbers are rounded downward on output.  The system-missing value and
numbers outside representable range are output as zero.
</para>
<para>The maximum field width is 16.  Decimal places may range from 0 up to
the number of decimal digits represented by the field.
</para>
<para>The default output format is an F format with twice the input field
width, plus one column for a decimal point (if decimal places were
requested).
</para>
<bridgehead renderas="sect3">IB and PIB Formats</bridgehead>

<para>These are integer binary formats.  IB reads and writes 2&#8217;s complement
binary integers, and PIB reads and writes unsigned binary integers.  The
byte ordering is by default the host machine&#8217;s, but SET RIB may be used
to select a specific byte ordering for reading (see <link linkend="SET-RIB">SET RIB</link>) and
SET WIB, similarly, for writing (see <link linkend="SET-WIB">SET WIB</link>).
</para>
<para>The maximum field width is 8.  Decimal places may range from 0 up to the
number of decimal digits in the largest value representable in the field
width.
</para>
<para>The default output format is an F format whose width is the number of
decimal digits in the largest value representable in the field width,
plus 1 if the format has decimal places.
</para>
<bridgehead renderas="sect3">RB Format</bridgehead>

<para>This is a binary format for real numbers.  By default it reads and
writes the host machine&#8217;s floating-point format, but SET RRB may be
used to select an alternate floating-point format for reading
(see <link linkend="SET-RRB">SET RRB</link>) and SET WRB, similarly, for writing (see <link linkend="SET-WRB">SET
WRB</link>).
</para>
<para>The recommended field width depends on the floating-point format.
NATIVE (the default format), IDL, IDB, VD, VG, and ZL formats should use
a field width of 8.  ISL, ISB, VF, and ZS formats should use a field
width of 4.  Other field widths will not produce useful results.  The
maximum field width is 8.  No decimal places may be specified.
</para>
<para>The default output format is F8.2.
</para>
<bridgehead renderas="sect3">PIBHEX and RBHEX Formats</bridgehead>

<para>These are hexadecimal formats, for reading and writing binary formats
where each byte has been recoded as a pair of hexadecimal digits.
</para>
<para>A hexadecimal field consists solely of hexadecimal digits
&#8216;<literal>0</literal>&#8217;&#8230;&#8216;<literal>9</literal>&#8217; and &#8216;<literal>A</literal>&#8217;&#8230;&#8216;<literal>F</literal>&#8217;.  Uppercase and
lowercase are accepted on input; output is in uppercase.
</para>
<para>Other than the hexadecimal representation, these formats are equivalent
to PIB and RB formats, respectively.  However, bytes in PIBHEX format
are always ordered with the most-significant byte first (big-endian
order), regardless of the host machine&#8217;s native byte order or pspp
settings.
</para>
<para>Field widths must be even and between 2 and 16.  RBHEX format allows no
decimal places; PIBHEX allows as many decimal places as a PIB format
with half the given width.
</para>
</sect3>
<sect3 label="6.7.4.5" id="Time-and-Date-Formats">
<title>Time and Date Formats</title>

<indexterm role="cp"><primary>time formats</primary></indexterm>
<indexterm role="cp"><primary>date formats</primary></indexterm>
<para>In pspp, a <firstterm>time</firstterm> is an interval.  The time formats translate
between human-friendly descriptions of time intervals and pspp&#8217;s
internal representation of time intervals, which is simply the number of
seconds in the interval.  pspp has two time formats:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="11*"></colspec><colspec colwidth="23*"></colspec><colspec colwidth="23*"></colspec><thead><row><entry><para>Time Format </para></entry><entry><para>Template                  </para></entry><entry><para>Example
</para></entry></row></thead><tbody><row><entry><para>TIME     </para></entry><entry><para><literal>hh:MM:SS.ss</literal>          </para></entry><entry><para><literal>04:31:17.01</literal>
</para></entry></row><row><entry><para>DTIME    </para></entry><entry><para><literal>DD HH:MM:SS.ss</literal>       </para></entry><entry><para><literal>00 04:31:17.01</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>A <firstterm>date</firstterm> is a moment in the past or the future.  Internally, pspp
represents a date as the number of seconds since the <firstterm>epoch</firstterm>,
midnight, Oct. 14, 1582.  The date formats translate between
human-readable dates and pspp&#8217;s numeric representation of dates and
times.  pspp has several date formats:
</para>
<informaltable><tgroup cols="3"><colspec colwidth="11*"></colspec><colspec colwidth="23*"></colspec><colspec colwidth="23*"></colspec><thead><row><entry><para>Date Format </para></entry><entry><para>Template                  </para></entry><entry><para>Example
</para></entry></row></thead><tbody><row><entry><para>DATE     </para></entry><entry><para><literal>dd-mmm-yyyy</literal>          </para></entry><entry><para><literal>01-OCT-1978</literal>
</para></entry></row><row><entry><para>ADATE    </para></entry><entry><para><literal>mm/dd/yyyy</literal>           </para></entry><entry><para><literal>10/01/1978</literal>
</para></entry></row><row><entry><para>EDATE    </para></entry><entry><para><literal>dd.mm.yyyy</literal>           </para></entry><entry><para><literal>01.10.1978</literal>
</para></entry></row><row><entry><para>JDATE    </para></entry><entry><para><literal>yyyyjjj</literal>              </para></entry><entry><para><literal>1978274</literal>
</para></entry></row><row><entry><para>SDATE    </para></entry><entry><para><literal>yyyy/mm/dd</literal>           </para></entry><entry><para><literal>1978/10/01</literal>
</para></entry></row><row><entry><para>QYR      </para></entry><entry><para><literal>q Q yyyy</literal>             </para></entry><entry><para><literal>3 Q 1978</literal>
</para></entry></row><row><entry><para>MOYR     </para></entry><entry><para><literal>mmm yyyy</literal>             </para></entry><entry><para><literal>OCT 1978</literal>
</para></entry></row><row><entry><para>WKYR     </para></entry><entry><para><literal>ww WK yyyy</literal>           </para></entry><entry><para><literal>40 WK 1978</literal>
</para></entry></row><row><entry><para>DATETIME </para></entry><entry><para><literal>dd-mmm-yyyy HH:MM:SS.ss</literal> </para></entry><entry><para><literal>01-OCT-1978 04:31:17.01</literal>
</para></entry></row></tbody></tgroup></informaltable>
<para>The templates in the preceding tables describe how the time and date
formats are input and output:
</para>
<variablelist><varlistentry><term><literal>dd</literal>
</term><listitem><para>Day of month, from 1 to 31.  Always output as two digits.
</para>
</listitem></varlistentry><varlistentry><term><literal>mm</literal>
</term><term><literal>mmm</literal>
</term><listitem><para>Month.  In output, <literal>mm</literal> is output as two digits, <literal>mmm</literal> as the
first three letters of an English month name (January, February,
&#8230;).  In input, both of these formats, plus Roman numerals, are
accepted.
</para>
</listitem></varlistentry><varlistentry><term><literal>yyyy</literal>
</term><listitem><para>Year.  In output, DATETIME always produces a 4-digit year; other
formats can produce a 2- or 4-digit year.  The century assumed for
2-digit years depends on the EPOCH setting (see <link linkend="SET-EPOCH">SET EPOCH</link>).  In
output, a year outside the epoch causes the whole field to be filled
with asterisks (&#8216;<literal>*</literal>&#8217;).
</para>
</listitem></varlistentry><varlistentry><term><literal>jjj</literal>
</term><listitem><para>Day of year (Julian day), from 1 to 366.  This is exactly three digits
giving the count of days from the start of the year.  January 1 is
considered day 1.
</para>
</listitem></varlistentry><varlistentry><term><literal>q</literal>
</term><listitem><para>Quarter of year, from 1 to 4.  Quarters start on January 1, April 1,
July 1, and October 1.
</para>
</listitem></varlistentry><varlistentry><term><literal>ww</literal>
</term><listitem><para>Week of year, from 1 to 53.  Output as exactly two digits.  January 1 is
the first day of week 1.
</para>
</listitem></varlistentry><varlistentry><term><literal>DD</literal>
</term><listitem><para>Count of days, which may be positive or negative.  Output as at least
two digits.
</para>
</listitem></varlistentry><varlistentry><term><literal>hh</literal>
</term><listitem><para>Count of hours, which may be positive or negative.  Output as at least
two digits.
</para>
</listitem></varlistentry><varlistentry><term><literal>HH</literal>
</term><listitem><para>Hour of day, from 0 to 23.  Output as exactly two digits.
</para>
</listitem></varlistentry><varlistentry><term><literal>MM</literal>
</term><listitem><para>Minute of hour, from 0 to 59.  Output as exactly two digits.
</para>
</listitem></varlistentry><varlistentry><term><literal>SS.ss</literal>
</term><listitem><para>Seconds within minute, from 0 to 59.  The integer part is output as
exactly two digits.  On output, seconds and fractional seconds may or
may not be included, depending on field width and decimal places.  On
input, seconds and fractional seconds are optional.  The DECIMAL setting
controls the character accepted and displayed as the decimal point
(see <link linkend="SET-DECIMAL">SET DECIMAL</link>).
</para></listitem></varlistentry></variablelist>
<para>For output, the date and time formats use the delimiters indicated in
the table.  For input, date components may be separated by spaces or by
one of the characters &#8216;<literal>-</literal>&#8217;, &#8216;<literal>/</literal>&#8217;, &#8216;<literal>.</literal>&#8217;, or &#8216;<literal>,</literal>&#8217;, and
time components may be separated by spaces, &#8216;<literal>:</literal>&#8217;, or &#8216;<literal>.</literal>&#8217;.  On
input, the &#8216;<literal>Q</literal>&#8217; separating quarter from year and the &#8216;<literal>WK</literal>&#8217;
separating week from year may be uppercase or lowercase, and the spaces
around them are optional.
</para>
<para>On input, all time and date formats accept any amount of leading and
trailing white space.
</para>
<para>The maximum width for time and date formats is 40 columns.  Minimum
input and output width for each of the time and date formats is shown
below:
</para>
<informaltable><tgroup cols="4"><colspec colwidth="8*"></colspec><colspec colwidth="16*"></colspec><colspec colwidth="17*"></colspec><colspec colwidth="12*"></colspec><thead><row><entry><para>Format </para></entry><entry><para>Min. Input Width </para></entry><entry><para>Min. Output Width </para></entry><entry><para>Option 
</para></entry></row></thead><tbody><row><entry><para>DATE </para></entry><entry><para>8 </para></entry><entry><para>9 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>ADATE </para></entry><entry><para>8 </para></entry><entry><para>8 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>EDATE </para></entry><entry><para>8 </para></entry><entry><para>8 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>JDATE </para></entry><entry><para>5 </para></entry><entry><para>5 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>SDATE </para></entry><entry><para>8 </para></entry><entry><para>8 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>QYR </para></entry><entry><para>4 </para></entry><entry><para>6 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>MOYR </para></entry><entry><para>6 </para></entry><entry><para>6 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>WKYR </para></entry><entry><para>6 </para></entry><entry><para>8 </para></entry><entry><para>4-digit year
</para></entry></row><row><entry><para>DATETIME </para></entry><entry><para>17 </para></entry><entry><para>17 </para></entry><entry><para>seconds
</para></entry></row><row><entry><para>TIME </para></entry><entry><para>5 </para></entry><entry><para>5 </para></entry><entry><para>seconds
</para></entry></row><row><entry><para>DTIME </para></entry><entry><para>8 </para></entry><entry><para>8 </para></entry><entry><para>seconds
</para></entry></row></tbody></tgroup></informaltable><para>In the table, &#8220;Option&#8221; describes what increased output width enables:
</para>
<variablelist><varlistentry><term>4-digit year
</term><listitem><para>A field 2 columns wider than minimum will include a 4-digit year.
(DATETIME format always includes a 4-digit year.)
</para>
</listitem></varlistentry><varlistentry><term>seconds
</term><listitem><para>A field 3 columns wider than minimum will include seconds as well as
minutes.  A field 5 columns wider than minimum, or more, can also
include a decimal point and fractional seconds (but no more than allowed
by the format&#8217;s decimal places).
</para></listitem></varlistentry></variablelist>
<para>For the time and date formats, the default output format is the same as
the input format, except that pspp increases the field width, if
necessary, to the minimum allowed for output.
</para>
<para>Time or dates narrower than the field width are right-justified within
the field.
</para>
<para>When a time or date exceeds the field width, characters are trimmed from
the end until it fits.  This can occur in an unusual situation, e.g.
with a year greater than 9999 (which adds an extra digit), or for a
negative value on TIME or DTIME (which adds a leading minus sign).
</para>
<!-- What about out-of-range values? -->

<para>The system-missing value is output as a period at the right end of the
field.  
</para>
</sect3>
<sect3 label="6.7.4.6" id="Date-Component-Formats">
<title>Date Component Formats</title>

<para>The WKDAY and MONTH formats provide input and output for the names of
weekdays and months, respectively.
</para>
<para>On output, these formats convert a number between 1 and 7, for WKDAY, or
between 1 and 12, for MONTH, into the English name of a day or month,
respectively.  If the name is longer than the field, it is trimmed to
fit.  If the name is shorter than the field, it is padded on the right
with spaces.  Values outside the valid range, and the system-missing
value, are output as all spaces.
</para>
<para>On input, English weekday or month names (in uppercase or lowercase) are
converted back to their corresponding numbers.  Weekday and month names
may be abbreviated to their first 2 or 3 letters, respectively.
</para>
<para>The field width may range from 2 to 40, for WKDAY, or from 3 to 40, for
MONTH.  No decimal places are allowed.
</para>
<para>The default output format is the same as the input format.
</para>
</sect3>
<sect3 label="6.7.4.7" id="String-Formats">
<title>String Formats</title>

<indexterm role="cp"><primary>string formats</primary></indexterm>
<para>The A and AHEX formats are the only ones that may be assigned to string
variables.  Neither format allows any decimal places.
</para>
<para>In A format, the entire field is treated as a string value.  The field
width may range from 1 to 32,767, the maximum string width.  The default
output format is the same as the input format.
</para>
<para>In AHEX format, the field is composed of characters in a string encoded
as hex digit pairs.  On output, hex digits are output in uppercase; on
input, uppercase and lowercase are both accepted.  The default output
format is A format with half the input width.
</para>
</sect3>
</sect2>
<sect2 label="6.7.5" id="Scratch-Variables">
<title>Scratch Variables</title>

<indexterm role="cp"><primary>scratch variables</primary></indexterm>
<para>Most of the time, variables don&#8217;t retain their values between cases.
Instead, either they&#8217;re being read from a data file or the active dataset,
in which case they assume the value read, or, if created with
<literal>COMPUTE</literal> or
another transformation, they&#8217;re initialized to the system-missing value
or to blanks, depending on type.
</para>
<para>However, sometimes it&#8217;s useful to have a variable that keeps its value
between cases.  You can do this with <literal>LEAVE</literal> (see <link linkend="LEAVE">LEAVE</link>), or you can
use a <firstterm>scratch variable</firstterm>.  Scratch variables are variables whose
names begin with an octothorpe (&#8216;<literal>#</literal>&#8217;).  
</para>
<para>Scratch variables have the same properties as variables left with
<literal>LEAVE</literal>: 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&#8217;t be used for analysis.  To use
a scratch variable in an analysis, use <literal>COMPUTE</literal> (see <link linkend="COMPUTE">COMPUTE</link>)
to copy its value into an ordinary variable, then use that ordinary
variable in the analysis.
</para>
</sect2>
</sect1>
<sect1 label="6.8" id="Files">
<title>Files Used by pspp</title>

<para>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:
</para>
<variablelist><indexterm role="cp"><primary>file, command</primary></indexterm>
<indexterm role="cp"><primary>file, syntax file</primary></indexterm>
<indexterm role="cp"><primary>command file</primary></indexterm>
<indexterm role="cp"><primary>syntax file</primary></indexterm>
<varlistentry><term><emphasis role="bold">command file</emphasis>
</term><term><emphasis role="bold">syntax file</emphasis>
</term><listitem><para>These names (synonyms) refer to the file that contains instructions
that tell pspp what to do.  The syntax file&#8217;s name is specified on
the pspp command line.  Syntax files can also be read with
<literal>INCLUDE</literal> (see <link linkend="INCLUDE">INCLUDE</link>).
</para>
<indexterm role="cp"><primary>file, data</primary></indexterm>
<indexterm role="cp"><primary>data file</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">data file</emphasis>
</term><listitem><para>Data files contain raw data in text or binary format.  Data can also
be embedded in a syntax file with <literal>BEGIN DATA</literal> and <literal>END DATA</literal>.
</para>
<indexterm role="cp"><primary>file, output</primary></indexterm>
<indexterm role="cp"><primary>output file</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">listing file</emphasis>
</term><listitem><para>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.
</para>
<indexterm role="cp"><primary>system file</primary></indexterm>
<indexterm role="cp"><primary>file, system</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">system file</emphasis>
</term><listitem><para>System files are binary files that store a dictionary and a set of
cases.  <literal>GET</literal> and <literal>SAVE</literal> read and write system files.
</para>
<indexterm role="cp"><primary>portable file</primary></indexterm>
<indexterm role="cp"><primary>file, portable</primary></indexterm>
</listitem></varlistentry><varlistentry><term><emphasis role="bold">portable file</emphasis>
</term><listitem><para>Portable files are files in a text-based format that store a dictionary
and a set of cases.  <literal>IMPORT</literal> and <literal>EXPORT</literal> read and write
portable files.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="6.9" id="File-Handles">
<title>File Handles</title>
<indexterm role="cp"><primary>file handles</primary></indexterm>

<para>A <firstterm>file handle</firstterm> is a reference to a data file, system file, or 
portable file.  Most often, a file handle is specified as the
name of a file as a string, that is, enclosed within &#8216;<literal>'</literal>&#8217; or
&#8216;<literal>&quot;</literal>&#8217;.
</para>
<para>A file name string that begins or ends with &#8216;<literal>|</literal>&#8217; is treated as the
name of a command to pipe data to or from.  You can use this feature
to read data over the network using a program such as &#8216;<literal>curl</literal>&#8217;
(e.g. <literal>GET '|curl -s -S http://example.com/mydata.sav'</literal>), to
read compressed data from a file using a program such as &#8216;<literal>zcat</literal>&#8217;
(e.g. <literal>GET '|zcat mydata.sav.gz'</literal>), and for many other
purposes.
</para>
<para>pspp also supports declaring named file handles with the <literal>FILE
HANDLE</literal> command.  This command associates an identifier of your choice
(the file handle&#8217;s name) with a file.  Later, the file handle name can
be substituted for the name of the file.  When pspp syntax accesses a
file multiple times, declaring a named file handle simplifies updating
the syntax later to use a different file.  Use of <literal>FILE HANDLE</literal> is
also required to read data files in binary formats.  See <link linkend="FILE-HANDLE">FILE HANDLE</link>,
for more information.
</para>
<para>In some circumstances, pspp must distinguish whether a file handle
refers to a system file or a portable file.  When this is necessary to
read a file, e.g. as an input file for <literal>GET</literal> or <literal>MATCH FILES</literal>,
pspp uses the file&#8217;s contents to decide.  In the context of writing a
file, e.g. as an output file for <literal>SAVE</literal> or <literal>AGGREGATE</literal>, pspp
decides based on the file&#8217;s name: if it ends in &#8216;<literal>.por</literal>&#8217; (with any
capitalization), then pspp writes a portable file; otherwise, pspp
writes a system file.
</para>
<para>INLINE is reserved as a file handle name.  It refers to the &#8220;data
file&#8221; embedded into the syntax file between <literal>BEGIN DATA</literal> and
<literal>END DATA</literal>.  See <link linkend="BEGIN-DATA">BEGIN DATA</link>, for more information.
</para>
<para>The file to which a file handle refers may be reassigned on a later
<literal>FILE HANDLE</literal> command if it is first closed using <literal>CLOSE FILE
HANDLE</literal>.  See <link linkend="CLOSE-FILE-HANDLE">CLOSE FILE HANDLE</link>, for
more information.
</para>
</sect1>
<sect1 label="6.10" id="BNF">
<title>Backus-Naur Form</title>
<indexterm role="cp"><primary>BNF</primary></indexterm>
<indexterm role="cp"><primary>Backus-Naur Form</primary></indexterm>
<indexterm role="cp"><primary>command syntax, description of</primary></indexterm>
<indexterm role="cp"><primary>description of command syntax</primary></indexterm>

<para>The syntax of some parts of the pspp language is presented in this
manual using the formalism known as <firstterm>Backus-Naur Form</firstterm>, or BNF. The
following table describes BNF:
</para>
<itemizedlist><listitem><indexterm role="cp"><primary>keywords</primary></indexterm>
<indexterm role="cp"><primary>terminals</primary></indexterm>
<para>Words in all-uppercase are pspp keyword tokens.  In BNF, these are
often called <firstterm>terminals</firstterm>.  There are some special terminals, which
are written in lowercase for clarity:
</para>
<variablelist><indexterm role="cp"><primary><literal>number</literal></primary></indexterm>
<varlistentry><term><literal>number</literal>
</term><listitem><para>A real number.
</para>
<indexterm role="cp"><primary><literal>integer</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>integer</literal>
</term><listitem><para>An integer number.
</para>
<indexterm role="cp"><primary><literal>string</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>string</literal>
</term><listitem><para>A string.
</para>
<indexterm role="cp"><primary><literal>var-name</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>var-name</literal>
</term><listitem><para>A single variable name.
</para>
<indexterm role="cp"><primary>operators</primary></indexterm>
<indexterm role="cp"><primary>punctuators</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>=</literal>, <literal>/</literal>, <literal>+</literal>, <literal>-</literal>, etc.
</term><listitem><para>Operators and punctuators.
</para>
<indexterm role="cp"><primary><literal>.</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>.</literal>
</term><listitem><para>The end of the command.  This is not necessarily an actual dot in the
syntax file: See <link linkend="Commands">Commands</link>, for more details.
</para></listitem></varlistentry></variablelist>
</listitem><listitem><indexterm role="cp"><primary>productions</primary></indexterm>
<indexterm role="cp"><primary>nonterminals</primary></indexterm>
<para>Other words in all lowercase refer to BNF definitions, called
<firstterm>productions</firstterm>.  These productions are also known as
<firstterm>nonterminals</firstterm>.  Some nonterminals are very common, so they are
defined here in English for clarity:
</para>
<variablelist><indexterm role="cp"><primary><literal>var-list</literal></primary></indexterm>
<varlistentry><term><literal>var-list</literal>
</term><listitem><para>A list of one or more variable names or the keyword <literal>ALL</literal>.
</para>
<indexterm role="cp"><primary><literal>expression</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>expression</literal>
</term><listitem><para>An expression.  See <link linkend="Expressions">Expressions</link>, for details.
</para></listitem></varlistentry></variablelist>
</listitem><listitem><indexterm role="cp"><primary>&#8220;is defined as&#8221;</primary></indexterm>
<indexterm role="cp"><primary>productions</primary></indexterm>
<para>&#8216;<literal>::=</literal>&#8217; means &#8220;is defined as&#8221;.  The left side of &#8216;<literal>::=</literal>&#8217; gives
the name of the nonterminal being defined.  The right side of &#8216;<literal>::=</literal>&#8217;
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 <firstterm>production</firstterm>.
</para>
</listitem><listitem><indexterm role="cp"><primary>terminals and nonterminals, differences</primary></indexterm>
<para>So, the key difference between a terminal and a nonterminal is that a
terminal cannot be broken into smaller parts&#8212;in fact, every terminal
is a single token (see <link linkend="Tokens">Tokens</link>).  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.)
</para>
</listitem><listitem><indexterm role="cp"><primary>start symbol</primary></indexterm>
<indexterm role="cp"><primary>symbol, start</primary></indexterm>
<para>The first nonterminal defined in a set of productions is called the
<firstterm>start symbol</firstterm>.  The start symbol defines the entire syntax for
that command.
</para></listitem></itemizedlist><!-- Use @func when refering to a function. -->
<!-- Use @deftypefn for their definitions  -->

</sect1>
</chapter>
<chapter label="7" id="Expressions">
<title>Mathematical Expressions</title>
<indexterm role="cp"><primary>expressions, mathematical</primary></indexterm>
<indexterm role="cp"><primary>mathematical expressions</primary></indexterm>

<para>Expressions share a common syntax each place they appear in pspp
commands.  Expressions are made up of <firstterm>operands</firstterm>, which can be
numbers, strings, or variable names, separated by <firstterm>operators</firstterm>.
There are five types of operators: grouping, arithmetic, logical,
relational, and functions.
</para>
<para>Every operator takes one or more operands as input and yields exactly
one result as output.  Depending on the operator, operands accept
strings or numbers as operands.  With few exceptions, operands may be
full-fledged expressions in themselves.
</para>

<sect1 label="7.1" id="Boolean-Values">
<title>Boolean Values</title>
<indexterm role="cp"><primary>Boolean</primary></indexterm>
<indexterm role="cp"><primary>values, Boolean</primary></indexterm>

<para>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.
</para>
<para>Boolean-typed operands or function arguments must take on one of these
three values.  Other values are considered false, but provoke a warning
when the expression is evaluated.
</para>
<para>Strings and Booleans are not compatible, and neither may be used in
place of the other.
</para>
</sect1>
<sect1 label="7.2" id="Missing-Values-in-Expressions">
<title>Missing Values in Expressions</title>

<para>Most numeric operators yield system-missing when given any
system-missing operand.  A string operator given any system-missing
operand typically results in the empty string.  Exceptions are listed
under particular operator descriptions.
</para>
<para>String user-missing values are not treated specially in expressions.
</para>
<para>User-missing values for numeric variables are always transformed into
the system-missing value, except inside the arguments to the
<literal>VALUE</literal> and <literal>SYSMIS</literal> functions.
</para>
<para>The missing-value functions can be used to precisely control how missing
values are treated in expressions.  See <link linkend="Missing-Value-Functions">Missing Value Functions</link>, for
more details.
</para>
</sect1>
<sect1 label="7.3" id="Grouping-Operators">
<title>Grouping Operators</title>
<indexterm role="cp"><primary>parentheses</primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>(  )</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>grouping operators</primary></indexterm>
<indexterm role="cp"><primary>operators, grouping</primary></indexterm>

<para>Parentheses (&#8216;<literal>()</literal>&#8217;) are the grouping operators.  Surround an
expression with parentheses to force early evaluation.
</para>
<para>Parentheses also surround the arguments to functions, but in that
situation they act as punctuators, not as operators.
</para>
</sect1>
<sect1 label="7.4" id="Arithmetic-Operators">
<title>Arithmetic Operators</title>
<indexterm role="cp"><primary>operators, arithmetic</primary></indexterm>
<indexterm role="cp"><primary>arithmetic operators</primary></indexterm>

<para>The arithmetic operators take numeric operands and produce numeric
results.
</para>
<variablelist><indexterm role="cp"><primary>&#8216;<literal>+</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>addition</primary></indexterm>
<varlistentry><term><literal><replaceable>a</replaceable> + <replaceable>b</replaceable></literal>
</term><listitem><para>Yields the sum of <replaceable>a</replaceable> and <replaceable>b</replaceable>.
</para>
<indexterm role="cp"><primary>&#8216;<literal>-</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>subtraction</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal><replaceable>a</replaceable> - <replaceable>b</replaceable></literal>
</term><listitem><para>Subtracts <replaceable>b</replaceable> from <replaceable>a</replaceable> and yields the difference.
</para>
<indexterm role="cp"><primary>&#8216;<literal>*</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>multiplication</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal><replaceable>a</replaceable> * <replaceable>b</replaceable></literal>
</term><listitem><para>Yields the product of <replaceable>a</replaceable> and <replaceable>b</replaceable>.  If either <replaceable>a</replaceable> or
<replaceable>b</replaceable> is 0, then the result is 0, even if the other operand is
missing.
</para>
<indexterm role="cp"><primary>&#8216;<literal>/</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>division</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal><replaceable>a</replaceable> / <replaceable>b</replaceable></literal>
</term><listitem><para>Divides <replaceable>a</replaceable> by <replaceable>b</replaceable> and yields the quotient.  If <replaceable>a</replaceable> is 0,
then the result is 0, even if <replaceable>b</replaceable> is missing.  If <replaceable>b</replaceable> is zero,
the result is system-missing.
</para>
<indexterm role="cp"><primary>&#8216;<literal>**</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>exponentiation</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal><replaceable>a</replaceable> ** <replaceable>b</replaceable></literal>
</term><listitem><para>Yields the result of raising <replaceable>a</replaceable> to the power <replaceable>b</replaceable>.  If
<replaceable>a</replaceable> is negative and <replaceable>b</replaceable> is not an integer, the result is
system-missing.  The result of <literal>0**0</literal> is system-missing as well.
</para>
<indexterm role="cp"><primary>&#8216;<literal>-</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>negation</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>- <replaceable>a</replaceable></literal>
</term><listitem><para>Reverses the sign of <replaceable>a</replaceable>.  
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="7.5" id="Logical-Operators">
<title>Logical Operators</title>
<indexterm role="cp"><primary>logical operators</primary></indexterm>
<indexterm role="cp"><primary>operators, logical</primary></indexterm>

<indexterm role="cp"><primary>true</primary></indexterm>
<indexterm role="cp"><primary>false</primary></indexterm>
<indexterm role="cp"><primary>Boolean</primary></indexterm>
<indexterm role="cp"><primary>values, system-missing</primary></indexterm>
<indexterm role="cp"><primary>system-missing</primary></indexterm>
<para>The logical operators take logical operands and produce logical
results, meaning &#8220;true or false.&#8221;  Logical operators are
not true Boolean operators because they may also result in a
system-missing value.  See <link linkend="Boolean-Values">Boolean Values</link>, for more information.
</para>
<variablelist><indexterm role="cp"><primary><literal>AND</literal></primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>&amp;</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>intersection, logical</primary></indexterm>
<indexterm role="cp"><primary>logical intersection</primary></indexterm>
<varlistentry><term><literal><replaceable>a</replaceable> AND <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &amp; <replaceable>b</replaceable></literal>
</term><listitem><para>True if both <replaceable>a</replaceable> and <replaceable>b</replaceable> are true, false otherwise.  If one
operand is false, the result is false even if the other is missing.  If
both operands are missing, the result is missing.
</para>
<indexterm role="cp"><primary><literal>OR</literal></primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>|</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>union, logical</primary></indexterm>
<indexterm role="cp"><primary>logical union</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal><replaceable>a</replaceable> OR <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> | <replaceable>b</replaceable></literal>
</term><listitem><para>True if at least one of <replaceable>a</replaceable> and <replaceable>b</replaceable> is true.  If one operand is
true, the result is true even if the other operand is missing.  If both
operands are missing, the result is missing.
</para>
<indexterm role="cp"><primary><literal>NOT</literal></primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>~</literal>&#8217;</primary></indexterm>
<indexterm role="cp"><primary>inversion, logical</primary></indexterm>
<indexterm role="cp"><primary>logical inversion</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>NOT <replaceable>a</replaceable></literal>
</term><term><literal>~ <replaceable>a</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is false.  If the operand is missing, then the result
is missing.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="7.6" id="Relational-Operators">
<title>Relational Operators</title>

<para>The relational operators take numeric or string operands and produce Boolean
results.
</para>
<para>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.
</para>
<para>The results of string comparisons, other than tests for equality or
inequality, depend on the character set in use.  String comparisons
are case-sensitive.
</para>
<variablelist><indexterm role="cp"><primary>equality, testing</primary></indexterm>
<indexterm role="cp"><primary>testing for equality</primary></indexterm>
<indexterm role="cp"><primary><literal>EQ</literal></primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>=</literal>&#8217;</primary></indexterm>
<varlistentry><term><literal><replaceable>a</replaceable> EQ <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> = <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is equal to <replaceable>b</replaceable>.
</para>
<indexterm role="cp"><primary>less than or equal to</primary></indexterm>
<indexterm role="cp"><primary><literal>LE</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>&lt;=</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal><replaceable>a</replaceable> LE <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &lt;= <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is less than or equal to <replaceable>b</replaceable>.
</para>
<indexterm role="cp"><primary>less than</primary></indexterm>
<indexterm role="cp"><primary><literal>LT</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>&lt;</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal><replaceable>a</replaceable> LT <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &lt; <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is less than <replaceable>b</replaceable>.
</para>
<indexterm role="cp"><primary>greater than or equal to</primary></indexterm>
<indexterm role="cp"><primary><literal>GE</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>&gt;=</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal><replaceable>a</replaceable> GE <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &gt;= <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is greater than or equal to <replaceable>b</replaceable>.
</para>
<indexterm role="cp"><primary>greater than</primary></indexterm>
<indexterm role="cp"><primary><literal>GT</literal></primary></indexterm>
<indexterm role="cp"><primary>&#8216;<literal>&gt;</literal>&#8217;</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal><replaceable>a</replaceable> GT <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &gt; <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is greater than <replaceable>b</replaceable>.
</para>
<indexterm role="cp"><primary>inequality, testing</primary></indexterm>
<indexterm role="cp"><primary>testing for inequality</primary></indexterm>
<indexterm role="cp"><primary><literal>NE</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>~=</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>&lt;&gt;</literal></primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal><replaceable>a</replaceable> NE <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> ~= <replaceable>b</replaceable></literal>
</term><term><literal><replaceable>a</replaceable> &lt;&gt; <replaceable>b</replaceable></literal>
</term><listitem><para>True if <replaceable>a</replaceable> is not equal to <replaceable>b</replaceable>.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="7.7" id="Functions">
<title>Functions</title>
<indexterm role="cp"><primary>functions</primary></indexterm>

<indexterm role="cp"><primary>mathematics</primary></indexterm>
<indexterm role="cp"><primary>operators</primary></indexterm>
<indexterm role="cp"><primary>parentheses</primary></indexterm>
<indexterm role="cp"><primary><literal>(</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>)</literal></primary></indexterm>
<indexterm role="cp"><primary>names, of functions</primary></indexterm>
<para>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.
</para>
<para>Function names are not reserved.  Their names are specially treated
only when followed by a left parenthesis, so that &#8216;<literal>EXP(10)</literal>&#8217;
refers to the constant value <inlineequation><mathphrase>e</mathphrase></inlineequation> raised to the 10th power, but
&#8216;<literal>EXP</literal>&#8217; by itself refers to the value of a variable called <literal>EXP</literal>.
</para>
<para>The sections below describe each function in detail.
</para>

<sect2 label="7.7.1" id="Mathematics">
<title>Mathematical Functions</title>
<indexterm role="cp"><primary>mathematics, advanced</primary></indexterm>

<para>Advanced mathematical functions take numeric arguments and produce
numeric results.
</para>
<synopsis><indexterm role="fn"><primary>EXP</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>EXP</function> (<replaceable><replaceable>exponent</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns <inlineequation><mathphrase>e</mathphrase></inlineequation> (approximately 2.71828) raised to power <replaceable>exponent</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>logarithms</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LG10</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LG10</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<blockquote><para>Takes the base-10 logarithm of <replaceable>number</replaceable>.  If <replaceable>number</replaceable> is
not positive, the result is system-missing.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>LN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LN</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<blockquote><para>Takes the base-<inlineequation><mathphrase>e</mathphrase></inlineequation> logarithm of <replaceable>number</replaceable>.  If <replaceable>number</replaceable> is
not positive, the result is system-missing.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>LNGAMMA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LNGAMMA</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<blockquote><para>Yields the base-<inlineequation><mathphrase>e</mathphrase></inlineequation> logarithm of the complete gamma of <replaceable>number</replaceable>.
If <replaceable>number</replaceable> is a negative integer, the result is system-missing.
</para></blockquote>
<indexterm role="cp"><primary>square roots</primary></indexterm>
<synopsis><indexterm role="fn"><primary>SQRT</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SQRT</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<blockquote><para>Takes the square root of <replaceable>number</replaceable>.  If <replaceable>number</replaceable> is negative,
the result is system-missing.
</para></blockquote>
</sect2>
<sect2 label="7.7.2" id="Miscellaneous-Mathematics">
<title>Miscellaneous Mathematical Functions</title>
<indexterm role="cp"><primary>mathematics, miscellaneous</primary></indexterm>

<para>Miscellaneous mathematical functions take numeric arguments and produce
numeric results.
</para>
<indexterm role="cp"><primary>absolute value</primary></indexterm>
<synopsis><indexterm role="fn"><primary>ABS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ABS</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the absolute value of <replaceable>number</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>modulus</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MOD</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MOD</function> (<replaceable><replaceable>numerator</replaceable></replaceable>, <replaceable><replaceable>denominator</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns the remainder (modulus) of <replaceable>numerator</replaceable> divided by
<replaceable>denominator</replaceable>.  If <replaceable>numerator</replaceable> is 0, then the result is 0,
even if <replaceable>denominator</replaceable> is missing.  If <replaceable>denominator</replaceable> is 0, the
result is system-missing.
</para></blockquote>
<indexterm role="cp"><primary>modulus, by 10</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MOD10</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MOD10</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns the remainder when <replaceable>number</replaceable> is divided by 10.  If
<replaceable>number</replaceable> is negative, MOD10(<replaceable>number</replaceable>) is negative or zero.
</para></blockquote>
<indexterm role="cp"><primary>rounding</primary></indexterm>
<synopsis><indexterm role="fn"><primary>RND</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RND</function> (<replaceable><replaceable>number</replaceable></replaceable> [, <replaceable><replaceable>mult</replaceable></replaceable>[, <replaceable><replaceable>fuzzbits</replaceable></replaceable>]])</synopsis>
<blockquote><para>Rounds <replaceable>number</replaceable> and rounds it to a multiple of <replaceable>mult</replaceable> (by
default 1).  Halves are rounded away from zero, as are values that
fall short of halves by less than <replaceable>fuzzbits</replaceable> of errors in the
least-significant bits of <replaceable>number</replaceable>.  If <replaceable>fuzzbits</replaceable> is not
specified then the default is taken from SET FUZZBITS (see <link linkend="SET-FUZZBITS">SET
FUZZBITS</link>), which is 6 unless overridden.
</para></blockquote>
<indexterm role="cp"><primary>truncation</primary></indexterm>
<synopsis><indexterm role="fn"><primary>TRUNC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>TRUNC</function> (<replaceable><replaceable>number</replaceable></replaceable> [, <replaceable><replaceable>mult</replaceable></replaceable>[, <replaceable><replaceable>fuzzbits</replaceable></replaceable>]])</synopsis>
<blockquote><para>Rounds <replaceable>number</replaceable> to a multiple of <replaceable>mult</replaceable>, toward zero.  For the
default <replaceable>mult</replaceable> of 1, this is equivalent to discarding the
fractional part of <replaceable>number</replaceable>.  Values that fall short of a multiple
of <replaceable>mult</replaceable> by less than <replaceable>fuzzbits</replaceable> of errors in the
least-significant bits of <replaceable>number</replaceable> are rounded away from zero.  If
<replaceable>fuzzbits</replaceable> is not specified then the default is taken from SET
FUZZBITS (see <link linkend="SET-FUZZBITS">SET FUZZBITS</link>), which is 6 unless overridden.
</para></blockquote>
</sect2>
<sect2 label="7.7.3" id="Trigonometry">
<title>Trigonometric Functions</title>
<indexterm role="cp"><primary>trigonometry</primary></indexterm>

<para>Trigonometric functions take numeric arguments and produce numeric
results.
</para>
<indexterm role="cp"><primary>arccosine</primary></indexterm>
<indexterm role="cp"><primary>inverse cosine</primary></indexterm>
<synopsis><indexterm role="fn"><primary>ARCOS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ARCOS</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>ACOS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ACOS</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<blockquote><para>Takes the arccosine, in radians, of <replaceable>number</replaceable>.  Results in
system-missing if <replaceable>number</replaceable> is not between -1 and 1 inclusive.
This function is a pspp extension.
</para></blockquote>
<indexterm role="cp"><primary>arcsine</primary></indexterm>
<indexterm role="cp"><primary>inverse sine</primary></indexterm>
<synopsis><indexterm role="fn"><primary>ARSIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ARSIN</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>ASIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ASIN</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<blockquote><para>Takes the arcsine, in radians, of <replaceable>number</replaceable>.  Results in
system-missing if <replaceable>number</replaceable> is not between -1 and 1 inclusive.
</para></blockquote>
<indexterm role="cp"><primary>arctangent</primary></indexterm>
<indexterm role="cp"><primary>inverse tangent</primary></indexterm>
<synopsis><indexterm role="fn"><primary>ARTAN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ARTAN</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>ATAN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ATAN</function> (<replaceable><replaceable>number</replaceable></replaceable>)</synopsis>
<blockquote><para>Takes the arctangent, in radians, of <replaceable>number</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>cosine</primary></indexterm>
<synopsis><indexterm role="fn"><primary>COS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>COS</function> (<replaceable><replaceable>angle</replaceable></replaceable>)</synopsis>
<blockquote><para>Takes the cosine of <replaceable>angle</replaceable> which should be in radians.
</para></blockquote>
<indexterm role="cp"><primary>sine</primary></indexterm>
<synopsis><indexterm role="fn"><primary>SIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SIN</function> (<replaceable><replaceable>angle</replaceable></replaceable>)</synopsis>
<blockquote><para>Takes the sine of <replaceable>angle</replaceable> which should be in radians.
</para></blockquote>
<indexterm role="cp"><primary>tangent</primary></indexterm>
<synopsis><indexterm role="fn"><primary>TAN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>TAN</function> (<replaceable><replaceable>angle</replaceable></replaceable>)</synopsis>
<blockquote><para>Takes the tangent of <replaceable>angle</replaceable> which should be in radians.
Results in system-missing at values
of <replaceable>angle</replaceable> that are too close to odd multiples of <inlineequation><mathphrase>\pi/2</mathphrase></inlineequation>.
Portability: none.
</para></blockquote>
</sect2>
<sect2 label="7.7.4" id="Missing-Value-Functions">
<title>Missing-Value Functions</title>
<indexterm role="cp"><primary>missing values</primary></indexterm>
<indexterm role="cp"><primary>values, missing</primary></indexterm>
<indexterm role="cp"><primary>functions, missing-value</primary></indexterm>

<para>Missing-value functions take various numeric arguments and yield
various types of results.  Except where otherwise stated below, 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.
</para>
<synopsis><indexterm role="fn"><primary>MISSING</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MISSING</function> (<replaceable><replaceable>expr</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns 1 if <replaceable>expr</replaceable> has the system-missing value, 0 otherwise.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>NMISS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NMISS</function> (<replaceable><replaceable>expr</replaceable></replaceable> [, <replaceable><replaceable>expr</replaceable></replaceable>]<replaceable>&#8230;</replaceable>)</synopsis>
<blockquote><para>Each argument must be a numeric expression.  Returns the number of
system-missing values in the list, which may include variable ranges
using the <literal><replaceable>var1</replaceable> TO <replaceable>var2</replaceable></literal> syntax.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>NVALID</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NVALID</function> (<replaceable><replaceable>expr</replaceable></replaceable> [, <replaceable><replaceable>expr</replaceable></replaceable>]<replaceable>&#8230;</replaceable>)</synopsis>
<blockquote><para>Each argument must be a numeric expression.  Returns the number of
values in the list that are not system-missing.  The list may include
variable ranges using the <literal><replaceable>var1</replaceable> TO <replaceable>var2</replaceable></literal> syntax.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>SYSMIS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SYSMIS</function> (<replaceable><replaceable>expr</replaceable></replaceable>)</synopsis>
<blockquote><para>When <replaceable>expr</replaceable> 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 <replaceable>expr</replaceable> takes another form, results in 1 if
the value is system-missing, 0 otherwise.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>VALUE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>VALUE</function> (<replaceable><replaceable>variable</replaceable></replaceable>)</synopsis>
<blockquote><para>Prevents the user-missing values of <replaceable>variable</replaceable> from being
transformed into system-missing values, and always results in the
actual value of <replaceable>variable</replaceable>, whether it is valid, user-missing, or
system-missing.
</para></blockquote>
</sect2>
<sect2 label="7.7.5" id="Set-Membership">
<title>Set-Membership Functions</title>
<indexterm role="cp"><primary>set membership</primary></indexterm>
<indexterm role="cp"><primary>membership, of set</primary></indexterm>

<para>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.
</para>
<para>String comparisons are performed according to the rules given in
<link linkend="Relational-Operators">Relational Operators</link>.
</para>
<synopsis><indexterm role="fn"><primary>ANY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>ANY</function> (<replaceable><replaceable>value</replaceable></replaceable>, <replaceable><replaceable>set</replaceable></replaceable> [, <replaceable><replaceable>set</replaceable></replaceable>]<replaceable>&#8230;</replaceable>)</synopsis>
<blockquote><para>Results in true if <replaceable>value</replaceable> is equal to any of the <replaceable>set</replaceable>
values.  Otherwise, results in false.  If <replaceable>value</replaceable> is
system-missing, returns system-missing.  System-missing values in
<replaceable>set</replaceable> do not cause <literal>/NAME/</literal> to return system-missing.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RANGE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RANGE</function> (<replaceable><replaceable>value</replaceable></replaceable>, <replaceable><replaceable>low</replaceable></replaceable>, <replaceable><replaceable>high</replaceable></replaceable> [, <replaceable><replaceable>low</replaceable></replaceable>, <replaceable><replaceable>high</replaceable></replaceable>]<replaceable>&#8230;</replaceable>)</synopsis>
<blockquote><para>Results in true if <replaceable>value</replaceable> is in any of the intervals bounded by
<replaceable>low</replaceable> and <replaceable>high</replaceable> inclusive.  Otherwise, results in false.
Each <replaceable>low</replaceable> must be less than or equal to its corresponding
<replaceable>high</replaceable> value.  <replaceable>low</replaceable> and <replaceable>high</replaceable> must be given in pairs.
If <replaceable>value</replaceable> is system-missing, returns system-missing.
System-missing values in <replaceable>set</replaceable> do not cause <literal>/NAME/</literal> to return
system-missing.
</para></blockquote>
</sect2>
<sect2 label="7.7.6" id="Statistical-Functions">
<title>Statistical Functions</title>
<indexterm role="cp"><primary>functions, statistical</primary></indexterm>
<indexterm role="cp"><primary>statistics</primary></indexterm>

<para>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&#8217;s weighting factor
(see <link linkend="WEIGHT">WEIGHT</link>) has no effect on statistical functions.
</para>
<para>These functions&#8217; argument lists may include entire ranges of variables
using the <literal><replaceable>var1</replaceable> TO <replaceable>var2</replaceable></literal> syntax.
</para>
<indexterm role="cp"><primary>arguments, minimum valid</primary></indexterm>
<indexterm role="cp"><primary>minimum valid number of arguments</primary></indexterm>
<para>Unlike most functions, statistical functions can return non-missing
values even when some of their arguments are missing.  Most
statistical functions, by default, require only 1 non-missing value to
have a non-missing return, but <literal>/NAME/</literal>, <literal>/NAME/</literal>, and <literal>/NAME/</literal> require 2.
These defaults can be increased (but not decreased) by appending a dot
and the minimum number of valid arguments to the function name.  For
example, <literal>MEAN.3(X, Y, Z)</literal> would only return non-missing if all
of &#8216;<literal>X</literal>&#8217;, &#8216;<literal>Y</literal>&#8217;, and &#8216;<literal>Z</literal>&#8217; were valid.
</para>
<indexterm role="cp"><primary>coefficient of variation</primary></indexterm>
<indexterm role="cp"><primary>variation, coefficient of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CFVAR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CFVAR</function> (<replaceable><replaceable>number</replaceable></replaceable>, <replaceable><replaceable>number</replaceable></replaceable>[, <replaceable>&#8230;</replaceable>])</synopsis>
<blockquote><para>Results in the coefficient of variation of the values of <replaceable>number</replaceable>.
(The coefficient of variation is the standard deviation divided by the
mean.)
</para></blockquote>
<indexterm role="cp"><primary>maximum</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MAX</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MAX</function> (<replaceable><replaceable>value</replaceable></replaceable>, <replaceable><replaceable>value</replaceable></replaceable>[, <replaceable>&#8230;</replaceable>])</synopsis>
<blockquote><para>Results in the value of the greatest <replaceable>value</replaceable>.  The <replaceable>value</replaceable>s may
be numeric or string.
</para></blockquote>
<indexterm role="cp"><primary>mean</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MEAN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MEAN</function> (<replaceable><replaceable>number</replaceable></replaceable>, <replaceable><replaceable>number</replaceable></replaceable>[, <replaceable>&#8230;</replaceable>])</synopsis>
<blockquote><para>Results in the mean of the values of <replaceable>number</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>median</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MEDIAN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MEDIAN</function> (<replaceable><replaceable>number</replaceable></replaceable>, <replaceable><replaceable>number</replaceable></replaceable>[, <replaceable>&#8230;</replaceable>])</synopsis>
<blockquote><para>Results in the median of the values of <replaceable>number</replaceable>.  Given an even
number of nonmissing arguments, yields the mean of the two middle
values.
</para></blockquote>
<indexterm role="cp"><primary>minimum</primary></indexterm>
<synopsis><indexterm role="fn"><primary>MIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>MIN</function> (<replaceable><replaceable>number</replaceable></replaceable>, <replaceable><replaceable>number</replaceable></replaceable>[, <replaceable>&#8230;</replaceable>])</synopsis>
<blockquote><para>Results in the value of the least <replaceable>value</replaceable>.  The <replaceable>value</replaceable>s may
be numeric or string.
</para></blockquote>
<indexterm role="cp"><primary>standard deviation</primary></indexterm>
<indexterm role="cp"><primary>deviation, standard</primary></indexterm>
<synopsis><indexterm role="fn"><primary>SD</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SD</function> (<replaceable><replaceable>number</replaceable></replaceable>, <replaceable><replaceable>number</replaceable></replaceable>[, <replaceable>&#8230;</replaceable>])</synopsis>
<blockquote><para>Results in the standard deviation of the values of <replaceable>number</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>sum</primary></indexterm>
<synopsis><indexterm role="fn"><primary>SUM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SUM</function> (<replaceable><replaceable>number</replaceable></replaceable>, <replaceable><replaceable>number</replaceable></replaceable>[, <replaceable>&#8230;</replaceable>])</synopsis>
<blockquote><para>Results in the sum of the values of <replaceable>number</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>variance</primary></indexterm>
<synopsis><indexterm role="fn"><primary>VARIANCE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>VARIANCE</function> (<replaceable><replaceable>number</replaceable></replaceable>, <replaceable><replaceable>number</replaceable></replaceable>[, <replaceable>&#8230;</replaceable>])</synopsis>
<blockquote><para>Results in the variance of the values of <replaceable>number</replaceable>.
</para></blockquote>
</sect2>
<sect2 label="7.7.7" id="String-Functions">
<title>String Functions</title>
<indexterm role="cp"><primary>functions, string</primary></indexterm>
<indexterm role="cp"><primary>string functions</primary></indexterm>

<para>String functions take various arguments and return various results.
</para>
<indexterm role="cp"><primary>concatenation</primary></indexterm>
<indexterm role="cp"><primary>strings, concatenation of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CONCAT</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CONCAT</function> (<replaceable><replaceable>string</replaceable></replaceable>, <replaceable><replaceable>string</replaceable></replaceable>[, <replaceable>&#8230;</replaceable>])</synopsis>
<blockquote><para>Returns a string consisting of each <replaceable>string</replaceable> in sequence.
<literal>CONCAT(&quot;abc&quot;, &quot;def&quot;, &quot;ghi&quot;)</literal> has a value of <literal>&quot;abcdefghi&quot;</literal>.
The resultant string is truncated to a maximum of 255 characters.
</para></blockquote>
<indexterm role="cp"><primary>searching strings</primary></indexterm>
<synopsis><indexterm role="fn"><primary>INDEX</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>INDEX</function> (<replaceable><replaceable>haystack</replaceable></replaceable>, <replaceable><replaceable>needle</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns a positive integer indicating the position of the first
occurrence of <replaceable>needle</replaceable> in <replaceable>haystack</replaceable>.  Returns 0 if <replaceable>haystack</replaceable>
does not contain <replaceable>needle</replaceable>.  Returns system-missing if <replaceable>needle</replaceable>
is an empty string.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>INDEX</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>INDEX</function> (<replaceable><replaceable>haystack</replaceable></replaceable>, <replaceable><replaceable>needles</replaceable></replaceable>, <replaceable><replaceable>needle_len</replaceable></replaceable>)</synopsis>
<blockquote><para>Divides <replaceable>needles</replaceable> into one or more needles, each with length
<replaceable>needle_len</replaceable>.
Searches <replaceable>haystack</replaceable> for the first occurrence of each needle, and
returns the smallest value.  Returns 0 if <replaceable>haystack</replaceable> does not
contain any part in <replaceable>needle</replaceable>.  It is an error if <replaceable>needle_len</replaceable>
does not evenly divide the length of <replaceable>needles</replaceable>.  Returns
system-missing if <replaceable>needles</replaceable> is an empty string.
</para></blockquote>
<indexterm role="cp"><primary>strings, finding length of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LENGTH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LENGTH</function> (<replaceable><replaceable>string</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns the number of characters in <replaceable>string</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>strings, case of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LOWER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LOWER</function> (<replaceable><replaceable>string</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns a string identical to <replaceable>string</replaceable> except that all uppercase
letters are changed to lowercase letters.  The definitions of
&#8220;uppercase&#8221; and &#8220;lowercase&#8221; are system-dependent.
</para></blockquote>
<indexterm role="cp"><primary>strings, padding</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LPAD</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LPAD</function> (<replaceable><replaceable>string</replaceable></replaceable>, <replaceable><replaceable>length</replaceable></replaceable>)</synopsis>
<blockquote><para>If <replaceable>string</replaceable> is at least <replaceable>length</replaceable> characters in length, returns
<replaceable>string</replaceable> unchanged.  Otherwise, returns <replaceable>string</replaceable> padded with
spaces on the left side to length <replaceable>length</replaceable>.  Returns an empty string
if <replaceable>length</replaceable> is system-missing, negative, or greater than 255.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>LPAD</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LPAD</function> (<replaceable><replaceable>string</replaceable></replaceable>, <replaceable><replaceable>length</replaceable></replaceable>, <replaceable><replaceable>padding</replaceable></replaceable>)</synopsis>
<blockquote><para>If <replaceable>string</replaceable> is at least <replaceable>length</replaceable> characters in length, returns
<replaceable>string</replaceable> unchanged.  Otherwise, returns <replaceable>string</replaceable> padded with
<replaceable>padding</replaceable> on the left side to length <replaceable>length</replaceable>.  Returns an empty
string if <replaceable>length</replaceable> is system-missing, negative, or greater than 255, or
if <replaceable>padding</replaceable> does not contain exactly one character.
</para></blockquote>
<indexterm role="cp"><primary>strings, trimming</primary></indexterm>
<indexterm role="cp"><primary>white space, trimming</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LTRIM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LTRIM</function> (<replaceable><replaceable>string</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns <replaceable>string</replaceable>, after removing leading spaces.  Other white space,
such as tabs, carriage returns, line feeds, and vertical tabs, is not
removed.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>LTRIM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LTRIM</function> (<replaceable><replaceable>string</replaceable></replaceable>, <replaceable><replaceable>padding</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns <replaceable>string</replaceable>, after removing leading <replaceable>padding</replaceable> characters.
If <replaceable>padding</replaceable> does not contain exactly one character, returns an
empty string.
</para></blockquote>
<indexterm role="cp"><primary>numbers, converting from strings</primary></indexterm>
<indexterm role="cp"><primary>strings, converting to numbers</primary></indexterm>
<synopsis><indexterm role="fn"><primary>NUMBER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NUMBER</function> (<replaceable><replaceable>string</replaceable></replaceable>, <replaceable><replaceable>format</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns the number produced when <replaceable>string</replaceable> is interpreted according
to format specifier <replaceable>format</replaceable>.  If the format width <replaceable>w</replaceable> is less
than the length of <replaceable>string</replaceable>, then only the first <replaceable>w</replaceable>
characters in <replaceable>string</replaceable> are used, e.g. <literal>NUMBER(&quot;123&quot;, F3.0)</literal>
and <literal>NUMBER(&quot;1234&quot;, F3.0)</literal> both have value 123.  If <replaceable>w</replaceable> is
greater than <replaceable>string</replaceable>&#8217;s length, then it is treated as if it were
right-padded with spaces.  If <replaceable>string</replaceable> is not in the correct
format for <replaceable>format</replaceable>, system-missing is returned.
</para></blockquote>
<indexterm role="cp"><primary>strings, replacing substrings</primary></indexterm>
<indexterm role="cp"><primary>replacing substrings</primary></indexterm>
<synopsis><indexterm role="fn"><primary>REPLACE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>REPLACE</function> (<replaceable><replaceable>haystack</replaceable></replaceable>, <replaceable><replaceable>needle</replaceable></replaceable>, <replaceable><replaceable>replacement</replaceable></replaceable>[, <replaceable><replaceable>n</replaceable></replaceable>])</synopsis>
<blockquote><para>Returns string <replaceable>haystack</replaceable> with instances of <replaceable>needle</replaceable> replaced
by <replaceable>replacement</replaceable>.  If nonnegative integer <replaceable>n</replaceable> is specified, it
limits the maximum number of replacements; otherwise, all instances of
<replaceable>needle</replaceable> are replaced.
</para></blockquote>
<indexterm role="cp"><primary>strings, searching backwards</primary></indexterm>
<synopsis><indexterm role="fn"><primary>RINDEX</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RINDEX</function> (<replaceable><replaceable>haystack</replaceable></replaceable>, <replaceable><replaceable>needle</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns a positive integer indicating the position of the last
occurrence of <replaceable>needle</replaceable> in <replaceable>haystack</replaceable>.  Returns 0 if
<replaceable>haystack</replaceable> does not contain <replaceable>needle</replaceable>.  Returns system-missing if
<replaceable>needle</replaceable> is an empty string.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RINDEX</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RINDEX</function> (<replaceable><replaceable>haystack</replaceable></replaceable>, <replaceable><replaceable>needle</replaceable></replaceable>, <replaceable><replaceable>needle_len</replaceable></replaceable>)</synopsis>
<blockquote><para>Divides <replaceable>needle</replaceable> into parts, each with length <replaceable>needle_len</replaceable>.
Searches <replaceable>haystack</replaceable> for the last occurrence of each part, and
returns the largest value.  Returns 0 if <replaceable>haystack</replaceable> does not contain
any part in <replaceable>needle</replaceable>.  It is an error if <replaceable>needle_len</replaceable> does not
evenly divide the length of <replaceable>needle</replaceable>.  Returns system-missing
if <replaceable>needle</replaceable> is an empty string or if needle_len is less than 1.
</para></blockquote>
<indexterm role="cp"><primary>padding strings</primary></indexterm>
<indexterm role="cp"><primary>strings, padding</primary></indexterm>
<synopsis><indexterm role="fn"><primary>RPAD</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RPAD</function> (<replaceable><replaceable>string</replaceable></replaceable>, <replaceable><replaceable>length</replaceable></replaceable>)</synopsis>
<blockquote><para>If <replaceable>string</replaceable> is at least <replaceable>length</replaceable> characters in length, returns
<replaceable>string</replaceable> unchanged.  Otherwise, returns <replaceable>string</replaceable> padded with
spaces on the right to length <replaceable>length</replaceable>.  Returns an empty string if
<replaceable>length</replaceable> is system-missing, negative, or greater than 255.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RPAD</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RPAD</function> (<replaceable><replaceable>string</replaceable></replaceable>, <replaceable><replaceable>length</replaceable></replaceable>, <replaceable><replaceable>padding</replaceable></replaceable>)</synopsis>
<blockquote><para>If <replaceable>string</replaceable> is at least <replaceable>length</replaceable> characters in length, returns
<replaceable>string</replaceable> unchanged.  Otherwise, returns <replaceable>string</replaceable> padded with
<replaceable>padding</replaceable> on the right to length <replaceable>length</replaceable>.  Returns an empty
string if <replaceable>length</replaceable> is system-missing, negative, or greater than 255,
or if <replaceable>padding</replaceable> does not contain exactly one character.
</para></blockquote>
<indexterm role="cp"><primary>strings, trimming</primary></indexterm>
<indexterm role="cp"><primary>white space, trimming</primary></indexterm>
<synopsis><indexterm role="fn"><primary>RTRIM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RTRIM</function> (<replaceable><replaceable>string</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns <replaceable>string</replaceable>, after removing trailing spaces.  Other types of
white space are not removed.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RTRIM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RTRIM</function> (<replaceable><replaceable>string</replaceable></replaceable>, <replaceable><replaceable>padding</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns <replaceable>string</replaceable>, after removing trailing <replaceable>padding</replaceable> characters.
If <replaceable>padding</replaceable> does not contain exactly one character, returns an
empty string.
</para></blockquote>
<indexterm role="cp"><primary>strings, converting from numbers</primary></indexterm>
<indexterm role="cp"><primary>numbers, converting to strings</primary></indexterm>
<synopsis><indexterm role="fn"><primary>STRING</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>STRING</function> (<replaceable><replaceable>number</replaceable></replaceable>, <replaceable><replaceable>format</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns a string corresponding to <replaceable>number</replaceable> in the format given by
format specifier <replaceable>format</replaceable>.  For example, <literal>STRING(123.56, F5.1)</literal>
has the value <literal>&quot;123.6&quot;</literal>.
</para></blockquote>
<indexterm role="cp"><primary>strings, trimming</primary></indexterm>
<indexterm role="cp"><primary>strings, truncating</primary></indexterm>
<indexterm role="cp"><primary>white space, trimming</primary></indexterm>
<synopsis><indexterm role="fn"><primary>STRUNC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>STRUNC</function> (<replaceable><replaceable>string</replaceable></replaceable>, <replaceable><replaceable>n</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns <replaceable>string</replaceable>, first trimming it to at most <replaceable>n</replaceable> bytes, then
removing trailing spaces.  Returns an empty string if <replaceable>n</replaceable> is
missing or negative.
</para></blockquote>
<indexterm role="cp"><primary>substrings</primary></indexterm>
<indexterm role="cp"><primary>strings, taking substrings of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>SUBSTR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SUBSTR</function> (<replaceable><replaceable>string</replaceable></replaceable>, <replaceable><replaceable>start</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns a string consisting of the value of <replaceable>string</replaceable> from position
<replaceable>start</replaceable> onward.  Returns an empty string if <replaceable>start</replaceable> is system-missing,
less than 1, or greater than the length of <replaceable>string</replaceable>.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>SUBSTR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SUBSTR</function> (<replaceable><replaceable>string</replaceable></replaceable>, <replaceable><replaceable>start</replaceable></replaceable>, <replaceable><replaceable>count</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns a string consisting of the first <replaceable>count</replaceable> characters from
<replaceable>string</replaceable> beginning at position <replaceable>start</replaceable>.  Returns an empty string
if <replaceable>start</replaceable> or <replaceable>count</replaceable> is system-missing, if <replaceable>start</replaceable> is less
than 1 or greater than the number of characters in <replaceable>string</replaceable>, or if
<replaceable>count</replaceable> is less than 1.  Returns a string shorter than <replaceable>count</replaceable>
characters if <replaceable>start</replaceable> + <replaceable>count</replaceable> - 1 is greater than the number
of characters in <replaceable>string</replaceable>.  Examples: <literal>SUBSTR(&quot;abcdefg&quot;, 3, 2)</literal>
has value <literal>&quot;cd&quot;</literal>; <literal>SUBSTR(&quot;nonsense&quot;, 4, 10)</literal> has the value
<literal>&quot;sense&quot;</literal>.
</para></blockquote>
<indexterm role="cp"><primary>case conversion</primary></indexterm>
<indexterm role="cp"><primary>strings, case of</primary></indexterm>
<synopsis><indexterm role="fn"><primary>UPCASE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>UPCASE</function> (<replaceable><replaceable>string</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns <replaceable>string</replaceable>, changing lowercase letters to uppercase letters.
</para></blockquote>
</sect2>
<sect2 label="7.7.8" id="Time-and-Date">
<title>Time &amp; Date Functions</title>
<indexterm role="cp"><primary>functions, time &amp; date</primary></indexterm>
<indexterm role="cp"><primary>times</primary></indexterm>
<indexterm role="cp"><primary>dates</primary></indexterm>

<indexterm role="cp"><primary>dates, valid</primary></indexterm>
<para>For compatibility, pspp considers dates before 15 Oct 1582 invalid.
Most time and date functions will not accept earlier dates.
</para>

<sect3 label="7.7.8.1" id="Time-and-Date-Concepts">
<title>How times &amp; dates are defined and represented</title>

<indexterm role="cp"><primary>time, concepts</primary></indexterm>
<indexterm role="cp"><primary>time, intervals</primary></indexterm>
<para>Times and dates are handled by pspp as single numbers.  A
<firstterm>time</firstterm> is an interval.  pspp measures times in seconds.
Thus, the following intervals correspond with the numeric values given:
</para>                
<screen>          10 minutes                        600
          1 hour                          3,600
          1 day, 3 hours, 10 seconds     97,210
          40 days                     3,456,000
</screen>
<indexterm role="cp"><primary>dates, concepts</primary></indexterm>
<indexterm role="cp"><primary>time, instants of</primary></indexterm>
<para>A <firstterm>date</firstterm>, on the other hand, is a particular instant in the past
or the future.  pspp represents a date as a number of seconds since
midnight preceding 14 Oct 1582.  Because midnight preceding the dates
given below correspond with the numeric pspp dates given:
</para>
<screen>              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
</screen>
</sect3>
<sect3 label="7.7.8.2" id="Time-Construction">
<title>Functions that Produce Times</title>
<indexterm role="cp"><primary>times, constructing</primary></indexterm>
<indexterm role="cp"><primary>constructing times</primary></indexterm>

<para>These functions take numeric arguments and return numeric values that
represent times.
</para>
<indexterm role="cp"><primary>days</primary></indexterm>
<indexterm role="cp"><primary>time, in days</primary></indexterm>
<synopsis><indexterm role="fn"><primary>TIME.DAYS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>TIME.DAYS</function> (<replaceable><replaceable>ndays</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns a time corresponding to <replaceable>ndays</replaceable> days.
</para></blockquote>
<indexterm role="cp"><primary>hours-minutes-seconds</primary></indexterm>
<indexterm role="cp"><primary>time, in hours-minutes-seconds</primary></indexterm>
<synopsis><indexterm role="fn"><primary>TIME.HMS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>TIME.HMS</function> (<replaceable><replaceable>nhours</replaceable></replaceable>, <replaceable><replaceable>nmins</replaceable></replaceable>, <replaceable><replaceable>nsecs</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns a time corresponding to <replaceable>nhours</replaceable> hours, <replaceable>nmins</replaceable>
minutes, and <replaceable>nsecs</replaceable> seconds.  The arguments may not have mixed
signs: if any of them are positive, then none may be negative, and
vice versa.  
</para></blockquote>
</sect3>
<sect3 label="7.7.8.3" id="Time-Extraction">
<title>Functions that Examine Times</title>
<indexterm role="cp"><primary>extraction, of time</primary></indexterm>
<indexterm role="cp"><primary>time examination</primary></indexterm>
<indexterm role="cp"><primary>examination, of times</primary></indexterm>
<indexterm role="cp"><primary>time, lengths of</primary></indexterm>

<para>These functions take numeric arguments in pspp time format and
give numeric results.
</para>
<indexterm role="cp"><primary>days</primary></indexterm>
<indexterm role="cp"><primary>time, in days</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CTIME.DAYS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CTIME.DAYS</function> (<replaceable><replaceable>time</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the number of days and fractional days in <replaceable>time</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>hours</primary></indexterm>
<indexterm role="cp"><primary>time, in hours</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CTIME.HOURS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CTIME.HOURS</function> (<replaceable><replaceable>time</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the number of hours and fractional hours in <replaceable>time</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>minutes</primary></indexterm>
<indexterm role="cp"><primary>time, in minutes</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CTIME.MINUTES</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CTIME.MINUTES</function> (<replaceable><replaceable>time</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the number of minutes and fractional minutes in <replaceable>time</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>seconds</primary></indexterm>
<indexterm role="cp"><primary>time, in seconds</primary></indexterm>
<synopsis><indexterm role="fn"><primary>CTIME.SECONDS</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CTIME.SECONDS</function> (<replaceable><replaceable>time</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the number of seconds and fractional seconds in <replaceable>time</replaceable>.
(<literal>CTIME.SECONDS</literal> does nothing; <literal>CTIME.SECONDS(<replaceable>x</replaceable>)</literal> is
equivalent to <literal><replaceable>x</replaceable></literal>.)
</para></blockquote>
</sect3>
<sect3 label="7.7.8.4" id="Date-Construction">
<title>Functions that Produce Dates</title>
<indexterm role="cp"><primary>dates, constructing</primary></indexterm>
<indexterm role="cp"><primary>constructing dates</primary></indexterm>

<indexterm role="cp"><primary>arguments, of date construction functions</primary></indexterm>
<para>These functions take numeric arguments and give numeric results that
represent dates.  Arguments taken by these functions are:
</para>
<variablelist><varlistentry><term><replaceable>day</replaceable>
</term><listitem><para>Refers to a day of the month between 1 and 31.  Day 0 is also accepted
and refers to the final day of the previous month.  Days 29, 30, and
31 are accepted even in months that have fewer days and refer to a day
near the beginning of the following month.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>month</replaceable>
</term><listitem><para>Refers to a month of the year between 1 and 12.  Months 0 and 13 are
also accepted and refer to the last month of the preceding year and
the first month of the following year, respectively.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>quarter</replaceable>
</term><listitem><para>Refers to a quarter of the year between 1 and 4.  The quarters of the
year begin on the first day of months 1, 4, 7, and 10.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>week</replaceable>
</term><listitem><para>Refers to a week of the year between 1 and 53.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>yday</replaceable>
</term><listitem><para>Refers to a day of the year between 1 and 366.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>year</replaceable>
</term><listitem><para>Refers to a year, 1582 or greater.  Years between 0 and 99 are treated
according to the epoch set on SET EPOCH, by default beginning 69 years
before the current date (see <link linkend="SET-EPOCH">SET EPOCH</link>).
</para></listitem></varlistentry></variablelist>
<indexterm role="cp"><primary>arguments, invalid</primary></indexterm>
<para>If these functions&#8217; arguments are out-of-range, they are correctly
normalized before conversion to date format.  Non-integers are rounded
toward zero.
</para>
<indexterm role="cp"><primary>day-month-year</primary></indexterm>
<indexterm role="cp"><primary>dates, day-month-year</primary></indexterm>
<synopsis><indexterm role="fn"><primary>DATE.DMY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.DMY</function> (<replaceable><replaceable>day</replaceable></replaceable>, <replaceable><replaceable>month</replaceable></replaceable>, <replaceable><replaceable>year</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>DATE.MDY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.MDY</function> (<replaceable><replaceable>month</replaceable></replaceable>, <replaceable><replaceable>day</replaceable></replaceable>, <replaceable><replaceable>year</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in a date value corresponding to the midnight before day
<replaceable>day</replaceable> of month <replaceable>month</replaceable> of year <replaceable>year</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>month-year</primary></indexterm>
<indexterm role="cp"><primary>dates, month-year</primary></indexterm>
<synopsis><indexterm role="fn"><primary>DATE.MOYR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.MOYR</function> (<replaceable><replaceable>month</replaceable></replaceable>, <replaceable><replaceable>year</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in a date value corresponding to the midnight before the first
day of month <replaceable>month</replaceable> of year <replaceable>year</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>quarter-year</primary></indexterm>
<indexterm role="cp"><primary>dates, quarter-year</primary></indexterm>
<synopsis><indexterm role="fn"><primary>DATE.QYR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.QYR</function> (<replaceable><replaceable>quarter</replaceable></replaceable>, <replaceable><replaceable>year</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in a date value corresponding to the midnight before the first
day of quarter <replaceable>quarter</replaceable> of year <replaceable>year</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>week-year</primary></indexterm>
<indexterm role="cp"><primary>dates, week-year</primary></indexterm>
<synopsis><indexterm role="fn"><primary>DATE.WKYR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.WKYR</function> (<replaceable><replaceable>week</replaceable></replaceable>, <replaceable><replaceable>year</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in a date value corresponding to the midnight before the first
day of week <replaceable>week</replaceable> of year <replaceable>year</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>year-day</primary></indexterm>
<indexterm role="cp"><primary>dates, year-day</primary></indexterm>
<synopsis><indexterm role="fn"><primary>DATE.YRDAY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATE.YRDAY</function> (<replaceable><replaceable>year</replaceable></replaceable>, <replaceable><replaceable>yday</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in a date value corresponding to the day
<replaceable>yday</replaceable> of year <replaceable>year</replaceable>.
</para></blockquote>
</sect3>
<sect3 label="7.7.8.5" id="Date-Extraction">
<title>Functions that Examine Dates</title>
<indexterm role="cp"><primary>extraction, of dates</primary></indexterm>
<indexterm role="cp"><primary>date examination</primary></indexterm>

<indexterm role="cp"><primary>arguments, of date extraction functions</primary></indexterm>
<para>These functions take numeric arguments in pspp date or time
format and give numeric results.  These names are used for arguments:
</para>
<variablelist><varlistentry><term><replaceable>date</replaceable>
</term><listitem><para>A numeric value in pspp date format.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>time</replaceable>
</term><listitem><para>A numeric value in pspp time format.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>time-or-date</replaceable>
</term><listitem><para>A numeric value in pspp time or date format.
</para></listitem></varlistentry></variablelist>
<indexterm role="cp"><primary>days</primary></indexterm>
<indexterm role="cp"><primary>dates, in days</primary></indexterm>
<indexterm role="cp"><primary>time, in days</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.DATE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.DATE</function> (<replaceable><replaceable>time-or-date</replaceable></replaceable>)</synopsis>
<blockquote><para>For a time, results in the time corresponding to the number of whole
days <replaceable>date-or-time</replaceable> includes.  For a date, results in the date
corresponding to the latest midnight at or before <replaceable>date-or-time</replaceable>;
that is, gives the date that <replaceable>date-or-time</replaceable> is in.
</para></blockquote>
<indexterm role="cp"><primary>hours</primary></indexterm>
<indexterm role="cp"><primary>dates, in hours</primary></indexterm>
<indexterm role="cp"><primary>time, in hours</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.HOUR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.HOUR</function> (<replaceable><replaceable>time-or-date</replaceable></replaceable>)</synopsis>
<blockquote><para>For a time, results in the number of whole hours beyond the number of
whole days represented by <replaceable>date-or-time</replaceable>.  For a date, results in
the hour (as an integer between 0 and 23) corresponding to
<replaceable>date-or-time</replaceable>.  
</para></blockquote>
<indexterm role="cp"><primary>day of the year</primary></indexterm>
<indexterm role="cp"><primary>dates, day of the year</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.JDAY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.JDAY</function> (<replaceable><replaceable>date</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the day of the year (as an integer between 1 and 366)
corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>day of the month</primary></indexterm>
<indexterm role="cp"><primary>dates, day of the month</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.MDAY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.MDAY</function> (<replaceable><replaceable>date</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the day of the month (as an integer between 1 and 31)
corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>minutes</primary></indexterm>
<indexterm role="cp"><primary>dates, in minutes</primary></indexterm>
<indexterm role="cp"><primary>time, in minutes</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.MINUTE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.MINUTE</function> (<replaceable><replaceable>time-or-date</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the number of minutes (as an integer between 0 and 59) after
the last hour in <replaceable>time-or-date</replaceable>. 
</para></blockquote>
<indexterm role="cp"><primary>months</primary></indexterm>
<indexterm role="cp"><primary>dates, in months</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.MONTH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.MONTH</function> (<replaceable><replaceable>date</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the month of the year (as an integer between 1 and 12)
corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>quarters</primary></indexterm>
<indexterm role="cp"><primary>dates, in quarters</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.QUARTER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.QUARTER</function> (<replaceable><replaceable>date</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the quarter of the year (as an integer between 1 and 4)
corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>seconds</primary></indexterm>
<indexterm role="cp"><primary>dates, in seconds</primary></indexterm>
<indexterm role="cp"><primary>time, in seconds</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.SECOND</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.SECOND</function> (<replaceable><replaceable>time-or-date</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the number of whole seconds after the last whole minute (as
an integer between 0 and 59) in <replaceable>time-or-date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>days</primary></indexterm>
<indexterm role="cp"><primary>times, in days</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.TDAY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.TDAY</function> (<replaceable><replaceable>date</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the number of whole days from 14 Oct 1582 to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>time</primary></indexterm>
<indexterm role="cp"><primary>dates, time of day</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.TIME</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.TIME</function> (<replaceable><replaceable>date</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the time of day at the instant corresponding to <replaceable>date</replaceable>,
as a time value.  This is the number of seconds since
midnight on the day corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>week</primary></indexterm>
<indexterm role="cp"><primary>dates, in weeks</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.WEEK</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.WEEK</function> (<replaceable><replaceable>date</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the week of the year (as an integer between 1 and 53)
corresponding to <replaceable>date</replaceable>.
</para></blockquote>
<indexterm role="cp"><primary>day of the week</primary></indexterm>
<indexterm role="cp"><primary>weekday</primary></indexterm>
<indexterm role="cp"><primary>dates, day of the week</primary></indexterm>
<indexterm role="cp"><primary>dates, in weekdays</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.WKDAY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.WKDAY</function> (<replaceable><replaceable>date</replaceable></replaceable>)</synopsis>
<blockquote><para>Results in the day of week (as an integer between 1 and 7) corresponding
to <replaceable>date</replaceable>, where 1 represents Sunday.
</para></blockquote>
<indexterm role="cp"><primary>years</primary></indexterm>
<indexterm role="cp"><primary>dates, in years</primary></indexterm>
<synopsis><indexterm role="fn"><primary>XDATE.YEAR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>XDATE.YEAR</function> (<replaceable><replaceable>date</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns the year (as an integer 1582 or greater) corresponding to
<replaceable>date</replaceable>.
</para></blockquote>
</sect3>
<sect3 label="7.7.8.6" id="Time-and-Date-Arithmetic">
<title>Time and Date Arithmetic</title>

<indexterm role="cp"><primary>time, mathematical properties of</primary></indexterm>
<indexterm role="cp"><primary>mathematics, applied to times &amp; dates</primary></indexterm>
<indexterm role="cp"><primary>dates, mathematical properties of</primary></indexterm>
<para>Ordinary arithmetic operations on dates and times often produce
sensible results.  Adding a time to, or subtracting one from, a date
produces a new date that much earlier or later.  The difference of two
dates yields the time between those dates.  Adding two times produces
the combined time.  Multiplying a time by a scalar produces a time
that many times longer.  Since times and dates are just numbers, the
ordinary addition and subtraction operators are employed for these
purposes.
</para>
<para>Adding two dates does not produce a useful result.
</para>
<para>Dates and times may have very large values.  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.
</para>
<para>pspp supplies a few functions for date arithmetic:
</para>
<synopsis><indexterm role="fn"><primary>DATEDIFF</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATEDIFF</function> (<replaceable><replaceable>date2</replaceable></replaceable>, <replaceable><replaceable>date1</replaceable></replaceable>, <replaceable><replaceable>unit</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns the span of time from <replaceable>date1</replaceable> to <replaceable>date2</replaceable> in terms of
<replaceable>unit</replaceable>, which must be a quoted string, one of &#8216;<literal>years</literal>&#8217;,
&#8216;<literal>quarters</literal>&#8217;, &#8216;<literal>months</literal>&#8217;, &#8216;<literal>weeks</literal>&#8217;, &#8216;<literal>days</literal>&#8217;,
&#8216;<literal>hours</literal>&#8217;, &#8216;<literal>minutes</literal>&#8217;, and &#8216;<literal>seconds</literal>&#8217;.  The result is an
integer, truncated toward zero.
</para>
<para>One year is considered to span from a given date to the same month,
day, and time of day the next year.  Thus, from Jan.&#160;1 of one
year to Jan.&#160;1 the next year is considered to be a full year, but
Feb.&#160;29 of a leap year to the following Feb.&#160;28 is not.
Similarly, one month spans from a given day of the month to the same
day of the following month.  Thus, there is never a full month from
Jan.&#160;31 of a given year to any day in the following February.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>DATESUM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>DATESUM</function> (<replaceable><replaceable>date</replaceable></replaceable>, <replaceable><replaceable>quantity</replaceable></replaceable>, <replaceable><replaceable>unit</replaceable></replaceable>[, <replaceable><replaceable>method</replaceable></replaceable>])</synopsis>
<blockquote><para>Returns <replaceable>date</replaceable> advanced by the given <replaceable>quantity</replaceable> of the
specified <replaceable>unit</replaceable>, which must be one of the strings &#8216;<literal>years</literal>&#8217;,
&#8216;<literal>quarters</literal>&#8217;, &#8216;<literal>months</literal>&#8217;, &#8216;<literal>weeks</literal>&#8217;, &#8216;<literal>days</literal>&#8217;,
&#8216;<literal>hours</literal>&#8217;, &#8216;<literal>minutes</literal>&#8217;, and &#8216;<literal>seconds</literal>&#8217;.
</para>
<para>When <replaceable>unit</replaceable> is &#8216;<literal>years</literal>&#8217;, &#8216;<literal>quarters</literal>&#8217;, or &#8216;<literal>months</literal>&#8217;,
only the integer part of <replaceable>quantity</replaceable> is considered.  Adding one of
these units can cause the day of the month to exceed the number of
days in the month.  In this case, the <replaceable>method</replaceable> comes into
play: if it is omitted or specified as &#8216;<literal>closest</literal>&#8217; (as a quoted
string), then the resulting day is the last day of the month;
otherwise, if it is specified as &#8216;<literal>rollover</literal>&#8217;, then the extra days
roll over into the following month.
</para>
<para>When <replaceable>unit</replaceable> is &#8216;<literal>weeks</literal>&#8217;, &#8216;<literal>days</literal>&#8217;, &#8216;<literal>hours</literal>&#8217;,
&#8216;<literal>minutes</literal>&#8217;, or &#8216;<literal>seconds</literal>&#8217;, the <replaceable>quantity</replaceable> is not rounded
to an integer and <replaceable>method</replaceable>, if specified, is ignored.
</para></blockquote>
</sect3>
</sect2>
<sect2 label="7.7.9" id="Miscellaneous-Functions">
<title>Miscellaneous Functions</title>
<indexterm role="cp"><primary>functions, miscellaneous</primary></indexterm>

<indexterm role="cp"><primary>cross-case function</primary></indexterm>
<indexterm role="cp"><primary>function, cross-case</primary></indexterm>
<synopsis><indexterm role="fn"><primary>LAG</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>LAG</function> (<replaceable><replaceable>variable</replaceable></replaceable>[, <replaceable><replaceable>n</replaceable></replaceable>])</synopsis>
<blockquote><anchor id="LAG"/>
<para><replaceable>variable</replaceable> must be a numeric or string variable name.  <literal>LAG</literal>
yields the value of that variable for the case <replaceable>n</replaceable> before the
current one.  Results in system-missing (for numeric variables) or
blanks (for string variables) for the first <replaceable>n</replaceable> cases.
</para>
<para><literal>LAG</literal> obtains values from the cases that become the new active
dataset
after a procedure executes.  Thus, <literal>LAG</literal> will not return values
from cases dropped by transformations such as <literal>SELECT IF</literal>, and
transformations like <literal>COMPUTE</literal> that modify data will change the
values returned by <literal>LAG</literal>.  These are both the case whether these
transformations precede or follow the use of <literal>LAG</literal>.
</para>
<para>If <literal>LAG</literal> is used before <literal>TEMPORARY</literal>, then the values it returns
are those in cases just before <literal>TEMPORARY</literal>.  <literal>LAG</literal> may not be
used after <literal>TEMPORARY</literal>.
</para>
<para>If omitted, <replaceable>ncases</replaceable> defaults to 1.  Otherwise, <replaceable>ncases</replaceable> must
be a small positive constant integer.  There is no explicit limit, but
use of a large value will increase memory consumption.
</para></blockquote>
<indexterm role="cp"><primary>date, Julian</primary></indexterm>
<indexterm role="cp"><primary>Julian date</primary></indexterm>
<synopsis><indexterm role="fn"><primary>YRMODA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>YRMODA</function> (<replaceable><replaceable>year</replaceable></replaceable>, <replaceable><replaceable>month</replaceable></replaceable>, <replaceable><replaceable>day</replaceable></replaceable>)</synopsis>
<blockquote><para><replaceable>year</replaceable> is a year, either between 0 and 99 or at least 1582.
Unlike other pspp date functions, years between 0 and 99 always
correspond to 1900 through 1999.  <replaceable>month</replaceable> is a month between 1 and
13.  <replaceable>day</replaceable> is a day between 0 and 31.  A <replaceable>day</replaceable> of 0 refers to
the last day of the previous month, and a <replaceable>month</replaceable> of 13 refers to
the first month of the next year.  <replaceable>year</replaceable> must be in range.
<replaceable>year</replaceable>, <replaceable>month</replaceable>, and <replaceable>day</replaceable> must all be integers.
</para>
<para><literal>YRMODA</literal> results in the number of days between 15 Oct 1582 and
the date specified, plus one.  The date passed to <literal>YRMODA</literal> must be
on or after 15 Oct 1582.  15 Oct 1582 has a value of 1.
</para></blockquote>
<indexterm role="cp"><primary>value label</primary></indexterm>
<synopsis><indexterm role="fn"><primary>(</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue>VALUELABEL</returnvalue> <function>(</function><replaceable><replaceable>variable</replaceable></replaceable>)</synopsis>
<blockquote><para>Returns a string matching the label associated with the current value
of <replaceable>variable</replaceable>.  If the current value of <replaceable>variable</replaceable> has no
associated label, then this function returns the empty string.
<replaceable>variable</replaceable> may be a numeric or string variable.
</para></blockquote>
</sect2>
<sect2 label="7.7.10" id="Statistical-Distribution-Functions">
<title>Statistical Distribution Functions</title>

<para>pspp can calculate several functions of standard statistical
distributions.  These functions are named systematically based on the
function and the distribution.  The table below describes the
statistical distribution functions in general:
</para>
<variablelist><varlistentry><term>PDF.<replaceable>dist</replaceable> (<replaceable>x</replaceable>[, <replaceable>param</replaceable>&#8230;])
</term><listitem><para>Probability density function for <replaceable>dist</replaceable>.  The domain of <replaceable>x</replaceable>
depends on <replaceable>dist</replaceable>.  For continuous distributions, the result is
the density of the probability function at <replaceable>x</replaceable>, and the range is
nonnegative real numbers.  For discrete distributions, the result is
the probability of <replaceable>x</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term>CDF.<replaceable>dist</replaceable> (<replaceable>x</replaceable>[, <replaceable>param</replaceable>&#8230;])
</term><listitem><para>Cumulative distribution function for <replaceable>dist</replaceable>, that is, the
probability that a random variate drawn from the distribution is less
than <replaceable>x</replaceable>.  The domain of <replaceable>x</replaceable> depends <replaceable>dist</replaceable>.  The result is
a probability.
</para>
</listitem></varlistentry><varlistentry><term>SIG.<replaceable>dist</replaceable> (<replaceable>x</replaceable>[, <replaceable>param</replaceable>&#8230;)
</term><listitem><para>Tail probability function for <replaceable>dist</replaceable>, that is, the probability
that a random variate drawn from the distribution is greater than
<replaceable>x</replaceable>.  The domain of <replaceable>x</replaceable> depends <replaceable>dist</replaceable>.  The result is a
probability.  Only a few distributions include an <literal>/NAME/</literal> function.
</para>
</listitem></varlistentry><varlistentry><term>IDF.<replaceable>dist</replaceable> (<replaceable>p</replaceable>[, <replaceable>param</replaceable>&#8230;])
</term><listitem><para>Inverse distribution function for <replaceable>dist</replaceable>, the value of <replaceable>x</replaceable> for
which the CDF would yield <replaceable>p</replaceable>.  The value of <replaceable>p</replaceable> is a
probability.  The range depends on <replaceable>dist</replaceable> and is identical to the
domain for the corresponding CDF.
</para>
</listitem></varlistentry><varlistentry><term>RV.<replaceable>dist</replaceable> ([<replaceable>param</replaceable>&#8230;])
</term><listitem><para>Random variate function for <replaceable>dist</replaceable>.  The range depends on the
distribution.
</para>
</listitem></varlistentry><varlistentry><term>NPDF.<replaceable>dist</replaceable> (<replaceable>x</replaceable>[, <replaceable>param</replaceable>&#8230;])
</term><listitem><para>Noncentral probability density function.  The result is the density of
the given noncentral distribution at <replaceable>x</replaceable>.  The domain of <replaceable>x</replaceable>
depends on <replaceable>dist</replaceable>.  The range is nonnegative real numbers.  Only a
few distributions include an <literal>/NAME/</literal> function.
</para>
</listitem></varlistentry><varlistentry><term>NCDF.<replaceable>dist</replaceable> (<replaceable>x</replaceable>[, <replaceable>param</replaceable>&#8230;])
</term><listitem><para>Noncentral cumulative distribution function for <replaceable>dist</replaceable>, that is,
the probability that a random variate drawn from the given noncentral
distribution is less than <replaceable>x</replaceable>.  The domain of <replaceable>x</replaceable> depends
<replaceable>dist</replaceable>.  The result is a probability.  Only a few distributions
include an NCDF function.
</para></listitem></varlistentry></variablelist>
<para>The individual distributions are described individually below.
</para>

<sect3 label="7.7.10.1" id="Continuous-Distributions">
<title>Continuous Distributions</title>

<para>The following continuous distributions are available:
</para>
<synopsis><indexterm role="fn"><primary>PDF.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.BETA</function> (<replaceable><replaceable>x</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.BETA</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.BETA</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.BETA</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>NPDF.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NPDF.BETA</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>, <replaceable><replaceable>lambda</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>NCDF.BETA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NCDF.BETA</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>, <replaceable><replaceable>lambda</replaceable></replaceable>)</synopsis>
<blockquote><para>Beta distribution with shape parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.  The
noncentral distribution takes an additional parameter <replaceable>lambda</replaceable>.
Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>b</replaceable> &gt; 0, <replaceable>lambda</replaceable> &gt;= 0, 0 &lt;= <replaceable>x</replaceable>
&lt;= 1, 0 &lt;= <replaceable>p</replaceable> &lt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.BVNOR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.BVNOR</function> (<replaceable><replaceable>x0</replaceable></replaceable>, <replaceable><replaceable>x1</replaceable></replaceable>, <replaceable><replaceable>rho</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.VBNOR</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.VBNOR</function> (<replaceable><replaceable>x0</replaceable></replaceable>, <replaceable><replaceable>x1</replaceable></replaceable>, <replaceable><replaceable>rho</replaceable></replaceable>)</synopsis>
<blockquote><para>Bivariate normal distribution of two standard normal variables with
correlation coefficient <replaceable>rho</replaceable>.  Two variates <replaceable>x0</replaceable> and <replaceable>x1</replaceable>
must be provided.  Constraints: 0 &lt;= <replaceable>rho</replaceable> &lt;= 1, 0 &lt;= <replaceable>p</replaceable> &lt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.CAUCHY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.CAUCHY</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.CAUCHY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.CAUCHY</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.CAUCHY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.CAUCHY</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.CAUCHY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.CAUCHY</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Cauchy distribution with location parameter <replaceable>a</replaceable> and scale
parameter <replaceable>b</replaceable>.  Constraints: <replaceable>b</replaceable> &gt; 0, 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<!-- @deftypefn {Function} {} PDF.CHISQ (@var{x}, @var{df}) -->
<synopsis><indexterm role="fn"><primary>CDF.CHISQ</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.CHISQ</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>df</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>SIG.CHISQ</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SIG.CHISQ</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>df</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.CHISQ</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.CHISQ</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>df</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.CHISQ</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.CHISQ</function> (<replaceable><replaceable>df</replaceable></replaceable>)</synopsis>
<!-- @deftypefnx {Function} {} NPDF.CHISQ (@var{x}, @var{df}, @var{lambda}) -->
<synopsis><indexterm role="fn"><primary>NCDF.CHISQ</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NCDF.CHISQ</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>df</replaceable></replaceable>, <replaceable><replaceable>lambda</replaceable></replaceable>)</synopsis>
<blockquote><para>Chi-squared distribution with <replaceable>df</replaceable> degrees of freedom.  The
noncentral distribution takes an additional parameter <replaceable>lambda</replaceable>.
Constraints: <replaceable>df</replaceable> &gt; 0, <replaceable>lambda</replaceable> &gt; 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;=
<replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.EXP</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.EXP</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.EXP</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.EXP</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.EXP</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.EXP</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.EXP</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.EXP</function> (<replaceable><replaceable>a</replaceable></replaceable>)</synopsis>
<blockquote><para>Exponential distribution with scale parameter <replaceable>a</replaceable>.  The inverse of
<replaceable>a</replaceable> represents the rate of decay.  Constraints: <replaceable>a</replaceable> &gt; 0,
<replaceable>x</replaceable> &gt;= 0, 0 &lt;= <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.XPOWER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.XPOWER</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.XPOWER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.XPOWER</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Exponential power distribution with positive scale parameter <replaceable>a</replaceable>
and nonnegative power parameter <replaceable>b</replaceable>.  Constraints: <replaceable>a</replaceable> &gt; 0,
<replaceable>b</replaceable> &gt;= 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;= <replaceable>p</replaceable> &lt;= 1.  This distribution is a
pspp extension.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.F</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.F</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>df1</replaceable></replaceable>, <replaceable><replaceable>df2</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.F</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.F</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>df1</replaceable></replaceable>, <replaceable><replaceable>df2</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>SIG.F</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>SIG.F</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>df1</replaceable></replaceable>, <replaceable><replaceable>df2</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.F</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.F</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>df1</replaceable></replaceable>, <replaceable><replaceable>df2</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.F</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.F</function> (<replaceable><replaceable>df1</replaceable></replaceable>, <replaceable><replaceable>df2</replaceable></replaceable>)</synopsis>
<blockquote><!-- @deftypefnx {Function} {} NPDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda}) -->
<!-- @deftypefnx {Function} {} NCDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda}) -->
<para>F-distribution of two chi-squared deviates with <replaceable>df1</replaceable> and
<replaceable>df2</replaceable> degrees of freedom.  The noncentral distribution takes an
additional parameter <replaceable>lambda</replaceable>.  Constraints: <replaceable>df1</replaceable> &gt; 0,
<replaceable>df2</replaceable> &gt; 0, <replaceable>lambda</replaceable> &gt;= 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;= <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.GAMMA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.GAMMA</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.GAMMA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.GAMMA</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.GAMMA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.GAMMA</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.GAMMA</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.GAMMA</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Gamma distribution with shape parameter <replaceable>a</replaceable> and scale parameter
<replaceable>b</replaceable>.  Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>b</replaceable> &gt; 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;=
<replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<!-- @deftypefn {Function} {} PDF.HALFNRM (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} CDF.HALFNRM (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} IDF.HALFNRM (@var{p}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} RV.HALFNRM (@var{a}, @var{b}) -->
<!-- Half-normal distribution with location parameter @var{a} and shape -->
<!-- parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1. -->
<!-- @end deftypefn -->

<!-- @deftypefn {Function} {} PDF.IGAUSS (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} CDF.IGAUSS (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} IDF.IGAUSS (@var{p}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} RV.IGAUSS (@var{a}, @var{b}) -->
<!-- Inverse Gaussian distribution with parameters @var{a} and @var{b}. -->
<!-- Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <= @var{p} < 1. -->
<!-- @end deftypefn -->

<synopsis><indexterm role="fn"><primary>PDF.LANDAU</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.LANDAU</function> (<replaceable><replaceable>x</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.LANDAU</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LANDAU</function> ()</synopsis>
<blockquote><para>Landau distribution.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.LAPLACE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.LAPLACE</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.LAPLACE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.LAPLACE</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.LAPLACE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.LAPLACE</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.LAPLACE</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LAPLACE</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Laplace distribution with location parameter <replaceable>a</replaceable> and scale
parameter <replaceable>b</replaceable>.  Constraints: <replaceable>b</replaceable> &gt; 0, 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RV.LEVY</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LEVY</function> (<replaceable><replaceable>c</replaceable></replaceable>, <replaceable><replaceable>alpha</replaceable></replaceable>)</synopsis>
<blockquote><para>Levy symmetric alpha-stable distribution with scale <replaceable>c</replaceable> and
exponent <replaceable>alpha</replaceable>.  Constraints: 0 &lt; <replaceable>alpha</replaceable> &lt;= 2.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>RV.LVSKEW</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LVSKEW</function> (<replaceable><replaceable>c</replaceable></replaceable>, <replaceable><replaceable>alpha</replaceable></replaceable>, <replaceable><replaceable>beta</replaceable></replaceable>)</synopsis>
<blockquote><para>Levy skew alpha-stable distribution with scale <replaceable>c</replaceable>, exponent
<replaceable>alpha</replaceable>, and skewness parameter <replaceable>beta</replaceable>.  Constraints: 0 &lt;
<replaceable>alpha</replaceable> &lt;= 2, -1 &lt;= <replaceable>beta</replaceable> &lt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.LOGISTIC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.LOGISTIC</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.LOGISTIC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.LOGISTIC</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.LOGISTIC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.LOGISTIC</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.LOGISTIC</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LOGISTIC</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Logistic distribution with location parameter <replaceable>a</replaceable> and scale
parameter <replaceable>b</replaceable>.  Constraints: <replaceable>b</replaceable> &gt; 0, 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.LNORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.LNORMAL</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.LNORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.LNORMAL</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.LNORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.LNORMAL</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.LNORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LNORMAL</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Lognormal distribution with parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.
Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>b</replaceable> &gt; 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;= <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.NORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.NORMAL</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>mu</replaceable></replaceable>, <replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.NORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.NORMAL</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>mu</replaceable></replaceable>, <replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.NORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.NORMAL</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>mu</replaceable></replaceable>, <replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.NORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.NORMAL</function> (<replaceable><replaceable>mu</replaceable></replaceable>, <replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<blockquote><para>Normal distribution with mean <replaceable>mu</replaceable> and standard deviation
<replaceable>sigma</replaceable>.  Constraints: <replaceable>b</replaceable> &gt; 0, 0 &lt; <replaceable>p</replaceable> &lt; 1.  Three
additional functions are available as shorthand:
</para>
<synopsis><indexterm role="fn"><primary>CDFNORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDFNORM</function> (<replaceable><replaceable>x</replaceable></replaceable>)</synopsis>
<blockquote><para>Equivalent to CDF.NORMAL(<replaceable>x</replaceable>, 0, 1).
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PROBIT</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PROBIT</function> (<replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<blockquote><para>Equivalent to IDF.NORMAL(<replaceable>p</replaceable>, 0, 1).
</para></blockquote>
<synopsis><indexterm role="fn"><primary>NORMAL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>NORMAL</function> (<replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<blockquote><para>Equivalent to RV.NORMAL(0, <replaceable>sigma</replaceable>).
</para></blockquote></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.NTAIL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.NTAIL</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.NTAIL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.NTAIL</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<blockquote><para>Normal tail distribution with lower limit <replaceable>a</replaceable> and standard
deviation <replaceable>sigma</replaceable>.  This distribution is a pspp extension.
Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>x</replaceable> &gt; <replaceable>a</replaceable>, 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.PARETO</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.PARETO</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.PARETO</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.PARETO</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.PARETO</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.PARETO</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.PARETO</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.PARETO</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Pareto distribution with threshold parameter <replaceable>a</replaceable> and shape
parameter <replaceable>b</replaceable>.  Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>b</replaceable> &gt; 0, <replaceable>x</replaceable> &gt;=
<replaceable>a</replaceable>, 0 &lt;= <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.RAYLEIGH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.RAYLEIGH</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.RAYLEIGH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.RAYLEIGH</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.RAYLEIGH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.RAYLEIGH</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.RAYLEIGH</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.RAYLEIGH</function> (<replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<blockquote><para>Rayleigh distribution with scale parameter <replaceable>sigma</replaceable>.  This
distribution is a pspp extension.  Constraints: <replaceable>sigma</replaceable> &gt; 0,
<replaceable>x</replaceable> &gt; 0.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.RTAIL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.RTAIL</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.RTAIL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.RTAIL</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>sigma</replaceable></replaceable>)</synopsis>
<blockquote><para>Rayleigh tail distribution with lower limit <replaceable>a</replaceable> and scale
parameter <replaceable>sigma</replaceable>.  This distribution is a pspp extension.
Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>sigma</replaceable> &gt; 0, <replaceable>x</replaceable> &gt; <replaceable>a</replaceable>.
</para></blockquote>
<!-- @deftypefn {Function} {} CDF.SMOD (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} IDF.SMOD (@var{p}, @var{a}, @var{b}) -->
<!-- Studentized maximum modulus distribution with parameters @var{a} and -->
<!-- @var{b}.  Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <= -->
<!-- @var{p} < 1. -->
<!-- @end deftypefn -->

<!-- @deftypefn {Function} {} CDF.SRANGE (@var{x}, @var{a}, @var{b}) -->
<!-- @deftypefnx {Function} {} IDF.SRANGE (@var{p}, @var{a}, @var{b}) -->
<!-- Studentized range distribution with parameters @var{a} and @var{b}. -->
<!-- Constraints:  @var{a} >= 1, @var{b} >= 1, @var{x} > 0, 0 <= @var{p} < -->
<!-- 1. -->
<!-- @end deftypefn -->

<synopsis><indexterm role="fn"><primary>PDF.T</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.T</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>df</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.T</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.T</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>df</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.T</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.T</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>df</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.T</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.T</function> (<replaceable><replaceable>df</replaceable></replaceable>)</synopsis>
<blockquote><!-- @deftypefnx {Function} {} NPDF.T (@var{x}, @var{df}, @var{lambda}) -->
<!-- @deftypefnx {Function} {} NCDF.T (@var{x}, @var{df}, @var{lambda}) -->
<para>T-distribution with <replaceable>df</replaceable> degrees of freedom.  The noncentral
distribution takes an additional parameter <replaceable>lambda</replaceable>.  Constraints:
<replaceable>df</replaceable> &gt; 0, 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.T1G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.T1G</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.T1G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.T1G</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.T1G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.T1G</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Type-1 Gumbel distribution with parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.  This
distribution is a pspp extension.  Constraints: 0 &lt; <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.T2G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.T2G</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.T2G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.T2G</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.T2G</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.T2G</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Type-2 Gumbel distribution with parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.  This
distribution is a pspp extension.  Constraints: <replaceable>x</replaceable> &gt; 0, 0 &lt;
<replaceable>p</replaceable> &lt; 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.UNIFORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.UNIFORM</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.UNIFORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.UNIFORM</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.UNIFORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.UNIFORM</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.UNIFORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.UNIFORM</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Uniform distribution with parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.
Constraints: <replaceable>a</replaceable> &lt;= <replaceable>x</replaceable> &lt;= <replaceable>b</replaceable>, 0 &lt;= <replaceable>p</replaceable> &lt;= 1.  An
additional function is available as shorthand:
</para>
<synopsis><indexterm role="fn"><primary>UNIFORM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>UNIFORM</function> (<replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Equivalent to RV.UNIFORM(0, <replaceable>b</replaceable>).
</para></blockquote></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.WEIBULL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.WEIBULL</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.WEIBULL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.WEIBULL</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>IDF.WEIBULL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>IDF.WEIBULL</function> (<replaceable><replaceable>p</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.WEIBULL</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.WEIBULL</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>)</synopsis>
<blockquote><para>Weibull distribution with parameters <replaceable>a</replaceable> and <replaceable>b</replaceable>.
Constraints: <replaceable>a</replaceable> &gt; 0, <replaceable>b</replaceable> &gt; 0, <replaceable>x</replaceable> &gt;= 0, 0 &lt;= <replaceable>p</replaceable> &lt; 1.
</para></blockquote>
</sect3>
<sect3 label="7.7.10.2" id="Discrete-Distributions">
<title>Discrete Distributions</title>

<para>The following discrete distributions are available:
</para>
<synopsis><indexterm role="fn"><primary>PDF.BERNOULLI</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.BERNOULLI</function> (<replaceable><replaceable>x</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.BERNOULLI</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.BERNOULLI</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.BERNOULLI</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.BERNOULLI</function> (<replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<blockquote><para>Bernoulli distribution with probability of success <replaceable>p</replaceable>.
Constraints: <replaceable>x</replaceable> = 0 or 1, 0 &lt;= <replaceable>p</replaceable> &lt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.BINOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.BINOM</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>n</replaceable></replaceable>, <replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.BINOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.BINOM</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>n</replaceable></replaceable>, <replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.BINOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.BINOM</function> (<replaceable><replaceable>n</replaceable></replaceable>, <replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<blockquote><para>Binomial distribution with <replaceable>n</replaceable> trials and probability of success
<replaceable>p</replaceable>.  Constraints: integer <replaceable>n</replaceable> &gt; 0, 0 &lt;= <replaceable>p</replaceable> &lt;= 1, integer
<replaceable>x</replaceable> &lt;= <replaceable>n</replaceable>.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.GEOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.GEOM</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>n</replaceable></replaceable>, <replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.GEOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.GEOM</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>n</replaceable></replaceable>, <replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.GEOM</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.GEOM</function> (<replaceable><replaceable>n</replaceable></replaceable>, <replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<blockquote><para>Geometric distribution with probability of success <replaceable>p</replaceable>.
Constraints: 0 &lt;= <replaceable>p</replaceable> &lt;= 1, integer <replaceable>x</replaceable> &gt; 0.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.HYPER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.HYPER</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>, <replaceable><replaceable>c</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.HYPER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.HYPER</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>, <replaceable><replaceable>c</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.HYPER</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.HYPER</function> (<replaceable><replaceable>a</replaceable></replaceable>, <replaceable><replaceable>b</replaceable></replaceable>, <replaceable><replaceable>c</replaceable></replaceable>)</synopsis>
<blockquote><para>Hypergeometric distribution when <replaceable>b</replaceable> objects out of <replaceable>a</replaceable> are
drawn and <replaceable>c</replaceable> of the available objects are distinctive.
Constraints: integer <replaceable>a</replaceable> &gt; 0, integer <replaceable>b</replaceable> &lt;= <replaceable>a</replaceable>, integer
<replaceable>c</replaceable> &lt;= <replaceable>a</replaceable>, integer <replaceable>x</replaceable> &gt;= 0.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.LOG</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.LOG</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.LOG</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.LOG</function> (<replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<blockquote><para>Logarithmic distribution with probability parameter <replaceable>p</replaceable>.
Constraints: 0 &lt;= <replaceable>p</replaceable> &lt; 1, <replaceable>x</replaceable> &gt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.NEGBIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.NEGBIN</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>n</replaceable></replaceable>, <replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.NEGBIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.NEGBIN</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>n</replaceable></replaceable>, <replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.NEGBIN</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.NEGBIN</function> (<replaceable><replaceable>n</replaceable></replaceable>, <replaceable><replaceable>p</replaceable></replaceable>)</synopsis>
<blockquote><para>Negative binomial distribution with number of successes parameter
<replaceable>n</replaceable> and probability of success parameter <replaceable>p</replaceable>.  Constraints:
integer <replaceable>n</replaceable> &gt;= 0, 0 &lt; <replaceable>p</replaceable> &lt;= 1, integer <replaceable>x</replaceable> &gt;= 1.
</para></blockquote>
<synopsis><indexterm role="fn"><primary>PDF.POISSON</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>PDF.POISSON</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>mu</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>CDF.POISSON</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>CDF.POISSON</function> (<replaceable><replaceable>x</replaceable></replaceable>, <replaceable><replaceable>mu</replaceable></replaceable>)</synopsis>
<synopsis><indexterm role="fn"><primary>RV.POISSON</primary></indexterm><phrase role="category"><emphasis role="bold">Function</emphasis>:</phrase> <returnvalue></returnvalue> <function>RV.POISSON</function> (<replaceable><replaceable>mu</replaceable></replaceable>)</synopsis>
<blockquote><para>Poisson distribution with mean <replaceable>mu</replaceable>.  Constraints: <replaceable>mu</replaceable> &gt; 0,
integer <replaceable>x</replaceable> &gt;= 0.
</para></blockquote>
</sect3>
</sect2>
</sect1>
<sect1 label="7.8" id="Order-of-Operations">
<title>Operator Precedence</title>
<indexterm role="cp"><primary>operator precedence</primary></indexterm>
<indexterm role="cp"><primary>precedence, operator</primary></indexterm>
<indexterm role="cp"><primary>order of operations</primary></indexterm>
<indexterm role="cp"><primary>operations, order of</primary></indexterm>

<para>The following table describes operator precedence.  Smaller-numbered
levels in the table have higher precedence.  Within a level,
operations are always performed from left to right.  The first
occurrence of &#8216;<literal>-</literal>&#8217; represents unary negation, the second binary
subtraction.
</para>
<orderedlist numeration="arabic"><listitem><para><literal>(  )</literal>
</para></listitem><listitem><para><literal>**</literal>
</para></listitem><listitem><para><literal>-</literal>
</para></listitem><listitem><para><literal>*  /</literal>
</para></listitem><listitem><para><literal>+  -</literal>
</para></listitem><listitem><para><literal>EQ  GE  GT  LE  LT  NE</literal>
</para></listitem><listitem><para><literal>AND  NOT  OR</literal>
</para></listitem></orderedlist><!-- (modify-syntax-entry ?_ "w") -->
<!-- (modify-syntax-entry ?' "'") -->
<!-- (modify-syntax-entry ?@ "'") -->


</sect1>
</chapter>
<chapter label="8" id="Data-Input-and-Output">
<title>Data Input and Output</title>
<indexterm role="cp"><primary>input</primary></indexterm>
<indexterm role="cp"><primary>output</primary></indexterm>
<indexterm role="cp"><primary>data</primary></indexterm>
<indexterm role="cp"><primary>cases</primary></indexterm>
<indexterm role="cp"><primary>observations</primary></indexterm>

<para>Data are the focus of the pspp language.  
Each datum  belongs to a <firstterm>case</firstterm> (also called an <firstterm>observation</firstterm>).
Each case represents an individual or &#8220;experimental unit&#8221;.
For example, in the results of a survey, the names of the respondents,
their sex, age, 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.
There are alternative commands to  read data from predefined sources
such as system files or databases (See <link linkend="GET">GET DATA</link>.)
</para>
<note><para>These commands tell pspp how to read data, but the data will not
actually be read until a procedure is executed.
</para></note>

<sect1 label="8.1" id="BEGIN-DATA">
<title>BEGIN DATA</title>
<indexterm role="vr"><primary>BEGIN DATA</primary></indexterm>
<indexterm role="vr"><primary>END DATA</primary></indexterm>
<indexterm role="cp"><primary>Embedding data in syntax files</primary></indexterm>
<indexterm role="cp"><primary>Data, embedding in syntax files</primary></indexterm>

<literallayout>BEGIN DATA.
&#8230;
END DATA.
</literallayout>
<para><literal>BEGIN DATA</literal> and <literal>END DATA</literal> can be used to embed raw ASCII
data in a pspp syntax file.  <literal>DATA LIST</literal> or another input
procedure must be used before <literal>BEGIN DATA</literal> (see <link linkend="DATA-LIST">DATA LIST</link>).
<literal>BEGIN DATA</literal> and <literal>END DATA</literal> must be used together.  <literal>END
DATA</literal> must appear by itself on a single line, with no leading
white space and exactly one space between the words <literal>END</literal> and
<literal>DATA</literal>, like this:
</para>
<screen>END DATA.
</screen>
</sect1>
<sect1 label="8.2" id="CLOSE-FILE-HANDLE">
<title>CLOSE FILE HANDLE</title>

<literallayout>CLOSE FILE HANDLE <replaceable>handle_name</replaceable>.
</literallayout>
<para><literal>CLOSE FILE HANDLE</literal> disassociates the name of a file handle with a
given file.  The only specification is the name of the handle to close.
Afterward
<literal>FILE HANDLE</literal>.
</para>
<para>The file named INLINE, which represents data entered between <literal>BEGIN
DATA</literal> and <literal>END DATA</literal>, cannot be closed.  Attempts to close it with
<literal>CLOSE FILE HANDLE</literal> have no effect.
</para>
<para><literal>CLOSE FILE HANDLE</literal> is a pspp extension.
</para>
</sect1>
<sect1 label="8.3" id="DATAFILE-ATTRIBUTE">
<title>DATAFILE ATTRIBUTE</title>
<indexterm role="vr"><primary>DATAFILE ATTRIBUTE</primary></indexterm>

<literallayout>DATAFILE ATTRIBUTE
         ATTRIBUTE=<replaceable>name</replaceable>(&#8217;<replaceable>value</replaceable>&#8217;) [<replaceable>name</replaceable>(&#8217;<replaceable>value</replaceable>&#8217;)]&#8230;
         ATTRIBUTE=<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>(&#8217;<replaceable>value</replaceable>&#8217;) [<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>(&#8217;<replaceable>value</replaceable>&#8217;)]&#8230;
         DELETE=<replaceable>name</replaceable> [<replaceable>name</replaceable>]&#8230;
         DELETE=<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis> [<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>]&#8230;
</literallayout>
<para><literal>DATAFILE ATTRIBUTE</literal> adds, modifies, or removes user-defined
attributes associated with the active dataset.  Custom data file
attributes are not interpreted by pspp, but they are saved as part of
system files and may be used by other software that reads them.
</para>
<para>Use the <literal>ATTRIBUTE</literal> subcommand to add or modify a custom data file
attribute.  Specify the name of the attribute as an identifier
(see <link linkend="Tokens">Tokens</link>), followed by the desired value, in parentheses, as a
quoted string.  Attribute names that begin with <literal>$</literal> are reserved
for pspp&#8217;s internal use, and attribute names that begin with <literal>@</literal>
or <literal>$@</literal> are not displayed by most pspp commands that display
other attributes.  Other attribute names are not treated specially.
</para>
<para>Attributes may also be organized into arrays.  To assign to an array
element, add an integer array index enclosed in square brackets
(<literal>[</literal> and <literal>]</literal>) between the attribute name and value.  Array
indexes start at 1, not 0.  An attribute array that has a single
element (number 1) is not distinguished from a non-array attribute.
</para>
<para>Use the <literal>DELETE</literal> subcommand to delete an attribute.  Specify an
attribute name by itself to delete an entire attribute, including all
array elements for attribute arrays.  Specify an attribute name
followed by an array index in square brackets to delete a single
element of an attribute array.  In the latter case, all the array
elements numbered higher than the deleted element are shifted down,
filling the vacated position.
</para>
<para>To associate custom attributes with particular variables, instead of
with the entire active dataset, use <literal>VARIABLE ATTRIBUTE</literal>
(see <link linkend="VARIABLE-ATTRIBUTE">VARIABLE ATTRIBUTE</link>) instead.
</para>
<para><literal>DATAFILE ATTRIBUTE</literal> takes effect immediately.  It is not affected
by conditional and looping structures such as <literal>DO IF</literal> or
<literal>LOOP</literal>.
</para>
</sect1>
<sect1 label="8.4" id="DATASET">
<title>DATASET commands</title>
<indexterm role="vr"><primary>DATASET</primary></indexterm>

<literallayout>DATASET NAME <replaceable>name</replaceable> [WINDOW={ASIS,FRONT}].
DATASET ACTIVATE <replaceable>name</replaceable> [WINDOW={ASIS,FRONT}].
DATASET COPY <replaceable>name</replaceable> [WINDOW={MINIMIZED,HIDDEN,FRONT}].
DATASET DECLARE <replaceable>name</replaceable> [WINDOW={MINIMIZED,HIDDEN,FRONT}].
DATASET CLOSE {<replaceable>name</replaceable>,*,ALL}.
DATASET DISPLAY.
</literallayout>
<para>The <literal>DATASET</literal> commands simplify use of multiple datasets within a
pspp session.  They allow datasets to be created and destroyed.  At
any given time, most pspp commands work with a single dataset, called
the active dataset.
</para>
<indexterm role="vr"><primary>DATASET NAME</primary></indexterm>
<para>The DATASET NAME command gives the active dataset the specified name, or
if it already had a name, it renames it.  If another dataset already
had the given name, that dataset is deleted.
</para>
<indexterm role="vr"><primary>DATASET ACTIVATE</primary></indexterm>
<para>The DATASET ACTIVATE command selects the named dataset, which must
already exist, as the active dataset.  Before switching the active
dataset, any pending transformations are executed, as if <literal>EXECUTE</literal>
had been specified.  If the active dataset is unnamed before
switching, then it is deleted and becomes unavailable after switching.
</para>
<indexterm role="vr"><primary>DATASET COPY</primary></indexterm>
<para>The DATASET COPY command creates a new dataset with the specified
name, whose contents are a copy of the active dataset.  Any pending
transformations are executed, as if <literal>EXECUTE</literal> had been specified,
before making the copy.  If a dataset with the given name already
exists, it is replaced.  If the name is the name of the active
dataset, then the active dataset becomes unnamed.
</para>
<indexterm role="vr"><primary>DATASET DECLARE</primary></indexterm>
<para>The DATASET DECLARE command creates a new dataset that is initially
&#8220;empty,&#8221; that is, it has no dictionary or data.  If a dataset with
the given name already exists, this has no effect.  The new dataset
can be used with commands that support output to a dataset,
e.g. AGGREGATE (see <link linkend="AGGREGATE">AGGREGATE</link>).
</para>
<indexterm role="vr"><primary>DATASET CLOSE</primary></indexterm>
<para>The DATASET CLOSE command deletes a dataset.  If the active dataset is
specified by name, or if &#8216;<literal>*</literal>&#8217; is specified, then the active
dataset becomes unnamed.  If a different dataset is specified by name,
then it is deleted and becomes unavailable.  Specifying ALL deletes
all datasets except for the active dataset, which becomes unnamed.
</para>
<indexterm role="vr"><primary>DATASET DISPLAY</primary></indexterm>
<para>The DATASET DISPLAY command lists all the currently defined datasets.
</para>
<para>Many DATASET commands accept an optional <literal>WINDOW</literal> subcommand.  In the
psppIRE GUI, the value given for this subcommand influences how the
dataset&#8217;s window is displayed.  Outside the GUI, the <literal>WINDOW</literal> subcommand
has no effect.  The valid values are:
</para>
<variablelist><varlistentry><term>ASIS
</term><listitem><para>Do not change how the window is displayed.  This is the default for
DATASET NAME and DATASET ACTIVATE.
</para>
</listitem></varlistentry><varlistentry><term>FRONT
</term><listitem><para>Raise the dataset&#8217;s window to the top.  Make it the default dataset
for running syntax.
</para>
</listitem></varlistentry><varlistentry><term>MINIMIZED
</term><listitem><para>Display the window &#8220;minimized&#8221; to an icon.  Prefer other datasets
for running syntax.  This is the default for DATASET COPY and DATASET
DECLARE.
</para>
</listitem></varlistentry><varlistentry><term>HIDDEN
</term><listitem><para>Hide the dataset&#8217;s window.  Prefer other datasets for running syntax.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="8.5" id="DATA-LIST">
<title>DATA LIST</title>
<indexterm role="vr"><primary>DATA LIST</primary></indexterm>
<indexterm role="cp"><primary>reading data from a file</primary></indexterm>
<indexterm role="cp"><primary>data, reading from a file</primary></indexterm>
<indexterm role="cp"><primary>data, embedding in syntax files</primary></indexterm>
<indexterm role="cp"><primary>embedding data in syntax files</primary></indexterm>

<para>Used to read text or binary data, <literal>DATA LIST</literal> is the most
fundamental data-reading command.  Even the more sophisticated input
methods use <literal>DATA LIST</literal> commands as a building block.
Understanding <literal>DATA LIST</literal> is important to understanding how to use
pspp to read your data files.
</para>
<para>There are two major variants of <literal>DATA LIST</literal>, 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.
</para>
<para>Each form of <literal>DATA LIST</literal> is described in detail below.
</para>
<para>See <link linkend="GET-DATA">GET DATA</link>, for a command that offers a few enhancements over
DATA LIST and that may be substituted for DATA LIST in many
situations.
</para>

<sect2 label="8.5.1" id="DATA-LIST-FIXED">
<title>DATA LIST FIXED</title>
<indexterm role="vr"><primary>DATA LIST FIXED</primary></indexterm>
<indexterm role="cp"><primary>reading fixed-format data</primary></indexterm>
<indexterm role="cp"><primary>fixed-format data, reading</primary></indexterm>
<indexterm role="cp"><primary>data, fixed-format, reading</primary></indexterm>
<indexterm role="cp"><primary>embedding fixed-format data</primary></indexterm>

<literallayout>DATA LIST [FIXED]
        {TABLE,NOTABLE}
        [FILE=&#8217;<replaceable>file_name</replaceable>&#8217; [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]]
        [RECORDS=<replaceable>record_count</replaceable>]
        [END=<replaceable>end_var</replaceable>]
        [SKIP=<replaceable>record_count</replaceable>]
        /[line_no] <replaceable>var_spec</replaceable>&#8230;

where each <replaceable>var_spec</replaceable> takes one of the forms
        <replaceable>var_list</replaceable> <replaceable>start</replaceable>-<replaceable>end</replaceable> [<replaceable>type_spec</replaceable>]
        <replaceable>var_list</replaceable> (<replaceable>fortran_spec</replaceable>)
</literallayout>
<para><literal>DATA LIST FIXED</literal> 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.
</para>
<para>The <literal>FILE</literal> subcommand must be used if input is to be taken from an
external file.  It may be used to specify a file name as a string or a
file handle (see <link linkend="File-Handles">File Handles</link>).  If the <literal>FILE</literal> subcommand is not used,
then input is assumed to be specified within the command file using
<literal>BEGIN DATA</literal>&#8230;<literal>END DATA</literal> (see <link linkend="BEGIN-DATA">BEGIN DATA</link>).
The <literal>ENCODING</literal> subcommand may only be used if the <literal>FILE</literal>
subcommand is also used.  It specifies the character encoding of the
file.  See <link linkend="INSERT">INSERT</link>, for information on supported encodings.
</para>
<para>The optional <literal>RECORDS</literal> subcommand, which takes a single integer as an
argument, is used to specify the number of lines per record.
If <literal>RECORDS</literal>
is not specified, then the number of lines per record is calculated from
the list of variable specifications later in <literal>DATA LIST</literal>.
</para>
<para>The <literal>END</literal> subcommand is only useful in conjunction with <literal>INPUT
PROGRAM</literal>.  See <link linkend="INPUT-PROGRAM">INPUT PROGRAM</link>, for details.
</para>
<para>The optional <literal>SKIP</literal> subcommand specifies a number of records to skip at
the beginning of an input file.  It can be used to skip over a row
that contains variable names, for example.
</para>
<para><literal>DATA LIST</literal> can optionally output a table describing how the data file
will be read.  The <literal>TABLE</literal> subcommand enables this output, and
<literal>NOTABLE</literal> disables it.  The default is to output the table.
</para>
<para>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 (&#8216;<literal>/</literal>&#8217;).
Optionally, a line number may follow the slash.  Following, any number
of variable specifications may be present.
</para>
<para>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 be specified using the <literal>DATA LIST</literal> <literal>TO</literal> convention
(see <link linkend="Sets-of-Variables">Sets of
Variables</link>).  There are two ways to specify the location of the variable
on the line: columnar style and FORTRAN style.
</para>
<para>In columnar style, the starting column and ending column for the field
are specified after the variable name, separated by a dash (&#8216;<literal>-</literal>&#8217;).
For instance, the third through fifth columns on a line would be
specified &#8216;<literal>3-5</literal>&#8217;.  By default, variables are considered to be in
&#8216;<literal>F</literal>&#8217; format (see <link linkend="Input-and-Output-Formats">Input and Output Formats</link>).  (This default can be
changed; see <link linkend="SET">SET</link> for more information.)
</para>
<para>In columnar style, to use a variable format other than the default,
specify the format type in parentheses after the column numbers.  For
instance, for alphanumeric &#8216;<literal>A</literal>&#8217; format, use &#8216;<literal>(A)</literal>&#8217;.  
</para>
<para>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 &#8216;<literal>1234</literal>&#8217; should be interpreted as
having the value 12.34.  Then this field has two implied decimal places,
and the corresponding specification would be &#8216;<literal>(2)</literal>&#8217;.  If a field
that has implied decimal places contains a decimal point, then the
implied decimal places are not applied.
</para>
<para>Changing the variable format and adding implied decimal places can be
done together; for instance, &#8216;<literal>(N,5)</literal>&#8217;.
</para>
<para>When using columnar 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.
</para>
<para>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.
</para>
<para>Implied decimal places also exist in FORTRAN style.  A format
specification with <replaceable>d</replaceable> decimal places also has <replaceable>d</replaceable> implied
decimal places.
</para>
<para>In addition to the standard format specifiers (see <link linkend="Input-and-Output-Formats">Input and Output
Formats</link>), FORTRAN style defines some extensions:
</para>
<variablelist><varlistentry><term><literal>X</literal>
</term><listitem><para>Advance the current column on this line by one character position.
</para>
</listitem></varlistentry><varlistentry><term><literal>T</literal><replaceable>x</replaceable>
</term><listitem><para>Set the current column on this line to column <replaceable>x</replaceable>, with column
numbers considered to begin with 1 at the left margin.
</para>
</listitem></varlistentry><varlistentry><term><literal>NEWREC</literal><replaceable>x</replaceable>
</term><listitem><para>Skip forward <replaceable>x</replaceable> lines in the current record, resetting the active
column to the left margin.
</para>
</listitem></varlistentry><varlistentry><term>Repeat count
</term><listitem><para>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.
</para>
</listitem></varlistentry><varlistentry><term>(<replaceable>spec1</replaceable>, &#8230;, <replaceable>specN</replaceable>)
</term><listitem><para>Group the given specifiers together.  This is most useful when preceded
by a repeat count.  Groups may be nested arbitrarily.
</para></listitem></varlistentry></variablelist>
<para>FORTRAN and columnar styles may be freely intermixed.  Columnar style
leaves the active column immediately after the ending column
specified.  Record motion using <literal>NEWREC</literal> in FORTRAN style also
applies to later FORTRAN and columnar specifiers.
</para> 

<sect3 label="" id="DATA-LIST-FIXED-Examples">
<title>Examples</title>

<orderedlist numeration="arabic"><listitem><screen>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.
</screen>
<para>Defines the following variables:
</para>
<itemizedlist><listitem><para><literal>NAME</literal>, a 10-character-wide string variable, in columns 1
through 10.
</para>
</listitem><listitem><para><literal>INFO1</literal>, a numeric variable, in columns 12 through 13.
</para>
</listitem><listitem><para><literal>INFO2</literal>, a numeric variable, in columns 14 through 15.
</para>
</listitem><listitem><para><literal>INFO3</literal>, a numeric variable, in columns 16 through 17.
</para></listitem></itemizedlist>
<para>The <literal>BEGIN DATA</literal>/<literal>END DATA</literal> commands cause three cases to be
defined:
</para>
<screen>Case   NAME         INFO1   INFO2   INFO3
   1   John Smith     10      23      11
   2   Bob Arnold     12      20      15
   3   Bill Yates      9      18       6
</screen>
<para>The <literal>TABLE</literal> keyword causes pspp to print out a table
describing the four variables defined.
</para>
</listitem><listitem><screen>DAT LIS FIL=&quot;survey.dat&quot;
        /ID 1-5 NAME 7-36 (A) SURNAME 38-67 (A) MINITIAL 69 (A)
        /Q01 TO Q50 7-56
        /.
</screen>
<para>Defines the following variables:
</para>
<itemizedlist><listitem><para><literal>ID</literal>, a numeric variable, in columns 1-5 of the first record.
</para>
</listitem><listitem><para><literal>NAME</literal>, a 30-character string variable, in columns 7-36 of the
first record.
</para>
</listitem><listitem><para><literal>SURNAME</literal>, a 30-character string variable, in columns 38-67 of
the first record.
</para>
</listitem><listitem><para><literal>MINITIAL</literal>, a 1-character string variable, in column 69 of
the first record.
</para>
</listitem><listitem><para>Fifty variables <literal>Q01</literal>, <literal>Q02</literal>, <literal>Q03</literal>, &#8230;, <literal>Q49</literal>,
<literal>Q50</literal>, all numeric, <literal>Q01</literal> in column 7, <literal>Q02</literal> in column 8,
&#8230;, <literal>Q49</literal> in column 55, <literal>Q50</literal> in column 56, all in the second
record.
</para></listitem></itemizedlist>
<para>Cases are separated by a blank record.
</para>
<para>Data is read from file <filename>survey.dat</filename> in the current directory.
</para>
<para>This example shows keywords abbreviated to their first 3 letters.
</para>
</listitem></orderedlist>
</sect3>
</sect2>
<sect2 label="8.5.2" id="DATA-LIST-FREE">
<title>DATA LIST FREE</title>
<indexterm role="vr"><primary>DATA LIST FREE</primary></indexterm>

<literallayout>DATA LIST FREE
        [({TAB,&#8217;<replaceable>c</replaceable>&#8217;}, &#8230;)]
        [{NOTABLE,TABLE}]
        [FILE=&#8217;<replaceable>file_name</replaceable>&#8217; [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]]
        [SKIP=<replaceable>record_cnt</replaceable>]
        /<replaceable>var_spec</replaceable>&#8230;

where each <replaceable>var_spec</replaceable> takes one of the forms
        <replaceable>var_list</replaceable> [(<replaceable>type_spec</replaceable>)]
        <replaceable>var_list</replaceable> *
</literallayout>
<para>In free format, the input data is, by default, structured as a series
of fields separated by spaces, tabs, or line breaks.
If the current <literal>DECIMAL</literal> separator is <literal>DOT</literal> (see <link linkend="SET">SET</link>),
then commas are also treated as field separators.
Each
field&#8217;s content may be unquoted, or it may be quoted with a pairs of
apostrophes (&#8216;<literal>'</literal>&#8217;) or double quotes (&#8216;<literal>&quot;</literal>&#8217;).  Unquoted white
space separates fields but is not part of any field.  Any mix of
spaces, tabs, and line breaks is equivalent to a single space for the
purpose of separating fields, but consecutive commas will skip a
field.
</para>
<para>Alternatively, delimiters can be specified explicitly, as a
parenthesized, comma-separated list of single-character strings
immediately following FREE.  The word TAB may also be used to specify
a tab character as a delimiter.  When delimiters are specified
explicitly, only the given characters, plus line breaks, separate
fields.  Furthermore, leading spaces at the beginnings of fields are
not trimmed, consecutive delimiters define empty fields, and no form
of quoting is allowed.
</para>
<para>The <literal>NOTABLE</literal> and <literal>TABLE</literal> subcommands are as in <literal>DATA LIST FIXED</literal> above.
<literal>NOTABLE</literal> is the default.
</para>
<para>The <literal>FILE</literal>, <literal>SKIP</literal>, and <literal>ENCODING</literal> subcommands
are as in <literal>DATA LIST FIXED</literal> above.
</para>
<para>The variables to be parsed are given as a single list of variable names.
This list must be introduced by a single slash (&#8216;<literal>/</literal>&#8217;).  The set of
variable names may contain format specifications in parentheses
(see <link linkend="Input-and-Output-Formats">Input and Output Formats</link>).  Format specifications apply to all
variables back to the previous parenthesized format specification.  
</para>
<para>In addition, an asterisk may be used to indicate that all variables
preceding it are to have input/output format &#8216;<literal>F8.0</literal>&#8217;.
</para>
<para>Specified field widths are ignored on input, although all normal limits
on field width apply, but they are honored on output.
</para>
</sect2>
<sect2 label="8.5.3" id="DATA-LIST-LIST">
<title>DATA LIST LIST</title>
<indexterm role="vr"><primary>DATA LIST LIST</primary></indexterm>

<literallayout>DATA LIST LIST
        [({TAB,&#8217;<replaceable>c</replaceable>&#8217;}, &#8230;)]
        [{NOTABLE,TABLE}]
        [FILE=&#8217;<replaceable>file_name</replaceable>&#8217; [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]]
        [SKIP=<replaceable>record_count</replaceable>]
        /<replaceable>var_spec</replaceable>&#8230;

where each <replaceable>var_spec</replaceable> takes one of the forms
        <replaceable>var_list</replaceable> [(<replaceable>type_spec</replaceable>)]
        <replaceable>var_list</replaceable> *
</literallayout>
<para>With one exception, <literal>DATA LIST LIST</literal> is syntactically and
semantically equivalent to <literal>DATA LIST FREE</literal>.  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.
</para>
</sect2>
</sect1>
<sect1 label="8.6" id="END-CASE">
<title>END CASE</title>
<indexterm role="vr"><primary>END CASE</primary></indexterm>

<literallayout>END CASE.
</literallayout>
<para><literal>END CASE</literal> is used only within <literal>INPUT PROGRAM</literal> to output the
current case.  See <link linkend="INPUT-PROGRAM">INPUT PROGRAM</link>, for details.
</para>
</sect1>
<sect1 label="8.7" id="END-FILE">
<title>END FILE</title>
<indexterm role="vr"><primary>END FILE</primary></indexterm>

<literallayout>END FILE.
</literallayout>
<para><literal>END FILE</literal> is used only within <literal>INPUT PROGRAM</literal> to terminate
the current input program.  See <link linkend="INPUT-PROGRAM">INPUT PROGRAM</link>.
</para>
</sect1>
<sect1 label="8.8" id="FILE-HANDLE">
<title>FILE HANDLE</title>
<indexterm role="vr"><primary>FILE HANDLE</primary></indexterm>

<literallayout>For text files:
        FILE HANDLE <replaceable>handle_name</replaceable>
                /NAME=&#8217;<replaceable>file_name</replaceable>
                [/MODE=CHARACTER]
                [/ENDS={CR,CRLF}]
                /TABWIDTH=<replaceable>tab_width</replaceable>
                [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]

For binary files in native encoding with fixed-length records:
        FILE HANDLE <replaceable>handle_name</replaceable>
                /NAME=&#8217;<replaceable>file_name</replaceable>&#8217;
                /MODE=IMAGE
                [/LRECL=<replaceable>rec_len</replaceable>]
                [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]

For binary files in native encoding with variable-length records:
        FILE HANDLE <replaceable>handle_name</replaceable>
                /NAME=&#8217;<replaceable>file_name</replaceable>&#8217;
                /MODE=BINARY
                [/LRECL=<replaceable>rec_len</replaceable>]
                [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]

For binary files encoded in EBCDIC:
        FILE HANDLE <replaceable>handle_name</replaceable>
                /NAME=&#8217;<replaceable>file_name</replaceable>&#8217;
                /MODE=360
                /RECFORM={FIXED,VARIABLE,SPANNED}
                [/LRECL=<replaceable>rec_len</replaceable>]
                [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]
</literallayout>
<para>Use <literal>FILE HANDLE</literal> to associate a file handle name with a file and
its attributes, so that later commands can refer to the file by its
handle name.  Names of text files can be specified directly on
commands that access files, so that <literal>FILE HANDLE</literal> is only needed when a
file is not an ordinary file containing lines of text.  However,
<literal>FILE HANDLE</literal> may be used even for text files, and it may be
easier to specify a file&#8217;s name once and later refer to it by an
abstract handle.
</para>
<para>Specify the file handle name as the identifier immediately following the
<literal>FILE HANDLE</literal> command name.  The identifier INLINE is reserved for
representing data embedded in the syntax file (see <link linkend="BEGIN-DATA">BEGIN DATA</link>) The
file handle name must not already have been used in a previous
invocation of <literal>FILE HANDLE</literal>, unless it has been closed by an
intervening command (see <link linkend="CLOSE-FILE-HANDLE">CLOSE FILE HANDLE</link>).
</para>
<para>The effect and syntax of <literal>FILE HANDLE</literal> depends on the selected MODE:
</para>
<itemizedlist><listitem><para>In CHARACTER mode, the default, the data file is read as a text file.
Each text line is read as one record.
</para>
<para>In CHARACTER mode only, tabs are expanded to spaces by input programs,
except by <literal>DATA LIST FREE</literal> with explicitly specified delimiters.
Each tab is 4 characters wide by default, but TABWIDTH (a pspp
extension) may be used to specify an alternate width.  Use a TABWIDTH
of 0 to suppress tab expansion.
</para>
<para>A file written in CHARACTER mode by default uses the line ends of the
system on which PSPP is running, that is, on Windows, the default is
CR LF line ends, and on other systems the default is LF only.  Specify
ENDS as CR or CRLF to override the default.  PSPP reads files using
either convention on any kind of system, regardless of ENDS.
</para>
</listitem><listitem><para>In IMAGE mode, the data file is treated as a series of fixed-length
binary records.  LRECL should be used to specify the record length in
bytes, with a default of 1024.  On input, it is an error if an IMAGE
file&#8217;s length is not a integer multiple of the record length.  On
output, each record is padded with spaces or truncated, if necessary,
to make it exactly the correct length.
</para>
</listitem><listitem><para>In BINARY mode, the data file is treated as a series of
variable-length binary records.  LRECL may be specified, but its value
is ignored.  The data for each record is both preceded and followed by
a 32-bit signed integer in little-endian byte order that specifies the
length of the record.  (This redundancy permits records in these
files to be efficiently read in reverse order, although pspp always
reads them in forward order.)  The length does not include either
integer.
</para>
</listitem><listitem><para>Mode 360 reads and writes files in formats first used for tapes in the
1960s on IBM mainframe operating systems and still supported today by
the modern successors of those operating systems.  For more
information, see <citetitle>OS/400 Tape and Diskette Device Programming</citetitle>,
available on IBM&#8217;s website.
</para>
<para>Alphanumeric data in mode 360 files are encoded in EBCDIC.  pspp
translates EBCDIC to or from the host&#8217;s native format as necessary on
input or output, using an ASCII/EBCDIC translation that is one-to-one,
so that a &#8220;round trip&#8221; from ASCII to EBCDIC back to ASCII, or vice
versa, always yields exactly the original data.
</para>
<para>The <literal>RECFORM</literal> subcommand is required in mode 360.  The precise file
format depends on its setting:
</para>
<variablelist><varlistentry><term>F
</term><term>FIXED
</term><listitem><para>This record format is equivalent to IMAGE mode, except for EBCDIC
translation.
</para>
<para>IBM documentation calls this <literal>*F</literal> (fixed-length, deblocked)
format.
</para>
</listitem></varlistentry><varlistentry><term>V
</term><term>VARIABLE
</term><listitem><para>The file comprises a sequence of zero or more variable-length blocks.
Each block begins with a 4-byte <firstterm>block descriptor word</firstterm> (BDW).
The first two bytes of the BDW are an unsigned integer in big-endian
byte order that specifies the length of the block, including the BDW
itself.  The other two bytes of the BDW are ignored on input and
written as zeros on output.
</para>
<para>Following the BDW, the remainder of each block is a sequence of one or
more variable-length records, each of which in turn begins with a
4-byte <firstterm>record descriptor word</firstterm> (RDW) that has the same format as
the BDW.  Following the RDW, the remainder of each record is the
record data.
</para>
<para>The maximum length of a record in VARIABLE mode is 65,527 bytes:
65,535 bytes (the maximum value of a 16-bit unsigned integer), minus 4
bytes for the BDW, minus 4 bytes for the RDW.
</para>
<para>In mode VARIABLE, LRECL specifies a maximum, not a fixed, record
length, in bytes.  The default is 8,192.
</para>
<para>IBM documentation calls this <literal>*VB</literal> (variable-length, blocked,
unspanned) format.
</para>
</listitem></varlistentry><varlistentry><term>VS
</term><term>SPANNED
</term><listitem><para>The file format is like that of VARIABLE mode, except that logical
records may be split among multiple physical records (called
<firstterm>segments</firstterm>) or blocks.  In SPANNED mode, the third byte of each
RDW is called the segment control character (SCC).  Odd SCC values
cause the segment to be appended to a record buffer maintained in
memory; even values also append the segment and then flush its
contents to the input procedure.  Canonically, SCC value 0 designates
a record not spanned among multiple segments, and values 1 through 3
designate the first segment, the last segment, or an intermediate
segment, respectively, within a multi-segment record.  The record
buffer is also flushed at end of file regardless of the final record&#8217;s
SCC.
</para>
<para>The maximum length of a logical record in VARIABLE mode is limited
only by memory available to pspp.  Segments are limited to 65,527
bytes, as in VARIABLE mode.
</para>
<para>This format is similar to what IBM documentation call <literal>*VS</literal>
(variable-length, deblocked, spanned) format.
</para></listitem></varlistentry></variablelist>
<para>In mode 360, fields of type A that extend beyond the end of a record
read from disk are padded with spaces in the host&#8217;s native character
set, which are then translated from EBCDIC to the native character
set.  Thus, when the host&#8217;s native character set is based on ASCII,
these fields are effectively padded with character <literal>X'80'</literal>.  This
wart is implemented for compatibility.
</para></listitem></itemizedlist>
<para>The <literal>NAME</literal> subcommand specifies the name of the file associated with the
handle.  It is required in all modes but SCRATCH mode, in which its
use is forbidden.
</para>
<para>The ENCODING subcommand specifies the encoding of text in the file.
For reading text files in CHARACTER mode, all of the forms described
for ENCODING on the INSERT command are supported (see <link linkend="INSERT">INSERT</link>).
For reading in other file-based modes, encoding autodetection is not
supported; if the specified encoding requests autodetection then the
default encoding will be used.  This is also true when a file handle
is used for writing a file in any mode.
</para>
</sect1>
<sect1 label="8.9" id="INPUT-PROGRAM">
<title>INPUT PROGRAM</title>
<indexterm role="vr"><primary>INPUT PROGRAM</primary></indexterm>

<literallayout>INPUT PROGRAM.
&#8230; input commands &#8230;
END INPUT PROGRAM.
</literallayout>
<para><literal>INPUT PROGRAM</literal>&#8230;<literal>END INPUT PROGRAM</literal> specifies a
complex input program.  By placing data input commands within <literal>INPUT
PROGRAM</literal>, pspp programs can take advantage of more complex file
structures than available with only <literal>DATA LIST</literal>.
</para>
<para>The first sort of extended input program is to simply put multiple <literal>DATA
LIST</literal> commands within the <literal>INPUT PROGRAM</literal>.  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.
</para>
<para>Transformations, such as conditional and looping constructs, can also be
included within <literal>INPUT PROGRAM</literal>.  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.
</para>
<para>To prevent <literal>INPUT PROGRAM</literal> from terminating at the first end of
file, use
the <literal>END</literal> subcommand on <literal>DATA LIST</literal>.  This subcommand takes a
variable name,
which should be a numeric scratch variable (see <link linkend="Scratch-Variables">Scratch Variables</link>).
(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.
</para>
<para>Two additional commands are useful in conjunction with <literal>INPUT PROGRAM</literal>.
<literal>END CASE</literal> is the first.  Normally each loop through the
<literal>INPUT PROGRAM</literal>
structure produces one case.  <literal>END CASE</literal> controls exactly
when cases are output.  When <literal>END CASE</literal> is used, looping from the end of
<literal>INPUT PROGRAM</literal> to the beginning does not cause a case to be output.
</para>
<para><literal>END FILE</literal> is the second.  When the <literal>END</literal> subcommand is used on <literal>DATA
LIST</literal>, there is no way for the <literal>INPUT PROGRAM</literal> construct to stop
looping,
so an infinite loop results.  <literal>END FILE</literal>, when executed,
stops the flow of input data and passes out of the <literal>INPUT PROGRAM</literal>
structure.
</para>
<para><literal>INPUT PROGRAM</literal> must contain at least one <literal>DATA LIST</literal> or
<literal>END FILE</literal> command.
</para>
<para>All this is very confusing.  A few examples should help to clarify.
</para>
<!-- If you change this example, change the regression test1 in -->
<!-- tests/command/input-program.sh to match. -->
<screen>INPUT PROGRAM.
        DATA LIST NOTABLE FILE='a.data'/X 1-10.
        DATA LIST NOTABLE FILE='b.data'/Y 1-10.
END INPUT PROGRAM.
LIST.
</screen>
<para>The example above reads variable X from file <filename>a.data</filename> and variable
Y from file <filename>b.data</filename>.  If one file is shorter than the other then
the extra data in the longer file is ignored.
</para>
<!-- If you change this example, change the regression test2 in -->
<!-- tests/command/input-program.sh to match. -->
<screen>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.
</screen>
<para>The above example reads variable X from <filename>a.data</filename> and variable Y from
<filename>b.data</filename>.  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.
</para>
<!-- If you change this example, change the regression test3 in -->
<!-- tests/command/input-program.sh to match. -->
<screen>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.
</screen>
<para>The above example reads data from file <filename>a.data</filename>, then from
<filename>b.data</filename>, and concatenates them into a single active dataset.
</para>
<!-- If you change this example, change the regression test4 in -->
<!-- tests/command/input-program.sh to match. -->
<screen>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.
</screen>
<para>The above example does the same thing as the previous example, in a
different way.
</para>
<!-- If you change this example, make similar changes to the regression -->
<!-- test5 in tests/command/input-program.sh. -->
<screen>INPUT PROGRAM.
        LOOP #I=1 TO 50.
                COMPUTE X=UNIFORM(10).
                END CASE.
        END LOOP.
        END FILE.
END INPUT PROGRAM.
LIST/FORMAT=NUMBERED.
</screen>
<para>The above example causes an active dataset to be created consisting of 50
random variates between 0 and 10.
</para>
</sect1>
<sect1 label="8.10" id="LIST">
<title>LIST</title>
<indexterm role="vr"><primary>LIST</primary></indexterm>

<literallayout>LIST
        /VARIABLES=<replaceable>var_list</replaceable>
        /CASES=FROM <replaceable>start_index</replaceable> TO <replaceable>end_index</replaceable> BY <replaceable>incr_index</replaceable>
        /FORMAT={UNNUMBERED,NUMBERED} {WRAP,SINGLE}
</literallayout>
<para>The <literal>LIST</literal> procedure prints the values of specified variables to the
listing file.
</para>
<para>The <literal>VARIABLES</literal> subcommand specifies the variables whose values are to be
printed.  Keyword VARIABLES is optional.  If <literal>VARIABLES</literal> subcommand is not
specified then all variables in the active dataset are printed.
</para>
<para>The <literal>CASES</literal> subcommand can be used to specify a subset of cases to be
printed.  Specify <literal>FROM</literal> and the case number of the first case to print,
<literal>TO</literal> and the case number of the last case to print, and <literal>BY</literal> and the number
of cases to advance between printing cases, or any subset of those
settings.  If <literal>CASES</literal> is not specified then all cases are printed.
</para>
<para>The <literal>FORMAT</literal> subcommand can be used to change the output format.  <literal>NUMBERED</literal>
will print case numbers along with each case; <literal>UNNUMBERED</literal>, the default,
causes the case numbers to be omitted.  The <literal>WRAP</literal> and <literal>SINGLE</literal> settings are
currently not used.
</para>
<para>Case numbers start from 1.  They are counted after all transformations
have been considered.
</para>
<para><literal>LIST</literal> is a procedure.  It causes the data to be read.
</para>
</sect1>
<sect1 label="8.11" id="NEW-FILE">
<title>NEW FILE</title>
<indexterm role="vr"><primary>NEW FILE</primary></indexterm>

<literallayout>NEW FILE.
</literallayout>
<para><literal>NEW FILE</literal> command clears the dictionary and data from the current
active dataset.
</para>
</sect1>
<sect1 label="8.12" id="PRINT">
<title>PRINT</title>
<indexterm role="vr"><primary>PRINT</primary></indexterm>

<literallayout>PRINT 
        [OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;]
        [RECORDS=<replaceable>n_lines</replaceable>]
        [{NOTABLE,TABLE}]
        [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]
        [/[<replaceable>line_no</replaceable>] <replaceable>arg</replaceable>&#8230;]

<replaceable>arg</replaceable> takes one of the following forms:
        &#8217;<replaceable>string</replaceable>&#8217; [<replaceable>start</replaceable>]
        <replaceable>var_list</replaceable> <replaceable>start</replaceable>-<replaceable>end</replaceable> [<replaceable>type_spec</replaceable>]
        <replaceable>var_list</replaceable> (<replaceable>fortran_spec</replaceable>)
        <replaceable>var_list</replaceable> *
</literallayout>
<para>The <literal>PRINT</literal> transformation writes variable data to the listing
file or an output file.  <literal>PRINT</literal> is executed when a procedure
causes the data to be read.  Follow <literal>PRINT</literal> by <literal>EXECUTE</literal> to
print variable data without invoking a procedure (see <link linkend="EXECUTE">EXECUTE</link>).
</para>
<para>All <literal>PRINT</literal> subcommands are optional.  If no strings or variables
are specified, <literal>PRINT</literal> outputs a single blank line.
</para>
<para>The <literal>OUTFILE</literal> subcommand specifies the file to receive the output.  The
file may be a file name as a string or a file handle (see <link linkend="File-Handles">File
Handles</link>).  If <literal>OUTFILE</literal> is not present then output will be sent to
pspp&#8217;s output listing file.  When <literal>OUTFILE</literal> is present, a space is
inserted at beginning of each output line, even lines that otherwise
would be blank.
</para>
<para>The <literal>ENCODING</literal> subcommand may only be used if the
<literal>OUTFILE</literal> subcommand is also used.  It specifies the character
encoding of the file.  See <link linkend="INSERT">INSERT</link>, for information on supported
encodings.
</para>
<para>The <literal>RECORDS</literal> subcommand specifies the number of lines to be output.  The
number of lines may optionally be surrounded by parentheses.
</para>
<para><literal>TABLE</literal> will cause the <literal>PRINT</literal> command to output a table to the listing file
that describes what it will print to the output file.  <literal>NOTABLE</literal>, the
default, suppresses this output table.
</para>
<para>Introduce the strings and variables to be printed with a slash
(&#8216;<literal>/</literal>&#8217;).  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.
</para>
<para>Literal strings may be printed.  Specify the string itself.
Optionally the string may be followed by a column number, specifying
the column on the line where the string should start.  Otherwise, the
string will be printed at the current position on the line.
</para>
<para>Variables to be printed can be specified in the same ways as available
for <literal>DATA LIST FIXED</literal> (see <link linkend="DATA-LIST-FIXED">DATA LIST FIXED</link>).  In addition, a
variable
list may be followed by an asterisk (&#8216;<literal>*</literal>&#8217;), 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.
</para>
<para>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.
</para>
</sect1>
<sect1 label="8.13" id="PRINT-EJECT">
<title>PRINT EJECT</title>
<indexterm role="vr"><primary>PRINT EJECT</primary></indexterm>

<literallayout>PRINT EJECT 
        OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        RECORDS=<replaceable>n_lines</replaceable>
        {NOTABLE,TABLE}
        /[<replaceable>line_no</replaceable>] <replaceable>arg</replaceable>&#8230;

<replaceable>arg</replaceable> takes one of the following forms:
        &#8217;<replaceable>string</replaceable>&#8217; [<replaceable>start</replaceable>-<replaceable>end</replaceable>]
        <replaceable>var_list</replaceable> <replaceable>start</replaceable>-<replaceable>end</replaceable> [<replaceable>type_spec</replaceable>]
        <replaceable>var_list</replaceable> (<replaceable>fortran_spec</replaceable>)
        <replaceable>var_list</replaceable> *
</literallayout>
<para><literal>PRINT EJECT</literal> advances to the beginning of a new output page in
the listing file or output file.  It can also output data in the same
way as <literal>PRINT</literal>.
</para>
<para>All <literal>PRINT EJECT</literal> subcommands are optional.
</para>
<para>Without <literal>OUTFILE</literal>, <literal>PRINT EJECT</literal> ejects the current page in
the listing file, then it produces other output, if any is specified.
</para>
<para>With <literal>OUTFILE</literal>, <literal>PRINT EJECT</literal> writes its output to the specified file.
The first line of output is written with &#8216;<literal>1</literal>&#8217; inserted in the
first column.  Commonly, this is the only line of output.  If
additional lines of output are specified, these additional lines are
written with a space inserted in the first column, as with <literal>PRINT</literal>.
</para>
<para>See <link linkend="PRINT">PRINT</link>, for more information on syntax and usage.
</para>
</sect1>
<sect1 label="8.14" id="PRINT-SPACE">
<title>PRINT SPACE</title>
<indexterm role="vr"><primary>PRINT SPACE</primary></indexterm>

<literallayout>PRINT SPACE [OUTFILE=&#8217;file_name&#8217;] [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;] [n_lines].
</literallayout>
<para><literal>PRINT SPACE</literal> prints one or more blank lines to an output file.
</para>
<para>The <literal>OUTFILE</literal> subcommand is optional.  It may be used to direct output to
a file specified by file name as a string or file handle (see <link linkend="File-Handles">File
Handles</link>).  If OUTFILE is not specified then output will be directed to
the listing file.
</para>
<para>The <literal>ENCODING</literal> subcommand may only be used if <literal>OUTFILE</literal>
is also used.  It specifies the character encoding of the file.
See <link linkend="INSERT">INSERT</link>, for information on supported encodings.
</para>
<para>n_lines is also optional.  If present, it is an expression
(see <link linkend="Expressions">Expressions</link>) specifying the number of blank lines to be
printed.  The expression must evaluate to a nonnegative value.
</para>
</sect1>
<sect1 label="8.15" id="REREAD">
<title>REREAD</title>
<indexterm role="vr"><primary>REREAD</primary></indexterm>

<literallayout>REREAD [FILE=handle] [COLUMN=column] [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;].
</literallayout>
<para>The <literal>REREAD</literal> transformation allows the previous input line in a
data file
already processed by <literal>DATA LIST</literal> or another input command to be re-read
for further processing.
</para>
<para>The <literal>FILE</literal> subcommand, which is optional, is used to specify the file to
have its line re-read.  The file must be specified as the name of a file
handle (see <link linkend="File-Handles">File Handles</link>).  If FILE is not specified then the last
file specified on <literal>DATA LIST</literal> will be assumed (last file specified
lexically, not in terms of flow-of-control).
</para>
<para>By default, the line re-read is re-read in its entirety.  With the
<literal>COLUMN</literal> subcommand, a prefix of the line can be exempted from
re-reading.  Specify an expression (see <link linkend="Expressions">Expressions</link>) evaluating to
the first column that should be included in the re-read line.  Columns
are numbered from 1 at the left margin.
</para>
<para>The <literal>ENCODING</literal> subcommand may only be used if the <literal>FILE</literal>
subcommand is also used.  It specifies the character encoding of the
file.   See <link linkend="INSERT">INSERT</link>, for information on supported encodings.
</para>
<para>Issuing <literal>REREAD</literal> multiple times will not back up in the data
file.  Instead, it will re-read the same line multiple times.
</para>
</sect1>
<sect1 label="8.16" id="REPEATING-DATA">
<title>REPEATING DATA</title>
<indexterm role="vr"><primary>REPEATING DATA</primary></indexterm>

<literallayout>REPEATING DATA
        /STARTS=<replaceable>start</replaceable>-<replaceable>end</replaceable>
        /OCCURS=<replaceable>n_occurs</replaceable>
        /FILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        /LENGTH=<replaceable>length</replaceable>
        /CONTINUED[=<replaceable>cont_start</replaceable>-<replaceable>cont_end</replaceable>]
        /ID=<replaceable>id_start</replaceable>-<replaceable>id_end</replaceable>=<replaceable>id_var</replaceable>
        /{TABLE,NOTABLE}
        /DATA=<replaceable>var_spec</replaceable>&#8230;

where each <replaceable>var_spec</replaceable> takes one of the forms
        <replaceable>var_list</replaceable> <replaceable>start</replaceable>-<replaceable>end</replaceable> [<replaceable>type_spec</replaceable>]
        <replaceable>var_list</replaceable> (<replaceable>fortran_spec</replaceable>)
</literallayout>
<para><literal>REPEATING DATA</literal> 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.  <literal>REPEATING DATA</literal> may only be
used within an <literal>INPUT PROGRAM</literal> structure (see <link linkend="INPUT-PROGRAM">INPUT PROGRAM</link>).
When used with <literal>DATA LIST</literal>, it
can be used to parse groups of cases that share a subset of variables
but differ in their other data.
</para>
<para>The <literal>STARTS</literal> 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 (see <link linkend="BEGIN-DATA">BEGIN
DATA</link>) 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.
</para>
<para>The <literal>OCCURS</literal> 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.
</para>
<para>The <literal>DATA</literal> 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 <literal>DATA LIST
FIXED</literal> (see <link linkend="DATA-LIST-FIXED">DATA LIST FIXED</link>).
</para>
<para>All other subcommands are optional.
</para>
<para>FILE specifies the file to read, either a file name as a string or a
file handle (see <link linkend="File-Handles">File Handles</link>).  If FILE is not present then the
default is the last file handle used on <literal>DATA LIST</literal> (lexically, not in
terms of flow of control).
</para>
<para>By default <literal>REPEATING DATA</literal> will output a table describing how it will
parse the input data.  Specifying <literal>NOTABLE</literal> will disable this behavior;
specifying TABLE will explicitly enable it.
</para>
<para>The <literal>LENGTH</literal> subcommand specifies the length in characters of each group.
If it is not present then length is inferred from the <literal>DATA</literal> subcommand.
LENGTH can be a number or a variable name.
</para>
<para>Normally all the data groups are expected to be present on a single
line.  Use the <literal>CONTINUED</literal> 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 <literal>CONTINUED</literal>.  Otherwise, specify the
possible range of columns in the same way as on STARTS.
</para>
<para>When data groups are continued from line to line, it is easy
for cases to get out of sync through careless hand editing.  The
<literal>ID</literal> subcommand allows a case identifier to be present on each line of
repeating data groups.  <literal>REPEATING DATA</literal> 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
(&#8216;<literal>=</literal>&#8217;) and the identifier variable name.  The variable must already
have been declared with <literal>NUMERIC</literal> or another command.
</para>
<para><literal>REPEATING DATA</literal> should be the last command given within an
<literal>INPUT PROGRAM</literal>.  It should not be enclosed within a <literal>LOOP</literal>
structure (see <link linkend="LOOP">LOOP</link>).  Use <literal>DATA LIST</literal> before, not after,
<literal>REPEATING DATA</literal>.
</para>
</sect1>
<sect1 label="8.17" id="WRITE">
<title>WRITE</title>
<indexterm role="vr"><primary>WRITE</primary></indexterm>

<literallayout>WRITE 
        OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        RECORDS=<replaceable>n_lines</replaceable>
        {NOTABLE,TABLE}
        /[<replaceable>line_no</replaceable>] <replaceable>arg</replaceable>&#8230;

<replaceable>arg</replaceable> takes one of the following forms:
        &#8217;<replaceable>string</replaceable>&#8217; [<replaceable>start</replaceable>-<replaceable>end</replaceable>]
        <replaceable>var_list</replaceable> <replaceable>start</replaceable>-<replaceable>end</replaceable> [<replaceable>type_spec</replaceable>]
        <replaceable>var_list</replaceable> (<replaceable>fortran_spec</replaceable>)
        <replaceable>var_list</replaceable> *
</literallayout>
<para><literal>WRITE</literal> writes text or binary data to an output file.  
</para>
<para>See <link linkend="PRINT">PRINT</link>, for more information on syntax and usage.  <literal>PRINT</literal>
and <literal>WRITE</literal> differ in only a few ways:
</para>
<itemizedlist><listitem><para><literal>WRITE</literal> uses write formats by default, whereas <literal>PRINT</literal> uses
print formats.
</para>
</listitem><listitem><para><literal>PRINT</literal> inserts a space between variables unless a format is
explicitly specified, but <literal>WRITE</literal> never inserts space between
variables in output.
</para>
</listitem><listitem><para><literal>PRINT</literal> inserts a space at the beginning of each line that it
writes to an output file (and <literal>PRINT EJECT</literal> inserts &#8216;<literal>1</literal>&#8217; at
the beginning of each line that should begin a new page), but
<literal>WRITE</literal> does not.
</para>
</listitem><listitem><para><literal>PRINT</literal> outputs the system-missing value according to its
specified output format, whereas <literal>WRITE</literal> outputs the
system-missing value as a field filled with spaces.  Binary formats
are an exception.
</para></listitem></itemizedlist></sect1>
</chapter>
<chapter label="9" id="System-and-Portable-File-IO">
<title>System and Portable File I/O</title>

<para>The commands in this chapter read, write, and examine system files and
portable files.
</para>

<sect1 label="9.1" id="APPLY-DICTIONARY">
<title>APPLY DICTIONARY</title>
<indexterm role="vr"><primary>APPLY DICTIONARY</primary></indexterm>

<literallayout>APPLY DICTIONARY FROM={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}.
</literallayout>
<para><literal>APPLY DICTIONARY</literal> applies the variable labels, value labels,
and missing values taken from a file to corresponding
variables in the active dataset.  In some cases it also updates the
weighting variable.
</para>
<para>Specify a system file or portable file&#8217;s name, a data set name
(see <link linkend="Datasets">Datasets</link>), or a file handle name (see <link linkend="File-Handles">File Handles</link>).  The
dictionary in the file will be read, but it will not replace the
active dataset&#8217;s dictionary.  The file&#8217;s data will not be read.
</para>
<para>Only variables with names that exist in both the active dataset 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&#8217; attributes will replace those in their matching
active dataset variables:
</para>
<itemizedlist><listitem><para>If a system file variable has a variable label, then it will replace
the variable label of the active dataset variable.  If the system
file variable does not have a variable label, then the active dataset
variable&#8217;s variable label, if any, will be retained.
</para>
</listitem><listitem><para>If the system file variable has custom attributes (see <link linkend="VARIABLE-ATTRIBUTE">VARIABLE
ATTRIBUTE</link>), then those attributes replace the active dataset variable&#8217;s
custom attributes.  If the system file variable does not have custom
attributes, then the active dataset variable&#8217;s custom attributes, if any,
will be retained.
</para>
</listitem><listitem><para>If the active dataset variable is numeric or short string, then value
labels and missing values, if any, will be copied to the active dataset
variable.  If the system file variable does not have value labels or
missing values, then those in the active dataset variable, if any, will not
be disturbed.
</para></listitem></itemizedlist>
<para>In addition to properties of variables, some properties of the active
file dictionary as a whole are updated:
</para>
<itemizedlist><listitem><para>If the system file has custom attributes (see <link linkend="DATAFILE-ATTRIBUTE">DATAFILE ATTRIBUTE</link>),
then those attributes replace the active dataset variable&#8217;s custom
attributes.
</para>
</listitem><listitem><para>If the active dataset has a weighting variable (see <link linkend="WEIGHT">WEIGHT</link>), and the
system file does not, or if the weighting variable in the system file
does not exist in the active dataset, then the active dataset weighting
variable, if any, is retained.  Otherwise, the weighting variable in
the system file becomes the active dataset weighting variable.
</para></listitem></itemizedlist>
<para><literal>APPLY DICTIONARY</literal> takes effect immediately.  It does not read the
active dataset.  The system file is not modified.
</para>
</sect1>
<sect1 label="9.2" id="EXPORT">
<title>EXPORT</title>
<indexterm role="vr"><primary>EXPORT</primary></indexterm>

<literallayout>EXPORT
        /OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        /UNSELECTED={RETAIN,DELETE}
        /DIGITS=<replaceable>n</replaceable>
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
        /TYPE={COMM,TAPE}
        /MAP
</literallayout>
<para>The <literal>EXPORT</literal> procedure writes the active dataset&#8217;s dictionary and
data to a specified portable file.
</para>
<para>By default, cases excluded with FILTER are written to the
file.  These can be excluded by specifying DELETE on the <literal>UNSELECTED</literal>
subcommand.  Specifying RETAIN makes the default explicit.
</para>
<para>Portable files express real numbers in base 30.  Integers are always
expressed to the maximum precision needed to make them exact.
Non-integers are, by default, expressed to the machine&#8217;s maximum
natural precision (approximately 15 decimal digits on many machines).
If many numbers require this many digits, the portable file may
significantly increase in size.  As an alternative, the <literal>DIGITS</literal>
subcommand may be used to specify the number of decimal digits of
precision to write.  <literal>DIGITS</literal> applies only to non-integers.
</para>
<para>The <literal>OUTFILE</literal> subcommand, which is the only required subcommand, specifies
the portable file to be written as a file name string or
a file handle (see <link linkend="File-Handles">File Handles</link>).
</para>
<para><literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> follow the same format as the 
<literal>SAVE</literal> procedure (see <link linkend="SAVE">SAVE</link>).
</para>
<para>The <literal>TYPE</literal> subcommand specifies the character set for use in the
portable file.  Its value is currently not used.
</para>
<para>The <literal>MAP</literal> subcommand is currently ignored.
</para>
<para><literal>EXPORT</literal> is a procedure.  It causes the active dataset to be read.
</para>
</sect1>
<sect1 label="9.3" id="GET">
<title>GET</title>
<indexterm role="vr"><primary>GET</primary></indexterm>

<literallayout>GET
        /FILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
        /ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;
</literallayout>
<para><literal>GET</literal> clears the current dictionary and active dataset and
replaces them with the dictionary and data from a specified file.
</para>
<para>The <literal>FILE</literal> subcommand is the only required subcommand.  Specify
the SPSS system file, SPSS/PC+ system file, or SPSS portable file to
be read as a string file name or a file handle (see <link linkend="File-Handles">File Handles</link>).
</para>
<para>By default, all the variables in a file are read.  The DROP
subcommand can be used to specify a list of variables that are not to be
read.  By contrast, the <literal>KEEP</literal> subcommand can be used to specify
variable that are to be read, with all other variables not read.
</para>
<para>Normally variables in a file retain the names that they were
saved under.  Use the <literal>RENAME</literal> subcommand to change these names.
Specify,
within parentheses, a list of variable names followed by an equals sign
(&#8216;<literal>=</literal>&#8217;) and the names that they should be renamed to.  Multiple
parenthesized groups of variable names can be included on a single
<literal>RENAME</literal> subcommand.
Variables&#8217; names may be swapped using a <literal>RENAME</literal>
subcommand of the form <literal>/RENAME=(<replaceable>A</replaceable> <replaceable>B</replaceable>=<replaceable>B</replaceable> <replaceable>A</replaceable>)</literal>.
</para>
<para>Alternate syntax for the <literal>RENAME</literal> subcommand allows the parentheses to be
eliminated.  When this is done, only a single variable may be renamed at
once.  For instance, <literal>/RENAME=<replaceable>A</replaceable>=<replaceable>B</replaceable></literal>.  This alternate syntax is
deprecated.
</para>
<para><literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> are executed in left-to-right order.  
Each may be present any number of times.  <literal>GET</literal> never modifies a
file on disk.  Only the active dataset read from the file
is affected by these subcommands.
</para>
<para>pspp automatically detects the encoding of string data in the file,
when possible.  The character encoding of old SPSS system files cannot
always be guessed correctly, and SPSS/PC+ system files do not include
any indication of their encoding.  Specify the <literal>ENCODING</literal>
subcommand with an <acronym>IANA</acronym> character set name as its string
argument to override the default.  Use <literal>SYSFILE INFO</literal> to analyze
the encodings that might be valid for a system file.  The
<literal>ENCODING</literal> subcommand is a pspp extension.
</para>
<para><literal>GET</literal> does not cause the data to be read, only the dictionary.  The data
is read later, when a procedure is executed.
</para>
<para>Use of <literal>GET</literal> to read a portable file is a pspp extension.
</para>
</sect1>
<sect1 label="9.4" id="GET-DATA">
<title>GET DATA</title>
<indexterm role="vr"><primary>GET DATA</primary></indexterm>

<literallayout>GET DATA
        /TYPE={GNM,ODS,PSQL,TXT}
        &#8230;additional subcommands depending on TYPE&#8230;
</literallayout>
<para>The <literal>GET DATA</literal> command is used to read files and other data
sources created by other applications.  When this command is executed,
the current dictionary and active dataset are replaced with variables
and data read from the specified source.
</para>
<para>The <literal>TYPE</literal> subcommand is mandatory and must be the first subcommand
specified.  It determines the type of the file or source to read.
pspp currently supports the following file types:
</para>
<variablelist><varlistentry><term>GNM
</term><listitem><para>Spreadsheet files created by Gnumeric (<ulink url="http://gnumeric.org">http://gnumeric.org</ulink>).
</para>
</listitem></varlistentry><varlistentry><term>ODS
</term><listitem><para>Spreadsheet files in OpenDocument format (<ulink url="http://opendocumentformat.org">http://opendocumentformat.org</ulink>).
</para>
</listitem></varlistentry><varlistentry><term>PSQL
</term><listitem><para>Relations from PostgreSQL databases (<ulink url="http://postgresql.org">http://postgresql.org</ulink>).
</para>
</listitem></varlistentry><varlistentry><term>TXT
</term><listitem><para>Textual data files in columnar and delimited formats.
</para></listitem></varlistentry></variablelist>
<para>Each supported file type has additional subcommands, explained in
separate sections below.
</para>

<sect2 label="9.4.1" id="GET-DATA-_002fTYPE_003dGNM_002fODS">
<title>Spreadsheet Files</title>

<literallayout>GET DATA /TYPE={GNM, ODS}
        /FILE={&#8217;<replaceable>file_name</replaceable>&#8217;}
        /SHEET={NAME &#8217;<replaceable>sheet_name</replaceable>&#8217;, INDEX <replaceable>n</replaceable>}
        /CELLRANGE={RANGE &#8217;<replaceable>range</replaceable>&#8217;, FULL}
        /READNAMES={ON, OFF}
        /ASSUMEDSTRWIDTH=<replaceable>n</replaceable>.
</literallayout>
<indexterm role="cp"><primary>Gnumeric</primary></indexterm>
<indexterm role="cp"><primary>OpenDocument</primary></indexterm>
<indexterm role="cp"><primary>spreadsheet files</primary></indexterm>

<para>Gnumeric spreadsheets (<ulink url="http://gnumeric.org">http://gnumeric.org</ulink>), and spreadsheets
in OpenDocument format
(<ulink url="http://libreplanet.org/wiki/Group:OpenDocument/Software">http://libreplanet.org/wiki/Group:OpenDocument/Software</ulink>)
can be read using the <literal>GET DATA</literal> command.
Use the <literal>TYPE</literal> subcommand to indicate the file&#8217;s format.  
/TYPE=GNM indicates Gnumeric files,
/TYPE=ODS indicates OpenDocument.
The <literal>FILE</literal> subcommand is mandatory.
Use it to specify the name file to be read. 
All other subcommands are optional.
</para>
<para>The format of each variable is determined by the format of the spreadsheet 
cell containing the first datum for the variable.
If this cell is of string (text) format, then the width of the variable is
determined from the length of the string it contains, unless the 
<literal>ASSUMEDSTRWIDTH</literal> subcommand is given.
</para>
<para>The <literal>SHEET</literal> subcommand specifies the sheet within the spreadsheet file to read.
There are two forms of the <literal>SHEET</literal> subcommand.
In the first form,
<literal>/SHEET=name <replaceable>sheet_name</replaceable></literal>, the string <replaceable>sheet_name</replaceable> is the
name of the sheet to read.
In the second form, <literal>/SHEET=index <replaceable>idx</replaceable></literal>, <replaceable>idx</replaceable> is a
integer which is the index of the sheet to read.
The first sheet has the index 1.
If the <literal>SHEET</literal> subcommand is omitted, then the command will read the
first sheet in the file.
</para>
<para>The <literal>CELLRANGE</literal> subcommand specifies the range of cells within the sheet to read.
If the subcommand is given as <literal>/CELLRANGE=FULL</literal>, then the entire
sheet  is read.
To read only part of a sheet, use the form 
<literal>/CELLRANGE=range '<replaceable>top_left_cell</replaceable>:<replaceable>bottom_right_cell</replaceable>'</literal>.
For example, the subcommand <literal>/CELLRANGE=range 'C3:P19'</literal> reads 
columns C&#8211;P, and rows 3&#8211;19 inclusive.
If no <literal>CELLRANGE</literal> subcommand is given, then the entire sheet is read.
</para>
<para>If <literal>/READNAMES=ON</literal> is specified, then the contents of cells of
the first row are used as the names of the variables in which to store
the data from subsequent rows.  This is the default.
If <literal>/READNAMES=OFF</literal> is
used, then the variables  receive automatically assigned names.
</para>
<para>The <literal>ASSUMEDSTRWIDTH</literal> subcommand specifies the maximum width of string
variables read  from the file.
If omitted, the default value is determined from the length of the 
string in the first spreadsheet cell for each variable.
</para>

</sect2>
<sect2 label="9.4.2" id="GET-DATA-_002fTYPE_003dPSQL">
<title>Postgres Database Queries</title>

<literallayout>GET DATA /TYPE=PSQL
         /CONNECT={<replaceable>connection info</replaceable>}
         /SQL={<replaceable>query</replaceable>}
         [/ASSUMEDSTRWIDTH=<replaceable>w</replaceable>]
         [/UNENCRYPTED]
         [/BSIZE=<replaceable>n</replaceable>].
</literallayout>
<indexterm role="cp"><primary>postgres</primary></indexterm>
<indexterm role="cp"><primary>databases</primary></indexterm>

<para>The PSQL type is used to import data from a postgres database server.
The server may be located locally or remotely.
Variables are automatically created based on the table column names 
or the names specified in the SQL query.
Postgres data types of high precision, will loose precision when 
imported into pspp.
Not all the postgres data types are able to be represented in pspp.
If a datum cannot be represented a warning will be issued and that 
datum will be set to SYSMIS.
</para>
<para>The <literal>CONNECT</literal> subcommand is mandatory.
It is a string specifying the parameters of the database server from
which the data should be fetched.
The format of the string is given in the postgres manual
<ulink url="http://www.postgresql.org/docs/8.0/static/libpq.html#LIBPQ-CONNECT">http://www.postgresql.org/docs/8.0/static/libpq.html#LIBPQ-CONNECT</ulink>.
</para>
<para>The <literal>SQL</literal> subcommand is mandatory.
It must be a valid SQL string to retrieve data from the database.
</para>
<para>The <literal>ASSUMEDSTRWIDTH</literal> subcommand specifies the maximum width of string
variables read  from the database.
If omitted, the default value is determined from the length of the 
string in the first value read for each variable.
</para>
<para>The <literal>UNENCRYPTED</literal> subcommand allows data to be retrieved over an insecure
connection.
If the connection is not encrypted, and the <literal>UNENCRYPTED</literal> subcommand is 
not given, then an error will occur.
Whether or not the connection is
encrypted depends upon the underlying psql library and the 
capabilities of the database server.
</para>
<para>The <literal>BSIZE</literal> subcommand serves only to optimise the speed of data transfer.
It specifies an upper limit on
number of cases to fetch from the database at once.
The default value is 4096.
If your SQL statement fetches a large number of cases but only a small number of
variables, then the data transfer may be faster if you increase this value.
Conversely, if the number of variables is large, or if the machine on which 
pspp is running has only a
small amount of memory, then a smaller value will be better.
</para>

<para>The following syntax is an example:
</para><screen>GET DATA /TYPE=PSQL
     /CONNECT='host=example.com port=5432 dbname=product user=fred passwd=xxxx'
     /SQL='select * from manufacturer'.
</screen>

</sect2>
<sect2 label="9.4.3" id="GET-DATA-_002fTYPE_003dTXT">
<title>Textual Data Files</title>

<literallayout>GET DATA /TYPE=TXT
        /FILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;]
        [/ARRANGEMENT={DELIMITED,FIXED}]
        [/FIRSTCASE={<replaceable>first_case</replaceable>}]
        [/IMPORTCASES=...]
        &#8230;additional subcommands depending on ARRANGEMENT&#8230;
</literallayout>
<indexterm role="cp"><primary>text files</primary></indexterm>
<indexterm role="cp"><primary>data files</primary></indexterm>
<para>When TYPE=TXT is specified, GET DATA reads data in a delimited or
fixed columnar format, much like DATA LIST (see <link linkend="DATA-LIST">DATA LIST</link>).
</para>
<para>The <literal>FILE</literal> subcommand is mandatory.  Specify the file to be read as 
a string file name or (for textual data only) a
file handle (see <link linkend="File-Handles">File Handles</link>).
</para>
<para>The <literal>ENCODING</literal> subcommand specifies the character encoding of
the file to be read.  See <link linkend="INSERT">INSERT</link>, for information on supported
encodings.
</para>
<para>The <literal>ARRANGEMENT</literal> subcommand determines the file&#8217;s basic format.
DELIMITED, the default setting, specifies that fields in the input
data are separated by spaces, tabs, or other user-specified
delimiters.  FIXED specifies that fields in the input data appear at
particular fixed column positions within records of a case.
</para>
<para>By default, cases are read from the input file starting from the first
line.  To skip lines at the beginning of an input file, set <literal>FIRSTCASE</literal>
to the number of the first line to read: 2 to skip the first line, 3
to skip the first two lines, and so on.
</para>
<para><literal>IMPORTCASES</literal> is ignored, for compatibility.  Use <literal>N OF
CASES</literal> to limit the number of cases read from a file (see <link linkend="N-OF-CASES">N OF
CASES</link>), or <literal>SAMPLE</literal> to obtain a random sample of cases
(see <link linkend="SAMPLE">SAMPLE</link>).
</para>
<para>The remaining subcommands apply only to one of the two file
arrangements, described below.
</para>

<sect3 label="9.4.3.1" id="GET-DATA-_002fTYPE_003dTXT-_002fARRANGEMENT_003dDELIMITED">
<title>Reading Delimited Data</title>

<literallayout>GET DATA /TYPE=TXT
        /FILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        [/ARRANGEMENT={DELIMITED,FIXED}]
        [/FIRSTCASE={<replaceable>first_case</replaceable>}]
        [/IMPORTCASE={ALL,FIRST <replaceable>max_cases</replaceable>,PERCENT <replaceable>percent</replaceable>}]

        /DELIMITERS=&quot;<replaceable>delimiters</replaceable>&quot;
        [/QUALIFIER=&quot;<replaceable>quotes</replaceable>&quot;
        [/DELCASE={LINE,VARIABLES <replaceable>n_variables</replaceable>}]
        /VARIABLES=<replaceable>del_var1</replaceable> [<replaceable>del_var2</replaceable>]&#8230;
where each <replaceable>del_var</replaceable> takes the form:
        variable format
</literallayout>
<para>The GET DATA command with TYPE=TXT and ARRANGEMENT=DELIMITED reads
input data from text files in delimited format, where fields are
separated by a set of user-specified delimiters.  Its capabilities are
similar to those of DATA LIST FREE (see <link linkend="DATA-LIST-FREE">DATA LIST FREE</link>), with a
few enhancements.
</para>
<para>The required <literal>FILE</literal> subcommand and optional <literal>FIRSTCASE</literal> and <literal>IMPORTCASE</literal>
subcommands are described above (see <link linkend="GET-DATA-_002fTYPE_003dTXT">GET DATA /TYPE=TXT</link>).
</para>
<para><literal>DELIMITERS</literal>, which is required, specifies the set of characters that
may separate fields.  Each character in the string specified on
<literal>DELIMITERS</literal> separates one field from the next.  The end of a line also
separates fields, regardless of <literal>DELIMITERS</literal>.  Two consecutive
delimiters in the input yield an empty field, as does a delimiter at
the end of a line.  A space character as a delimiter is an exception:
consecutive spaces do not yield an empty field and neither does any
number of spaces at the end of a line.
</para>
<para>To use a tab as a delimiter, specify &#8216;<literal>\t</literal>&#8217; at the beginning of the
<literal>DELIMITERS</literal> string.  To use a backslash as a delimiter, specify
&#8216;<literal>\\</literal>&#8217; as the first delimiter or, if a tab should also be a
delimiter, immediately following &#8216;<literal>\t</literal>&#8217;.  To read a data file in
which each field appears on a separate line, specify the empty string
for <literal>DELIMITERS</literal>.
</para>
<para>The optional <literal>QUALIFIER</literal> subcommand names one or more characters that
can be used to quote values within fields in the input.  A field that
begins with one of the specified quote characters ends at the next
matching quote.  Intervening delimiters become part of the field,
instead of terminating it.  The ability to specify more than one quote
character is a pspp extension.
</para>
<para>The character specified on <literal>QUALIFIER</literal> can be embedded within a
field that it quotes by doubling the qualifier.  For example, if
&#8216;<literal>'</literal>&#8217; is specified on <literal>QUALIFIER</literal>, then <literal>'a''b'</literal>
specifies a field that contains &#8216;<literal>a'b</literal>&#8217;.
</para>
<para>The <literal>DELCASE</literal> subcommand controls how data may be broken across lines in
the data file.  With LINE, the default setting, each line must contain
all the data for exactly one case.  For additional flexibility, to
allow a single case to be split among lines or multiple cases to be
contained on a single line, specify VARIABLES <emphasis>n_variables</emphasis>, where
<emphasis>n_variables</emphasis> is the number of variables per case.
</para>
<para>The <literal>VARIABLES</literal> subcommand is required and must be the last subcommand.
Specify the name of each variable and its input format (see <link linkend="Input-and-Output-Formats">Input
and Output Formats</link>) in the order they should be read from the input
file.
</para>
<bridgehead renderas="sect3">Examples</bridgehead>

<para>On a Unix-like system, the &#8216;<literal>/etc/passwd</literal>&#8217; file has a format
similar to this:
</para>
<screen>root:$1$nyeSP5gD$pDq/:0:0:,,,:/root:/bin/bash
blp:$1$BrP/pFg4$g7OG:1000:1000:Ben Pfaff,,,:/home/blp:/bin/bash
john:$1$JBuq/Fioq$g4A:1001:1001:John Darrington,,,:/home/john:/bin/bash
jhs:$1$D3li4hPL$88X1:1002:1002:Jason Stover,,,:/home/jhs:/bin/csh
</screen>
<para>The following syntax reads a file in the format used by
&#8216;<literal>/etc/passwd</literal>&#8217;:
</para>
<!-- If you change this example, change the regression test in -->
<!-- tests/language/data-io/get-data.at to match. -->
<screen>GET DATA /TYPE=TXT /FILE='/etc/passwd' /DELIMITERS=':'
        /VARIABLES=username A20
                   password A40
                   uid F10
                   gid F10
                   gecos A40
                   home A40
                   shell A40.
</screen>
<para>Consider the following data on used cars:
</para>
<screen>model   year    mileage price   type    age
Civic   2002    29883   15900   Si      2
Civic   2003    13415   15900   EX      1
Civic   1992    107000  3800    n/a     12
Accord  2002    26613   17900   EX      1
</screen>
<para>The following syntax can be used to read the used car data:
</para>
<!-- If you change this example, change the regression test in -->
<!-- tests/language/data-io/get-data.at to match. -->
<screen>GET DATA /TYPE=TXT /FILE='cars.data' /DELIMITERS=' ' /FIRSTCASE=2
        /VARIABLES=model A8
                   year F4
                   mileage F6
                   price F5
                   type A4
                   age F2.
</screen>
<para>Consider the following information on animals in a pet store:
</para>
<screen>'Pet''s Name', &quot;Age&quot;, &quot;Color&quot;, &quot;Date Received&quot;, &quot;Price&quot;, &quot;Height&quot;, &quot;Type&quot;
, (Years), , , (Dollars), ,
&quot;Rover&quot;, 4.5, Brown, &quot;12 Feb 2004&quot;, 80, '1''4&quot;', &quot;Dog&quot;
&quot;Charlie&quot;, , Gold, &quot;5 Apr 2007&quot;, 12.3, &quot;3&quot;&quot;&quot;, &quot;Fish&quot;
&quot;Molly&quot;, 2, Black, &quot;12 Dec 2006&quot;, 25, '5&quot;', &quot;Cat&quot;
&quot;Gilly&quot;, , White, &quot;10 Apr 2007&quot;, 10, &quot;3&quot;&quot;&quot;, &quot;Guinea Pig&quot;
</screen>
<para>The following syntax can be used to read the pet store data:
</para>
<!-- If you change this example, change the regression test in -->
<!-- tests/language/data-io/get-data.at to match. -->
<screen>GET DATA /TYPE=TXT /FILE='pets.data' /DELIMITERS=', ' /QUALIFIER='''&quot;' /ESCAPE
        /FIRSTCASE=3
        /VARIABLES=name A10
                   age F3.1
                   color A5
                   received EDATE10
                   price F5.2
                   height a5
                   type a10.
</screen>
</sect3>
<sect3 label="9.4.3.2" id="GET-DATA-_002fTYPE_003dTXT-_002fARRANGEMENT_003dFIXED">
<title>Reading Fixed Columnar Data</title>

<!-- (modify-syntax-entry ?_ "w") -->
<!-- (modify-syntax-entry ?' "'") -->
<!-- (modify-syntax-entry ?@ "'") -->

<literallayout>GET DATA /TYPE=TXT
        /FILE={&#8217;file_name&#8217;,<replaceable>file_handle</replaceable>}
        [/ARRANGEMENT={DELIMITED,FIXED}]
        [/FIRSTCASE={<replaceable>first_case</replaceable>}]
        [/IMPORTCASE={ALL,FIRST <replaceable>max_cases</replaceable>,PERCENT <replaceable>percent</replaceable>}]

        [/FIXCASE=<replaceable>n</replaceable>]
        /VARIABLES <replaceable>fixed_var</replaceable> [<replaceable>fixed_var</replaceable>]&#8230;
            [/rec# <replaceable>fixed_var</replaceable> [<replaceable>fixed_var</replaceable>]&#8230;]&#8230;
where each <replaceable>fixed_var</replaceable> takes the form:
        <replaceable>variable</replaceable> <replaceable>start</replaceable>-<replaceable>end</replaceable> <replaceable>format</replaceable>
</literallayout>
<para>The <literal>GET DATA</literal> command with TYPE=TXT and ARRANGEMENT=FIXED reads input
data from text files in fixed format, where each field is located in
particular fixed column positions within records of a case.  Its
capabilities are similar to those of DATA LIST FIXED (see <link linkend="DATA-LIST-FIXED">DATA LIST
FIXED</link>), with a few enhancements.
</para>
<para>The required <literal>FILE</literal> subcommand and optional <literal>FIRSTCASE</literal> and <literal>IMPORTCASE</literal>
subcommands are described above (see <link linkend="GET-DATA-_002fTYPE_003dTXT">GET DATA /TYPE=TXT</link>).
</para>
<para>The optional <literal>FIXCASE</literal> subcommand may be used to specify the positive
integer number of input lines that make up each case.  The default
value is 1.
</para>
<para>The <literal>VARIABLES</literal> subcommand, which is required, specifies the positions
at which each variable can be found.  For each variable, specify its
name, followed by its start and end column separated by &#8216;<literal>-</literal>&#8217;
(e.g. &#8216;<literal>0-9</literal>&#8217;), followed by an input format type (e.g.
&#8216;<literal>F</literal>&#8217;) or a full format specification (e.g. &#8216;<literal>DOLLAR12.2</literal>&#8217;).
For this command, columns are numbered starting from 0 at
the left column.  Introduce the variables in the second and later
lines of a case by a slash followed by the number of the line within
the case, e.g. &#8216;<literal>/2</literal>&#8217; for the second line.
</para>
<bridgehead renderas="sect3">Examples</bridgehead>

<para>Consider the following data on used cars:
</para>
<screen>model   year    mileage price   type    age
Civic   2002    29883   15900   Si      2
Civic   2003    13415   15900   EX      1
Civic   1992    107000  3800    n/a     12
Accord  2002    26613   17900   EX      1
</screen>
<para>The following syntax can be used to read the used car data:
</para>
<!-- If you change this example, change the regression test in -->
<!-- tests/language/data-io/get-data.at to match. -->
<screen>GET DATA /TYPE=TXT /FILE='cars.data' /ARRANGEMENT=FIXED /FIRSTCASE=2
        /VARIABLES=model 0-7 A
                   year 8-15 F
                   mileage 16-23 F
                   price 24-31 F
                   type 32-40 A
                   age 40-47 F.
</screen>
</sect3>
</sect2>
</sect1>
<sect1 label="9.5" id="IMPORT">
<title>IMPORT</title>
<indexterm role="vr"><primary>IMPORT</primary></indexterm>

<literallayout>IMPORT
        /FILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        /TYPE={COMM,TAPE}
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
</literallayout>
<para>The <literal>IMPORT</literal> transformation clears the active dataset dictionary and
data and
replaces them with a dictionary and data from a system file or
portable file.
</para>
<para>The <literal>FILE</literal> subcommand, which is the only required subcommand, specifies
the portable file to be read as a file name string or a file handle
(see <link linkend="File-Handles">File Handles</link>).
</para>
<para>The <literal>TYPE</literal> subcommand is currently not used.
</para>
<para><literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> follow the syntax used by <literal>GET</literal> (see <link linkend="GET">GET</link>).
</para>
<para><literal>IMPORT</literal> does not cause the data to be read; only the dictionary.  The
data is read later, when a procedure is executed.
</para>
<para>Use of <literal>IMPORT</literal> to read a system file is a pspp extension.
</para>
</sect1>
<sect1 label="9.6" id="SAVE">
<title>SAVE</title>
<indexterm role="vr"><primary>SAVE</primary></indexterm>

<literallayout>SAVE
        /OUTFILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        /UNSELECTED={RETAIN,DELETE}
        /{UNCOMPRESSED,COMPRESSED,ZCOMPRESSED}
        /PERMISSIONS={WRITEABLE,READONLY}
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /VERSION=<replaceable>version</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
        /NAMES
        /MAP
</literallayout>
<para>The <literal>SAVE</literal> procedure causes the dictionary and data in the active
dataset to
be written to a system file.
</para>
<para>OUTFILE is the only required subcommand.  Specify the system file
to be written as a string file name or a file handle
(see <link linkend="File-Handles">File Handles</link>).
</para>
<para>By default, cases excluded with FILTER are written to the system file.
These can be excluded by specifying <literal>DELETE</literal> on the <literal>UNSELECTED</literal>
subcommand.  Specifying <literal>RETAIN</literal> makes the default explicit.
</para>
<para>The <literal>UNCOMPRESSED</literal>, <literal>COMPRESSED</literal>, and
<literal>ZCOMPRESSED</literal> subcommand determine the system file&#8217;s
compression level:
</para>
<variablelist><varlistentry><term><literal>UNCOMPRESSED</literal>
</term><listitem><para>Data is not compressed.  Each numeric value uses 8 bytes of disk
space.  Each string value uses one byte per column width, rounded up
to a multiple of 8 bytes.
</para>
</listitem></varlistentry><varlistentry><term><literal>COMPRESSED</literal>
</term><listitem><para>Data is compressed with a simple algorithm.  Each integer numeric
value between &#8722;99 and 151, inclusive, or system missing value
uses one byte of disk space.  Each 8-byte segment of a string that
consists only of spaces uses 1 byte.  Any other numeric value or
8-byte string segment uses 9 bytes of disk space.
</para>
</listitem></varlistentry><varlistentry><term><literal>ZCOMPRESSED</literal>
</term><listitem><para>Data is compressed with the &#8220;deflate&#8221; compression algorithm
specified in RFC&#160;1951 (the same algorithm used by
<command>gzip</command>).  Files written with this compression level cannot be
read by PSPP 0.8.1 or earlier or by SPSS 20 or earlier.
</para></listitem></varlistentry></variablelist>
<para><literal>COMPRESSED</literal> is the default compression level.  The SET command
(see <link linkend="SET">SET</link>) can change this default.
</para>
<para>The <literal>PERMISSIONS</literal> subcommand specifies permissions for the new system
file.  WRITEABLE, the default, creates the file with read and write
permission.  READONLY creates the file for read-only access.
</para>
<para>By default, all the variables in the active dataset dictionary are written
to the system file.  The <literal>DROP</literal> 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.
</para>
<para>Normally variables are saved to a system file under the same names they
have in the active dataset.  Use the <literal>RENAME</literal> subcommand to change these names.
Specify, within parentheses, a list of variable names followed by an
equals sign (&#8216;<literal>=</literal>&#8217;) and the names that they should be renamed to.
Multiple parenthesized groups of variable names can be included on a
single <literal>RENAME</literal> subcommand.  Variables&#8217; names may be swapped using a
<literal>RENAME</literal> subcommand of the 
form <literal>/RENAME=(<replaceable>A</replaceable> <replaceable>B</replaceable>=<replaceable>B</replaceable> <replaceable>A</replaceable>)</literal>.
</para>
<para>Alternate syntax for the <literal>RENAME</literal> subcommand allows the parentheses to be
eliminated.  When this is done, only a single variable may be renamed at
once.  For instance, <literal>/RENAME=<replaceable>A</replaceable>=<replaceable>B</replaceable></literal>.  This alternate syntax is
deprecated.
</para>
<para><literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> are performed in
left-to-right order.  They
each may be present any number of times.  <literal>SAVE</literal> never modifies
the active dataset.  <literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> only
affect the system file written to disk.
</para>
<para>The <literal>VERSION</literal> subcommand specifies the version of the file format. Valid
versions are 2 and 3.  The default version is 3.  In version 2 system
files, variable names longer than 8 bytes will be truncated.  The two
versions are otherwise identical.
</para>
<para>The <literal>NAMES</literal> and <literal>MAP</literal> subcommands are currently ignored.
</para>
<para><literal>SAVE</literal> causes the data to be read.  It is a procedure.
</para>
</sect1>
<sect1 label="9.7" id="SAVE-TRANSLATE">
<title>SAVE TRANSLATE</title>
<indexterm role="vr"><primary>SAVE TRANSLATE</primary></indexterm>

<literallayout>SAVE TRANSLATE
        /OUTFILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        /TYPE={CSV,TAB}
        [/REPLACE]
        [/MISSING={IGNORE,RECODE}]

        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/UNSELECTED={RETAIN,DELETE}]
        [/MAP]

        &#8230;additional subcommands depending on TYPE&#8230;
</literallayout>
<para>The <literal>SAVE TRANSLATE</literal> command is used to save data into various
formats understood by other applications.
</para>
<para>The <literal>OUTFILE</literal> and <literal>TYPE</literal> subcommands are mandatory.
<literal>OUTFILE</literal> specifies the file to be written, as a string file name or a file handle
(see <link linkend="File-Handles">File Handles</link>).  <literal>TYPE</literal> determines the type of the file or
source to read.  It must be one of the following:
</para>
<variablelist><varlistentry><term>CSV
</term><listitem><para>Comma-separated value format,
</para>
</listitem></varlistentry><varlistentry><term>TAB
</term><listitem><para>Tab-delimited format.
</para></listitem></varlistentry></variablelist>
<para>By default, <literal>SAVE TRANSLATE</literal> will not overwrite an existing file.  Use
<literal>REPLACE</literal> to force an existing file to be overwritten.
</para>
<para>With MISSING=IGNORE, the default, <literal>SAVE TRANSLATE</literal> treats user-missing
values as if they were not missing.  Specify MISSING=RECODE to output
numeric user-missing values like system-missing values and string
user-missing values as all spaces.
</para>
<para>By default, all the variables in the active dataset dictionary are saved
to the system file, but <literal>DROP</literal> or <literal>KEEP</literal> can select a subset of variable
to save.  The <literal>RENAME</literal> subcommand can also be used to change the names
under which variables are saved.  <literal>UNSELECTED</literal> determines whether cases
filtered out by the <literal>FILTER</literal> command are written to the output file.
These subcommands have the same syntax and meaning as on the
<literal>SAVE</literal> command (see <link linkend="SAVE">SAVE</link>).
</para>
<para>Each supported file type has additional subcommands, explained in
separate sections below.
</para>
<para><literal>SAVE TRANSLATE</literal> causes the data to be read.  It is a procedure.
</para>

<sect2 label="9.7.1" id="SAVE-TRANSLATE-_002fTYPE_003dCSV-and-TYPE_003dTAB">
<title>Writing Comma- and Tab-Separated Data Files</title>

<literallayout>SAVE TRANSLATE
        /OUTFILE={&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>}
        /TYPE=CSV
        [/REPLACE]
        [/MISSING={IGNORE,RECODE}]

        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/UNSELECTED={RETAIN,DELETE}]

        [/FIELDNAMES]
        [/CELLS={VALUES,LABELS}]
        [/TEXTOPTIONS DELIMITER=&#8217;<replaceable>delimiter</replaceable>&#8217;]
        [/TEXTOPTIONS QUALIFIER=&#8217;<replaceable>qualifier</replaceable>&#8217;]
        [/TEXTOPTIONS DECIMAL={DOT,COMMA}]
        [/TEXTOPTIONS FORMAT={PLAIN,VARIABLE}]
</literallayout>
<para>The SAVE TRANSLATE command with TYPE=CSV or TYPE=TAB writes data in a
comma- or tab-separated value format similar to that described by
RFC&#160;4180.  Each variable becomes one output column, and each case
becomes one line of output.  If FIELDNAMES is specified, an additional
line at the top of the output file lists variable names.
</para>
<para>The CELLS and TEXTOPTIONS FORMAT settings determine how values are
written to the output file:
</para>
<variablelist><varlistentry><term>CELLS=VALUES FORMAT=PLAIN (the default settings)
</term><listitem><para>Writes variables to the output in &#8220;plain&#8221; formats that ignore the
details of variable formats.  Numeric values are written as plain
decimal numbers with enough digits to indicate their exact values in
machine representation.  Numeric values include &#8216;<literal>e</literal>&#8217; followed by
an exponent if the exponent value would be less than -4 or greater
than 16.  Dates are written in MM/DD/YYYY format and times in HH:MM:SS
format.  WKDAY and MONTH values are written as decimal numbers.
</para>
<para>Numeric values use, by default, the decimal point character set with
SET DECIMAL (see <link linkend="SET-DECIMAL">SET DECIMAL</link>).  Use DECIMAL=DOT or DECIMAL=COMMA
to force a particular decimal point character.
</para>
</listitem></varlistentry><varlistentry><term>CELLS=VALUES FORMAT=VARIABLE
</term><listitem><para>Writes variables using their print formats.  Leading and trailing
spaces are removed from numeric values, and trailing spaces are
removed from string values.
</para>
</listitem></varlistentry><varlistentry><term>CELLS=LABEL FORMAT=PLAIN
</term><term>CELLS=LABEL FORMAT=VARIABLE
</term><listitem><para>Writes value labels where they exist, and otherwise writes the values
themselves as described above.
</para></listitem></varlistentry></variablelist>
<para>Regardless of CELLS and TEXTOPTIONS FORMAT, numeric system-missing
values are output as a single space.
</para>
<para>For TYPE=TAB, tab characters delimit values.  For TYPE=CSV, the
TEXTOPTIONS DELIMITER and DECIMAL settings determine the character
that separate values within a line.  If DELIMITER is specified, then
the specified string separate values.  If DELIMITER is not specified,
then the default is a comma with DECIMAL=DOT or a semicolon with
DECIMAL=COMMA.  If DECIMAL is not given either, it is implied by the
decimal point character set with SET DECIMAL (see <link linkend="SET-DECIMAL">SET DECIMAL</link>).
</para>
<para>The TEXTOPTIONS QUALIFIER setting specifies a character that is output
before and after a value that contains the delimiter character or the
qualifier character.  The default is a double quote (&#8216;<literal>&quot;</literal>&#8217;).  A
qualifier character that appears within a value is doubled.
</para>
</sect2>
</sect1>
<sect1 label="9.8" id="SYSFILE-INFO">
<title>SYSFILE INFO</title>
<indexterm role="vr"><primary>SYSFILE INFO</primary></indexterm>

<literallayout>SYSFILE INFO FILE=&#8217;<replaceable>file_name</replaceable>&#8217; [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;].
</literallayout>
<para><literal>SYSFILE INFO</literal> reads the dictionary in an SPSS system file,
SPSS/PC+ system file, or SPSS portable file, and displays the
information in its dictionary.
</para>
<para>Specify a file name or file handle.  <literal>SYSFILE INFO</literal> reads that
file and displays information on its dictionary.
</para>
<para>pspp automatically detects the encoding of string data in the file,
when possible.  The character encoding of old SPSS system files cannot
always be guessed correctly, and SPSS/PC+ system files do not include
any indication of their encoding.  Specify the <literal>ENCODING</literal>
subcommand with an <acronym>IANA</acronym> character set name as its string
argument to override the default, or specify <literal>ENCODING='DETECT'</literal>
to analyze and report possibly valid encodings for the system file.
The <literal>ENCODING</literal> subcommand is a pspp extension.
</para>
<para><literal>SYSFILE INFO</literal> does not affect the current active dataset.
</para>
</sect1>
<sect1 label="9.9" id="XEXPORT">
<title>XEXPORT</title>
<indexterm role="vr"><primary>XEXPORT</primary></indexterm>

<literallayout>XEXPORT
        /OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        /DIGITS=<replaceable>n</replaceable>
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
        /TYPE={COMM,TAPE}
        /MAP
</literallayout>
<para>The <literal>EXPORT</literal> transformation writes the active dataset dictionary and
data to a specified portable file.
</para>
<para>This transformation is a pspp extension.
</para>
<para>It is similar to the <literal>EXPORT</literal> procedure, with two differences:
</para>
<itemizedlist><listitem><para><literal>XEXPORT</literal> is a transformation, not a procedure.  It is executed when
the data is read by a procedure or procedure-like command.
</para>
</listitem><listitem><para><literal>XEXPORT</literal> does not support the <literal>UNSELECTED</literal> subcommand.
</para></listitem></itemizedlist>
<para>See <link linkend="EXPORT">EXPORT</link>, for more information.
</para>
</sect1>
<sect1 label="9.10" id="XSAVE">
<title>XSAVE</title>
<indexterm role="vr"><primary>XSAVE</primary></indexterm>

<literallayout>XSAVE
        /OUTFILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        /{UNCOMPRESSED,COMPRESSED,ZCOMPRESSED}
        /PERMISSIONS={WRITEABLE,READONLY}
        /DROP=<replaceable>var_list</replaceable>
        /KEEP=<replaceable>var_list</replaceable>
        /VERSION=<replaceable>version</replaceable>
        /RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;
        /NAMES
        /MAP
</literallayout>
<para>The <literal>XSAVE</literal> transformation writes the active dataset&#8217;s dictionary and
data to a system file.  It is similar to the <literal>SAVE</literal>
procedure, with two differences:
</para>
<itemizedlist><listitem><para><literal>XSAVE</literal> is a transformation, not a procedure.  It is executed when
the data is read by a procedure or procedure-like command.
</para>
</listitem><listitem><para><literal>XSAVE</literal> does not support the <literal>UNSELECTED</literal> subcommand.
</para></listitem></itemizedlist>
<para>See <link linkend="SAVE">SAVE</link>, for more information.
</para></sect1>
</chapter>
<chapter label="10" id="Combining-Data-Files">
<title>Combining Data Files</title>

<para>This chapter describes commands that allow data from system files,
portable files, and open datasets to be combined to
form a new active dataset.  These commands can combine data files in the
following ways:
</para>
<itemizedlist><listitem><para><literal>ADD FILES</literal> interleaves or appends the cases from each input file.
It is used with input files that have variables in common, but
distinct sets of cases.
</para>
</listitem><listitem><para><literal>MATCH FILES</literal> adds the data together in cases that match across
multiple input files.  It is used with input files that have cases in
common, but different information about each case.
</para>
</listitem><listitem><para><literal>UPDATE</literal> updates a master data file from data in a set of
transaction files.  Each case in a transaction data file modifies a
matching case in the primary data file, or it adds a new case if no
matching case can be found.
</para></listitem></itemizedlist>
<para>These commands share the majority of their syntax, which is described
in the following section, followed by one section for each command
that describes its specific syntax and semantics.
</para>

<sect1 label="10.1" id="Combining-Files-Common-Syntax">
<title>Common Syntax</title>

<literallayout>Per input file:
        /FILE={*,&#8217;<replaceable>file_name</replaceable>&#8217;}
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/IN=<replaceable>var_name</replaceable>]
        [/SORT]

Once per command:
        /BY <replaceable>var_list</replaceable>[({D|A})] [<replaceable>var_list</replaceable>[({D|A}]]&#8230;
        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/FIRST=<replaceable>var_name</replaceable>]
        [/LAST=<replaceable>var_name</replaceable>]
        [/MAP]
</literallayout>
<para>This section describes the syntactical features in common among the
<literal>ADD FILES</literal>, <literal>MATCH FILES</literal>, and <literal>UPDATE</literal> commands.  The
following sections describe details specific to each command.
</para>
<para>Each of these commands reads two or more input files and combines them.  
The command&#8217;s output becomes the new active dataset.
None of the commands actually change the input files.
Therefore, if you want the changes to become permanent, you must explicitly
save them using an appropriate procedure or transformation (see <link linkend="System-and-Portable-File-IO">System and Portable File IO</link>).
</para>
<para>The syntax of each command begins with a specification of the files to
be read as input.  For each input file, specify FILE with a system
file or portable file&#8217;s name as a string, a dataset (see <link linkend="Datasets">Datasets</link>)
or file handle name, (see <link linkend="File-Handles">File Handles</link>), or an asterisk (&#8216;<literal>*</literal>&#8217;)
to use the active dataset as input.  Use of portable files on <literal>FILE</literal> is a
pspp extension.
</para>
<para>At least two <literal>FILE</literal> subcommands must be specified.  If the active dataset
is used as an input source, then <literal>TEMPORARY</literal> must not be in
effect.
</para>
<para>Each <literal>FILE</literal> subcommand may be followed by any number of <literal>RENAME</literal>
subcommands that specify a parenthesized group or groups of variable
names as they appear in the input file, followed by those variables&#8217;
new names, separated by an equals sign (<literal>=</literal>),
e.g. <literal>/RENAME=(OLD1=NEW1)(OLD2=NEW2)</literal>.  To rename a single
variable, the parentheses may be omitted: <literal>/RENAME=<replaceable>old</replaceable>=<replaceable>new</replaceable></literal>.
Within a parenthesized group, variables are renamed simultaneously, so
that <literal>/RENAME=(<replaceable>A</replaceable> <replaceable>B</replaceable>=<replaceable>B</replaceable> <replaceable>A</replaceable>)</literal> exchanges the
names of variables <replaceable>A</replaceable> and <replaceable>B</replaceable>.
Otherwise, renaming occurs in left-to-right order.
</para>
<para>Each <literal>FILE</literal> subcommand may optionally be followed by a single <literal>IN</literal>
subcommand, which creates a numeric variable with the specified name
and format F1.0.  The IN variable takes value 1 in an output case if
the given input file contributed to that output case, and 0 otherwise.
The <literal>DROP</literal>, <literal>KEEP</literal>, and <literal>RENAME</literal> subcommands have no effect on IN variables.
</para>
<para>If <literal>BY</literal> is used (see below), the <literal>SORT</literal> keyword must be specified after a
<literal>FILE</literal> if that input file is not already sorted on the <literal>BY</literal> variables.
When <literal>SORT</literal> is specified, pspp sorts the input file&#8217;s data on the <literal>BY</literal>
variables before it applies it to the command.  When <literal>SORT</literal> is used, <literal>BY</literal>
is required.  <literal>SORT</literal> is a pspp extension.
</para>
<para>pspp merges the dictionaries of all of the input files to form the
dictionary of the new active dataset, like so:
</para>
<itemizedlist><listitem><para>The variables in the new active dataset are the union of all the input files&#8217;
variables, matched based on their name.  When a single input file
contains a variable with a given name, the output file will contain
exactly that variable.  When more than one input file contains a
variable with a given name, those variables must all have the same
type (numeric or string) and, for string variables, the same width.
Variables are matched after renaming with the <literal>RENAME</literal> subcommand.
Thus, <literal>RENAME</literal> can be used to resolve conflicts.
</para>
</listitem><listitem><para>The variable label for each output variable is taken from the first
specified input file that has a variable label for that variable, and
similarly for value labels and missing values.
</para>
</listitem><listitem><para>The file label of the new active dataset (see <link linkend="FILE-LABEL">FILE LABEL</link>) is that of the
first specified <literal>FILE</literal> that has a file label.
</para>
</listitem><listitem><para>The documents in the new active dataset (see <link linkend="DOCUMENT">DOCUMENT</link>) are the
concatenation of all the input files&#8217; documents, in the order in which
the <literal>FILE</literal> subcommands are specified.
</para>
</listitem><listitem><para>If all of the input files are weighted on the same variable, then the
new active dataset is weighted on that variable.  Otherwise, the new
active dataset is not weighted.
</para></listitem></itemizedlist>
<para>The remaining subcommands apply to the output file as a whole, rather
than to individual input files.  They must be specified at the end of
the command specification, following all of the <literal>FILE</literal> and related
subcommands.  The most important of these subcommands is <literal>BY</literal>, which
specifies a set of one or more variables that may be used to find
corresponding cases in each of the input files.  The variables
specified on <literal>BY</literal> must be present in all of the input files.
Furthermore, if any of the input files are not sorted on the <literal>BY</literal>
variables, then <literal>SORT</literal> must be specified for those input files.
</para>
<para>The variables listed on <literal>BY</literal> may include (A) or (D) annotations to
specify ascending or descending sort order.  See <link linkend="SORT-CASES">SORT CASES</link>, for
more details on this notation.  Adding (A) or (D) to the <literal>BY</literal> subcommand
specification is a pspp extension.
</para>
<para>The <literal>DROP</literal> subcommand can be used to specify a list of variables to
exclude from the output.  By contrast, the <literal>KEEP</literal> subcommand can be used
to specify variables to include in the output; all variables not
listed are dropped.  <literal>DROP</literal> and <literal>KEEP</literal> are executed in left-to-right order
and may be repeated any number of times.  <literal>DROP</literal> and <literal>KEEP</literal> do not affect
variables created by the <literal>IN</literal>, <literal>FIRST</literal>, and <literal>LAST</literal> subcommands, which are
always included in the new active dataset, but they can be used to drop
<literal>BY</literal> variables.
</para>
<para>The <literal>FIRST</literal> and <literal>LAST</literal> subcommands are optional.  They may only be
specified on <literal>MATCH FILES</literal> and <literal>ADD FILES</literal>, and only when <literal>BY</literal>
is used.  <literal>FIRST</literal> and <literal>LIST</literal> each adds a numeric variable to the new
active dataset, with the name given as the subcommand&#8217;s argument and F1.0
print and write formats.  The value of the <literal>FIRST</literal> variable is 1 in the
first output case with a given set of values for the <literal>BY</literal> variables, and
0 in other cases.  Similarly, the <literal>LAST</literal> variable is 1 in the last case
with a given of <literal>BY</literal> values, and 0 in other cases.
</para>
<para>When any of these commands creates an output case, variables that are
only in files that are not present for the current case are set to the
system-missing value for numeric variables or spaces for string
variables.
</para>
<para>These commands may combine any number of files, limited only by the
machine&#8217;s memory.
</para>
</sect1>
<sect1 label="10.2" id="ADD-FILES">
<title>ADD FILES</title>
<indexterm role="vr"><primary>ADD FILES</primary></indexterm>

<literallayout>ADD FILES

Per input file:
        /FILE={*,&#8217;<replaceable>file_name</replaceable>&#8217;}
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/IN=<replaceable>var_name</replaceable>]
        [/SORT]

Once per command:
        [/BY <replaceable>var_list</replaceable>[({D|A})] [<replaceable>var_list</replaceable>[({D|A})]&#8230;]]
        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/FIRST=<replaceable>var_name</replaceable>]
        [/LAST=<replaceable>var_name</replaceable>]
        [/MAP]
</literallayout>
<para><literal>ADD FILES</literal> adds cases from multiple input files.  The output,
which replaces the active dataset, consists all of the cases in all of
the input files.
</para>
<para><literal>ADD FILES</literal> shares the bulk of its syntax with other pspp commands for
combining multiple data files.  See <link linkend="Combining-Files-Common-Syntax">Combining Files Common Syntax</link>,
above, for an explanation of this common syntax.
</para>
<para>When <literal>BY</literal> is not used, the output of <literal>ADD FILES</literal> consists of all the cases
from the first input file specified, followed by all the cases from
the second file specified, and so on.  When <literal>BY</literal> is used, the output is
additionally sorted on the <literal>BY</literal> variables.
</para>
<para>When <literal>ADD FILES</literal> creates an output case, variables that are not part of
the input file from which the case was drawn are set to the
system-missing value for numeric variables or spaces for string
variables.
</para>
</sect1>
<sect1 label="10.3" id="MATCH-FILES">
<title>MATCH FILES</title>
<indexterm role="vr"><primary>MATCH FILES</primary></indexterm>

<literallayout>MATCH FILES

Per input file:
        /{FILE,TABLE}={*,&#8217;<replaceable>file_name</replaceable>&#8217;}
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/IN=<replaceable>var_name</replaceable>]
        [/SORT]

Once per command:
        /BY <replaceable>var_list</replaceable>[({D|A}] [<replaceable>var_list</replaceable>[({D|A})]&#8230;]
        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/FIRST=<replaceable>var_name</replaceable>]
        [/LAST=<replaceable>var_name</replaceable>]
        [/MAP]
</literallayout>
<para><literal>MATCH FILES</literal> merges sets of corresponding cases in multiple
input files into single cases in the output, combining their data.
</para>
<para><literal>MATCH FILES</literal> shares the bulk of its syntax with other pspp commands for
combining multiple data files.  See <link linkend="Combining-Files-Common-Syntax">Combining Files Common Syntax</link>,
above, for an explanation of this common syntax.
</para>
<para>How <literal>MATCH FILES</literal> matches up cases from the input files depends on
whether <literal>BY</literal> is specified:
</para>
<itemizedlist><listitem><para>If <literal>BY</literal> is not used, <literal>MATCH FILES</literal> combines the first case from each input
file to produce the first output case, then the second case from each
input file for the second output case, and so on.  If some input files
have fewer cases than others, then the shorter files do not contribute
to cases output after their input has been exhausted.
</para>
</listitem><listitem><para>If <literal>BY</literal> is used, <literal>MATCH FILES</literal> combines cases from each input file that
have identical values for the <literal>BY</literal> variables.
</para>
<para>When <literal>BY</literal> is used, <literal>TABLE</literal> subcommands may be used to introduce <firstterm>table
lookup file</firstterm>.  <literal>TABLE</literal> has same syntax as <literal>FILE</literal>, and the <literal>RENAME</literal>, <literal>IN</literal>, and
<literal>SORT</literal> subcommands may follow a <literal>TABLE</literal> in the same way as <literal>FILE</literal>.
Regardless of the number of <literal>TABLE</literal>s, at least one <literal>FILE</literal> must specified.
Table lookup files are treated in the same way as other input files
for most purposes and, in particular, table lookup files must be
sorted on the <literal>BY</literal> variables or the <literal>SORT</literal> subcommand must be specified
for that <literal>TABLE</literal>.
</para>
<para>Cases in table lookup files are not consumed after they have been used
once.  This means that data in table lookup files can correspond to
any number of cases in <literal>FILE</literal> input files.  Table lookup files are
analogous to lookup tables in traditional relational database systems.
</para>
<para>If a table lookup file contains more than one case with a given set of
<literal>BY</literal> variables, only the first case is used.
</para></listitem></itemizedlist>
<para>When <literal>MATCH FILES</literal> creates an output case, variables that are only in
files that are not present for the current case are set to the
system-missing value for numeric variables or spaces for string
variables.
</para>
</sect1>
<sect1 label="10.4" id="UPDATE">
<title>UPDATE</title>
<indexterm role="vr"><primary>UPDATE</primary></indexterm>

<literallayout>UPDATE

Per input file:
        /FILE={*,&#8217;<replaceable>file_name</replaceable>&#8217;}
        [/RENAME=(<replaceable>src_names</replaceable>=<replaceable>target_names</replaceable>)&#8230;]
        [/IN=<replaceable>var_name</replaceable>]
        [/SORT]

Once per command:
        /BY <replaceable>var_list</replaceable>[({D|A})] [<replaceable>var_list</replaceable>[({D|A})]]&#8230;
        [/DROP=<replaceable>var_list</replaceable>]
        [/KEEP=<replaceable>var_list</replaceable>]
        [/MAP]
</literallayout>
<para><literal>UPDATE</literal> updates a <firstterm>master file</firstterm> by applying modifications
from one or more <firstterm>transaction files</firstterm>.  
</para>
<para><literal>UPDATE</literal> shares the bulk of its syntax with other pspp commands for
combining multiple data files.  See <link linkend="Combining-Files-Common-Syntax">Combining Files Common Syntax</link>,
above, for an explanation of this common syntax.
</para>
<para>At least two <literal>FILE</literal> subcommands must be specified.  The first <literal>FILE</literal>
subcommand names the master file, and the rest name transaction files.
Every input file must either be sorted on the variables named on the
<literal>BY</literal> subcommand, or the <literal>SORT</literal> subcommand must be used just after the <literal>FILE</literal>
subcommand for that input file.
</para>
<para><literal>UPDATE</literal> uses the variables specified on the <literal>BY</literal> subcommand, which is
required, to attempt to match each case in a transaction file with a
case in the master file:
</para>
<itemizedlist><listitem><para>When a match is found, then the values of the variables present in the
transaction file replace those variables&#8217; values in the new active
file.  If there are matching cases in more than more transaction file,
pspp applies the replacements from the first transaction file, then
from the second transaction file, and so on.  Similarly, if a single
transaction file has cases with duplicate <literal>BY</literal> values, then those are
applied in order to the master file.
</para>
<para>When a variable in a transaction file has a missing value or when a string
variable&#8217;s value is all blanks, that value is never used to update the
master file.
</para>
</listitem><listitem><para>If a case in the master file has no matching case in any transaction
file, then it is copied unchanged to the output.
</para>
</listitem><listitem><para>If a case in a transaction file has no matching case in the master
file, then it causes a new case to be added to the output, initialized
from the values in the transaction file.
</para></listitem></itemizedlist></sect1>
</chapter>
<chapter label="11" id="Variable-Attributes">
<title>Manipulating variables</title>

<para>The variables in the active dataset dictionary are important.  There are
several utility functions for examining and adjusting them.
</para>

<sect1 label="11.1" id="ADD-VALUE-LABELS">
<title>ADD VALUE LABELS</title>
<indexterm role="vr"><primary>ADD VALUE LABELS</primary></indexterm>

<literallayout>ADD VALUE LABELS
        /<replaceable>var_list</replaceable> <replaceable>value</replaceable> &#8217;<replaceable>label</replaceable>&#8217; [<replaceable>value</replaceable> &#8217;<replaceable>label</replaceable>&#8217;]&#8230;
</literallayout>
<para><literal>ADD VALUE LABELS</literal> has the same syntax and purpose as <literal>VALUE
LABELS</literal> (see <link linkend="VALUE-LABELS">VALUE LABELS</link>), but it does not clear value
labels from the variables before adding the ones specified.
</para>
</sect1>
<sect1 label="11.2" id="DELETE-VARIABLES">
<title>DELETE VARIABLES</title>
<indexterm role="vr"><primary>DELETE VARIABLES</primary></indexterm>

<literallayout>DELETE VARIABLES <replaceable>var_list</replaceable>.
</literallayout>
<para><literal>DELETE VARIABLES</literal> deletes the specified variables from the
dictionary.  It may not be used to delete all variables from the
dictionary; use <literal>NEW FILE</literal> to do that (see <link linkend="NEW-FILE">NEW FILE</link>).
</para>
<para><literal>DELETE VARIABLES</literal> should not be used after defining transformations
but before executing a procedure.  If it is used in such a context, it
causes the data to be read.  If it is used while <literal>TEMPORARY</literal> is in
effect, it causes the temporary transformations to become permanent.
</para>
</sect1>
<sect1 label="11.3" id="DISPLAY">
<title>DISPLAY</title>
<indexterm role="vr"><primary>DISPLAY</primary></indexterm>

<literallayout>DISPLAY [SORTED] NAMES [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] INDEX [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] LABELS [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] VARIABLES [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] SCRATCH [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] @ATTRIBUTES [[/VARIABLES=]<replaceable>var_list</replaceable>].
DISPLAY [SORTED] VECTORS.
</literallayout>
<para><literal>DISPLAY</literal> displays information about the active dataset.  A variety
of different forms of information can be requested.
</para>
<para>The following keywords primarily cause information about variables to
be displayed.  With these keywords, by default information is
displayed about all variable in the active dataset, in the order that
variables occur in the active dataset dictionary.  The <literal>SORTED</literal> keyword
causes output to be sorted alphabetically by variable name.  The
<literal>VARIABLES</literal> subcommand limits output to the specified variables.
</para>
<variablelist><varlistentry><term>NAMES
</term><listitem><para>The variables&#8217; names are displayed.
</para>
</listitem></varlistentry><varlistentry><term>INDEX
</term><listitem><para>The variables&#8217; names are displayed along with a value describing their
position within the active dataset dictionary.
</para>
</listitem></varlistentry><varlistentry><term>LABELS
</term><listitem><para>Variable names, positions, and variable labels are displayed.
</para>
</listitem></varlistentry><varlistentry><term>VARIABLES
</term><listitem><para>Variable names, positions, print and write formats, and missing values
are displayed.
</para>
</listitem></varlistentry><varlistentry><term>DICTIONARY
</term><listitem><para>Variable names, positions, print and write formats, missing values,
variable labels, and value labels are displayed.
</para>
</listitem></varlistentry><varlistentry><term>SCRATCH
</term><listitem><para>Variable names are displayed, for scratch variables only (see <link linkend="Scratch-Variables">Scratch
Variables</link>).
</para>
</listitem></varlistentry><varlistentry><term>ATTRIBUTES
</term><term>@ATTRIBUTES
</term><listitem><para>Datafile and variable attributes are displayed.
The first form of the command omits those attributes 
whose names begin with <literal>@</literal> or <literal>$@</literal>.
In the second for, all datafile and variable attributes are displayed.
</para></listitem></varlistentry></variablelist>
<para>With the <literal>VECTOR</literal> keyword, <literal>DISPLAY</literal> lists all the currently
declared vectors.  If the <literal>SORTED</literal> keyword is given, the vectors are
listed in alphabetical order; otherwise, they are listed in textual
order of definition within the pspp syntax file.
</para>
<para>For related commands, see <link linkend="DISPLAY-DOCUMENTS">DISPLAY DOCUMENTS</link> and <link linkend="DISPLAY-FILE-LABEL">DISPLAY
FILE LABEL</link>.
</para>
</sect1>
<sect1 label="11.4" id="FORMATS">
<title>FORMATS</title>
<indexterm role="vr"><primary>FORMATS</primary></indexterm>

<literallayout>FORMATS <replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>) [<replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>)]&#8230;.
</literallayout>
<para><literal>FORMATS</literal> set both print and write formats for the specified
variables to the specified format specification.
See <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.
</para>
<para>Specify a list of variables followed by a format specification in
parentheses.  The print and write formats of the specified variables
will be changed.  All of the variables listed together must have
the same type and, for string variables, the same width.
</para>
<para>Additional lists of variables and formats may be included following
the first one.
</para>
<para><literal>FORMATS</literal> takes effect immediately.  It is not affected by
conditional and looping structures such as <literal>DO IF</literal> or <literal>LOOP</literal>.
</para>
</sect1>
<sect1 label="11.5" id="LEAVE">
<title>LEAVE</title>
<indexterm role="vr"><primary>LEAVE</primary></indexterm>

<literallayout>LEAVE <replaceable>var_list</replaceable>.
</literallayout>
<para><literal>LEAVE</literal> prevents the specified variables from being
reinitialized whenever a new case is processed.
</para>
<para>Normally, when a data file is processed, every variable in the active
dataset is initialized to the system-missing value or spaces at the
beginning of processing for each case.  When a variable has been
specified on <literal>LEAVE</literal>, 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.
</para>
<para>This becomes useful for counters.  For instance, in the example below
the variable <literal>SUM</literal> maintains a running total of the values in the <literal>ITEM</literal>
variable.
</para>
<screen>DATA LIST /ITEM 1-3.
COMPUTE SUM=SUM+ITEM.
PRINT /ITEM SUM.
LEAVE SUM
BEGIN DATA.
123
404
555
999
END DATA.
</screen>
<para>Partial output from this example:
</para>
<screen>123   123.00
404   527.00
555  1082.00
999  2081.00
</screen>
<para>It is best to use <literal>LEAVE</literal> command immediately before invoking a
procedure command, because the left status of variables is reset by
certain transformations&#8212;for instance, <literal>COMPUTE</literal> and <literal>IF</literal>.
Left status is also reset by all procedure invocations.
</para>
</sect1>
<sect1 label="11.6" id="MISSING-VALUES">
<title>MISSING VALUES</title>
<indexterm role="vr"><primary>MISSING VALUES</primary></indexterm>

<literallayout>MISSING VALUES <replaceable>var_list</replaceable> (<replaceable>missing_values</replaceable>).

where <replaceable>missing_values</replaceable> takes one of the following forms:
        <replaceable>num1</replaceable>
        <replaceable>num1</replaceable>, <replaceable>num2</replaceable>
        <replaceable>num1</replaceable>, <replaceable>num2</replaceable>, <replaceable>num3</replaceable>
        <replaceable>num1</replaceable> THRU <replaceable>num2</replaceable>
        <replaceable>num1</replaceable> THRU <replaceable>num2</replaceable>, <replaceable>num3</replaceable>
        <replaceable>string1</replaceable>
        <replaceable>string1</replaceable>, <replaceable>string2</replaceable>
        <replaceable>string1</replaceable>, <replaceable>string2</replaceable>, <replaceable>string3</replaceable>
As part of a range, <literal>LO</literal> or <literal>LOWEST</literal> may take the place of <replaceable>num1</replaceable>;
<literal>HI</literal> or <literal>HIGHEST</literal> may take the place of <replaceable>num2</replaceable>.
</literallayout>
<para><literal>MISSING VALUES</literal> sets user-missing values for numeric and string
variables.  Long string variables may have missing values, but
characters after the first 8 bytes of the missing value must be
spaces.
</para>
<para>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 <literal>LO</literal> or <literal>LOWEST</literal> or <literal>HI</literal> or <literal>HIGHEST</literal>.
</para>
<para>The <literal>MISSING VALUES</literal> command takes effect immediately.  It is not
affected by conditional and looping constructs such as <literal>DO IF</literal> or
<literal>LOOP</literal>.
</para>
</sect1>
<sect1 label="11.7" id="MODIFY-VARS">
<title>MODIFY VARS</title>
<indexterm role="vr"><primary>MODIFY VARS</primary></indexterm>

<literallayout>MODIFY VARS
        /REORDER={FORWARD,BACKWARD} {POSITIONAL,ALPHA} (<replaceable>var_list</replaceable>)&#8230;
        /RENAME=(<replaceable>old_names</replaceable>=<replaceable>new_names</replaceable>)&#8230;
        /{DROP,KEEP}=<replaceable>var_list</replaceable>
        /MAP    
</literallayout>
<para><literal>MODIFY VARS</literal> reorders, renames, and deletes variables in the
active dataset.
</para>
<para>At least one subcommand must be specified, and no subcommand may be
specified more than once.  <literal>DROP</literal> and <literal>KEEP</literal> may not both
be specified.
</para>
<para>The <literal>REORDER</literal> subcommand changes the order of variables in the active
dataset.  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 <literal>BACKWARD</literal> before the parentheses.  To put them into alphabetical
order in the dictionary, specify keyword <literal>ALPHA</literal> before the parentheses.
<literal>BACKWARD</literal> and <literal>ALPHA</literal> may also be combined.
</para>
<para>To rename variables in the active dataset, specify <literal>RENAME</literal>, an equals sign
(&#8216;<literal>=</literal>&#8217;), 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.
</para>
<para>The <literal>DROP</literal> subcommand deletes a specified list of variables from the
active dataset.
</para>
<para>The <literal>KEEP</literal> subcommand keeps the specified list of variables in the active
dataset.  Any unlisted variables are deleted from the active dataset.
</para>
<para><literal>MAP</literal> is currently ignored.
</para>
<para>If either <literal>DROP</literal> or <literal>KEEP</literal> is specified, the data is read;
otherwise it is not.
</para>
<para><literal>MODIFY VARS</literal> may not be specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>).
</para>
</sect1>
<sect1 label="11.8" id="MRSETS">
<title>MRSETS</title>
<indexterm role="vr"><primary>MRSETS</primary></indexterm>

<literallayout>MRSETS 
    /MDGROUP NAME=<replaceable>name</replaceable> VARIABLES=<replaceable>var_list</replaceable> VALUE=<replaceable>value</replaceable>
     [CATEGORYLABELS={VARLABELS,COUNTEDVALUES}]
     [{LABEL=&#8217;<replaceable>label</replaceable>&#8217;,LABELSOURCE=VARLABEL}]

    /MCGROUP NAME=<replaceable>name</replaceable> VARIABLES=<replaceable>var_list</replaceable> [LABEL=&#8217;<replaceable>label</replaceable>&#8217;]

    /DELETE NAME={[<replaceable>names</replaceable>],ALL}

    /DISPLAY NAME={[<replaceable>names</replaceable>],ALL}
</literallayout>
<para><literal>MRSETS</literal> creates, modifies, deletes, and displays multiple
response sets.  A multiple response set is a set of variables that
represent multiple responses to a single survey question in one of the
two following ways:
</para>
<itemizedlist><listitem><para>A <firstterm>multiple dichotomy set</firstterm> is analogous to a survey question with
a set of checkboxes.  Each variable in the set is treated in a Boolean
fashion: one value (the &quot;counted value&quot;) means that the box was
checked, and any other value means that it was not.
</para>
</listitem><listitem><para>A <firstterm>multiple category set</firstterm> represents a survey question where the
respondent is instructed to list up to <replaceable>n</replaceable> choices.  Each variable
represents one of the responses.
</para></listitem></itemizedlist>
<para>Any number of subcommands may be specified in any order.
</para>
<para>The <literal>MDGROUP</literal> subcommand creates a new multiple dichotomy set or
replaces an existing multiple response set.  The <literal>NAME</literal>,
<literal>VARIABLES</literal>, and
<literal>VALUE</literal> specifications are required.  The others are optional:
</para>
<itemizedlist><listitem><para><replaceable>NAME</replaceable> specifies the name used in syntax for the new multiple dichotomy
set.  The name must begin with &#8216;<literal>$</literal>&#8217;; it must otherwise follow the
rules for identifiers (see <link linkend="Tokens">Tokens</link>).
</para>
</listitem><listitem><para><literal>VARIABLES</literal> specifies the variables that belong to the set.  At least
two variables must be specified.  The variables must be all string or
all numeric.
</para>
</listitem><listitem><para><literal>VALUE</literal> specifies the counted value.  If the variables are numeric, the
value must be an integer.  If the variables are strings, then the
value must be a string that is no longer than the shortest of the
variables in the set (ignoring trailing spaces).
</para>
</listitem><listitem><para><literal>CATEGORYLABELS</literal> optionally specifies the source of the labels for each
category in the set:
</para>
<itemizedlist><listitem><para>&#8722; <literal>VARLABELS</literal>, the default, uses variable labels or, for variables without
variable labels, variable names.  pspp warns if two variables have the
same variable label, since these categories cannot be distinguished in
output.
</para>
</listitem><listitem><para>&#8722; <literal>COUNTEDVALUES</literal> instead uses each variable&#8217;s value label for the counted
value.  pspp warns if two variables have the same value label for the
counted value or if one of the variables lacks a value label, since
such categories cannot be distinguished in output.
</para></listitem></itemizedlist>
</listitem><listitem><para><literal>LABEL</literal> optionally specifies a label for the multiple response set.  If
neither <literal>LABEL</literal> nor <literal>LABELSOURCE=VARLABEL</literal> is specified, the set is
unlabeled.
</para>
</listitem><listitem><para><literal>LABELSOURCE=VARLABEL</literal> draws the multiple response set&#8217;s label from the
first variable label among the variables in the set; if none of the
variables has a label, the name of the first variable is used.
<literal>LABELSOURCE=VARLABEL</literal> must be used with <literal>CATEGORYLABELS=COUNTEDVALUES</literal>.
It is mutually exclusive with <literal>LABEL</literal>.
</para></listitem></itemizedlist>
<para>The <literal>MCGROUP</literal> subcommand creates a new multiple category set or
replaces an existing multiple response set.  The <literal>NAME</literal> and <literal>VARIABLES</literal>
specifications are required, and <literal>LABEL</literal> is optional.  Their meanings
are as described above in <literal>MDGROUP</literal>.  pspp warns if two variables in the
set have different value labels for a single value, since each of the
variables in the set should have the same possible categories.
</para>
<para>The <literal>DELETE</literal> subcommand deletes multiple response groups.  A list of
groups may be named within a set of required square brackets, or ALL
may be used to delete all groups.
</para>
<para>The <literal>DISPLAY</literal> subcommand displays information about defined multiple
response sets.  Its syntax is the same as the <literal>DELETE</literal> subcommand.
</para>
<para>Multiple response sets are saved to and read from system files by,
e.g., the <literal>SAVE</literal> and <literal>GET</literal> command.  Otherwise, multiple
response sets are currently used only by third party software.
</para>
</sect1>
<sect1 label="11.9" id="NUMERIC">
<title>NUMERIC</title>
<indexterm role="vr"><primary>NUMERIC</primary></indexterm>

<literallayout>NUMERIC /<replaceable>var_list</replaceable> [(<replaceable>fmt_spec</replaceable>)].
</literallayout>
<para><literal>NUMERIC</literal> explicitly declares new numeric variables, optionally
setting their output formats.
</para>
<para>Specify a slash (&#8216;<literal>/</literal>&#8217;), 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 (see <link linkend="Input-and-Output-Formats">Input and Output
Formats</link>); otherwise, the default is F8.2.
</para>
<para>Variables created with <literal>NUMERIC</literal> are initialized to the
system-missing value.
</para>
</sect1>
<sect1 label="11.10" id="PRINT-FORMATS">
<title>PRINT FORMATS</title>
<indexterm role="vr"><primary>PRINT FORMATS</primary></indexterm>

<literallayout>PRINT FORMATS <replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>) [<replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>)]&#8230;.
</literallayout>
<para><literal>PRINT FORMATS</literal> sets the print formats for the specified
variables to the specified format specification.
</para>
<para>Its syntax is identical to that of <literal>FORMATS</literal> (see <link linkend="FORMATS">FORMATS</link>),
but <literal>PRINT FORMATS</literal> sets only print formats, not write formats.
</para>
</sect1>
<sect1 label="11.11" id="RENAME-VARIABLES">
<title>RENAME VARIABLES</title>
<indexterm role="vr"><primary>RENAME VARIABLES</primary></indexterm>

<literallayout>RENAME VARIABLES (<replaceable>old_names</replaceable>=<replaceable>new_names</replaceable>)&#8230; .
</literallayout>
<para><literal>RENAME VARIABLES</literal> changes the names of variables in the active
dataset.  Specify lists of the old variable names and new
variable names, separated by an equals sign (&#8216;<literal>=</literal>&#8217;), 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.
When the old and new variable names contain only a single variable name,
the parentheses are optional.
</para>
<para><literal>RENAME VARIABLES</literal> takes effect immediately.  It does not cause the data
to be read.
</para>
<para><literal>RENAME VARIABLES</literal> may not be specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>).
</para>
</sect1>
<sect1 label="11.12" id="SORT-VARIABLES">
<title>SORT VARIABLES</title>
<indexterm role="vr"><primary>SORT VARIABLES</primary></indexterm>

<literallayout>SORT VARIABLES [BY]
    (NAME | TYPE | FORMAT | LABEL | VALUES | MISSING | MEASURE
     | ROLE | COLUMNS | ALIGNMENT | ATTRIBUTE <replaceable>name</replaceable>)
    [(D)].
</literallayout>
<para><literal>SORT VARIABLES</literal> reorders the variables in the active dataset.
The main specification is one of the following identifiers, which
determines how the variables are sorted:
</para>
<variablelist><varlistentry><term>NAME
</term><listitem><para>Sorts the variables according to their names, in a case-insensitive
fashion.  However, when variable names differ only in a number at the
end, they are sorted numerically.  For example, <literal>VAR5</literal> is sorted
before <literal>VAR400</literal> even though &#8216;<literal>4</literal>&#8217; precedes &#8216;<literal>5</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term>TYPE
</term><listitem><para>Sorts numeric variables before string variables, and shorter string
variables before longer ones.
</para>
</listitem></varlistentry><varlistentry><term>FORMAT
</term><listitem><para>Groups variables by print format; within a format, sorts narrower
formats before wider ones; with the same format and width, sorts fewer
decimal places before more decimal places.
See <link linkend="FORMATS">FORMATS</link>.
</para>
</listitem></varlistentry><varlistentry><term>LABEL
</term><listitem><para>Sorts variables without a variable label before those with one.
See <link linkend="VARIABLE-LABELS">VARIABLE LABELS</link>.
</para>
</listitem></varlistentry><varlistentry><term>VALUES
</term><listitem><para>Sorts variables without value labels before those with some.
See <link linkend="VALUE-LABELS">VALUE LABELS</link>.
</para>
</listitem></varlistentry><varlistentry><term>MISSING
</term><listitem><para>Sorts variables without missing values before those with some.
See <link linkend="MISSING-VALUES">MISSING VALUES</link>.
</para>
</listitem></varlistentry><varlistentry><term>MEASURE
</term><listitem><para>Sorts nominal variables first, followed by ordinal variables, followed
by scale variables.  See <link linkend="VARIABLE-LEVEL">VARIABLE LEVEL</link>.
</para>
</listitem></varlistentry><varlistentry><term>ROLE
</term><listitem><para>Groups variables according to their role.  See <link linkend="VARIABLE-ROLE">VARIABLE ROLE</link>.
</para>
</listitem></varlistentry><varlistentry><term>COLUMNS
</term><listitem><para>Sorts variables in ascending display width.  See <link linkend="VARIABLE-WIDTH">VARIABLE WIDTH</link>.
</para>
</listitem></varlistentry><varlistentry><term>ALIGNMENT
</term><listitem><para>Sorts variables according to their alignment, first left-aligned, then
right-aligned, then centered.  See <link linkend="VARIABLE-ALIGNMENT">VARIABLE ALIGNMENT</link>.
</para>
</listitem></varlistentry><varlistentry><term>ATTRIBUTE <replaceable>name</replaceable>
</term><listitem><para>Sorts variables according to the first value of their <replaceable>name</replaceable>
attribute.  Variables without attribute are sorted first.
See <link linkend="VARIABLE-ATTRIBUTE">VARIABLE ATTRIBUTE</link>.
</para></listitem></varlistentry></variablelist>
<para>Only one sort criterion can be specified.  The sort is &#8220;stable,&#8221; so
to sort on multiple criteria one may perform multiple sorts.  For
example, the following will sort primarily based on alignment, with
variables that have the same alignment ordered based on display width:
</para>
<screen>SORT VARIABLES BY COLUMNS.
SORT VARIABLES BY ALIGNMENT.
</screen>
<para>Specify <literal>(D)</literal> to reverse the sort order.
</para>
</sect1>
<sect1 label="11.13" id="VALUE-LABELS">
<title>VALUE LABELS</title>
<indexterm role="vr"><primary>VALUE LABELS</primary></indexterm>

<literallayout>VALUE LABELS
        /<replaceable>var_list</replaceable> <replaceable>value</replaceable> &#8217;<replaceable>label</replaceable>&#8217; [<replaceable>value</replaceable> &#8217;<replaceable>label</replaceable>&#8217;]&#8230;
</literallayout>
<para><literal>VALUE LABELS</literal> allows values of
variables to be associated with labels.  In this way, a short value can
stand for a longer, more descriptive label.
</para>
<para>Both numeric and string variables can be given labels.  For string
variables, the values are case-sensitive, so that, for example, a
capitalized value and its lowercase variant would have to be labeled
separately if both are present in the data.
</para>
<para>To set up value labels for one or more variables, specify the
variable names after a slash (&#8216;<literal>/</literal>&#8217;), followed by a list of values
and their associated labels, separated by spaces.
</para>
<para>Value labels in output are normally broken into lines automatically.
Put &#8216;<literal>\n</literal>&#8217; in a label string to force a line break at that point.
The label may still be broken into lines at additional points.
</para>
<para>Before <literal>VALUE LABELS</literal> is executed, any existing value labels
are cleared from the variables specified.  Use <literal>ADD VALUE LABELS</literal>
(see <link linkend="ADD-VALUE-LABELS">ADD VALUE LABELS</link>) to add value labels without clearing those
already present.
</para>
</sect1>
<sect1 label="11.14" id="STRING">
<title>STRING</title>
<indexterm role="vr"><primary>STRING</primary></indexterm>

<literallayout>STRING <replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>) [/<replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>)] [&#8230;].
</literallayout>
<para><literal>STRING</literal> creates new string variables for use in
transformations.
</para>
<para>Specify a list of names for the variable you want to create,
followed by the desired output format specification in
parentheses (see <link linkend="Input-and-Output-Formats">Input and Output Formats</link>).  
Variable widths are
implicitly derived from the specified output formats.
The created variables will be initialized to spaces.
</para>
<para>If you want to create several variables with  distinct
output formats, you can either use two or more separate <literal>STRING</literal> commands,
or you can specify further variable list and format specification pairs, each separated
from the previous by a slash (&#8216;<literal>/</literal>&#8217;).
</para>
<para>The following example is one way to create three string variables; Two of the
variables have format A24 and the other A80:
</para><screen>STRING firstname lastname (A24) / address (A80).
</screen>
<para>Here is another way to achieve the same result:
</para><screen>STRING firstname lastname (A24).
STRING address (A80).
</screen>
<para>&#8230; and here is yet another way:
</para>
<screen>STRING firstname (A24).
STRING lastname (A24).
STRING address (A80).
</screen>



</sect1>
<sect1 label="11.15" id="VARIABLE-ATTRIBUTE">
<title>VARIABLE ATTRIBUTE</title>
<indexterm role="vr"><primary>VARIABLE ATTRIBUTE</primary></indexterm>

<literallayout>VARIABLE ATTRIBUTE
         VARIABLES=<replaceable>var_list</replaceable>
         ATTRIBUTE=<replaceable>name</replaceable>(&#8217;<replaceable>value</replaceable>&#8217;) [<replaceable>name</replaceable>(&#8217;<replaceable>value</replaceable>&#8217;)]&#8230;
         ATTRIBUTE=<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>(&#8217;<replaceable>value</replaceable>&#8217;) [<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>(&#8217;<replaceable>value</replaceable>&#8217;)]&#8230;
         DELETE=<replaceable>name</replaceable> [<replaceable>name</replaceable>]&#8230;
         DELETE=<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis> [<replaceable>name</replaceable><emphasis role="bold">[</emphasis><replaceable>index</replaceable><emphasis role="bold">]</emphasis>]&#8230;
</literallayout>
<para><literal>VARIABLE ATTRIBUTE</literal> adds, modifies, or removes user-defined
attributes associated with variables in the active dataset.  Custom
variable attributes are not interpreted by pspp, but they are saved as
part of system files and may be used by other software that reads
them.
</para>
<para>The required <literal>VARIABLES</literal> subcommand must come first.  Specify the
variables to which the following <literal>ATTRIBUTE</literal> or <literal>DELETE</literal> subcommand
should apply.
</para>
<para>Use the <literal>ATTRIBUTE</literal> subcommand to add or modify custom variable
attributes.  Specify the name of the attribute as an identifier
(see <link linkend="Tokens">Tokens</link>), followed by the desired value, in parentheses, as a
quoted string.  The specified attributes are then added or modified in
the variables specified on <literal>VARIABLES</literal>.  Attribute names that begin with
<literal>$</literal> are reserved for pspp&#8217;s internal use, and attribute names
that begin with <literal>@</literal> or <literal>$@</literal> are not displayed by most pspp
commands that display other attributes.  Other attribute names are not
treated specially.
</para>
<para>Attributes may also be organized into arrays.  To assign to an array
element, add an integer array index enclosed in square brackets
(<literal>[</literal> and <literal>]</literal>) between the attribute name and value.  Array
indexes start at 1, not 0.  An attribute array that has a single
element (number 1) is not distinguished from a non-array attribute.
</para>
<para>Use the <literal>DELETE</literal> subcommand to delete an attribute from the variable
specified on <literal>VARIABLES</literal>.  Specify an attribute name by itself to delete
an entire attribute, including all array elements for attribute
arrays.  Specify an attribute name followed by an array index in
square brackets to delete a single element of an attribute array.  In
the latter case, all the array elements numbered higher than the
deleted element are shifted down, filling the vacated position.
</para>
<para>To associate custom attributes with the entire active dataset, instead of
with particular variables, use <literal>DATAFILE ATTRIBUTE</literal> (see <link linkend="DATAFILE-ATTRIBUTE">DATAFILE ATTRIBUTE</link>) instead.
</para>
<para><literal>VARIABLE ATTRIBUTE</literal> takes effect immediately.  It is not affected
by conditional and looping structures such as <literal>DO IF</literal> or
<literal>LOOP</literal>.
</para>
</sect1>
<sect1 label="11.16" id="VARIABLE-LABELS">
<title>VARIABLE LABELS</title>
<indexterm role="vr"><primary>VARIABLE LABELS</primary></indexterm>

<literallayout>VARIABLE LABELS
        <replaceable>var_list</replaceable> &#8217;<replaceable>var_label</replaceable>&#8217; 
        [ /<replaceable>var_list</replaceable> &#8217;<replaceable>var_label</replaceable>&#8217;]
        .
        .
        .
        [ /<replaceable>var_list</replaceable> &#8217;<replaceable>var_label</replaceable>&#8217;]
</literallayout>
<para><literal>VARIABLE LABELS</literal> associates explanatory names
with variables.  This name, called a <firstterm>variable label</firstterm>, is displayed by
statistical procedures.
</para>
<para>To assign a variable label to a group of variables, specify a 
list of variable names and the variable label as a string.
To assign different labels to different variables in the same command, 
precede the subsequent variable list with a slash (&#8216;<literal>/</literal>&#8217;).
</para>

</sect1>
<sect1 label="11.17" id="VARIABLE-ALIGNMENT">
<title>VARIABLE ALIGNMENT</title>
<indexterm role="vr"><primary>VARIABLE ALIGNMENT</primary></indexterm>

<literallayout>VARIABLE ALIGNMENT
        <replaceable>var_list</replaceable> ( LEFT | RIGHT | CENTER )
        [ /<replaceable>var_list</replaceable> ( LEFT | RIGHT | CENTER ) ]
        .
        .
        .
        [ /<replaceable>var_list</replaceable> ( LEFT | RIGHT | CENTER ) ]
</literallayout>
<para><literal>VARIABLE ALIGNMENT</literal> sets the alignment of variables for display editing 
purposes.   This only has effect for third party software.  It does not affect 
the display of variables in the pspp output.
</para>



</sect1>
<sect1 label="11.18" id="VARIABLE-WIDTH">
<title>VARIABLE WIDTH</title>
<indexterm role="vr"><primary>VARIABLE WIDTH</primary></indexterm>
<literallayout>VARIABLE WIDTH
        <replaceable>var_list</replaceable> (width)
        [ /<replaceable>var_list</replaceable> (width) ] 
        .
        .
        .
        [ /<replaceable>var_list</replaceable> (width) ] 
</literallayout>
<para><literal>VARIABLE WIDTH</literal> sets the column width of variables for display editing
purposes.   This only affects third party software.  It does not affect 
the display of variables in the pspp output.
</para>

</sect1>
<sect1 label="11.19" id="VARIABLE-LEVEL">
<title>VARIABLE LEVEL</title>
<indexterm role="vr"><primary>VARIABLE LEVEL</primary></indexterm>
<literallayout>VARIABLE LEVEL
        <replaceable>var_list</replaceable> ( SCALE | NOMINAL | ORDINAL )
        [ /<replaceable>var_list</replaceable> ( SCALE | NOMINAL | ORDINAL ) ]
        .
        .
        .
        [ /<replaceable>var_list</replaceable> ( SCALE | NOMINAL | ORDINAL ) ]
</literallayout>
<para><literal>VARIABLE LEVEL</literal> sets the measurement level of  variables.
Currently, this has no effect except for certain third party software.
</para>

</sect1>
<sect1 label="11.20" id="VARIABLE-ROLE">
<title>VARIABLE ROLE</title>
<indexterm role="vr"><primary>VARIABLE ROLE</primary></indexterm>
<literallayout>VARIABLE ROLE
        /<replaceable>role</replaceable> <replaceable>var_list</replaceable>
        [/<replaceable>role</replaceable> <replaceable>var_list</replaceable>]&#8230;
</literallayout>
<para><literal>VARIABLE ROLE</literal> sets the intended role of a variable for use in
dialog boxes in graphical user interfaces.  Each <replaceable>role</replaceable> specifies
one of the following roles for the variables that follow it:
</para>
<variablelist><varlistentry><term><literal>INPUT</literal>
</term><listitem><para>An input variable, such as an independent variable.
</para>
</listitem></varlistentry><varlistentry><term><literal>TARGET</literal>
</term><listitem><para>An output variable, such as an dependent variable.
</para>
</listitem></varlistentry><varlistentry><term><literal>BOTH</literal>
</term><listitem><para>A variable used for input and output.
</para>
</listitem></varlistentry><varlistentry><term><literal>NONE</literal>
</term><listitem><para>No role assigned.  (This is a variable&#8217;s default role.)
</para>
</listitem></varlistentry><varlistentry><term><literal>PARTITION</literal>
</term><listitem><para>Used to break the data into groups for testing.
</para>
</listitem></varlistentry><varlistentry><term><literal>SPLIT</literal>
</term><listitem><para>No meaning except for certain third party software.  (This role&#8217;s
meaning is unrelated to <literal>SPLIT FILE</literal>.)
</para></listitem></varlistentry></variablelist>
<para>The PSPPIRE GUI does not yet use variable roles as intended.
</para>
</sect1>
<sect1 label="11.21" id="VECTOR">
<title>VECTOR</title>
<indexterm role="vr"><primary>VECTOR</primary></indexterm>

<literallayout>Two possible syntaxes:
        VECTOR <replaceable>vec_name</replaceable>=<replaceable>var_list</replaceable>.
        VECTOR <replaceable>vec_name_list</replaceable>(<replaceable>count</replaceable> [<replaceable>format</replaceable>]).
</literallayout>
<para><literal>VECTOR</literal> allows a group of variables to be accessed as if they
were consecutive members of an array with a vector(index) notation.
</para>
<para>To make a vector out of a set of existing variables, specify a name
for the vector followed by an equals sign (&#8216;<literal>=</literal>&#8217;) and the variables
to put in the vector.  All the variables in the vector must be the same
type.  String variables in a vector must all have the same width.
</para>
<para>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 <literal><replaceable>vec</replaceable>1</literal> through <literal><replaceable>vec</replaceable><replaceable>count</replaceable></literal>
to be created as numeric variables.  By default, the new variables
have print and write format F8.2, but an alternate format may be
specified inside the parentheses before or after the count and
separated from it by white space or a comma.  Variable names including
numeric suffixes may not exceed 64 characters in length, and none of
the variables may exist prior to <literal>VECTOR</literal>.
</para>
<para>Vectors created with <literal>VECTOR</literal> disappear after any procedure or
procedure-like command is executed.  The variables contained in the
vectors remain, unless they are scratch variables (see <link linkend="Scratch-Variables">Scratch
Variables</link>).
</para>
<para>Variables within a vector may be referenced in expressions using
<literal>vector(index)</literal> syntax.
</para>
</sect1>
<sect1 label="11.22" id="WRITE-FORMATS">
<title>WRITE FORMATS</title>
<indexterm role="vr"><primary>WRITE FORMATS</primary></indexterm>

<literallayout>WRITE FORMATS <replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>) [<replaceable>var_list</replaceable> (<replaceable>fmt_spec</replaceable>)]&#8230;.
</literallayout>
<para><literal>WRITE FORMATS</literal> sets the write formats for the specified variables
to the specified format specification.  Its syntax is identical to
that of <literal>FORMATS</literal> (see <link linkend="FORMATS">FORMATS</link>), but <literal>WRITE FORMATS</literal> sets only
write formats, not print formats.
</para></sect1>
</chapter>
<chapter label="12" id="Data-Manipulation">
<title>Data transformations</title>
<indexterm role="cp"><primary>transformations</primary></indexterm>

<para>The pspp procedures examined in this chapter manipulate data and
prepare the active dataset for later analyses.  They do not produce output,
as a rule.
</para>

<sect1 label="12.1" id="AGGREGATE">
<title>AGGREGATE</title>
<indexterm role="vr"><primary>AGGREGATE</primary></indexterm>

<literallayout>AGGREGATE 
        OUTFILE={*,&#8217;<replaceable>file_name</replaceable>&#8217;,<replaceable>file_handle</replaceable>} [MODE={REPLACE, ADDVARIABLES}]
        /PRESORTED
        /DOCUMENT
        /MISSING=COLUMNWISE
        /BREAK=<replaceable>var_list</replaceable>
        /<replaceable>dest_var</replaceable>[&#8217;<replaceable>label</replaceable>&#8217;]&#8230;=<replaceable>agr_func</replaceable>(<replaceable>src_vars</replaceable>, <replaceable>args</replaceable>&#8230;)&#8230;
</literallayout>
<para><literal>AGGREGATE</literal> summarizes groups of cases into single cases.
Cases are divided into groups that have the same values for one or more
variables called <firstterm>break variables</firstterm>.  Several functions are available
for summarizing case contents.
</para>
<para>The <literal>OUTFILE</literal> subcommand is required and must appear first.  Specify a
system file or portable file by file name or file
handle (see <link linkend="File-Handles">File Handles</link>), or a dataset by its name
(see <link linkend="Datasets">Datasets</link>).
The aggregated cases are written to this file.  If &#8216;<literal>*</literal>&#8217; is
specified, then the aggregated cases replace the active dataset&#8217;s data.
Use of <literal>OUTFILE</literal> to write a portable file is a pspp extension.
</para>
<para>If <literal>OUTFILE=*</literal> is given, then the subcommand <literal>MODE</literal> may also be
specified.
The mode subcommand has two possible values: <literal>ADDVARIABLES</literal> or <literal>REPLACE</literal>.
In <literal>REPLACE</literal> mode, the entire active dataset is replaced by a new dataset
which contains just the break variables and the destination varibles.
In this mode, the new file will contain as many cases as there are
unique combinations of the break variables.
In <literal>ADDVARIABLES</literal> mode, the destination variables will be appended to 
the existing active dataset.
Cases which have identical combinations of values in their break
variables, will receive identical values for the destination variables.
The number of cases in the active dataset will remain unchanged.
Note that if <literal>ADDVARIABLES</literal> is specified, then the data <emphasis>must</emphasis> be
sorted on the break variables.
</para>
<para>By default, the active dataset will be sorted based on the break variables
before aggregation takes place.  If the active dataset is already sorted
or otherwise grouped in terms of the break variables, specify
<literal>PRESORTED</literal> to save time.
<literal>PRESORTED</literal> is assumed if <literal>MODE=ADDVARIABLES</literal> is used.
</para>
<para>Specify <literal>DOCUMENT</literal> to copy the documents from the active dataset into the
aggregate file (see <link linkend="DOCUMENT">DOCUMENT</link>).  Otherwise, the aggregate file will
not contain any documents, even if the aggregate file replaces the
active dataset.
</para>
<para>Normally, only a single case (for <literal>SD</literal> and <literal>SD</literal>., two cases) need be
non-missing in each group for the aggregate variable to be
non-missing.  Specifying <literal>/MISSING=COLUMNWISE</literal> inverts this behavior, so
that the aggregate variable becomes missing if any aggregated value is
missing.
</para>
<para>If <literal>PRESORTED</literal>, <literal>DOCUMENT</literal>, or <literal>MISSING</literal> are specified, they must appear
between <literal>OUTFILE</literal> and <literal>BREAK</literal>.
</para>
<para>At least one break variable must be specified on <literal>BREAK</literal>, a
required subcommand.  The values of these variables are used to divide
the active dataset into groups to be summarized.  In addition, at least
one <replaceable>dest_var</replaceable> must be specified.
</para>
<para>One or more sets of aggregation variables must be specified.  Each set
comprises a list of aggregation variables, an equals sign (&#8216;<literal>=</literal>&#8217;),
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.
</para>
<para>Aggregation variables typically are created with no variable label,
value labels, or missing values.  Their default print and write
formats depend on the aggregation function used, with details given in
the table below.  A variable label for an aggregation variable may be
specified just after the variable&#8217;s name in the aggregation variable
list.
</para>
<para>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.  The <literal>MEAN</literal>, <literal>MEDIAN</literal>, <literal>SD</literal>, and <literal>SUM</literal>
aggregation functions may only be
applied to numeric variables.  All the rest may be applied to numeric
and string variables.
</para>
<para>The available aggregation functions are as follows:
</para>
<variablelist><varlistentry><term><literal>FGT(<replaceable>var_name</replaceable>, <replaceable>value</replaceable>)</literal>
</term><listitem><para>Fraction of values greater than the specified constant.  The default
format is F5.3.
</para>
</listitem></varlistentry><varlistentry><term><literal>FIN(<replaceable>var_name</replaceable>, <replaceable>low</replaceable>, <replaceable>high</replaceable>)</literal>
</term><listitem><para>Fraction of values within the specified inclusive range of constants.
The default format is F5.3.
</para>
</listitem></varlistentry><varlistentry><term><literal>FLT(<replaceable>var_name</replaceable>, <replaceable>value</replaceable>)</literal>
</term><listitem><para>Fraction of values less than the specified constant.  The default
format is F5.3.
</para>
</listitem></varlistentry><varlistentry><term><literal>FIRST(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>First non-missing value in break group.  The aggregation variable
receives the complete dictionary information from the source variable.
The sort performed by <literal>AGGREGATE</literal> (and by <literal>SORT CASES</literal>) is stable, so that
the first case with particular values for the break variables before
sorting will also be the first case in that break group after sorting.
</para>
</listitem></varlistentry><varlistentry><term><literal>FOUT(<replaceable>var_name</replaceable>, <replaceable>low</replaceable>, <replaceable>high</replaceable>)</literal>
</term><listitem><para>Fraction of values strictly outside the specified range of constants.
The default format is F5.3.
</para>
</listitem></varlistentry><varlistentry><term><literal>LAST(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>Last non-missing value in break group.  The aggregation variable
receives the complete dictionary information from the source variable.
The sort performed by <literal>AGGREGATE</literal> (and by <literal>SORT CASES</literal>) is stable, so that
the last case with particular values for the break variables before
sorting will also be the last case in that break group after sorting.
</para>
</listitem></varlistentry><varlistentry><term><literal>MAX(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>Maximum value.  The aggregation variable receives the complete
dictionary information from the source variable.
</para>
</listitem></varlistentry><varlistentry><term><literal>MEAN(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>Arithmetic mean.  Limited to numeric values.  The default format is
F8.2.
</para>
</listitem></varlistentry><varlistentry><term><literal>MEDIAN(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>The median value.  Limited to numeric values.  The default format is F8.2.
</para>
</listitem></varlistentry><varlistentry><term><literal>MIN(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>Minimum value.  The aggregation variable receives the complete
dictionary information from the source variable.
</para>
</listitem></varlistentry><varlistentry><term><literal>N(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>Number of non-missing values.  The default format is F7.0 if weighting
is not enabled, F8.2 if it is (see <link linkend="WEIGHT">WEIGHT</link>).
</para>
</listitem></varlistentry><varlistentry><term><literal>N</literal>
</term><listitem><para>Number of cases aggregated to form this group.  The default format is
F7.0 if weighting is not enabled, F8.2 if it is (see <link linkend="WEIGHT">WEIGHT</link>).
</para>
</listitem></varlistentry><varlistentry><term><literal>NMISS(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>Number of missing values.  The default format is F7.0 if weighting is
not enabled, F8.2 if it is (see <link linkend="WEIGHT">WEIGHT</link>).
</para>
</listitem></varlistentry><varlistentry><term><literal>NU(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>Number of non-missing values.  Each case is considered to have a weight
of 1, regardless of the current weighting variable (see <link linkend="WEIGHT">WEIGHT</link>).
The default format is F7.0.
</para>
</listitem></varlistentry><varlistentry><term><literal>NU</literal>
</term><listitem><para>Number of cases aggregated to form this group.  Each case is considered
to have a weight of 1, regardless of the current weighting variable.
The default format is F7.0.
</para>
</listitem></varlistentry><varlistentry><term><literal>NUMISS(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>Number of missing values.  Each case is considered to have a weight of
1, regardless of the current weighting variable.  The default format is F7.0.
</para>
</listitem></varlistentry><varlistentry><term><literal>PGT(<replaceable>var_name</replaceable>, <replaceable>value</replaceable>)</literal>
</term><listitem><para>Percentage between 0 and 100 of values greater than the specified
constant.  The default format is F5.1.
</para>
</listitem></varlistentry><varlistentry><term><literal>PIN(<replaceable>var_name</replaceable>, <replaceable>low</replaceable>, <replaceable>high</replaceable>)</literal>
</term><listitem><para>Percentage of values within the specified inclusive range of
constants.  The default format is F5.1.
</para>
</listitem></varlistentry><varlistentry><term><literal>PLT(<replaceable>var_name</replaceable>, <replaceable>value</replaceable>)</literal>
</term><listitem><para>Percentage of values less than the specified constant.  The default
format is F5.1.
</para>
</listitem></varlistentry><varlistentry><term><literal>POUT(<replaceable>var_name</replaceable>, <replaceable>low</replaceable>, <replaceable>high</replaceable>)</literal>
</term><listitem><para>Percentage of values strictly outside the specified range of
constants.  The default format is F5.1.
</para>
</listitem></varlistentry><varlistentry><term><literal>SD(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>Standard deviation of the mean.  Limited to numeric values.  The
default format is F8.2.
</para>
</listitem></varlistentry><varlistentry><term><literal>SUM(<replaceable>var_name</replaceable>)</literal>
</term><listitem><para>Sum.  Limited to numeric values.  The default format is F8.2.
</para></listitem></varlistentry></variablelist>
<para>Aggregation functions compare string values in terms of internal
character codes.
On most modern computers, this is  <acronym>ASCII</acronym> or a superset thereof.
</para>
<para>The aggregation functions listed above exclude all user-missing values
from calculations.  To include user-missing values, insert a period
(&#8216;<literal>.</literal>&#8217;) at the end of the function name.  (e.g. &#8216;<literal>SUM.</literal>&#8217;).
(Be aware that specifying such a function as the last token on a line
will cause the period to be interpreted as the end of the command.)
</para>
<para><literal>AGGREGATE</literal> both ignores and cancels the current <literal>SPLIT FILE</literal>
settings (see <link linkend="SPLIT-FILE">SPLIT FILE</link>).
</para>
</sect1>
<sect1 label="12.2" id="AUTORECODE">
<title>AUTORECODE</title>
<indexterm role="vr"><primary>AUTORECODE</primary></indexterm>

<literallayout>AUTORECODE VARIABLES=<replaceable>src_vars</replaceable> INTO <replaceable>dest_vars</replaceable>
        [ /DESCENDING ]
        [ /PRINT ]
        [ /GROUP ]
        [ /BLANK = {VALID, MISSING} ]
</literallayout>
<para>The <literal>AUTORECODE</literal> procedure considers the <replaceable>n</replaceable> values that a variable
takes on and maps them onto values 1&#8230;<replaceable>n</replaceable> on a new numeric
variable.
</para>
<para>Subcommand <literal>VARIABLES</literal> is the only required subcommand and must come
first.  Specify <literal>VARIABLES</literal>, an equals sign (&#8216;<literal>=</literal>&#8217;), a list of source
variables, <literal>INTO</literal>, and a list of target variables.  There must the same
number of source and target variables.  The target variables must not
already exist.
</para>
<para>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 (<replaceable>n</replaceable> down
to 1), specify <literal>DESCENDING</literal>.
</para>
<para><literal>PRINT</literal> is currently ignored.
</para>
<para>The <literal>GROUP</literal> subcommand is relevant only if more than one variable is to be
recoded.   It causes a single mapping between source and target values to
be used, instead of one map per variable.
</para>
<para>If <literal>/BLANK=MISSING</literal> is given, then string variables which contain only 
whitespace are recoded as SYSMIS.  If <literal>/BLANK=VALID</literal> is given then they
will be allocated a value like any other.  <literal>/BLANK</literal> is not relevant
to numeric values. <literal>/BLANK=VALID</literal> is the default.
</para>
<para><literal>AUTORECODE</literal> is a procedure.  It causes the data to be read.
</para>
</sect1>
<sect1 label="12.3" id="COMPUTE">
<title>COMPUTE</title>
<indexterm role="vr"><primary>COMPUTE</primary></indexterm>

<literallayout>COMPUTE <replaceable>variable</replaceable> = <replaceable>expression</replaceable>.
</literallayout><para>or
</para><literallayout>COMPUTE vector(<replaceable>index</replaceable>) = <replaceable>expression</replaceable>.
</literallayout>
<para><literal>COMPUTE</literal> 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 string
variables may be assigned.  When a string expression&#8217;s width differs
from the target variable&#8217;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.
</para>
<para>For numeric variables only, the target variable need not already
exist.  Numeric variables created by <literal>COMPUTE</literal> are assigned an
<literal>F8.2</literal> output format.  String variables must be declared before
they can be used as targets for <literal>COMPUTE</literal>.
</para>
<para>The target variable may be specified as an element of a vector
(see <link linkend="VECTOR">VECTOR</link>).  In this case, an expression <replaceable>index</replaceable> must be
specified in parentheses following the vector name.  The expression <replaceable>index</replaceable>
must evaluate to a numeric value that, after rounding down
to the nearest integer, is a valid index for the named vector.
</para>
<para>Using <literal>COMPUTE</literal> to assign to a variable specified on <literal>LEAVE</literal>
(see <link linkend="LEAVE">LEAVE</link>) resets the variable&#8217;s left state.  Therefore,
<literal>LEAVE</literal> should be specified following <literal>COMPUTE</literal>, not before.
</para>
<para><literal>COMPUTE</literal> is a transformation.  It does not cause the active dataset to be
read.
</para>
<para>When <literal>COMPUTE</literal> is specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>), the <literal>LAG</literal> function may not be used
(see <link linkend="LAG">LAG</link>).
</para>
</sect1>
<sect1 label="12.4" id="COUNT">
<title>COUNT</title>
<indexterm role="vr"><primary>COUNT</primary></indexterm>

<literallayout>COUNT <replaceable>var_name</replaceable> = <replaceable>var</replaceable>&#8230; (<replaceable>value</replaceable>&#8230;).

Each <replaceable>value</replaceable> takes one of the following forms:
        <replaceable>number</replaceable>
        <replaceable>string</replaceable>
        <replaceable>num1</replaceable> THRU <replaceable>num2</replaceable>
        MISSING
        SYSMIS
where <replaceable>num1</replaceable> is a numeric expression or the words <literal>LO</literal>  or <literal>LOWEST</literal>
      and <replaceable>num2</replaceable> is a numeric expression  or <literal>HI</literal> or <literal>HIGHEST</literal>.
</literallayout>
<para><literal>COUNT</literal> creates or replaces a numeric <firstterm>target</firstterm> variable that
counts the occurrence of a <firstterm>criterion</firstterm> value or set of values over
one or more <firstterm>test</firstterm> variables for each case.
</para>
<para>The target variable values are always nonnegative integers.  They are
never missing.  The target variable is assigned an F8.2 output format.
See <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.  Any variables, including
string variables, may be test variables.
</para>
<para>User-missing values of test variables are treated just like any other
values.  They are <emphasis role="bold">not</emphasis> 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 <literal>MISSING</literal> may be used to refer to all system-
and user-missing values.
</para>
<para><literal>COUNT</literal> target variables are assigned values in the order
specified.  In the command <literal>COUNT <replaceable>A</replaceable>=<replaceable>A</replaceable> <replaceable>B</replaceable>(1) /<replaceable>B</replaceable>=<replaceable>A</replaceable> <replaceable>B</replaceable>(2).</literal>, the
following actions occur:
</para>
<itemizedlist><listitem><para>&#8722; The number of occurrences of 1 between <replaceable>A</replaceable> and <replaceable>B</replaceable> is counted.
</para>
</listitem><listitem><para>&#8722; <replaceable>A</replaceable> is assigned this value.
</para>
</listitem><listitem><para>&#8722; The number of occurrences of 1 between <replaceable>B</replaceable> and the <emphasis role="bold">new</emphasis>
value of <replaceable>A</replaceable> is counted.
</para>
</listitem><listitem><para>&#8722; <replaceable>B</replaceable> is assigned this value.
</para></listitem></itemizedlist>
<para>Despite this ordering, all <literal>COUNT</literal> criterion variables must exist
before the procedure is executed&#8212;they may not be created as target
variables earlier in the command!  Break such a command into two
separate commands.
</para>
<para>The examples below may help to clarify.
</para>
<orderedlist numeration="upperalpha"><listitem><para>Assuming <literal>Q0</literal>, <literal>Q2</literal>, &#8230;, <literal>Q9</literal> are numeric variables,
the following commands:
</para>
<orderedlist numeration="arabic"><listitem><para>Count the number of times the value 1 occurs through these variables
for each case and assigns the count to variable <literal>QCOUNT</literal>.  
</para>
</listitem><listitem><para>Print out the total number of times the value 1 occurs throughout
<emphasis>all</emphasis> cases using <literal>DESCRIPTIVES</literal>.  See <link linkend="DESCRIPTIVES">DESCRIPTIVES</link>, for
details.
</para></listitem></orderedlist>
<screen>COUNT QCOUNT=Q0 TO Q9(1).
DESCRIPTIVES QCOUNT /STATISTICS=SUM.
</screen>
</listitem><listitem><para>Given these same variables, the following commands:
</para>
<orderedlist numeration="arabic"><listitem><para>Count the number of valid values of these variables for each case and
assigns the count to variable <literal>QVALID</literal>.
</para>
</listitem><listitem><para>Multiplies each value of <literal>QVALID</literal> by 10 to obtain a percentage of
valid values, using <literal>COMPUTE</literal>.  See <link linkend="COMPUTE">COMPUTE</link>, for details.
</para>
</listitem><listitem><para>Print out the percentage of valid values across all cases, using
<literal>DESCRIPTIVES</literal>.  See <link linkend="DESCRIPTIVES">DESCRIPTIVES</link>, for details.
</para></listitem></orderedlist>
<screen>COUNT QVALID=Q0 TO Q9 (LO THRU HI).
COMPUTE QVALID=QVALID*10.
DESCRIPTIVES QVALID /STATISTICS=MEAN.
</screen></listitem></orderedlist>
</sect1>
<sect1 label="12.5" id="FLIP">
<title>FLIP</title>
<indexterm role="vr"><primary>FLIP</primary></indexterm>

<literallayout>FLIP /VARIABLES=<replaceable>var_list</replaceable> /NEWNAMES=<replaceable>var_name</replaceable>.
</literallayout>
<para><literal>FLIP</literal> transposes rows and columns in the active dataset.  It
causes cases to be swapped with variables, and vice versa.
</para>
<para>All variables in the transposed active dataset are numeric.  String
variables take on the system-missing value in the transposed file.
</para>
<para><literal>N</literal> subcommands are required.  If specified, the <literal>VARIABLES</literal> subcommand
selects variables to be transformed into cases, and variables not
specified are discarded.  If the <literal>VARIABLES</literal> subcommand is omitted, all
variables are selected for transposition.
</para>
<para>The variables specified by <literal>NEWNAMES</literal>, which must be a
string variable, is
used to give names to the variables created by <literal>FLIP</literal>.  Only the
first 8 characters of the variable are used.  If
<literal>NEWNAMES</literal> is not
specified then the default is a variable named CASE_LBL, if it exists.
If it does not then the variables created by <literal>FLIP</literal> are named VAR000
through VAR999, then VAR1000, VAR1001, and so on.
</para>
<para>When a <literal>NEWNAMES</literal> variable is available, the names must be canonicalized
before becoming variable names.  Invalid characters are replaced by
letter &#8216;<literal>V</literal>&#8217; in the first position, or by &#8216;<literal>_</literal>&#8217; 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
<literal>FLIP</literal> operation aborts.
</para>
<para>The resultant dictionary contains a CASE_LBL variable, a string
variable of width 8, which stores the names of the variables in the
dictionary before the transposition.  Variables names longer than 8
characters are truncated.  If the active dataset is subsequently
transposed using <literal>FLIP</literal>, this variable can be used to recreate the
original variable names.
</para>
<para><literal>FLIP</literal> honors <literal>N OF CASES</literal> (see <link linkend="N-OF-CASES">N OF CASES</link>).  It ignores
<literal>TEMPORARY</literal> (see <link linkend="TEMPORARY">TEMPORARY</link>), so that &#8220;temporary&#8221;
transformations become permanent.
</para>
</sect1>
<sect1 label="12.6" id="IF">
<title>IF</title>
<indexterm role="vr"><primary>IF</primary></indexterm>

<literallayout>IF <replaceable>condition</replaceable> <replaceable>variable</replaceable>=<replaceable>expression</replaceable>.
</literallayout><para>or
</para><literallayout>IF <replaceable>condition</replaceable> vector(<replaceable>index</replaceable>)=<replaceable>expression</replaceable>.
</literallayout>
<para>The <literal>IF</literal> transformation conditionally assigns the value of a target
expression to a target variable, based on the truth of a test
expression.
</para>
<para>Specify a boolean-valued expression (see <link linkend="Expressions">Expressions</link>) to be tested
following the <literal>IF</literal> 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 string variables may be
assigned.  When a string expression&#8217;s width differs from the target
variable&#8217;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.
</para>
<para>The target variable may be specified as an element of a vector
(see <link linkend="VECTOR">VECTOR</link>).  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.
</para>
<para>Using <literal>IF</literal> to assign to a variable specified on <literal>LEAVE</literal>
(see <link linkend="LEAVE">LEAVE</link>) resets the variable&#8217;s left state.  Therefore,
<literal>LEAVE</literal> should be specified following <literal>IF</literal>, not before.
</para>
<para>When <literal>IF</literal> is specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>), the <literal>LAG</literal> function may not be used
(see <link linkend="LAG">LAG</link>).
</para>
</sect1>
<sect1 label="12.7" id="RECODE">
<title>RECODE</title>
<indexterm role="vr"><primary>RECODE</primary></indexterm>

<para>The <literal>RECODE</literal> command is used to transform existing values into other,
user specified values.
The general form is:
</para>
<literallayout>RECODE <replaceable>src_vars</replaceable>
        (<replaceable>src_value</replaceable> <replaceable>src_value</replaceable> &#8230; = <replaceable>dest_value</replaceable>)
        (<replaceable>src_value</replaceable> <replaceable>src_value</replaceable> &#8230; = <replaceable>dest_value</replaceable>)
        (<replaceable>src_value</replaceable> <replaceable>src_value</replaceable> &#8230; = <replaceable>dest_value</replaceable>) &#8230;
         [INTO <replaceable>dest_vars</replaceable>].
</literallayout>
<para>Following the <literal>RECODE</literal> keyword itself comes <replaceable>src_vars</replaceable> which is a list
of variables whose values are to be transformed.
These variables may be string variables or they may be numeric.
However the list must be homogeneous; you may not mix string variables and
numeric variables in the same recoding.
</para>
<para>After the list of source variables, there should be one or more <firstterm>mappings</firstterm>.
Each mapping is enclosed in parentheses, and contains the source values and
a destination value separated by a single &#8216;<literal>=</literal>&#8217;.
The source values are used to specify the values in the dataset which 
need to change, and the destination value specifies the new value
to which they should be changed.
Each <replaceable>src_value</replaceable> may take one of the following forms:
</para><variablelist><varlistentry><term><replaceable>number</replaceable>
</term><listitem><para>If the source variables are numeric then <replaceable>src_value</replaceable> may be a literal
number.
</para></listitem></varlistentry><varlistentry><term><replaceable>string</replaceable>
</term><listitem><para>If the source variables are string variables then <replaceable>src_value</replaceable> may be a
literal string (like all strings, enclosed in single or double quotes).
</para></listitem></varlistentry><varlistentry><term><replaceable>num1</replaceable> THRU <replaceable>num2</replaceable>
</term><listitem><para>This form is valid only when the source variables are numeric.
It specifies all values in the range between <replaceable>num1</replaceable> and <replaceable>num2</replaceable>,
including both endpoints of the range.  By convention, <replaceable>num1</replaceable>
should be less than <replaceable>num2</replaceable>.
Open-ended ranges may be specified using &#8216;<literal>LO</literal>&#8217; or &#8216;<literal>LOWEST</literal>&#8217; 
for <replaceable>num1</replaceable>
or &#8216;<literal>HI</literal>&#8217; or &#8216;<literal>HIGHEST</literal>&#8217; for <replaceable>num2</replaceable>.
</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>MISSING</literal>&#8217;
</term><listitem><para>The literal keyword &#8216;<literal>MISSING</literal>&#8217; matches both system missing and user
missing values.
It is valid for both numeric and string variables.
</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>SYSMIS</literal>&#8217;
</term><listitem><para>The literal keyword &#8216;<literal>SYSMIS</literal>&#8217; matches system missing
values.
It is valid for both numeric variables only.
</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>ELSE</literal>&#8217;
</term><listitem><para>The &#8216;<literal>ELSE</literal>&#8217; keyword may be used to match any values which are
not matched by any other <replaceable>src_value</replaceable> appearing in the command.
If this keyword appears, it should be used in the last mapping of the 
command.
</para></listitem></varlistentry></variablelist>
<para>After the source variables comes an &#8216;<literal>=</literal>&#8217; and then the <replaceable>dest_value</replaceable>.
The <replaceable>dest_value</replaceable> may take any of the following forms:
</para><variablelist><varlistentry><term><replaceable>number</replaceable>
</term><listitem><para>A literal numeric value to which the source values should be changed.
This implies the destination variable must be numeric.
</para></listitem></varlistentry><varlistentry><term><replaceable>string</replaceable>
</term><listitem><para>A literal string value (enclosed in quotation marks) to which the source
values should be changed.
This implies the destination variable must be a string variable.
</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>SYSMIS</literal>&#8217;
</term><listitem><para>The keyword &#8216;<literal>SYSMIS</literal>&#8217; changes the value to the system missing value.
This implies the destination variable must be numeric.
</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>COPY</literal>&#8217;
</term><listitem><para>The special keyword &#8216;<literal>COPY</literal>&#8217; means that the source value should not be
modified, but
copied directly to the destination value.
This is meaningful only if &#8216;<literal>INTO <replaceable>dest_vars</replaceable></literal>&#8217; is specified.
</para></listitem></varlistentry></variablelist>
<para>Mappings are considered from left to right.
Therefore, if a value is matched by a <replaceable>src_value</replaceable> from more than 
one mapping, the first (leftmost) mapping which matches will be considered.
Any subsequent matches will be ignored.
</para>
<para>The clause &#8216;<literal>INTO <replaceable>dest_vars</replaceable></literal>&#8217; is optional.
The behaviour of the command is slightly different depending on whether it
appears or not.
</para>
<para>If &#8216;<literal>INTO <replaceable>dest_vars</replaceable></literal>&#8217; does not appear, then values will be recoded
&#8220;in place&#8221;.
This means that the recoded values are written back to the
source variables from whence the original values came.
In this case, the <replaceable>dest_value</replaceable> for every mapping must imply a value which
has the same type as the <replaceable>src_value</replaceable>.
For example, if the source value is a string value, it is not permissible for
<replaceable>dest_value</replaceable> to be &#8216;<literal>SYSMIS</literal>&#8217; or another forms which implies a numeric
result.
It is also not permissible for <replaceable>dest_value</replaceable> to be  longer than the width
of the source variable.
</para>
<para>The following example two numeric variables <replaceable>x</replaceable> and <replaceable>y</replaceable> are recoded
in place.
Zero is recoded to 99, the values 1 to 10 inclusive are unchanged,
values 1000 and higher are recoded to the system-missing value and all other
values are changed to 999:
</para><screen>recode <replaceable>x</replaceable> <replaceable>y</replaceable> 
        (0 = 99)
        (1 THRU 10 = COPY)
        (1000 THRU HIGHEST = SYSMIS)
        (ELSE = 999).
</screen>
<para>If &#8216;<literal>INTO <replaceable>dest_vars</replaceable></literal>&#8217; is given, then recoded values are written
into the variables specified in <replaceable>dest_vars</replaceable>, which must therefore
 contain a list of valid variable names.
The number of variables in <replaceable>dest_vars</replaceable> must be the same as the number
of variables in <replaceable>src_vars</replaceable>
and the respective order of the variables in <replaceable>dest_vars</replaceable> corresponds to 
the order of <replaceable>src_vars</replaceable>.
That is to say, recoded values whose 
original value came from the <replaceable>n</replaceable>th variable in <replaceable>src_vars</replaceable> will be
placed into the <replaceable>n</replaceable>th variable in <replaceable>dest_vars</replaceable>.
The source variables will be unchanged.
If any mapping implies a string as its destination value, then the respective
destination variable must already exist, or 
have been declared using <literal>STRING</literal> or another transformation.
Numeric variables however will be automatically created if they don&#8217;t already
exist.
The following example deals with two source variables, <replaceable>a</replaceable> and <replaceable>b</replaceable>
which contain string values.  Hence there are two destination variables
<replaceable>v1</replaceable> and <replaceable>v2</replaceable>.
Any cases where <replaceable>a</replaceable> or <replaceable>b</replaceable> contain the values &#8216;<literal>apple</literal>&#8217;, 
&#8216;<literal>pear</literal>&#8217; or &#8216;<literal>pomegranate</literal>&#8217; will result in <replaceable>v1</replaceable> or <replaceable>v2</replaceable> being
filled with the string &#8216;<literal>fruit</literal>&#8217; whilst cases with 
&#8216;<literal>tomato</literal>&#8217;, &#8216;<literal>lettuce</literal>&#8217; or &#8216;<literal>carrot</literal>&#8217; will result in &#8216;<literal>vegetable</literal>&#8217;.
Any other values will produce the result &#8216;<literal>unknown</literal>&#8217;:
</para><screen>string <replaceable>v1</replaceable> (a20).
string <replaceable>v2</replaceable> (a20).

recode <replaceable>a</replaceable> <replaceable>b</replaceable> 
        (&quot;apple&quot; &quot;pear&quot; &quot;pomegranate&quot; = &quot;fruit&quot;)
        (&quot;tomato&quot; &quot;lettuce&quot; &quot;carrot&quot; = &quot;vegetable&quot;)
        (ELSE = &quot;unknown&quot;)
        into <replaceable>v1</replaceable> <replaceable>v2</replaceable>.
</screen>
<para>There is one very special mapping, not mentioned above.
If the source variable is a string variable
then a mapping may be specified as &#8216;<literal>(CONVERT)</literal>&#8217;.
This mapping, if it appears must be the last mapping given and
the &#8216;<literal>INTO <replaceable>dest_vars</replaceable></literal>&#8217; clause must also be given and 
must not refer to a string variable. 
&#8216;<literal>CONVERT</literal>&#8217; causes a number specified as a string to
be converted to a numeric value. 
For example it will convert the string &#8216;<literal>&quot;3&quot;</literal>&#8217; into the numeric
value 3 (note that it will not convert &#8216;<literal>three</literal>&#8217; into 3).
If the string cannot be parsed as a number, then the system-missing value
is assigned instead.
In the following example, cases where the value of <replaceable>x</replaceable> (a string variable)
is the empty string, are recoded to 999 and all others are converted to the
numeric equivalent of the input value.  The results are placed into the 
numeric variable <replaceable>y</replaceable>:
</para><screen>recode <replaceable>x</replaceable> 
       (&quot;&quot; = 999)
        (convert)
        into <replaceable>y</replaceable>.
</screen>
<para>It is possible to specify multiple recodings on a single command.
Introduce additional recodings with a slash (&#8216;<literal>/</literal>&#8217;) to
separate them from the previous recodings:
</para><screen>recode 
        <replaceable>a</replaceable>  (2 = 22) (else = 99) 
        /<replaceable>b</replaceable> (1 = 3) into <replaceable>z</replaceable>
        .
</screen><para>Here we have two recodings. The first affects the source variable
<replaceable>a</replaceable> and recodes in-place the value 2 into 22 and all other values to 99.
The second recoding copies the values of <replaceable>b</replaceable> into the variable <replaceable>z</replaceable>, 
changing any instances of 1 into 3.
</para>
</sect1>
<sect1 label="12.8" id="SORT-CASES">
<title>SORT CASES</title>
<indexterm role="vr"><primary>SORT CASES</primary></indexterm>

<literallayout>SORT CASES BY <replaceable>var_list</replaceable>[({D|A}] [ <replaceable>var_list</replaceable>[({D|A}] ] ...
</literallayout>
<para><literal>SORT CASES</literal> sorts the active dataset by the values of one or more
variables.
</para>
<para>Specify <literal>BY</literal> and a list of variables to sort by.  By default, variables
are sorted in ascending order.  To override sort order, specify <literal>(D)</literal> or
<literal>(DOWN)</literal> after a list of variables to get descending order, or <literal>(A)</literal> or <literal>(UP)</literal>
for ascending order.  These apply to all the listed variables
up until the preceding <literal>(A)</literal>, <literal>(D)</literal>, <literal>(UP)</literal> or <literal>(DOWN)</literal>.
</para>
<para>The sort algorithms used by <literal>SORT CASES</literal> are stable.  That is,
records that have equal values of the sort variables will have the
same relative order before and after sorting.  As a special case,
re-sorting an already sorted file will not affect the ordering of
cases.
</para>
<para><literal>SORT CASES</literal> is a procedure.  It causes the data to be read.
</para>
<para><literal>SORT CASES</literal> attempts to sort the entire active dataset in main memory.
If workspace is exhausted, it falls back to a merge sort algorithm that
involves creates numerous temporary files.
</para>
<para><literal>SORT CASES</literal> may not be specified following <literal>TEMPORARY</literal>.  
</para></sect1>
</chapter>
<chapter label="13" id="Data-Selection">
<title>Selecting data for analysis</title>

<para>This chapter documents pspp commands that temporarily or permanently
select data records from the active dataset for analysis.
</para>

<sect1 label="13.1" id="FILTER">
<title>FILTER</title>
<indexterm role="vr"><primary>FILTER</primary></indexterm>

<literallayout>FILTER BY <replaceable>var_name</replaceable>.
FILTER OFF.
</literallayout>
<para><literal>FILTER</literal> allows a boolean-valued variable to be used to select
cases from the data stream for processing.
</para>
<para>To set up filtering, specify <literal>BY</literal> 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 <literal>COMPUTE</literal> or <literal>RECODE</literal> to compute a
filter variable of the required form, then specify that variable on
<literal>FILTER</literal>.
</para>
<para><literal>FILTER OFF</literal> turns off case filtering.
</para>
<para>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 <literal>FILTER
OFF</literal>.  However, if <literal>FILTER</literal> is placed after <literal>TEMPORARY</literal>, it filters only
the next procedure or procedure-like command.
</para>
</sect1>
<sect1 label="13.2" id="N-OF-CASES">
<title>N OF CASES</title>
<indexterm role="vr"><primary>N OF CASES</primary></indexterm>

<literallayout>N [OF CASES] <replaceable>num_of_cases</replaceable> [ESTIMATED].
</literallayout>
<para><literal>N OF CASES</literal> limits the number of cases processed by any
procedures that follow it in the command stream.  <literal>N OF CASES
100</literal>, for example, tells pspp to disregard all cases after the first
100.
</para>
<para>When <literal>N OF CASES</literal> is specified after <literal>TEMPORARY</literal>, it affects
only the next procedure (see <link linkend="TEMPORARY">TEMPORARY</link>).  Otherwise, cases beyond
the limit specified are not processed by any later procedure.
</para>
<para>If the limit specified on <literal>N OF CASES</literal> is greater than the number
of cases in the active dataset, it has no effect.
</para>
<para>When <literal>N OF CASES</literal> is used along with <literal>SAMPLE</literal> or <literal>SELECT
IF</literal>, the case limit is applied to the cases obtained after sampling or
case selection, regardless of how <literal>N OF CASES</literal> is placed relative
to <literal>SAMPLE</literal> or <literal>SELECT IF</literal> in the command file.  Thus, the
commands <literal>N OF CASES 100</literal> and <literal>SAMPLE .5</literal> will both randomly
sample approximately half of the active dataset&#8217;s cases, then select the
first 100 of those sampled, regardless of their order in the command
file.
</para>
<para><literal>N OF CASES</literal> with the <literal>ESTIMATED</literal> keyword gives an estimated
number of cases before <literal>DATA LIST</literal> or another command to read in
data.  <literal>ESTIMATED</literal> never limits the number of cases processed by
procedures.  pspp currently does not make use of case count estimates.
</para>
</sect1>
<sect1 label="13.3" id="SAMPLE">
<title>SAMPLE</title>
<indexterm role="vr"><primary>SAMPLE</primary></indexterm>

<literallayout>SAMPLE <replaceable>num1</replaceable> [FROM <replaceable>num2</replaceable>].
</literallayout>
<para><literal>SAMPLE</literal> randomly samples a proportion of the cases in the active
file.  Unless it follows <literal>TEMPORARY</literal>, it operates as a
transformation, permanently removing cases from the active dataset.
</para>
<para>The proportion to sample can be expressed as a single number between 0
and 1.  If <replaceable>k</replaceable> is the number specified, and <replaceable>N</replaceable> is the number
of currently-selected cases in the active dataset, then after
<literal>SAMPLE <replaceable>k</replaceable>.</literal>, approximately <replaceable>k</replaceable>*<replaceable>N</replaceable> cases will be
selected.
</para>
<para>The proportion to sample can also be specified in the style <literal>SAMPLE
<replaceable>m</replaceable> FROM <replaceable>N</replaceable></literal>.  With this style, cases are selected as follows:
</para>
<orderedlist numeration="arabic"><listitem><para>If <replaceable>N</replaceable> is equal to the number of currently-selected cases in the
active dataset, exactly <replaceable>m</replaceable> cases will be selected.
</para>
</listitem><listitem><para>If <replaceable>N</replaceable> is greater than the number of currently-selected cases in the
active dataset, an equivalent proportion of cases will be selected.
</para>
</listitem><listitem><para>If <replaceable>N</replaceable> is less than the number of currently-selected cases in the
active, exactly <replaceable>m</replaceable> cases will be selected <emphasis>from the first
<replaceable>N</replaceable> cases in the active dataset.</emphasis>
</para></listitem></orderedlist>
<para><literal>SAMPLE</literal> and <literal>SELECT IF</literal> are performed in
the order specified by the syntax file.
</para>
<para><literal>SAMPLE</literal> is always performed before <literal>N OF CASES</literal>, regardless
of ordering in the syntax file (see <link linkend="N-OF-CASES">N OF CASES</link>).
</para>
<para>The same values for <literal>SAMPLE</literal> may result in different samples.  To
obtain the same sample, use the <literal>SET</literal> command to set the random
number seed to the same value before each <literal>SAMPLE</literal>.  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.
</para>
</sect1>
<sect1 label="13.4" id="SELECT-IF">
<title>SELECT IF</title>
<indexterm role="vr"><primary>SELECT IF</primary></indexterm>

<literallayout>SELECT IF <replaceable>expression</replaceable>.
</literallayout>
<para><literal>SELECT IF</literal> selects cases for analysis based on the value of
<replaceable>expression</replaceable>.  Cases not selected are permanently eliminated
from the active dataset, unless <literal>TEMPORARY</literal> is in effect
(see <link linkend="TEMPORARY">TEMPORARY</link>).
</para>
<para>Specify a boolean expression (see <link linkend="Expressions">Expressions</link>).  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.
</para>
<para>Place <literal>SELECT IF</literal> as early in the command file as
possible.  Cases that are deleted early can be processed more
efficiently in time and space.
</para>
<para>When <literal>SELECT IF</literal> is specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>), the <literal>LAG</literal> function may not be used
(see <link linkend="LAG">LAG</link>).
</para>
</sect1>
<sect1 label="13.5" id="SPLIT-FILE">
<title>SPLIT FILE</title>
<indexterm role="vr"><primary>SPLIT FILE</primary></indexterm>

<literallayout>SPLIT FILE [{LAYERED, SEPARATE}] BY <replaceable>var_list</replaceable>.
SPLIT FILE OFF.
</literallayout>
<para><literal>SPLIT FILE</literal> allows multiple sets of data present in one data
file to be analyzed separately using single statistical procedure
commands.
</para>
<para>Specify a list of variable names to analyze multiple sets of
data separately.  Groups of adjacent 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.
</para>
<para>When a list of variable names is specified, one of the keywords
<literal>LAYERED</literal> or <literal>SEPARATE</literal> may also be specified.  If provided, either
keyword are ignored.
</para>
<para>Groups are formed only by <emphasis>adjacent</emphasis> cases.  To create a split 
using a variable where like values are not adjacent in the working file,
you should first sort the data by that variable (see <link linkend="SORT-CASES">SORT CASES</link>).
</para>
<para>Specify <literal>OFF</literal> to disable <literal>SPLIT FILE</literal> and resume analysis of the
entire active dataset as a single group of data.
</para>
<para>When <literal>SPLIT FILE</literal> is specified after <literal>TEMPORARY</literal>, it affects only
the next procedure (see <link linkend="TEMPORARY">TEMPORARY</link>).
</para>
</sect1>
<sect1 label="13.6" id="TEMPORARY">
<title>TEMPORARY</title>
<indexterm role="vr"><primary>TEMPORARY</primary></indexterm>

<literallayout>TEMPORARY.
</literallayout>
<para><literal>TEMPORARY</literal> 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 dataset.
</para>
<para>The only specification on <literal>TEMPORARY</literal> is the command name.
</para>
<para><literal>TEMPORARY</literal> may not appear within a <literal>DO IF</literal> or <literal>LOOP</literal>
construct.  It may appear only once between procedures and
procedure-like commands.
</para>
<para>Scratch variables cannot be used following <literal>TEMPORARY</literal>.
</para>
<para>An example may help to clarify:
</para>
<screen>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.
</screen>
<para>The data read by the first <literal>DESCRIPTIVES</literal> are 4, 5, 8,
10.5, 13, 15.  The data read by the first <literal>DESCRIPTIVES</literal> are 1, 2,
5, 7.5, 10, 12.
</para>
</sect1>
<sect1 label="13.7" id="WEIGHT">
<title>WEIGHT</title>
<indexterm role="vr"><primary>WEIGHT</primary></indexterm>

<literallayout>WEIGHT BY <replaceable>var_name</replaceable>.
WEIGHT OFF.
</literallayout>
<para><literal>WEIGHT</literal> assigns cases varying weights,
changing the frequency distribution of the active dataset.  Execution of
<literal>WEIGHT</literal> is delayed until data have been read.
</para>
<para>If a variable name is specified, <literal>WEIGHT</literal> causes the values of that
variable to be used as weighting factors for subsequent statistical
procedures.  Use of keyword <literal>BY</literal> is optional but recommended.  Weighting
variables must be numeric.  Scratch variables may not be used for
weighting (see <link linkend="Scratch-Variables">Scratch Variables</link>).
</para>
<para>When <literal>OFF</literal> is specified, subsequent statistical procedures will weight all
cases equally.
</para>
<para>A positive integer weighting factor <replaceable>w</replaceable> on a case will yield the
same statistical output as would replicating the case <replaceable>w</replaceable> 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.
</para>
<para>When <literal>WEIGHT</literal> is specified after <literal>TEMPORARY</literal>, it affects only
the next procedure (see <link linkend="TEMPORARY">TEMPORARY</link>).
</para>
<para><literal>WEIGHT</literal> does not cause cases in the active dataset to be
replicated in memory.
</para>
</sect1>
</chapter>
<chapter label="14" id="Conditionals-and-Looping">
<title>Conditional and Looping Constructs</title>
<indexterm role="cp"><primary>conditionals</primary></indexterm>
<indexterm role="cp"><primary>loops</primary></indexterm>
<indexterm role="cp"><primary>flow of control</primary></indexterm>
<indexterm role="cp"><primary>control flow</primary></indexterm>

<para>This chapter documents pspp commands used for conditional execution,
looping, and flow of control.
</para>

<sect1 label="14.1" id="BREAK">
<title>BREAK</title>
<indexterm role="vr"><primary>BREAK</primary></indexterm>

<literallayout>BREAK.
</literallayout>
<para><literal>BREAK</literal> terminates execution of the innermost currently executing
<literal>LOOP</literal> construct.
</para>
<para><literal>BREAK</literal> is allowed only inside <literal>LOOP</literal>&#8230;<literal>END LOOP</literal>.
See <link linkend="LOOP">LOOP</link>, for more details.
</para>
</sect1>
<sect1 label="14.2" id="DO-IF">
<title>DO IF</title>
<indexterm role="vr"><primary>DO IF</primary></indexterm>

<literallayout>DO IF condition.
        &#8230;
[ELSE IF condition.
        &#8230;
]&#8230;
[ELSE.
        &#8230;]
END IF.
</literallayout>
<para><literal>DO IF</literal> allows one of several sets of transformations to be
executed, depending on user-specified conditions.
</para>
<para>If the specified boolean expression evaluates as true, then the block
of code following <literal>DO IF</literal> 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 <literal>ELSE IF</literal>, if present, is tested in
turn, with the same rules applied.  If all expressions evaluate to
false, then the <literal>ELSE</literal> code block is executed, if it is present.
</para>
<para>When <literal>DO IF</literal> or <literal>ELSE IF</literal> is specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>), the <literal>LAG</literal> function may not be used
(see <link linkend="LAG">LAG</link>).
</para>
</sect1>
<sect1 label="14.3" id="DO-REPEAT">
<title>DO REPEAT</title>
<indexterm role="vr"><primary>DO REPEAT</primary></indexterm>

<literallayout>DO REPEAT dummy_name=expansion&#8230;.
        &#8230;
END REPEAT [PRINT].

expansion takes one of the following forms:
        var_list
        num_or_range&#8230;
        &#8217;string&#8217;&#8230;
        ALL

num_or_range takes one of the following forms:
        number
        num1 TO num2
</literallayout>
<para><literal>DO REPEAT</literal> repeats a block of code, textually substituting
different variables, numbers, or strings into the block with each
repetition.
</para>
<para>Specify a dummy variable name followed by an equals sign (&#8216;<literal>=</literal>&#8217;)
and the list of replacements.  Replacements can be a list of existing
or new variables, numbers, strings, or <literal>ALL</literal> to specify all
existing variables.  When numbers are specified, runs of increasing
integers may be indicated as <literal><replaceable>num1</replaceable> TO <replaceable>num2</replaceable></literal>, so that
&#8216;<literal>1 TO 5</literal>&#8217; is short for &#8216;<literal>1 2 3 4 5</literal>&#8217;.
</para>
<para>Multiple dummy variables can be specified.  Each
variable must have the same number of replacements.
</para>
<para>The code within <literal>DO REPEAT</literal> is repeated as many times as there are
replacements for each variable.  The first time, the first value for
each dummy variable is substituted; the second time, the second value
for each dummy variable is substituted; and so on.
</para>
<para>Dummy variable substitutions work like macros.  They take place
anywhere in a line that the dummy variable name occurs.  This includes
command and subcommand names, so command and subcommand names that
appear in the code block should not be used as dummy variable
identifiers.  Dummy variable substitutions do not occur inside quoted
strings, comments, unquoted strings (such as the text on the
<literal>TITLE</literal> or <literal>DOCUMENT</literal> command), or inside <literal>BEGIN
DATA</literal>&#8230;<literal>END DATA</literal>.
</para>
<para>Substitution occurs only on whole words, so that, for example, a dummy
variable PRINT would not be substituted into the word PRINTOUT.
</para>
<para>New variable names used as replacements are not automatically created
as variables, but only if used in the code block in a context that
would create them, e.g. on a <literal>NUMERIC</literal> or <literal>STRING</literal> command
or on the left side of a <literal>COMPUTE</literal> assignment.
</para>
<para>Any command may appear within <literal>DO REPEAT</literal>, including nested <literal>DO REPEAT</literal>
commands.  If <literal>INCLUDE</literal> or <literal>INSERT</literal> appears within <literal>DO REPEAT</literal>,
the substitutions do not apply to the included file.
</para>
<para>If <literal>PRINT</literal> is specified on <literal>END REPEAT</literal>, the commands after substitutions
are made are printed to the listing file, prefixed by a plus sign
(&#8216;<literal>+</literal>&#8217;).
</para>
</sect1>
<sect1 label="14.4" id="LOOP">
<title>LOOP</title>
<indexterm role="vr"><primary>LOOP</primary></indexterm>

<literallayout>LOOP [<replaceable>index_var</replaceable>=<replaceable>start</replaceable> TO <replaceable>end</replaceable> [BY <replaceable>incr</replaceable>]] [IF <replaceable>condition</replaceable>].
        &#8230;
END LOOP [IF <replaceable>condition</replaceable>].
</literallayout>
<para><literal>LOOP</literal> iterates a group of commands.  A number of
termination options are offered.
</para>
<para>Specify index_var to make that variable count from one value to
another by a particular increment.  <replaceable>index_var</replaceable> must be a pre-existing
numeric variable.  <replaceable>start</replaceable>, <replaceable>end</replaceable>, and <replaceable>incr</replaceable> are numeric expressions
(see <link linkend="Expressions">Expressions</link>.)  
</para>
<para>During the first iteration, <replaceable>index_var</replaceable> is set to the value of <replaceable>start</replaceable>.
During each successive iteration, <replaceable>index_var</replaceable> is increased by the value of
<replaceable>incr</replaceable>.  If <replaceable>end</replaceable> &gt; <replaceable>start</replaceable>, then the loop terminates 
when <replaceable>index_var</replaceable> &gt; <replaceable>end</replaceable>;
otherwise it terminates when <replaceable>index_var</replaceable> &lt; <replaceable>end</replaceable>.  If <replaceable>incr</replaceable> is not specified
then it defaults to +1 or -1 as appropriate.
</para>
<para>If <replaceable>end</replaceable> &gt; <replaceable>start</replaceable> and <replaceable>incr</replaceable> &lt; 0, or if <replaceable>end</replaceable> &lt; <replaceable>start</replaceable> and
 <replaceable>incr</replaceable> &gt; 0, then the
loop is never executed.  <replaceable>index_var</replaceable> is nevertheless set to the value of
start.
</para>
<para>Modifying <replaceable>index_var</replaceable> within the loop is allowed, but it has no effect on
the value of <replaceable>index_var</replaceable> in the next iteration.
</para>
<para>Specify a boolean expression for the condition on <literal>LOOP</literal> 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.
</para>
<para>If index and condition clauses are both present on <literal>LOOP</literal>, the
index variable is always set before the condition is evaluated.  Thus,
a condition that makes use of the index variable will always see the
index value to be used in the next execution of the body.
</para>
<para>Specify a boolean expression for the condition on <literal>END LOOP</literal> to cause
the loop to terminate if the condition is true after the enclosed
code block is executed.  The condition is evaluated at the end of the
loop, not at the beginning, so that the body of a loop with only a
condition on <literal>END LOOP</literal> will always execute at least once.
</para>
<para>If neither the index clause nor either condition clause is
present, then the loop is executed <replaceable>max_loops</replaceable> (see <link linkend="SET">SET</link>) times.
The default value of <replaceable>max_loops</replaceable> is 40.
</para>
<para><literal>BREAK</literal> also terminates <literal>LOOP</literal> execution (see <link linkend="BREAK">BREAK</link>).
</para>
<para>Loop index variables are by default reset to system-missing from one
case to another, not left, unless a scratch variable is used as index.
When loops are nested, this is usually undesired behavior, which can
be corrected with <literal>LEAVE</literal> (see <link linkend="LEAVE">LEAVE</link>) or by using a scratch
variable as the loop index.
</para>
<para>When <literal>LOOP</literal> or <literal>END LOOP</literal> is specified following <literal>TEMPORARY</literal>
(see <link linkend="TEMPORARY">TEMPORARY</link>), the <literal>LAG</literal> function may not be used
(see <link linkend="LAG">LAG</link>).
</para></sect1>
</chapter>
<chapter label="15" id="Statistics">
<title>Statistics</title>

<para>This chapter documents the statistical procedures that pspp supports so
far.
</para>

<sect1 label="15.1" id="DESCRIPTIVES">
<title>DESCRIPTIVES</title>

<indexterm role="vr"><primary>DESCRIPTIVES</primary></indexterm>
<literallayout>DESCRIPTIVES
        /VARIABLES=<replaceable>var_list</replaceable>
        /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}
</literallayout>
<para>The <literal>DESCRIPTIVES</literal> procedure reads the active dataset and outputs
descriptive
statistics requested by the user.  In addition, it can optionally
compute Z-scores.
</para>
<para>The <literal>VARIABLES</literal> subcommand, which is required, specifies the list of
variables to be analyzed.  Keyword <literal>VARIABLES</literal> is optional.
</para>
<para>All other subcommands are optional:
</para>
<para>The <literal>MISSING</literal> subcommand determines the handling of missing variables.  If
<literal>INCLUDE</literal> is set, then user-missing values are included in the
calculations.  If <literal>NOINCLUDE</literal> is set, which is the default, user-missing
values are excluded.  If <literal>VARIABLE</literal> is set, then missing values are
excluded on a variable by variable basis; if <literal>LISTWISE</literal> is set, then
the entire case is excluded whenever any value in that case has a
system-missing or, if <literal>INCLUDE</literal> is set, user-missing value.
</para>
<para>The <literal>FORMAT</literal> subcommand affects the output format.  Currently the
<literal>LABELS/NOLABELS</literal> and <literal>NOINDEX/INDEX</literal> settings are not used.
When <literal>SERIAL</literal> is
set, both valid and missing number of cases are listed in the output;
when <literal>NOSERIAL</literal> is set, only valid cases are listed.
</para>
<para>The <literal>SAVE</literal> subcommand causes <literal>DESCRIPTIVES</literal> 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 <literal>VARIABLES</literal> in the variable
list by enclosing them in parentheses after each variable.
When Z scores are calculated, pspp ignores <literal>TEMPORARY</literal>,
treating temporary transformations as permanent.
</para>
<para>The <literal>STATISTICS</literal> subcommand specifies the statistics to be displayed:
</para>
<variablelist><varlistentry><term><literal><literal>ALL</literal></literal>
</term><listitem><para>All of the statistics below.
</para></listitem></varlistentry><varlistentry><term><literal><literal>MEAN</literal></literal>
</term><listitem><para>Arithmetic mean.
</para></listitem></varlistentry><varlistentry><term><literal><literal>SEMEAN</literal></literal>
</term><listitem><para>Standard error of the mean.
</para></listitem></varlistentry><varlistentry><term><literal><literal>STDDEV</literal></literal>
</term><listitem><para>Standard deviation.
</para></listitem></varlistentry><varlistentry><term><literal><literal>VARIANCE</literal></literal>
</term><listitem><para>Variance.
</para></listitem></varlistentry><varlistentry><term><literal><literal>KURTOSIS</literal></literal>
</term><listitem><para>Kurtosis and standard error of the kurtosis.
</para></listitem></varlistentry><varlistentry><term><literal><literal>SKEWNESS</literal></literal>
</term><listitem><para>Skewness and standard error of the skewness.
</para></listitem></varlistentry><varlistentry><term><literal><literal>RANGE</literal></literal>
</term><listitem><para>Range.
</para></listitem></varlistentry><varlistentry><term><literal>MINIMUM</literal>
</term><listitem><para>Minimum value.
</para></listitem></varlistentry><varlistentry><term><literal>MAXIMUM</literal>
</term><listitem><para>Maximum value.
</para></listitem></varlistentry><varlistentry><term><literal>SUM</literal>
</term><listitem><para>Sum.
</para></listitem></varlistentry><varlistentry><term><literal>DEFAULT</literal>
</term><listitem><para>Mean, standard deviation of the mean, minimum, maximum.
</para></listitem></varlistentry><varlistentry><term><literal>SEKURTOSIS</literal>
</term><listitem><para>Standard error of the kurtosis.
</para></listitem></varlistentry><varlistentry><term><literal>SESKEWNESS</literal>
</term><listitem><para>Standard error of the skewness.
</para></listitem></varlistentry></variablelist>
<para>The <literal>SORT</literal> subcommand specifies how the statistics should be sorted.  Most
of the possible values should be self-explanatory.  <literal>NAME</literal> causes the
statistics to be sorted by name.  By default, the statistics are listed
in the order that they are specified on the <literal>VARIABLES</literal> subcommand.
The <literal>A</literal> and <literal>D</literal> settings request an ascending or descending
sort order, respectively.
</para>
</sect1>
<sect1 label="15.2" id="FREQUENCIES">
<title>FREQUENCIES</title>

<indexterm role="vr"><primary>FREQUENCIES</primary></indexterm>
<literallayout>FREQUENCIES
        /VARIABLES=<replaceable>var_list</replaceable>
        /FORMAT={TABLE,NOTABLE,LIMIT(<replaceable>limit</replaceable>)}
                {AVALUE,DVALUE,AFREQ,DFREQ}
        /MISSING={EXCLUDE,INCLUDE}
        /STATISTICS={DEFAULT,MEAN,SEMEAN,MEDIAN,MODE,STDDEV,VARIANCE,
                     KURTOSIS,SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,
                     SESKEWNESS,SEKURTOSIS,ALL,NONE}
        /NTILES=<replaceable>ntiles</replaceable>
        /PERCENTILES=percent&#8230;
        /HISTOGRAM=[MINIMUM(<replaceable>x_min</replaceable>)] [MAXIMUM(<replaceable>x_max</replaceable>)] 
                   [{FREQ[(<replaceable>y_max</replaceable>)],PERCENT[(<replaceable>y_max</replaceable>)]}] [{NONORMAL,NORMAL}]
        /PIECHART=[MINIMUM(<replaceable>x_min</replaceable>)] [MAXIMUM(<replaceable>x_max</replaceable>)]
                  [{FREQ,PERCENT}] [{NOMISSING,MISSING}]
        /BARCHART=[MINIMUM(<replaceable>x_min</replaceable>)] [MAXIMUM(<replaceable>x_max</replaceable>)]
                  [{FREQ,PERCENT}]
        /ORDER={ANALYSIS,VARIABLE}


(These options are not currently implemented.)
        /HBAR=&#8230;
        /GROUPED=&#8230;
</literallayout>
<para>The <literal>FREQUENCIES</literal> procedure outputs frequency tables for specified
variables.
<literal>FREQUENCIES</literal> can also calculate and display descriptive statistics
(including median and mode) and percentiles, and various graphical representations
of the frequency distribution.
</para>
<para>The <literal>VARIABLES</literal> subcommand is the only required subcommand.  Specify the
variables to be analyzed.
</para>
<para>The <literal>FORMAT</literal> subcommand controls the output format.  It has several
possible settings:  
</para>
<itemizedlist><listitem><para><literal></literal> <literal>TABLE</literal>, the default, causes a frequency table to be output for every
variable specified.  <literal>NOTABLE</literal> prevents them from being output.  <literal>LIMIT</literal>
with a numeric argument causes them to be output except when there are
more than the specified number of values in the table.
</para>
</listitem><listitem><para><literal></literal> Normally frequency tables are sorted in ascending order by value.  This
is <literal>AVALUE</literal>.  <literal>DVALUE</literal> tables are sorted in descending order by value.
<literal>AFREQ</literal> and <literal>DFREQ</literal> tables are sorted in ascending and descending order,
respectively, by frequency count.
</para></listitem></itemizedlist>
<para>The <literal>MISSING</literal> subcommand controls the handling of user-missing values.
When <literal>EXCLUDE</literal>, the default, is set, user-missing values are not included
in frequency tables or statistics.  When <literal>INCLUDE</literal> is set, user-missing
are included.  System-missing values are never included in statistics,
but are listed in frequency tables.
</para>
<para>The available <literal>STATISTICS</literal> are the same as available 
in <literal>DESCRIPTIVES</literal> (see <link linkend="DESCRIPTIVES">DESCRIPTIVES</link>), with the addition 
of <literal>MEDIAN</literal>, the data&#8217;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.
</para>
<indexterm role="cp"><primary>percentiles</primary></indexterm>
<para><literal>PERCENTILES</literal> causes the specified percentiles to be reported.
The percentiles should  be presented at a list of numbers between 0
and 100 inclusive.  
The <literal>NTILES</literal> subcommand causes the percentiles to be reported at the
boundaries of the data set divided into the specified number of ranges.
For instance, <literal>/NTILES=4</literal> would cause quartiles to be reported.
</para>
<indexterm role="cp"><primary>histogram</primary></indexterm>
<para>The <literal>HISTOGRAM</literal> subcommand causes the output to include a histogram for
each specified numeric variable.  The X axis by default ranges from
the minimum to the maximum value observed in the data, but the <literal>MINIMUM</literal>
and <literal>MAXIMUM</literal> keywords can set an explicit range. 
<footnote><para>The number of
bins is chosen according to the Freedman-Diaconis rule:
<inlineequation><mathphrase>2 \times IQR(x)n^{-1/3}</mathphrase></inlineequation>, where <inlineequation><mathphrase>IQR(x)</mathphrase></inlineequation> is the interquartile range of <inlineequation><mathphrase>x</mathphrase></inlineequation>
and <inlineequation><mathphrase>n</mathphrase></inlineequation> is the number of samples.    Note that
<literal>EXAMINE</literal> uses a different algorithm to determine bin sizes.</para></footnote>
Histograms are not created for string variables.
</para>
<para>Specify <literal>NORMAL</literal> to superimpose a normal curve on the
histogram.
</para>
<indexterm role="cp"><primary>piechart</primary></indexterm>
<para>The <literal>PIECHART</literal> subcommand adds a pie chart for each variable to the data.  Each
slice represents one value, with the size of the slice proportional to
the value&#8217;s frequency.  By default, all non-missing values are given
slices.  
The <literal>MINIMUM</literal> and <literal>MAXIMUM</literal> keywords can be used to limit the
displayed slices to a given range of values.  
The keyword <literal>NOMISSING</literal> causes missing values to be omitted from the
piechart.  This is the default.
If instead, <literal>MISSING</literal> is specified, then a single slice
will be included representing all system missing and user-missing cases.
</para>
<indexterm role="cp"><primary>bar chart</primary></indexterm>
<para>The <literal>BARCHART</literal> subcommand produces a bar chart for each variable.
The <literal>MINIMUM</literal> and <literal>MAXIMUM</literal> keywords can be used to omit
categories whose counts which lie outside the specified limits.
The <literal>FREQ</literal> option (default) causes the ordinate to display the frequency
of each category, whereas the <literal>PERCENT</literal> option will display relative
percentages.
</para>
<para>The <literal>FREQ</literal> and <literal>PERCENT</literal> options on <literal>HISTOGRAM</literal> and 
<literal>PIECHART</literal> are accepted but not currently honoured.
</para>
<para>The <literal>ORDER</literal> subcommand is accepted but ignored.
</para>
</sect1>
<sect1 label="15.3" id="EXAMINE">
<title>EXAMINE</title>

<indexterm role="vr"><primary>EXAMINE</primary></indexterm>
<indexterm role="cp"><primary>Exploratory data analysis</primary></indexterm>
<indexterm role="cp"><primary>normality, testing</primary></indexterm>

<literallayout>EXAMINE
        VARIABLES= <replaceable>var1</replaceable> [<replaceable>var2</replaceable>] &#8230; [<replaceable>varN</replaceable>]
           [BY <replaceable>factor1</replaceable> [BY <replaceable>subfactor1</replaceable>]
             [ <replaceable>factor2</replaceable> [BY <replaceable>subfactor2</replaceable>]]
             &#8230;
             [ <replaceable>factor3</replaceable> [BY <replaceable>subfactor3</replaceable>]]
            ]
        /STATISTICS={DESCRIPTIVES, EXTREME[(<replaceable>n</replaceable>)], ALL, NONE}
        /PLOT={BOXPLOT, NPPLOT, HISTOGRAM, SPREADLEVEL[(<replaceable>t</replaceable>)], ALL, NONE}
        /CINTERVAL <replaceable>p</replaceable>
        /COMPARE={GROUPS,VARIABLES}
        /ID=<replaceable>identity_variable</replaceable>
        /{TOTAL,NOTOTAL}
        /PERCENTILE=[<replaceable>percentiles</replaceable>]={HAVERAGE, WAVERAGE, ROUND, AEMPIRICAL, EMPIRICAL }
        /MISSING={LISTWISE, PAIRWISE} [{EXCLUDE, INCLUDE}] 
		[{NOREPORT,REPORT}]

</literallayout>
<para>The <literal>EXAMINE</literal> command is used to perform exploratory data analysis.
In particular, it is useful for testing how closely a distribution follows a
normal distribution, and for finding outliers and extreme values.
</para>
<para>The <literal>VARIABLES</literal> subcommand is mandatory.  
It specifies the dependent variables and optionally variables to use as
factors for the analysis.
Variables listed before the first <literal>BY</literal> keyword (if any) are the 
dependent variables.
The dependent variables may optionally be followed by a list of
factors which tell pspp how to break down the analysis for each
dependent variable. 
</para>
<para>Following the dependent variables, factors may be specified.
The factors (if desired) should be preceded by a single <literal>BY</literal> keyword.
The format for each factor is 
</para><literallayout><replaceable>factorvar</replaceable> [BY <replaceable>subfactorvar</replaceable>].
</literallayout><para>Each unique combination of the values of  <replaceable>factorvar</replaceable> and
<replaceable>subfactorvar</replaceable> divide the dataset into <firstterm>cells</firstterm>.
Statistics will be calculated for each cell
and for the entire dataset (unless <literal>NOTOTAL</literal> is given).
</para>
<para>The <literal>STATISTICS</literal> subcommand specifies which statistics to show.
<literal>DESCRIPTIVES</literal> will produce a table showing some parametric and
non-parametrics statistics.
<literal>EXTREME</literal> produces a table showing the extremities of each cell.
A number in parentheses, <replaceable>n</replaceable> determines
how many upper and lower extremities to show.
The default number is 5.
</para>
<para>The subcommands <literal>TOTAL</literal> and <literal>NOTOTAL</literal> are mutually exclusive.
If <literal>TOTAL</literal> appears, then statistics will be produced for the entire dataset
as well as for each cell.
If <literal>NOTOTAL</literal> appears, then statistics will be produced only for the cells
(unless no factor variables have been given).
These subcommands have no effect if there have  been no factor variables
specified.
</para>
<indexterm role="cp"><primary>boxplot</primary></indexterm>
<indexterm role="cp"><primary>histogram</primary></indexterm>
<indexterm role="cp"><primary>npplot</primary></indexterm>
<indexterm role="cp"><primary>spreadlevel plot</primary></indexterm>
<para>The <literal>PLOT</literal> subcommand specifies which plots are to be produced if any.
Available plots are <literal>HISTOGRAM</literal>, <literal>NPPLOT</literal>,  <literal>BOXPLOT</literal> and
<literal>SPREADLEVEL</literal>.
The first three can be used to visualise how closely each cell conforms to a 
normal distribution, whilst the spread vs. level plot can be useful to visualise
how the variance of differs between factors.
Boxplots will also show you the outliers and extreme values.
<footnote><para><literal>HISTOGRAM</literal> uses Sturges&#8217; rule to determine the number of
bins, as approximately <inlineequation><mathphrase>1 + \log2(n)</mathphrase></inlineequation>, where <inlineequation><mathphrase>n</mathphrase></inlineequation> is the number of samples.
Note that <literal>FREQUENCIES</literal> uses a different algorithm to find the bin size.</para></footnote>
</para>
<para>The <literal>SPREADLEVEL</literal> plot displays the interquartile range versus the 
median.  It takes an optional parameter <replaceable>t</replaceable>, which specifies how the data
should be transformed prior to plotting.
The given value <replaceable>t</replaceable> is a power to which the data is raised.  For example, if
<replaceable>t</replaceable> is given as 2, then the data will be squared.
Zero, however is a special value.  If <replaceable>t</replaceable> is 0 or 
is omitted, then data will be transformed by taking its natural logarithm instead of
raising to the power of <replaceable>t</replaceable>.
</para>
<para>The <literal>COMPARE</literal> subcommand is only relevant if producing boxplots, and it is only 
useful there is more than one dependent variable and at least one factor.
If 
<literal>/COMPARE=GROUPS</literal> is specified, then one plot per dependent variable is produced,
each of which contain boxplots for all the cells.
If <literal>/COMPARE=VARIABLES</literal> is specified, then one plot per cell is produced,
each containing one boxplot per dependent variable.
If the <literal>/COMPARE</literal> subcommand is omitted, then pspp behaves as if
<literal>/COMPARE=GROUPS</literal> were given.
</para> 
<para>The <literal>ID</literal> subcommand is relevant only if <literal>/PLOT=BOXPLOT</literal> or 
<literal>/STATISTICS=EXTREME</literal> has been given.
If given, it should provide the name of a variable which is to be used
to labels extreme values and outliers.
Numeric or string variables are permissible.  
If the <literal>ID</literal> subcommand is not given, then the case number will be used for
labelling.
</para>
<para>The <literal>CINTERVAL</literal> subcommand specifies the confidence interval to use in
calculation of the descriptives command.  The default is 95%.
</para>
<indexterm role="cp"><primary>percentiles</primary></indexterm>
<para>The <literal>PERCENTILES</literal> subcommand specifies which percentiles are to be calculated, 
and which algorithm to use for calculating them.  The default is to
calculate the 5, 10, 25, 50, 75, 90, 95 percentiles using the
<literal>HAVERAGE</literal> algorithm.
</para>
<para>The <literal>TOTAL</literal> and <literal>NOTOTAL</literal> subcommands are mutually exclusive.  If <literal>NOTOTAL</literal>
is given and factors have been specified in the <literal>VARIABLES</literal> subcommand,
then then statistics for the unfactored dependent variables are
produced in addition to the factored variables.  If there are no
factors specified then <literal>TOTAL</literal> and <literal>NOTOTAL</literal> have no effect.
</para>

<para>The following example will generate descriptive statistics and histograms for
two variables <replaceable>score1</replaceable> and <replaceable>score2</replaceable>.
Two factors are given, <emphasis>viz</emphasis>: <replaceable>gender</replaceable> and <replaceable>gender</replaceable> BY <replaceable>culture</replaceable>.
Therefore, the descriptives and histograms will be generated for each
distinct  value
of <replaceable>gender</replaceable> <emphasis>and</emphasis> for each distinct combination of the values
of <replaceable>gender</replaceable> and <replaceable>race</replaceable>.
Since the <literal>NOTOTAL</literal> keyword is given, statistics and histograms for 
<replaceable>score1</replaceable> and <replaceable>score2</replaceable> covering the  whole dataset are not produced.
</para><screen>EXAMINE <replaceable>score1</replaceable> <replaceable>score2</replaceable> BY 
        <replaceable>gender</replaceable>
        <replaceable>gender</replaceable> BY <replaceable>culture</replaceable>
        /STATISTICS = DESCRIPTIVES
        /PLOT = HISTOGRAM
        /NOTOTAL.
</screen>
<para>Here is a second example showing how the <literal>examine</literal> command can be used to find extremities.
</para><screen>EXAMINE <replaceable>height</replaceable> <replaceable>weight</replaceable> BY 
        <replaceable>gender</replaceable>
        /STATISTICS = EXTREME (3)
        /PLOT = BOXPLOT
        /COMPARE = GROUPS
        /ID = <replaceable>name</replaceable>.
</screen><para>In this example, we look at the height and weight of a sample of individuals and
how they differ between male and female.
A table showing the 3 largest and the 3 smallest values of <replaceable>height</replaceable> and 
<replaceable>weight</replaceable> for each gender, and for the whole dataset will be shown.
Boxplots will also be produced.
Because <literal>/COMPARE = GROUPS</literal> was given, boxplots for male and female will be
shown in the same graphic, allowing us to easily see the difference between
the genders.
Since the variable <replaceable>name</replaceable> was specified on the <literal>ID</literal> subcommand, this will be
used to label the extreme values.
</para>
<para><emphasis role="bold">Warning!</emphasis>
If many dependent variables are specified, or if factor variables are
specified for which
there are many distinct values, then <literal>EXAMINE</literal> will produce a very
large quantity of output.
</para>
</sect1>
<sect1 label="15.4" id="GRAPH">
<title>GRAPH</title>

<indexterm role="vr"><primary>GRAPH</primary></indexterm>
<indexterm role="cp"><primary>Exploratory data analysis</primary></indexterm>
<indexterm role="cp"><primary>normality, testing</primary></indexterm>

<literallayout>GRAPH
        /HISTOGRAM [(NORMAL)]= <replaceable>var</replaceable>
        /SCATTERPLOT [(BIVARIATE)] = <replaceable>var1</replaceable> WITH <replaceable>var2</replaceable> [BY <replaceable>var3</replaceable>]
        /BAR = {<replaceable>summary-function</replaceable>(<replaceable>var1</replaceable>) | <replaceable>count-function</replaceable>} BY <replaceable>var2</replaceable> [BY <replaceable>var3</replaceable>] 
        [ /MISSING={LISTWISE, VARIABLE} [{EXCLUDE, INCLUDE}] ] 
		[{NOREPORT,REPORT}]

</literallayout>
<para>The <literal>GRAPH</literal> produces graphical plots of data. Only one of the subcommands 
<literal>HISTOGRAM</literal> or <literal>SCATTERPLOT</literal> can be specified, i.e. only one plot
can be produced per call of <literal>GRAPH</literal>. The <literal>MISSING</literal> is optional. 
</para>

<sect2 label="15.4.1" id="SCATTERPLOT">
<title>Scatterplot</title>
<indexterm role="cp"><primary>scatterplot</primary></indexterm>

<para>The subcommand <literal>SCATTERPLOT</literal> produces an xy plot of the
data. The different values of the optional third variable <replaceable>var3</replaceable>
will result in different colours and/or markers for the plot. The
following is an example for producing a scatterplot.
</para>
<screen>GRAPH   
        /SCATTERPLOT = <replaceable>height</replaceable> WITH <replaceable>weight</replaceable> BY <replaceable>gender</replaceable>.
</screen>
<para>This example will produce a scatterplot where <replaceable>height</replaceable> is plotted versus <replaceable>weight</replaceable>. Depending
on the value of the <replaceable>gender</replaceable> variable, the colour of the datapoint is different. With
this plot it is possible to analyze gender differences for <replaceable>height</replaceable> vs. <replaceable>weight</replaceable> relation.
</para>
</sect2>
<sect2 label="15.4.2" id="HISTOGRAM">
<title>Histogram</title>
<indexterm role="cp"><primary>histogram</primary></indexterm>

<para>The subcommand <literal>HISTOGRAM</literal> produces a histogram. Only one variable is allowed for
the histogram plot.
The keyword <literal>NORMAL</literal> may be specified in parentheses, to indicate that the ideal normal curve
should be superimposed over the histogram.
For an alternative method to produce histograms see <link linkend="EXAMINE">EXAMINE</link>. The
following example produces a histogram plot for the variable <replaceable>weight</replaceable>.
</para>
<screen>GRAPH   
        /HISTOGRAM = <replaceable>weight</replaceable>.
</screen>
</sect2>
<sect2 label="15.4.3" id="BAR-CHART">
<title>Bar Chart</title>
<indexterm role="cp"><primary>bar chart</primary></indexterm>

<para>The subcommand <literal>BAR</literal> produces a bar chart.
This subcommand requires that a <replaceable>count-function</replaceable> be specified (with no arguments) or a <replaceable>summary-function</replaceable> with a variable <replaceable>var1</replaceable> in parentheses.
Following the summary or count function, the keyword <literal>BY</literal> should be specified and then a catagorical variable, <replaceable>var2</replaceable>.
The values of the variable <replaceable>var2</replaceable> determine the labels of the bars to be plotted.
Optionally a second categorical variable <replaceable>var3</replaceable> may be specified in which case a clustered (grouped) bar chart is produced.
</para>
<para>Valid count functions are
</para><variablelist><varlistentry><term><literal>COUNT</literal>
</term><listitem><para>The weighted counts of the cases in each category.
</para></listitem></varlistentry><varlistentry><term><literal>PCT</literal>
</term><listitem><para>The weighted counts of the cases in each category expressed as a percentage of the total weights of the cases.
</para></listitem></varlistentry><varlistentry><term><literal>CUFREQ</literal>
</term><listitem><para>The cumulative weighted counts of the cases in each category.
</para></listitem></varlistentry><varlistentry><term><literal>CUPCT</literal>
</term><listitem><para>The cumulative weighted counts of the cases in each category expressed as a percentage of the total weights of the cases.
</para></listitem></varlistentry></variablelist>
<para>The summary function is applied to <replaceable>var1</replaceable> across all cases in each category.
The recognised summary functions are:
</para><variablelist><varlistentry><term><literal>SUM</literal>
</term><listitem><para>The sum.
</para></listitem></varlistentry><varlistentry><term><literal>MEAN</literal>
</term><listitem><para>The arithmetic mean.
</para></listitem></varlistentry><varlistentry><term><literal>MAXIMUM</literal>
</term><listitem><para>The maximum value.
</para></listitem></varlistentry><varlistentry><term><literal>MINIMUM</literal>
</term><listitem><para>The minimum value.
</para></listitem></varlistentry></variablelist>
<para>The following examples assume a dataset which is the results of a survey.
Each respondent has indicated annual income, their sex and city of residence.
One could create a bar chart showing how the mean income varies between of residents of different cities, thus:
</para><screen>GRAPH  /BAR  = MEAN(<replaceable>income</replaceable>) BY <replaceable>city</replaceable>.
</screen>
<para>This can be extended to also indicate how income in each city differs between the sexes.
</para><screen>GRAPH  /BAR  = MEAN(<replaceable>income</replaceable>) BY <replaceable>city</replaceable> BY <replaceable>sex</replaceable>.
</screen>
<para>One might also want to see how many respondents there are from each city.  This can be achieved as follows:
</para><screen>GRAPH  /BAR  = COUNT BY <replaceable>city</replaceable>.
</screen>
<para>Bar charts can also be produced using the <link linkend="FREQUENCIES">FREQUENCIES</link> and <link linkend="CROSSTABS">CROSSTABS</link> commands.
</para>
</sect2>
</sect1>
<sect1 label="15.5" id="CORRELATIONS">
<title>CORRELATIONS</title>

<indexterm role="vr"><primary>CORRELATIONS</primary></indexterm>
<literallayout>CORRELATIONS
     /VARIABLES = <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> ]
     [
      .
      .
      .
      /VARIABLES = <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> ]
      /VARIABLES = <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> ]
     ]

     [ /PRINT={TWOTAIL, ONETAIL} {SIG, NOSIG} ]
     [ /STATISTICS=DESCRIPTIVES XPROD ALL]
     [ /MISSING={PAIRWISE, LISTWISE} {INCLUDE, EXCLUDE} ]
</literallayout>
<indexterm role="cp"><primary>correlation</primary></indexterm>
<para>The <literal>CORRELATIONS</literal> procedure produces tables of the Pearson correlation coefficient
for a set of variables.  The significance of the coefficients are also given.
</para>
<para>At least one <literal>VARIABLES</literal> subcommand is required. If the <literal>WITH</literal> 
keyword is used, then a non-square correlation table will be produced.
The variables preceding <literal>WITH</literal>, will be used as the rows of the table,
and the variables following will be the columns of the table.
If no <literal>WITH</literal> subcommand is given, then a square, symmetrical table using all variables is produced.
</para>

<para>The <literal>MISSING</literal> subcommand determines the handling of missing variables.  
If <literal>INCLUDE</literal> is set, then user-missing values are included in the
calculations, but system-missing values are not.
If <literal>EXCLUDE</literal> is set, which is the default, user-missing
values are excluded as well as system-missing values. 
</para>
<para>If <literal>LISTWISE</literal> is set, then the entire case is excluded from analysis
whenever any variable  specified in any <literal>/VARIABLES</literal> subcommand
contains a missing value.   
If <literal>PAIRWISE</literal> is set, then a case is considered missing only if either of the
values  for the particular coefficient are missing.
The default is <literal>PAIRWISE</literal>.
</para>
<para>The <literal>PRINT</literal> subcommand is used to control how the reported significance values are printed.
If the <literal>TWOTAIL</literal> option is used, then a two-tailed test of significance is 
printed.  If the <literal>ONETAIL</literal> option is given, then a one-tailed test is used.
The default is <literal>TWOTAIL</literal>.
</para>
<para>If the <literal>NOSIG</literal> option is specified, then correlation coefficients with significance less than
0.05 are highlighted.
If <literal>SIG</literal> is specified, then no highlighting is performed.  This is the default.
</para>
<indexterm role="cp"><primary>covariance</primary></indexterm>
<para>The <literal>STATISTICS</literal> subcommand requests additional statistics to be displayed.  The keyword 
<literal>DESCRIPTIVES</literal> requests that the mean, number of non-missing cases, and the non-biased
estimator of the standard deviation are displayed.
These statistics will be displayed in a separated table, for all the variables listed
in any <literal>/VARIABLES</literal> subcommand.
The <literal>XPROD</literal> keyword requests cross-product deviations and covariance estimators to 
be displayed for each pair of variables.
The keyword <literal>ALL</literal> is the union of <literal>DESCRIPTIVES</literal> and <literal>XPROD</literal>.
</para>
</sect1>
<sect1 label="15.6" id="CROSSTABS">
<title>CROSSTABS</title>

<indexterm role="vr"><primary>CROSSTABS</primary></indexterm>
<literallayout>CROSSTABS
        /TABLES=<replaceable>var_list</replaceable> BY <replaceable>var_list</replaceable> [BY <replaceable>var_list</replaceable>]&#8230;
        /MISSING={TABLE,INCLUDE,REPORT}
        /WRITE={NONE,CELLS,ALL}
        /FORMAT={TABLES,NOTABLES}
                {PIVOT,NOPIVOT}
                {AVALUE,DVALUE}
                {NOINDEX,INDEX}
                {BOX,NOBOX}
        /CELLS={COUNT,ROW,COLUMN,TOTAL,EXPECTED,RESIDUAL,SRESIDUAL,
                ASRESIDUAL,ALL,NONE}
        /COUNT={ASIS,CASE,CELL}
               {ROUND,TRUNCATE}
        /STATISTICS={CHISQ,PHI,CC,LAMBDA,UC,BTAU,CTAU,RISK,GAMMA,D,
                     KAPPA,ETA,CORR,ALL,NONE}
        /BARCHART
        
(Integer mode.)
        /VARIABLES=<replaceable>var_list</replaceable> (<replaceable>low</replaceable>,<replaceable>high</replaceable>)&#8230;
</literallayout>
<para>The <literal>CROSSTABS</literal> 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.
</para>
<para>The <literal>TABLES</literal> 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 <literal>TABLES</literal> subcommand may be repeated as many
times as needed.  This is the only required subcommand in <firstterm>general
mode</firstterm>.  
</para>
<para>Occasionally, one may want to invoke a special mode called <firstterm>integer
mode</firstterm>.  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
<literal>VARIABLES</literal> subcommand, giving a range of data values in parentheses for
each variable to be used on the <literal>TABLES</literal> 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 <literal>VARIABLES</literal> subcommand must precede the <literal>TABLES</literal>
subcommand.
</para>
<para>In general mode, numeric and string variables may be specified on
TABLES.  In integer mode, only numeric variables are allowed.
</para>
<para>The <literal>MISSING</literal> subcommand determines the handling of user-missing values.
When set to <literal>TABLE</literal>, the default, missing values are dropped on a table by
table basis.  When set to <literal>INCLUDE</literal>, user-missing values are included in
tables and statistics.  When set to <literal>REPORT</literal>, which is allowed only in
integer mode, user-missing values are included in tables but marked with
an &#8216;<literal>M</literal>&#8217; (for &#8220;missing&#8221;) and excluded from statistical
calculations.
</para>
<para>Currently the <literal>WRITE</literal> subcommand is ignored.
</para>
<para>The <literal>FORMAT</literal> subcommand controls the characteristics of the
crosstabulation tables to be displayed.  It has a number of possible
settings:
</para>
<itemizedlist><listitem><para><!-- /@w --> <literal>TABLES</literal>, the default, causes crosstabulation tables to be output.
<literal>NOTABLES</literal> suppresses them.
</para>
</listitem><listitem><para><!-- /@w --> <literal>PIVOT</literal>, the default, causes each <literal>TABLES</literal> subcommand to be displayed in a
pivot table format.  <literal>NOPIVOT</literal> causes the old-style crosstabulation format
to be used.
</para>
</listitem><listitem><para><!-- /@w --> <literal>AVALUE</literal>, the default, causes values to be sorted in ascending order.
<literal>DVALUE</literal> asserts a descending sort order.
</para>
</listitem><listitem><para><!-- /@w --> <literal>INDEX</literal> and <literal>NOINDEX</literal> are currently ignored.
</para>
</listitem><listitem><para><!-- /@w --> <literal>BOX</literal> and <literal>NOBOX</literal> is currently ignored.
</para></listitem></itemizedlist>
<para>The <literal>CELLS</literal> subcommand controls the contents of each cell in the displayed
crosstabulation table.  The possible settings are:
</para>
<variablelist><varlistentry><term>COUNT
</term><listitem><para>Frequency count.
</para></listitem></varlistentry><varlistentry><term>ROW
</term><listitem><para>Row percent.
</para></listitem></varlistentry><varlistentry><term>COLUMN
</term><listitem><para>Column percent.
</para></listitem></varlistentry><varlistentry><term>TOTAL
</term><listitem><para>Table percent.
</para></listitem></varlistentry><varlistentry><term>EXPECTED
</term><listitem><para>Expected value.
</para></listitem></varlistentry><varlistentry><term>RESIDUAL
</term><listitem><para>Residual.
</para></listitem></varlistentry><varlistentry><term>SRESIDUAL
</term><listitem><para>Standardized residual.
</para></listitem></varlistentry><varlistentry><term>ASRESIDUAL
</term><listitem><para>Adjusted standardized residual.
</para></listitem></varlistentry><varlistentry><term>ALL
</term><listitem><para>All of the above.
</para></listitem></varlistentry><varlistentry><term>NONE
</term><listitem><para>Suppress cells entirely.
</para></listitem></varlistentry></variablelist>
<para>&#8216;<literal>/CELLS</literal>&#8217; without any settings specified requests <literal>COUNT</literal>, <literal>ROW</literal>,
<literal>COLUMN</literal>, and <literal>TOTAL</literal>.  
If <literal>CELLS</literal> is not specified at all then only <literal>COUNT</literal>
will be selected.
</para>
<para>By default, crosstabulation and statistics use raw case weights,
without rounding.  Use the <literal>/COUNT</literal> subcommand to perform
rounding: CASE rounds the weights of individual weights as cases are
read, CELL rounds the weights of cells within each crosstabulation
table after it has been constructed, and ASIS explicitly specifies the
default non-rounding behavior.  When rounding is requested, ROUND, the
default, rounds to the nearest integer and TRUNCATE rounds toward
zero.
</para>
<para>The <literal>STATISTICS</literal> subcommand selects statistics for computation:
</para>
<variablelist><varlistentry><term>CHISQ
</term><listitem><indexterm role="cp"><primary>chisquare</primary></indexterm>
<indexterm role="cp"><primary>chi-square</primary></indexterm>

<para>Pearson chi-square, likelihood ratio, Fisher&#8217;s exact test, continuity
correction, linear-by-linear association.
</para></listitem></varlistentry><varlistentry><term>PHI
</term><listitem><para>Phi.
</para></listitem></varlistentry><varlistentry><term>CC
</term><listitem><para>Contingency coefficient.
</para></listitem></varlistentry><varlistentry><term>LAMBDA
</term><listitem><para>Lambda.
</para></listitem></varlistentry><varlistentry><term>UC
</term><listitem><para>Uncertainty coefficient.
</para></listitem></varlistentry><varlistentry><term>BTAU
</term><listitem><para>Tau-b.
</para></listitem></varlistentry><varlistentry><term>CTAU
</term><listitem><para>Tau-c.
</para></listitem></varlistentry><varlistentry><term>RISK
</term><listitem><para>Risk estimate.
</para></listitem></varlistentry><varlistentry><term>GAMMA
</term><listitem><para>Gamma.
</para></listitem></varlistentry><varlistentry><term>D
</term><listitem><para>Somers&#8217; D.
</para></listitem></varlistentry><varlistentry><term>KAPPA
</term><listitem><para>Cohen&#8217;s Kappa.
</para></listitem></varlistentry><varlistentry><term>ETA
</term><listitem><para>Eta.
</para></listitem></varlistentry><varlistentry><term>CORR
</term><listitem><para>Spearman correlation, Pearson&#8217;s r.
</para></listitem></varlistentry><varlistentry><term>ALL
</term><listitem><para>All of the above.
</para></listitem></varlistentry><varlistentry><term>NONE
</term><listitem><para>No statistics.
</para></listitem></varlistentry></variablelist>
<para>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.
</para>
<para>&#8216;<literal>/STATISTICS</literal>&#8217; without any settings selects CHISQ.  If the
<literal>STATISTICS</literal> subcommand is not given, no statistics are calculated.
</para>
<indexterm role="cp"><primary>bar chart</primary></indexterm>
<para>The &#8216;<literal>/BARCHART</literal>&#8217; subcommand produces a clustered bar chart for the first two
variables on each table.
If a table has more than two variables, the counts for the third and subsequent levels 
will be aggregated and the chart will be produces as if there were only two variables.  
</para>

<para><emphasis role="bold">Please note:</emphasis> Currently the implementation of <literal>CROSSTABS</literal> has the
following limitations:
</para>
<itemizedlist><listitem><para>Significance of some symmetric and directional measures is not calculated.
</para></listitem><listitem><para>Asymptotic standard error is not calculated for
Goodman and Kruskal&#8217;s tau or symmetric Somers&#8217; d.
</para></listitem><listitem><para>Approximate T is not calculated for symmetric uncertainty coefficient.
</para></listitem></itemizedlist>
<para>Fixes for any of these deficiencies would be welcomed.
</para>
</sect1>
<sect1 label="15.7" id="FACTOR">
<title>FACTOR</title>

<indexterm role="vr"><primary>FACTOR</primary></indexterm>
<indexterm role="cp"><primary>factor analysis</primary></indexterm>
<indexterm role="cp"><primary>principal components analysis</primary></indexterm>
<indexterm role="cp"><primary>principal axis factoring</primary></indexterm>
<indexterm role="cp"><primary>data reduction</primary></indexterm>

<literallayout>FACTOR  VARIABLES=<replaceable>var_list</replaceable>

        [ /METHOD = {CORRELATION, COVARIANCE} ]

        [ /ANALYSIS=<replaceable>var_list</replaceable> ]

        [ /EXTRACTION={PC, PAF}] 

        [ /ROTATION={VARIMAX, EQUAMAX, QUARTIMAX, PROMAX[(<replaceable>k</replaceable>)], NOROTATE}]

        [ /PRINT=[INITIAL] [EXTRACTION] [ROTATION] [UNIVARIATE] [CORRELATION] [COVARIANCE] [DET] [KMO] [SIG] [ALL] [DEFAULT] ]

        [ /PLOT=[EIGEN] ]

        [ /FORMAT=[SORT] [BLANK(<replaceable>n</replaceable>)] [DEFAULT] ]

        [ /CRITERIA=[FACTORS(<replaceable>n</replaceable>)] [MINEIGEN(<replaceable>l</replaceable>)] [ITERATE(<replaceable>m</replaceable>)] [ECONVERGE (<replaceable>delta</replaceable>)] [DEFAULT] ]

        [ /MISSING=[{LISTWISE, PAIRWISE}] [{INCLUDE, EXCLUDE}] ]
</literallayout>
<para>The <literal>FACTOR</literal> command performs Factor Analysis or Principal Axis Factoring on a dataset.  It may be used to find
common factors in the data or for data reduction purposes.
</para>
<para>The <literal>VARIABLES</literal> subcommand is required.  It lists the variables
which are to partake in the analysis.  (The <literal>ANALYSIS</literal>
subcommand may optionally further limit the variables that
participate; it is not useful and implemented only for compatibility.)
</para>
<para>The <literal>/EXTRACTION</literal> subcommand is used to specify the way in which factors (components) are extracted from the data.
If <literal>PC</literal> is specified, then Principal Components Analysis is used.  
If <literal>PAF</literal> is specified, then Principal Axis Factoring is
used. By default Principal Components Analysis will be used.
</para>
<para>The <literal>/ROTATION</literal> subcommand is used to specify the method by which the extracted solution will be rotated.
Three orthogonal rotation methods are available: 
<literal>VARIMAX</literal> (which is the default), <literal>EQUAMAX</literal>, and <literal>QUARTIMAX</literal>.
There is one oblique rotation method, <emphasis>viz</emphasis>: <literal>PROMAX</literal>.
Optionally you may enter the power of the promax rotation <replaceable>k</replaceable>, which must be enclosed in parentheses.
The default value of <replaceable>k</replaceable> is 5.
If you don&#8217;t want any rotation to be performed, the word <literal>NOROTATE</literal> will prevent the command from performing any
rotation on the data. 
</para>
<para>The <literal>/METHOD</literal> subcommand should be used to determine whether the covariance matrix or the correlation matrix of the data is
to be analysed.  By default, the correlation matrix is analysed.
</para>
<para>The <literal>/PRINT</literal> subcommand may be used to select which features of the analysis are reported:
</para>
<itemizedlist><listitem><para><literal>UNIVARIATE</literal>
      A table of mean values, standard deviations and total weights are printed.
</para></listitem><listitem><para><literal>INITIAL</literal>
      Initial communalities and eigenvalues are printed.
</para></listitem><listitem><para><literal>EXTRACTION</literal>
      Extracted communalities and eigenvalues are printed.
</para></listitem><listitem><para><literal>ROTATION</literal>
      Rotated communalities and eigenvalues are printed.
</para></listitem><listitem><para><literal>CORRELATION</literal>
      The correlation matrix is printed.
</para></listitem><listitem><para><literal>COVARIANCE</literal>
      The covariance matrix is printed.
</para></listitem><listitem><para><literal>DET</literal>
      The determinant of the correlation or covariance matrix is printed.
</para></listitem><listitem><para><literal>KMO</literal>
      The Kaiser-Meyer-Olkin measure of sampling adequacy and the Bartlett test of sphericity is printed.
</para></listitem><listitem><para><literal>SIG</literal>
      The significance of the elements of correlation matrix is printed.
</para></listitem><listitem><para><literal>ALL</literal>
      All of the above are printed.
</para></listitem><listitem><para><literal>DEFAULT</literal>
      Identical to <literal>INITIAL</literal> and <literal>EXTRACTION</literal>.
</para></listitem></itemizedlist>
<para>If <literal>/PLOT=EIGEN</literal> is given, then a &#8220;Scree&#8221; plot of the eigenvalues will be printed.  This can be useful for visualizing
which factors (components) should be retained.
</para>
<para>The <literal>/FORMAT</literal> subcommand determined how data are to be displayed in loading matrices.  If <literal>SORT</literal> is specified, then the variables
are sorted in descending order of significance.  If <literal>BLANK(<replaceable>n</replaceable>)</literal> is specified, then coefficients whose absolute value is less
than <replaceable>n</replaceable> will not be printed.  If the keyword <literal>DEFAULT</literal> is given, or if no <literal>/FORMAT</literal> subcommand is given, then no sorting is 
performed, and all coefficients will be printed.
</para>
<para>The <literal>/CRITERIA</literal> subcommand is used to specify how the number of extracted factors (components) are chosen.
If <literal>FACTORS(<replaceable>n</replaceable>)</literal> is
specified, where <replaceable>n</replaceable> is an integer, then <replaceable>n</replaceable> factors will be extracted.  Otherwise, the <literal>MINEIGEN</literal> setting will
be used.  
<literal>MINEIGEN(<replaceable>l</replaceable>)</literal> requests that all factors whose eigenvalues are greater than or equal to <replaceable>l</replaceable> are extracted.
The default value of <replaceable>l</replaceable> is 1.    
The <literal>ECONVERGE</literal> setting has effect only when iterative algorithms for factor
extraction (such as Principal Axis Factoring) are used.   
<literal>ECONVERGE(<replaceable>delta</replaceable>)</literal> specifies that
iteration should cease when
the maximum absolute value of the communality estimate between one iteration and the previous is less than <replaceable>delta</replaceable>. The
default value of <replaceable>delta</replaceable> is 0.001.
The <literal>ITERATE(<replaceable>m</replaceable>)</literal> may appear any number of times and is used for two different purposes.  
It is used to set the maximum number of iterations (<replaceable>m</replaceable>) for convergence and also to set the maximum number of iterations
for rotation.
Whether it affects convergence or rotation depends upon which subcommand follows the <literal>ITERATE</literal> subcommand.
If <literal>EXTRACTION</literal> follows, it affects convergence.  
If <literal>ROTATION</literal> follows, it affects rotation.  
If neither <literal>ROTATION</literal> nor <literal>EXTRACTION</literal> follow a <literal>ITERATE</literal> subcommand it will be ignored.
The default value of <replaceable>m</replaceable> is 25.
</para>
<para>The <literal>MISSING</literal> subcommand determines the handling of missing variables.  
If <literal>INCLUDE</literal> is set, then user-missing values are included in the
calculations, but system-missing values are not.
If <literal>EXCLUDE</literal> is set, which is the default, user-missing
values are excluded as well as system-missing values. 
This is the default.
If <literal>LISTWISE</literal> is set, then the entire case is excluded from analysis
whenever any variable  specified in the <literal>VARIABLES</literal> subcommand
contains a missing value.   
If <literal>PAIRWISE</literal> is set, then a case is considered missing only if either of the
values  for the particular coefficient are missing.
The default is <literal>LISTWISE</literal>.
</para>
</sect1>
<sect1 label="15.8" id="GLM">
<title>GLM</title>

<indexterm role="vr"><primary>GLM</primary></indexterm>
<indexterm role="cp"><primary>univariate analysis of variance</primary></indexterm>
<indexterm role="cp"><primary>fixed effects</primary></indexterm>
<indexterm role="cp"><primary>factorial anova</primary></indexterm>
<indexterm role="cp"><primary>analysis of variance</primary></indexterm>
<indexterm role="cp"><primary>ANOVA</primary></indexterm>


<literallayout>GLM <replaceable>dependent_vars</replaceable> BY <replaceable>fixed_factors</replaceable>
     [/METHOD = SSTYPE(<replaceable>type</replaceable>)]
     [/DESIGN = <replaceable>interaction_0</replaceable> [<replaceable>interaction_1</replaceable> [... <replaceable>interaction_n</replaceable>]]]
     [/INTERCEPT = {INCLUDE|EXCLUDE}]
     [/MISSING = {INCLUDE|EXCLUDE}]
</literallayout>
<para>The <literal>GLM</literal> procedure can be used for fixed effects factorial Anova.
</para>
<para>The <replaceable>dependent_vars</replaceable> are the variables to be analysed.
You may analyse several variables in the same command in which case they should all
appear before the <literal>BY</literal> keyword.
</para>
<para>The <replaceable>fixed_factors</replaceable> list must be one or more categorical variables.  Normally it
will not make sense to enter a scalar variable in the <replaceable>fixed_factors</replaceable> and doing
so may cause pspp to do a lot of unnecessary processing.
</para>
<para>The <literal>METHOD</literal> subcommand is used to change the method for producing the sums of
squares.  Available values of <replaceable>type</replaceable> are 1, 2 and 3.  The default is type 3.
</para>
<para>You may specify a custom design using the <literal>DESIGN</literal> subcommand.
The design comprises a list of interactions where each interaction is a 
list of variables separated by a &#8216;<literal>*</literal>&#8217;.  For example the command
</para><literallayout>GLM subject BY sex age_group race
    /DESIGN = age_group sex group age_group*sex age_group*race
</literallayout><para>specifies the model <inlineequation><mathphrase>subject = age_group + sex + race + age_group*sex + age_group*race</mathphrase></inlineequation>.
If no <literal>DESIGN</literal> subcommand is specified, then the default is all possible combinations
of the fixed factors.  That is to say
</para><literallayout>GLM subject BY sex age_group race
</literallayout><para>implies the model
<inlineequation><mathphrase>subject = age_group + sex + race + age_group*sex + age_group*race + sex*race + age_group*sex*race</mathphrase></inlineequation>.
</para>

<para>The <literal>MISSING</literal> subcommand determines the handling of missing
variables.  
If <literal>INCLUDE</literal> is set then, for the purposes of GLM analysis,
only system-missing values are considered
to be missing; user-missing values are not regarded as missing.
If <literal>EXCLUDE</literal> is set, which is the default, then user-missing
values are considered to be missing as well as system-missing values. 
A case for which any dependent variable or any factor
variable has a missing value is excluded from the analysis.
</para>
</sect1>
<sect1 label="15.9" id="LOGISTIC-REGRESSION">
<title>LOGISTIC REGRESSION</title>

<indexterm role="vr"><primary>LOGISTIC REGRESSION</primary></indexterm>
<indexterm role="cp"><primary>logistic regression</primary></indexterm>
<indexterm role="cp"><primary>bivariate logistic regression</primary></indexterm>

<literallayout>LOGISTIC REGRESSION [VARIABLES =] <replaceable>dependent_var</replaceable> WITH <replaceable>predictors</replaceable>

     [/CATEGORICAL = <replaceable>categorical_predictors</replaceable>]

     [{/NOCONST | /ORIGIN | /NOORIGIN }]

     [/PRINT = [SUMMARY] [DEFAULT] [CI(<replaceable>confidence</replaceable>)] [ALL]]

     [/CRITERIA = [BCON(<replaceable>min_delta</replaceable>)] [ITERATE(<replaceable>max_interations</replaceable>)]
                  [LCON(<replaceable>min_likelihood_delta</replaceable>)] [EPS(<replaceable>min_epsilon</replaceable>)]
                  [CUT(<replaceable>cut_point</replaceable>)]]

     [/MISSING = {INCLUDE|EXCLUDE}]
</literallayout>
<para>Bivariate Logistic Regression is used when you want to explain a dichotomous dependent
variable in terms of one or more predictor variables.
</para>
<para>The minimum command is
</para><screen>LOGISTIC REGRESSION <replaceable>y</replaceable> WITH <replaceable>x1</replaceable> <replaceable>x2</replaceable> &#8230; <replaceable>xn</replaceable>.
</screen><para>Here, <replaceable>y</replaceable> is the dependent variable, which must be dichotomous and <replaceable>x1</replaceable> &#8230; <replaceable>xn</replaceable>
are the predictor variables whose coefficients the procedure estimates.
</para>
<para>By default, a constant term is included in the model.
Hence, the full model is
<inlineequation><mathphrase>{\bf y} 
= b_0 + b_1 {\bf x_1} 
+ b_2 {\bf x_2} 
+ \dots
+ b_n {\bf x_n}
</mathphrase></inlineequation>
</para>
<para>Predictor variables which are categorical in nature should be listed on the <literal>/CATEGORICAL</literal> subcommand.
Simple variables as well as interactions between variables may be listed here.
</para>
<para>If you want a model without the constant term <inlineequation><mathphrase>b_0</mathphrase></inlineequation>, use the keyword <literal>/ORIGIN</literal>.
<literal>/NOCONST</literal> is a synonym for <literal>/ORIGIN</literal>.
</para>
<para>An iterative Newton-Raphson procedure is used to fit the model.
The <literal>/CRITERIA</literal> subcommand is used to specify the stopping criteria of the procedure,
and other parameters.
The value of <replaceable>cut_point</replaceable> is used in the classification table.  It is the 
threshold above which predicted values are considered to be 1.  Values
of <replaceable>cut_point</replaceable> must lie in the range [0,1].
During iterations, if any one of the stopping criteria are satisfied, the procedure is
considered complete.
The stopping criteria are:
</para><itemizedlist><listitem><para>The number of iterations exceeds <replaceable>max_iterations</replaceable>.  
      The default value of <replaceable>max_iterations</replaceable> is 20.
</para></listitem><listitem><para>The change in the all coefficient estimates are less than <replaceable>min_delta</replaceable>.
The default value of <replaceable>min_delta</replaceable> is 0.001.
</para></listitem><listitem><para>The magnitude of change in the likelihood estimate is less than <replaceable>min_likelihood_delta</replaceable>.
The default value of <replaceable>min_delta</replaceable> is zero.
This means that this criterion is disabled.
</para></listitem><listitem><para>The differential of the estimated probability for all cases is less than <replaceable>min_epsilon</replaceable>.
In other words, the probabilities are close to zero or one.
The default value of <replaceable>min_epsilon</replaceable> is 0.00000001.
</para></listitem></itemizedlist>

<para>The <literal>PRINT</literal> subcommand controls the display of optional statistics.
Currently there is one such option, <literal>CI</literal>, which indicates that the 
confidence interval of the odds ratio should be displayed as well as its value.
<literal>CI</literal> should be followed by an integer in parentheses, to indicate the
confidence level of the desired confidence interval.
</para>
<para>The <literal>MISSING</literal> subcommand determines the handling of missing
variables.  
If <literal>INCLUDE</literal> is set, then user-missing values are included in the
calculations, but system-missing values are not.
If <literal>EXCLUDE</literal> is set, which is the default, user-missing
values are excluded as well as system-missing values. 
This is the default.
</para>
</sect1>
<sect1 label="15.10" id="MEANS">
<title>MEANS</title>

<indexterm role="vr"><primary>MEANS</primary></indexterm>
<indexterm role="cp"><primary>means</primary></indexterm>

<literallayout>MEANS [TABLES =] 
      {<replaceable>var_list</replaceable>} 
        [ BY {<replaceable>var_list</replaceable>} [BY {<replaceable>var_list</replaceable>} [BY {<replaceable>var_list</replaceable>} &#8230; ]]]

      [ /{<replaceable>var_list</replaceable>} 
         [ BY {<replaceable>var_list</replaceable>} [BY {<replaceable>var_list</replaceable>} [BY {<replaceable>var_list</replaceable>} &#8230; ]]] ]

      [/CELLS = [MEAN] [COUNT] [STDDEV] [SEMEAN] [SUM] [MIN] [MAX] [RANGE]
        [VARIANCE] [KURT] [SEKURT] 
        [SKEW] [SESKEW] [FIRST] [LAST] 
        [HARMONIC] [GEOMETRIC] 
        [DEFAULT]
        [ALL]
        [NONE] ]

      [/MISSING = [TABLE] [INCLUDE] [DEPENDENT]]
</literallayout>
<para>You can use the <literal>MEANS</literal> command to calculate the arithmetic mean and similar
statistics, either for the dataset as a whole or for categories of data.
</para>
<para>The simplest form of the command is
</para><screen>MEANS <replaceable>v</replaceable>.
</screen><para>which calculates the mean, count and standard deviation for <replaceable>v</replaceable>.
If you specify a grouping variable, for example
</para><screen>MEANS <replaceable>v</replaceable> BY <replaceable>g</replaceable>.
</screen><para>then the means, counts and standard deviations for <replaceable>v</replaceable> after having
been grouped by <replaceable>g</replaceable> will be calculated.
Instead of the mean, count and standard deviation, you could specify the statistics
in which you are interested:
</para><screen>MEANS <replaceable>x</replaceable> <replaceable>y</replaceable> BY <replaceable>g</replaceable>
      /CELLS = HARMONIC SUM MIN.
</screen><para>This example calculates the harmonic mean, the sum and the minimum values of <replaceable>x</replaceable> and <replaceable>y</replaceable>
grouped by <replaceable>g</replaceable>.
</para>
<para>The <literal>CELLS</literal> subcommand specifies which statistics to calculate.  The available statistics
are:
</para><itemizedlist><listitem><para><literal>MEAN</literal>
<indexterm role="cp"><primary>arithmetic mean</primary></indexterm>
      The arithmetic mean.
</para></listitem><listitem><para><literal>COUNT</literal>
      The count of the values.
</para></listitem><listitem><para><literal>STDDEV</literal>
      The standard deviation.
</para></listitem><listitem><para><literal>SEMEAN</literal>
      The standard error of the mean.
</para></listitem><listitem><para><literal>SUM</literal>
      The sum of the values.
</para></listitem><listitem><para><literal>MIN</literal>
      The minimum value.
</para></listitem><listitem><para><literal>MAX</literal>
      The maximum value.
</para></listitem><listitem><para><literal>RANGE</literal>
      The difference between the maximum and minimum values.
</para></listitem><listitem><para><literal>VARIANCE</literal>
      The variance.
</para></listitem><listitem><para><literal>FIRST</literal>
      The first value in the category.
</para></listitem><listitem><para><literal>LAST</literal>
      The last value in the category.
</para></listitem><listitem><para><literal>SKEW</literal>
      The skewness.
</para></listitem><listitem><para><literal>SESKEW</literal>
      The standard error of the skewness.
</para></listitem><listitem><para><literal>KURT</literal>
      The kurtosis
</para></listitem><listitem><para><literal>SEKURT</literal>
      The standard error of the kurtosis.
</para></listitem><listitem><para><literal>HARMONIC</literal>
<indexterm role="cp"><primary>harmonic mean</primary></indexterm>
      The harmonic mean.
</para></listitem><listitem><para><literal>GEOMETRIC</literal>
<indexterm role="cp"><primary>geometric mean</primary></indexterm>
      The geometric mean.
</para></listitem></itemizedlist>
<para>In addition, three special keywords are recognized:
</para><itemizedlist><listitem><para><literal>DEFAULT</literal>
      This is the same as <literal>MEAN</literal> <literal>COUNT</literal> <literal>STDDEV</literal>.
</para></listitem><listitem><para><literal>ALL</literal>
      All of the above statistics will be calculated.
</para></listitem><listitem><para><literal>NONE</literal>
      No statistics will be calculated (only a summary will be shown).
</para></listitem></itemizedlist>

<para>More than one <firstterm>table</firstterm> can be specified in a single command. 
Each table is separated by a &#8216;<literal>/</literal>&#8217;. For
example
</para><screen>MEANS TABLES =
      <replaceable>c</replaceable> <replaceable>d</replaceable> <replaceable>e</replaceable> BY <replaceable>x</replaceable>
      /<replaceable>a</replaceable> <replaceable>b</replaceable> BY <replaceable>x</replaceable> <replaceable>y</replaceable>
      /<replaceable>f</replaceable> BY <replaceable>y</replaceable> BY <replaceable>z</replaceable>.
</screen><para>has three tables (the &#8216;<literal>TABLE =</literal>&#8217; is optional).
The first table has three dependent variables <replaceable>c</replaceable>, <replaceable>d</replaceable> and <replaceable>e</replaceable>
and a single categorical variable <replaceable>x</replaceable>.
The second table has two dependent variables <replaceable>a</replaceable> and <replaceable>b</replaceable>, 
and two categorical variables <replaceable>x</replaceable> and <replaceable>y</replaceable>.
The third table has a single dependent variables <replaceable>f</replaceable>
and a categorical variable formed by the combination of <replaceable>y</replaceable> and <replaceable>z</replaceable>.
</para>

<para>By default values are omitted from the analysis only if missing values
(either system missing or user missing)
for any of the variables directly involved in their calculation are 
encountered.
This behaviour can be modified with the  <literal>/MISSING</literal> subcommand.
Three options are possible: <literal>TABLE</literal>, <literal>INCLUDE</literal> and <literal>DEPENDENT</literal>.
</para>
<para><literal>/MISSING = TABLE</literal> causes cases to be dropped if any variable is missing 
in the table specification currently being processed, regardless of 
whether it is needed to calculate the statistic.
</para>
<para><literal>/MISSING = INCLUDE</literal> says that user missing values, either in the dependent
variables or in the categorical variables should be taken at their face
value, and not excluded.
</para>
<para><literal>/MISSING = DEPENDENT</literal> says that user missing values, in the dependent
variables should be taken at their face value, however cases which 
have user missing values for the categorical variables should be omitted 
from the calculation.
</para>
</sect1>
<sect1 label="15.11" id="NPAR-TESTS">
<title>NPAR TESTS</title>

<indexterm role="vr"><primary>NPAR TESTS</primary></indexterm>
<indexterm role="cp"><primary>nonparametric tests</primary></indexterm>

<literallayout>NPAR TESTS
     
     nonparametric test subcommands
     .
     .
     .
     
     [ /STATISTICS={DESCRIPTIVES} ]

     [ /MISSING={ANALYSIS, LISTWISE} {INCLUDE, EXCLUDE} ]

     [ /METHOD=EXACT [ TIMER [(<replaceable>n</replaceable>)] ] ]
</literallayout>
<para><literal>NPAR TESTS</literal> performs nonparametric tests. 
Non parametric tests make very few assumptions about the distribution of the 
data.
One or more tests may be specified by using the corresponding subcommand.
If the <literal>/STATISTICS</literal> subcommand is also specified, then summary statistics are 
produces for each variable that is the subject of any test.
</para>
<para>Certain tests may take a long time to execute, if an exact figure is required.
Therefore, by default asymptotic approximations are used unless the
subcommand <literal>/METHOD=EXACT</literal> is specified.  
Exact tests give more accurate results, but may take an unacceptably long 
time to perform.  If the <literal>TIMER</literal> keyword is used, it sets a maximum time,
after which the test will be abandoned, and a warning message printed.
The time, in minutes, should be specified in parentheses after the <literal>TIMER</literal> keyword.
If the <literal>TIMER</literal> keyword is given without this figure, then a default value of 5 minutes 
is used.
</para>



<sect2 label="15.11.1" id="BINOMIAL">
<title>Binomial test</title>
<indexterm role="vr"><primary>BINOMIAL</primary></indexterm>
<indexterm role="cp"><primary>binomial test</primary></indexterm>

<literallayout>     [ /BINOMIAL[(<replaceable>p</replaceable>)]=<replaceable>var_list</replaceable>[(<replaceable>value1</replaceable>[, <replaceable>value2</replaceable>)] ] ]
</literallayout>
<para>The <literal>/BINOMIAL</literal> subcommand compares the observed distribution of a dichotomous 
variable with that of a binomial distribution.
The variable <replaceable>p</replaceable> specifies the test proportion of the binomial 
distribution.  
The default value of 0.5 is assumed if <replaceable>p</replaceable> is omitted.
</para>
<para>If a single value appears after the variable list, then that value is
used as the threshold to partition the observed values. Values less
than or equal to the threshold value form the first category.  Values
greater than the threshold form the second category. 
</para>
<para>If two values appear after the variable list, then they will be used
as the values which a variable must take to be in the respective
category. 
Cases for which a variable takes a value equal to neither of the specified  
values, take no part in the test for that variable.
</para>
<para>If no values appear, then the variable must assume dichotomous
values.
If more than two distinct, non-missing values for a variable
under test are encountered then an error occurs.
</para>
<para>If the test proportion is equal to 0.5, then a two tailed test is
reported.   For any other test proportion, a one tailed test is
reported.   
For one tailed tests, if the test proportion is less than
or equal to the observed proportion, then the significance of
observing the observed proportion or more is reported.
If the test proportion is more than the observed proportion, then the
significance of observing the observed proportion or less is reported.
That is to say, the test is always performed in the observed
direction. 
</para>
<para>pspp uses a very precise approximation to the gamma function to
compute the binomial significance.  Thus, exact results are reported
even for very large sample sizes.
</para>


</sect2>
<sect2 label="15.11.2" id="CHISQUARE">
<title>Chisquare Test</title>
<indexterm role="vr"><primary>CHISQUARE</primary></indexterm>
<indexterm role="cp"><primary>chisquare test</primary></indexterm>


<literallayout>     [ /CHISQUARE=<replaceable>var_list</replaceable>[(<replaceable>lo</replaceable>,<replaceable>hi</replaceable>)] [/EXPECTED={EQUAL|<replaceable>f1</replaceable>, <replaceable>f2</replaceable> &#8230; <replaceable>fn</replaceable>}] ]
</literallayout>

<para>The <literal>/CHISQUARE</literal> subcommand produces a chi-square statistic for the differences 
between the expected and observed frequencies of the categories of a variable. 
Optionally, a range of values may appear after the variable list.  
If a range is given, then non integer values are truncated, and values
outside the  specified range are excluded from the analysis.
</para>
<para>The <literal>/EXPECTED</literal> subcommand specifies the expected values of each
category.  
There must be exactly one non-zero expected value, for each observed
category, or the <literal>EQUAL</literal> keyword must be specified.
You may use the notation <literal><replaceable>n</replaceable>*<replaceable>f</replaceable></literal> to specify <replaceable>n</replaceable>
consecutive expected categories all taking a frequency of <replaceable>f</replaceable>.
The frequencies given are proportions, not absolute frequencies.  The
sum of the frequencies need not be 1.
If no <literal>/EXPECTED</literal> subcommand is given, then then equal frequencies 
are expected.
</para>

</sect2>
<sect2 label="15.11.3" id="COCHRAN">
<title>Cochran Q Test</title>
<indexterm role="vr"><primary>Cochran</primary></indexterm>
<indexterm role="cp"><primary>Cochran Q test</primary></indexterm>
<indexterm role="cp"><primary>Q, Cochran Q</primary></indexterm>

<literallayout>     [ /COCHRAN = <replaceable>var_list</replaceable> ]
</literallayout>
<para>The Cochran Q test is used to test for differences between three or more groups.
The data for <replaceable>var_list</replaceable> in all cases must assume exactly two distinct values (other than missing values). 
</para>
<para>The value of Q will be displayed and its Asymptotic significance based on a chi-square distribution.
</para>
</sect2>
<sect2 label="15.11.4" id="FRIEDMAN">
<title>Friedman Test</title>
<indexterm role="vr"><primary>FRIEDMAN</primary></indexterm>
<indexterm role="cp"><primary>Friedman test</primary></indexterm>

<literallayout>     [ /FRIEDMAN = <replaceable>var_list</replaceable> ]
</literallayout>
<para>The Friedman test is used to test for differences between repeated measures when
there is no indication that the distributions are normally distributed.
</para>
<para>A list of variables which contain the measured data must be given.  The procedure
prints the sum of ranks for each variable, the test statistic and its significance.
</para>
</sect2>
<sect2 label="15.11.5" id="KENDALL">
<title>Kendall&#8217;s W Test</title>
<indexterm role="vr"><primary>KENDALL</primary></indexterm>
<indexterm role="cp"><primary>Kendall&#8217;s W test</primary></indexterm>
<indexterm role="cp"><primary>coefficient of concordance</primary></indexterm>

<literallayout>     [ /KENDALL = <replaceable>var_list</replaceable> ]
</literallayout>
<para>The Kendall test investigates whether an arbitrary number of related samples come from the 
same population.
It is identical to the Friedman test except that the additional statistic W, Kendall&#8217;s Coefficient of Concordance is printed.
It has the range [0,1] &#8212; a value of zero indicates no agreement between the samples whereas a value of
unity indicates complete agreement.
</para>

</sect2>
<sect2 label="15.11.6" id="KOLMOGOROV_002dSMIRNOV">
<title>Kolmogorov-Smirnov Test</title>
<indexterm role="vr"><primary>KOLMOGOROV-SMIRNOV</primary></indexterm>
<indexterm role="vr"><primary>K-S</primary></indexterm>
<indexterm role="cp"><primary>Kolmogorov-Smirnov test</primary></indexterm>

<literallayout>     [ /KOLMOGOROV-SMIRNOV ({NORMAL [<replaceable>mu</replaceable>, <replaceable>sigma</replaceable>], UNIFORM [<replaceable>min</replaceable>, <replaceable>max</replaceable>], POISSON [<replaceable>lambda</replaceable>], EXPONENTIAL [<replaceable>scale</replaceable>] }) = <replaceable>var_list</replaceable> ]
</literallayout>
<para>The one sample Kolmogorov-Smirnov subcommand is used to test whether or not a dataset is
drawn from a particular distribution.  Four distributions are supported, <emphasis>viz:</emphasis>
Normal, Uniform, Poisson and Exponential.
</para>
<para>Ideally you should provide the parameters of the distribution against which you wish to test
the data. For example, with the normal distribution  the mean (<replaceable>mu</replaceable>)and standard deviation (<replaceable>sigma</replaceable>)
should be given; with the uniform distribution, the minimum (<replaceable>min</replaceable>)and maximum (<replaceable>max</replaceable>) value should
be provided.
However, if the parameters are omitted they will be imputed from the data. Imputing the
parameters reduces the power of the test so should be avoided if possible.
</para>
<para>In the following example, two variables <replaceable>score</replaceable> and <replaceable>age</replaceable> are tested to see if
they follow a normal distribution with a mean of 3.5 and a standard deviation of 2.0.
</para><screen>  NPAR TESTS
        /KOLMOGOROV-SMIRNOV (normal 3.5 2.0) = <replaceable>score</replaceable> <replaceable>age</replaceable>.
</screen><para>If the variables need to be tested against different distributions, then a separate
subcommand must be used.  For example the following syntax tests <replaceable>score</replaceable> against
a normal distribution with mean of 3.5 and standard deviation of 2.0 whilst <replaceable>age</replaceable>
is tested against a normal distribution of mean 40 and standard deviation 1.5.
</para><screen>  NPAR TESTS
        /KOLMOGOROV-SMIRNOV (normal 3.5 2.0) = <replaceable>score</replaceable>
        /KOLMOGOROV-SMIRNOV (normal 40 1.5) =  <replaceable>age</replaceable>.
</screen>
<para>The abbreviated subcommand  <literal>K-S</literal> may be used in place of <literal>KOLMOGOROV-SMIRNOV</literal>.
</para>
</sect2>
<sect2 label="15.11.7" id="KRUSKAL_002dWALLIS">
<title>Kruskal-Wallis Test</title>
<indexterm role="vr"><primary>KRUSKAL-WALLIS</primary></indexterm>
<indexterm role="vr"><primary>K-W</primary></indexterm>
<indexterm role="cp"><primary>Kruskal-Wallis test</primary></indexterm>

<literallayout>     [ /KRUSKAL-WALLIS = <replaceable>var_list</replaceable> BY var (<replaceable>lower</replaceable>, <replaceable>upper</replaceable>) ]
</literallayout>
<para>The Kruskal-Wallis test is used to compare data from an 
arbitrary number of populations.  It does not assume normality.
The data to be compared are specified by <replaceable>var_list</replaceable>.
The categorical variable determining the groups to which the
data belongs is given by <replaceable>var</replaceable>. The limits <replaceable>lower</replaceable> and
<replaceable>upper</replaceable> specify the valid range of <replaceable>var</replaceable>. Any cases for
which <replaceable>var</replaceable> falls outside [<replaceable>lower</replaceable>, <replaceable>upper</replaceable>] will be
ignored.
</para>
<para>The mean rank of each group as well as the chi-squared value and significance
of the test will be printed.
The abbreviated subcommand  <literal>K-W</literal> may be used in place of <literal>KRUSKAL-WALLIS</literal>.
</para>

</sect2>
<sect2 label="15.11.8" id="MANN_002dWHITNEY">
<title>Mann-Whitney U Test</title>
<indexterm role="vr"><primary>MANN-WHITNEY</primary></indexterm>
<indexterm role="vr"><primary>M-W</primary></indexterm>
<indexterm role="cp"><primary>Mann-Whitney U test</primary></indexterm>
<indexterm role="cp"><primary>U, Mann-Whitney U</primary></indexterm>

<literallayout>     [ /MANN-WHITNEY = <replaceable>var_list</replaceable> BY var (<replaceable>group1</replaceable>, <replaceable>group2</replaceable>) ]
</literallayout>
<para>The Mann-Whitney subcommand is used to test whether two groups of data come from different populations.
The variables to be tested should be specified in <replaceable>var_list</replaceable> and the grouping variable, that determines to which group the test variables belong, in <replaceable>var</replaceable>.
<replaceable>Var</replaceable> may be either a string or an alpha variable.
<replaceable>Group1</replaceable> and <replaceable>group2</replaceable> specify the
two values of <replaceable>var</replaceable> which determine the groups of the test data.
Cases for which the <replaceable>var</replaceable> value is neither <replaceable>group1</replaceable> or <replaceable>group2</replaceable> will be ignored.
</para>
<para>The value of the Mann-Whitney U statistic, the Wilcoxon W, and the significance will be printed.
The abbreviated subcommand  <literal>M-W</literal> may be used in place of <literal>MANN-WHITNEY</literal>.
</para>
</sect2>
<sect2 label="15.11.9" id="MCNEMAR">
<title>McNemar Test</title>
<indexterm role="vr"><primary>MCNEMAR</primary></indexterm>
<indexterm role="cp"><primary>McNemar test</primary></indexterm>

<literallayout>     [ /MCNEMAR <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> [ (PAIRED) ]]]
</literallayout>
<para>Use McNemar&#8217;s test to analyse the significance of the difference between
pairs of correlated proportions.
</para>
<para>If the <literal>WITH</literal> keyword is omitted, then tests for all
combinations of the listed variables are performed.
If the <literal>WITH</literal> keyword is given, and the <literal>(PAIRED)</literal> keyword
is also given, then the number of variables preceding <literal>WITH</literal>
must be the same as the number following it.
In this case, tests for each respective pair of variables are
performed.
If the <literal>WITH</literal> keyword is given, but the
<literal>(PAIRED)</literal> keyword is omitted, then tests for each combination
of variable preceding <literal>WITH</literal> against variable following
<literal>WITH</literal> are performed.
</para>
<para>The data in each variable must be dichotomous.  If there are more
than two distinct variables an error will occur and the test will
not be run.
</para>
</sect2>
<sect2 label="15.11.10" id="MEDIAN">
<title>Median Test</title>
<indexterm role="vr"><primary>MEDIAN</primary></indexterm>
<indexterm role="cp"><primary>Median test</primary></indexterm>

<literallayout>     [ /MEDIAN [(<replaceable>value</replaceable>)] = <replaceable>var_list</replaceable> BY <replaceable>variable</replaceable> (<replaceable>value1</replaceable>, <replaceable>value2</replaceable>) ]
</literallayout>
<para>The median test is used to test whether independent samples come from 
populations with a common median.
The median of the populations against which the samples are to be tested
may be given in parentheses immediately after the 
<literal>/MEDIAN</literal> subcommand.  If it is not given, the median will be imputed from the 
union of all the samples.
</para>
<para>The variables of the samples to be tested should immediately follow the &#8216;<literal>=</literal>&#8217; sign. The
keyword <literal>BY</literal> must come next, and then the grouping variable.  Two values
in parentheses should follow.  If the first value is greater than the second,
then a 2 sample test is performed using these two values to determine the groups.
If however, the first variable is less than the second, then a <emphasis>k</emphasis> sample test is
conducted and the group values used are all values encountered which lie in the
range [<replaceable>value1</replaceable>,<replaceable>value2</replaceable>].
</para>

</sect2>
<sect2 label="15.11.11" id="RUNS">
<title>Runs Test</title>
<indexterm role="vr"><primary>RUNS</primary></indexterm>
<indexterm role="cp"><primary>runs test</primary></indexterm>

<literallayout>     [ /RUNS ({MEAN, MEDIAN, MODE, <replaceable>value</replaceable>})  = <replaceable>var_list</replaceable> ]
</literallayout>
<para>The <literal>/RUNS</literal> subcommand tests whether a data sequence is randomly ordered.
</para>
<para>It works by examining the number of times a variable&#8217;s value crosses a given threshold. 
The desired threshold must be specified within parentheses.
It may either be specified as a number or as one of <literal>MEAN</literal>, <literal>MEDIAN</literal> or <literal>MODE</literal>.
Following the threshold specification comes the list of variables whose values are to be
tested.
</para>
<para>The subcommand shows the number of runs, the asymptotic significance based on the
length of the data.
</para>
</sect2>
<sect2 label="15.11.12" id="SIGN">
<title>Sign Test</title>
<indexterm role="vr"><primary>SIGN</primary></indexterm>
<indexterm role="cp"><primary>sign test</primary></indexterm>

<literallayout>     [ /SIGN <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> [ (PAIRED) ]]]
</literallayout>
<para>The <literal>/SIGN</literal> subcommand tests for differences between medians of the 
variables listed.
The test does not make any assumptions about the
distribution of the data.
</para>
<para>If the <literal>WITH</literal> keyword is omitted, then tests for all
combinations of the listed variables are performed.
If the <literal>WITH</literal> keyword is given, and the <literal>(PAIRED)</literal> keyword
is also given, then the number of variables preceding <literal>WITH</literal>
must be the same as the number following it.
In this case, tests for each respective pair of variables are
performed.
If the <literal>WITH</literal> keyword is given, but the
<literal>(PAIRED)</literal> keyword is omitted, then tests for each combination
of variable preceding <literal>WITH</literal> against variable following
<literal>WITH</literal> are performed.
</para>
</sect2>
<sect2 label="15.11.13" id="WILCOXON">
<title>Wilcoxon Matched Pairs Signed Ranks Test</title>
<indexterm role="vr"><primary>WILCOXON</primary></indexterm>
<indexterm role="cp"><primary>wilcoxon matched pairs signed ranks test</primary></indexterm>

<literallayout>     [ /WILCOXON <replaceable>var_list</replaceable> [ WITH <replaceable>var_list</replaceable> [ (PAIRED) ]]]
</literallayout>
<para>The <literal>/WILCOXON</literal> subcommand tests for differences between medians of the 
variables listed.
The test does not make any assumptions about the variances of the samples.
It does however assume that the distribution is symmetrical.
</para>
<para>If the <literal>WITH</literal> keyword is omitted, then tests for all
combinations of the listed variables are performed.
If the <literal>WITH</literal> keyword is given, and the <literal>(PAIRED)</literal> keyword
is also given, then the number of variables preceding <literal>WITH</literal>
must be the same as the number following it.
In this case, tests for each respective pair of variables are
performed.
If the <literal>WITH</literal> keyword is given, but the
<literal>(PAIRED)</literal> keyword is omitted, then tests for each combination
of variable preceding <literal>WITH</literal> against variable following
<literal>WITH</literal> are performed.
</para>
</sect2>
</sect1>
<sect1 label="15.12" id="T_002dTEST">
<title>T-TEST</title>

<indexterm role="vr"><primary>T-TEST</primary></indexterm>

<literallayout>T-TEST
        /MISSING={ANALYSIS,LISTWISE} {EXCLUDE,INCLUDE}
        /CRITERIA=CI(<replaceable>confidence</replaceable>)


(One Sample mode.)
        TESTVAL=<replaceable>test_value</replaceable>
        /VARIABLES=<replaceable>var_list</replaceable>


(Independent Samples mode.)
        GROUPS=var(<replaceable>value1</replaceable> [, <replaceable>value2</replaceable>])
        /VARIABLES=<replaceable>var_list</replaceable>


(Paired Samples mode.)
        PAIRS=<replaceable>var_list</replaceable> [WITH <replaceable>var_list</replaceable> [(PAIRED)] ]

</literallayout>

<para>The <literal>T-TEST</literal> procedure outputs tables used in testing hypotheses about 
means.  
It operates in one of three modes:
</para><itemizedlist><listitem><para>One Sample mode.
</para></listitem><listitem><para>Independent Groups mode.
</para></listitem><listitem><para>Paired mode.
</para></listitem></itemizedlist>
<para>Each of these modes are described in more detail below.
There are two optional subcommands which are common to all modes.
</para>
<para>The <literal>/CRITERIA</literal> subcommand tells pspp the confidence interval used
in the tests.  The default value is 0.95.
</para>

<para>The <literal>MISSING</literal> subcommand determines the handling of missing
variables.  
If <literal>INCLUDE</literal> is set, then user-missing values are included in the
calculations, but system-missing values are not.
If <literal>EXCLUDE</literal> is set, which is the default, user-missing
values are excluded as well as system-missing values. 
This is the default.
</para>
<para>If <literal>LISTWISE</literal> is set, then the entire case is excluded from analysis
whenever any variable  specified in the <literal>/VARIABLES</literal>, <literal>/PAIRS</literal> or 
<literal>/GROUPS</literal> subcommands contains a missing value.   
If <literal>ANALYSIS</literal> is set, then missing values are excluded only in the analysis for
which they would be needed. This is the default.
</para>


<sect2 label="15.12.1" id="One-Sample-Mode">
<title>One Sample Mode</title>

<para>The <literal>TESTVAL</literal> subcommand invokes the One Sample mode.
This mode is used to test a population mean against a hypothesized
mean. 
The value given to the <literal>TESTVAL</literal> subcommand is the value against
which you wish to test.
In this mode, you must also use the <literal>/VARIABLES</literal> subcommand to
tell pspp which variables you wish to test.
</para>
</sect2>
<sect2 label="15.12.2" id="Independent-Samples-Mode">
<title>Independent Samples Mode</title>

<para>The <literal>GROUPS</literal> subcommand invokes Independent Samples mode or
&#8216;Groups&#8217; 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 <literal>/VARIABLES</literal> subcommand to
tell pspp the dependent variables you wish to test.
</para>
<para>The variable given in the <literal>GROUPS</literal> 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.
</para>
<para>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
greater than or equal to this value belong to the first group, and cases
less than this value belong to the second group.
When using this form of the <literal>GROUPS</literal> subcommand, missing values in
the independent variable are excluded on a listwise basis, regardless
of whether <literal>/MISSING=LISTWISE</literal> was specified.
</para>

</sect2>
<sect2 label="15.12.3" id="Paired-Samples-Mode">
<title>Paired Samples Mode</title>

<para>The <literal>PAIRS</literal> subcommand introduces Paired Samples mode.
Use this mode when repeated measures have been taken from the same
samples.
If the <literal>WITH</literal> keyword is omitted, then tables for all
combinations of variables given in the <literal>PAIRS</literal> subcommand are
generated. 
If the <literal>WITH</literal> keyword is given, and the <literal>(PAIRED)</literal> keyword
is also given, then the number of variables preceding <literal>WITH</literal>
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 <literal>WITH</literal> keyword is given, but the
<literal>(PAIRED)</literal> keyword is omitted, then tables for each combination
of variable preceding <literal>WITH</literal> against variable following
<literal>WITH</literal> are generated.
</para>

</sect2>
</sect1>
<sect1 label="15.13" id="ONEWAY">
<title>ONEWAY</title>

<indexterm role="vr"><primary>ONEWAY</primary></indexterm>
<indexterm role="cp"><primary>analysis of variance</primary></indexterm>
<indexterm role="cp"><primary>ANOVA</primary></indexterm>

<literallayout>ONEWAY
        [/VARIABLES = ] <replaceable>var_list</replaceable> BY <replaceable>var</replaceable>
        /MISSING={ANALYSIS,LISTWISE} {EXCLUDE,INCLUDE}
        /CONTRAST= <replaceable>value1</replaceable> [, <replaceable>value2</replaceable>] ... [,<replaceable>valueN</replaceable>]
        /STATISTICS={DESCRIPTIVES,HOMOGENEITY}
        /POSTHOC={BONFERRONI, GH, LSD, SCHEFFE, SIDAK, TUKEY, ALPHA ([<replaceable>value</replaceable>])}
</literallayout>
<para>The <literal>ONEWAY</literal> procedure performs a one-way analysis of variance of
variables factored by a single independent variable.
It is used to compare the means of a population
divided into more than two groups. 
</para>
<para>The dependent variables to be analysed should be given in the <literal>VARIABLES</literal>
subcommand.  
The list of variables must be followed by the <literal>BY</literal> keyword and
the name of the independent (or factor) variable.
</para>
<para>You can use the <literal>STATISTICS</literal> subcommand to tell pspp to display
ancillary information.  The options accepted are:
</para><itemizedlist><listitem><para>DESCRIPTIVES
Displays descriptive statistics about the groups factored by the independent
variable.
</para></listitem><listitem><para>HOMOGENEITY
Displays the Levene test of Homogeneity of Variance for the
variables and their groups.
</para></listitem></itemizedlist>
<para>The <literal>CONTRAST</literal> subcommand is used when you anticipate certain
differences between the groups.
The subcommand must be followed by a list of numerals which are the
coefficients of the groups to be tested.
The number of coefficients must correspond to the number of distinct
groups (or values of the independent variable).
If the total sum of the coefficients are not zero, then pspp will
display a warning, but will proceed with the analysis.
The <literal>CONTRAST</literal> subcommand may be given up to 10 times in order
to specify different contrast tests.
The <literal>MISSING</literal> subcommand defines how missing values are handled.
If <literal>LISTWISE</literal> is specified then cases which have missing values for 
the independent variable or any dependent variable will be ignored.
If <literal>ANALYSIS</literal> is specified, then cases will be ignored if the independent
variable is missing or if the dependent variable currently being 
analysed is missing.  The default is <literal>ANALYSIS</literal>.
A setting of <literal>EXCLUDE</literal> means that variables whose values are
user-missing are to be excluded from the analysis. A setting of
<literal>INCLUDE</literal> means they are to be included.  The default is <literal>EXCLUDE</literal>.
</para>
<para>Using the <literal>POSTHOC</literal> subcommand you can perform multiple
pairwise comparisons on the data. The following comparison methods
are available:
</para><itemizedlist><listitem><para><literal>LSD</literal>
Least Significant Difference.
</para></listitem><listitem><para><literal>TUKEY</literal>
Tukey Honestly Significant Difference.
</para></listitem><listitem><para><literal>BONFERRONI</literal>
Bonferroni test.
</para></listitem><listitem><para><literal>SCHEFFE</literal>
Scheff&#233;&#8217;s test.
</para></listitem><listitem><para><literal>SIDAK</literal>
Sidak test.
</para></listitem><listitem><para><literal>GH</literal>
The Games-Howell test.
</para></listitem></itemizedlist>
<para>The optional syntax <literal>ALPHA(<replaceable>value</replaceable>)</literal> is used to indicate
that <replaceable>value</replaceable> should be used as the
confidence level for which the posthoc tests will be performed.
The default is 0.05.
</para>
</sect1>
<sect1 label="15.14" id="QUICK-CLUSTER">
<title>QUICK CLUSTER</title>
<indexterm role="vr"><primary>QUICK CLUSTER</primary></indexterm>

<indexterm role="cp"><primary>K-means clustering</primary></indexterm>
<indexterm role="cp"><primary>clustering</primary></indexterm>

<literallayout>QUICK CLUSTER <replaceable>var_list</replaceable>
      [/CRITERIA=CLUSTERS(<replaceable>k</replaceable>) [MXITER(<replaceable>max_iter</replaceable>)] CONVERGE(<replaceable>epsilon</replaceable>) [NOINITIAL]]
      [/MISSING={EXCLUDE,INCLUDE} {LISTWISE, PAIRWISE}]
      [/PRINT={INITIAL} {CLUSTER}]
</literallayout>
<para>The <literal>QUICK CLUSTER</literal> command performs k-means clustering on the
dataset.  This is useful when you wish to allocate cases into clusters
of similar values and you already know the number of clusters.
</para>
<para>The minimum specification is &#8216;<literal>QUICK CLUSTER</literal>&#8217; followed by the names
of the variables which contain the cluster data.  Normally you will also
want to specify <literal>/CRITERIA=CLUSTERS(<replaceable>k</replaceable>)</literal> where <replaceable>k</replaceable> is the
number of clusters.  If this is not specified, then <replaceable>k</replaceable> defaults to 2.
</para>
<para>If you use <literal>/CRITERIA=NOINITIAL</literal> then a naive algorithm to select
the initial clusters is used.   This will provide for faster execution but
less well separated initial clusters and hence possibly an inferior final
result.
</para>

<para><literal>QUICK CLUSTER</literal> uses an iterative algorithm to select the clusters centers.
The subcommand  <literal>/CRITERIA=MXITER(<replaceable>max_iter</replaceable>)</literal> sets the maximum number of iterations.
During classification, pspp will continue iterating until until <replaceable>max_iter</replaceable>
iterations have been done or the convergence criterion (see below) is fulfilled.
The default value of <replaceable>max_iter</replaceable> is 2.
</para>
<para>If however, you specify <literal>/CRITERIA=NOUPDATE</literal> then after selecting the initial centers,
no further update to the cluster centers is done.  In this case, <replaceable>max_iter</replaceable>, if specified.
is ignored.
</para>
<para>The subcommand  <literal>/CRITERIA=CONVERGE(<replaceable>epsilon</replaceable>)</literal> is used
to set the convergence criterion.  The value of convergence criterion is  <replaceable>epsilon</replaceable>
times the minimum distance between the <emphasis>initial</emphasis> cluster centers.  Iteration stops when
the  mean cluster distance between  one iteration and the next  
is less than the convergence criterion.  The default value of <replaceable>epsilon</replaceable> is zero.
</para>
<para>The <literal>MISSING</literal> subcommand determines the handling of missing variables.  
If <literal>INCLUDE</literal> is set, then user-missing values are considered at their face
value and not as missing values.
If <literal>EXCLUDE</literal> is set, which is the default, user-missing
values are excluded as well as system-missing values. 
</para>
<para>If <literal>LISTWISE</literal> is set, then the entire case is excluded from the analysis
whenever any of the clustering variables contains a missing value.   
If <literal>PAIRWISE</literal> is set, then a case is considered missing only if all the
clustering variables contain missing values.  Otherwise it is clustered
on the basis of the non-missing values.
The default is <literal>LISTWISE</literal>.
</para>
<para>The <literal>PRINT</literal> subcommand requests additional output to be printed.
If <literal>INITIAL</literal> is set, then the initial cluster memberships will
be printed.
If <literal>CLUSTER</literal> is set, the cluster memberships of the individual
cases will be displayed (potentially generating lengthy output).
</para>

</sect1>
<sect1 label="15.15" id="RANK">
<title>RANK</title>

<indexterm role="vr"><primary>RANK</primary></indexterm>
<literallayout>RANK
        [VARIABLES=] <replaceable>var_list</replaceable> [{A,D}] [BY <replaceable>var_list</replaceable>]
        /TIES={MEAN,LOW,HIGH,CONDENSE}
        /FRACTION={BLOM,TUKEY,VW,RANKIT}
        /PRINT[={YES,NO}
        /MISSING={EXCLUDE,INCLUDE}

        /RANK [INTO <replaceable>var_list</replaceable>]
        /NTILES(k) [INTO <replaceable>var_list</replaceable>]
        /NORMAL [INTO <replaceable>var_list</replaceable>]
        /PERCENT [INTO <replaceable>var_list</replaceable>]
        /RFRACTION [INTO <replaceable>var_list</replaceable>]
        /PROPORTION [INTO <replaceable>var_list</replaceable>]
        /N [INTO <replaceable>var_list</replaceable>]
        /SAVAGE [INTO <replaceable>var_list</replaceable>]
</literallayout>
<para>The <literal>RANK</literal> command ranks variables and stores the results into new
variables. 
</para>
<para>The <literal>VARIABLES</literal> subcommand, which is mandatory, specifies one or
more variables whose values are to be ranked.  
After each variable, &#8216;<literal>A</literal>&#8217; or &#8216;<literal>D</literal>&#8217; may appear, indicating that
the variable is to be ranked in ascending or descending order.
Ascending is the default.
If a <literal>BY</literal> keyword appears, it should be followed by a list of variables
which are to serve as group variables.  
In this case, the cases are gathered into groups, and ranks calculated
for each group.
</para>
<para>The <literal>TIES</literal> subcommand specifies how tied values are to be treated.  The
default is to take the mean value of all the tied cases.
</para>
<para>The <literal>FRACTION</literal> subcommand specifies how proportional ranks are to be
calculated.  This only has any effect if <literal>NORMAL</literal> or <literal>PROPORTIONAL</literal> rank
functions are requested.
</para>
<para>The <literal>PRINT</literal> subcommand may be used to specify that a summary of the rank
variables created should appear in the output.
</para>
<para>The function subcommands are <literal>RANK</literal>, <literal>NTILES</literal>, <literal>NORMAL</literal>, <literal>PERCENT</literal>, <literal>RFRACTION</literal>,
<literal>PROPORTION</literal> and <literal>SAVAGE</literal>.  Any number of function subcommands may appear.
If none are given, then the default is RANK.
The <literal>NTILES</literal> subcommand must take an integer specifying the number of
partitions into which values should be ranked.
Each subcommand may be followed by the <literal>INTO</literal> keyword and a list of
variables which are the variables to be created and receive the rank
scores.  There may be as many variables specified as there are
variables named on the <literal>VARIABLES</literal> subcommand.  If fewer are specified,
then the variable names are automatically created.
</para>
<para>The <literal>MISSING</literal> subcommand determines how user missing values are to be
treated. A setting of <literal>EXCLUDE</literal> means that variables whose values are
user-missing are to be excluded from the rank scores. A setting of
<literal>INCLUDE</literal> means they are to be included.  The default is <literal>EXCLUDE</literal>.
</para>
</sect1>
<sect1 label="15.16" id="REGRESSION">
<title>REGRESSION</title>

<indexterm role="cp"><primary>regression</primary></indexterm>
<indexterm role="cp"><primary>linear regression</primary></indexterm>
<para>The <literal>REGRESSION</literal> procedure fits linear models to data via least-squares
estimation. The procedure is appropriate for data which satisfy those
assumptions typical in linear regression:
</para>
<itemizedlist><listitem><para>The data set contains <inlineequation><mathphrase>n</mathphrase></inlineequation> observations of a dependent variable, say
<inlineequation><mathphrase>Y_1,&#8230;,Y_n</mathphrase></inlineequation>, and <inlineequation><mathphrase>n</mathphrase></inlineequation> observations of one or more explanatory
variables.
Let <inlineequation><mathphrase>X_{11}, X_{12}</mathphrase></inlineequation>, &#8230;, <inlineequation><mathphrase>X_{1n}</mathphrase></inlineequation> denote the <inlineequation><mathphrase>n</mathphrase></inlineequation> observations
of the first explanatory variable;
<inlineequation><mathphrase>X_{21}</mathphrase></inlineequation>,&#8230;,<inlineequation><mathphrase>X_{2n}</mathphrase></inlineequation> denote the <inlineequation><mathphrase>n</mathphrase></inlineequation> observations of the second
explanatory variable;
<inlineequation><mathphrase>X_{k1}</mathphrase></inlineequation>,&#8230;,<inlineequation><mathphrase>X_{kn}</mathphrase></inlineequation> denote the <inlineequation><mathphrase>n</mathphrase></inlineequation> observations of 
the <inlineequation><mathphrase>k</mathphrase></inlineequation>th explanatory variable.
</para>
</listitem><listitem><para>The dependent variable <inlineequation><mathphrase>Y</mathphrase></inlineequation> has the following relationship to the 
explanatory variables:
<inlineequation><mathphrase>Y_i = b_0 + b_1 X_{1i} + ... + b_k X_{ki} + Z_i</mathphrase></inlineequation>
where <inlineequation><mathphrase>b_0, b_1, &#8230;, b_k</mathphrase></inlineequation> are unknown
coefficients, and <inlineequation><mathphrase>Z_1,&#8230;,Z_n</mathphrase></inlineequation> are independent, normally
distributed <firstterm>noise</firstterm> terms with mean zero and common variance.
The noise, or <firstterm>error</firstterm> terms are unobserved.
This relationship is called the <firstterm>linear model</firstterm>.
</para></listitem></itemizedlist>
<para>The <literal>REGRESSION</literal> procedure estimates the coefficients
<inlineequation><mathphrase>b_0,&#8230;,b_k</mathphrase></inlineequation> and produces output relevant to inferences for the
linear model. 
</para>

<sect2 label="15.16.1" id="Syntax">
<title>Syntax</title>

<indexterm role="vr"><primary>REGRESSION</primary></indexterm>
<literallayout>REGRESSION
        /VARIABLES=<replaceable>var_list</replaceable>
        /DEPENDENT=<replaceable>var_list</replaceable>
        /STATISTICS={ALL, DEFAULTS, R, COEFF, ANOVA, BCOV, CI[<replaceable>conf</replaceable>]}
        /SAVE={PRED, RESID}
</literallayout>
<para>The <literal>REGRESSION</literal> procedure reads the active dataset and outputs
statistics relevant to the linear model specified by the user.
</para>
<para>The <literal>VARIABLES</literal> subcommand, which is required, specifies the list of
variables to be analyzed.  Keyword <literal>VARIABLES</literal> is required. The
<literal>DEPENDENT</literal> subcommand specifies the dependent variable of the linear
model. The <literal>DEPENDENT</literal> subcommand is required. All variables listed in
the <literal>VARIABLES</literal> subcommand, but not listed in the <literal>DEPENDENT</literal> subcommand,
are treated as explanatory variables in the linear model.
</para>
<para>All other subcommands are optional:
</para>
<para>The <literal>STATISTICS</literal> subcommand specifies which statistics are to be displayed.
The following keywords are accepted:
</para>
<variablelist><varlistentry><term><literal>ALL</literal>
</term><listitem><para>All of the statistics below.
</para></listitem></varlistentry><varlistentry><term><literal>R</literal>
</term><listitem><para>The ratio of the sums of squares due to the model to the total sums of
squares for the dependent variable.
</para></listitem></varlistentry><varlistentry><term><literal>COEFF</literal>
</term><listitem><para>A table containing the estimated model coefficients and their standard errors.
</para></listitem></varlistentry><varlistentry><term><literal>CI (<replaceable>conf</replaceable>)</literal>
</term><listitem><para>This item is only relevant if COEFF has also been selected.  It specifies that the
confidence interval for the coefficients should be printed.  The optional value <replaceable>conf</replaceable>,
which must be in parentheses, is the desired confidence level expressed as a percentage.
</para></listitem></varlistentry><varlistentry><term><literal>ANOVA</literal>
</term><listitem><para>Analysis of variance table for the model.
</para></listitem></varlistentry><varlistentry><term><literal>BCOV</literal>
</term><listitem><para>The covariance matrix for the estimated model coefficients.
</para></listitem></varlistentry><varlistentry><term><literal>DEFAULT</literal>
</term><listitem><para>The same as if R, COEFF, and ANOVA had been selected.
This is what you get if the /STATISTICS command is not specified,
or if it is specified without any parameters.
</para></listitem></varlistentry></variablelist>
<para>The <literal>SAVE</literal> subcommand causes pspp to save the residuals or predicted
values from the fitted
model to the active dataset. pspp will store the residuals in a variable
called &#8216;<literal>RES1</literal>&#8217; if no such variable exists, &#8216;<literal>RES2</literal>&#8217; if &#8216;<literal>RES1</literal>&#8217; 
already exists,
&#8216;<literal>RES3</literal>&#8217; if &#8216;<literal>RES1</literal>&#8217; and &#8216;<literal>RES2</literal>&#8217; already exist, etc. It will
choose the name of
the variable for the predicted values similarly, but with &#8216;<literal>PRED</literal>&#8217; as a
prefix.
When <literal>SAVE</literal> is used, pspp ignores <literal>TEMPORARY</literal>, treating
temporary transformations as permanent.
</para>
</sect2>
<sect2 label="15.16.2" id="Examples">
<title>Examples</title>
<para>The following pspp syntax will generate the default output and save the
predicted values and residuals to the active dataset.
</para>
<screen>title 'Demonstrate REGRESSION procedure'.
data list / v0 1-2 (A) v1 v2 3-22 (10).
begin data.
b  7.735648 -23.97588
b  6.142625 -19.63854
a  7.651430 -25.26557
c  6.125125 -16.57090
a  8.245789 -25.80001
c  6.031540 -17.56743
a  9.832291 -28.35977
c  5.343832 -16.79548
a  8.838262 -29.25689
b  6.200189 -18.58219
end data.
list.
regression /variables=v0 v1 v2 /statistics defaults /dependent=v2 
           /save pred resid /method=enter.
</screen>

</sect2>
</sect1>
<sect1 label="15.17" id="RELIABILITY">
<title>RELIABILITY</title>

<indexterm role="vr"><primary>RELIABILITY</primary></indexterm>
<literallayout>RELIABILITY
        /VARIABLES=<replaceable>var_list</replaceable>
        /SCALE (<replaceable>name</replaceable>) = {<replaceable>var_list</replaceable>, ALL}
        /MODEL={ALPHA, SPLIT[(<replaceable>n</replaceable>)]}
        /SUMMARY={TOTAL,ALL}
        /MISSING={EXCLUDE,INCLUDE}
</literallayout>
<indexterm role="cp"><primary>Cronbach&#8217;s Alpha</primary></indexterm>
<para>The <literal>RELIABILITY</literal> command performs reliability analysis on the data.
</para>
<para>The <literal>VARIABLES</literal> subcommand is required. It determines the set of variables 
upon which analysis is to be performed.
</para>
<para>The <literal>SCALE</literal> subcommand determines which variables reliability is to be 
calculated for.  If it is omitted, then analysis for all variables named
in the <literal>VARIABLES</literal> subcommand will be used.
Optionally, the <replaceable>name</replaceable> parameter may be specified to set a string name 
for the scale.
</para>
<para>The <literal>MODEL</literal> subcommand determines the type of analysis. If <literal>ALPHA</literal> is specified, 
then Cronbach&#8217;s Alpha is calculated for the scale.  If the model is <literal>SPLIT</literal>, 
then the variables  are divided into 2 subsets.  An optional parameter 
<replaceable>n</replaceable> may be given, to specify how many variables to be in the first subset.
If <replaceable>n</replaceable> is omitted, then it defaults to one half of the variables in the 
scale, or one half minus one if there are an odd number of variables.
The default model is <literal>ALPHA</literal>.
</para>
<para>By default, any cases with user missing, or system missing values for 
any variables given 
in the <literal>VARIABLES</literal> subcommand will be omitted from analysis.
The <literal>MISSING</literal> subcommand determines whether user missing values are to 
be included or excluded in the analysis.
</para>
<para>The <literal>SUMMARY</literal> subcommand determines the type of summary analysis to be performed.
Currently there is only one type: <literal>SUMMARY=TOTAL</literal>, which displays per-item
analysis tested against the totals.
</para>


</sect1>
<sect1 label="15.18" id="ROC">
<title>ROC</title>

<indexterm role="vr"><primary>ROC</primary></indexterm>
<indexterm role="cp"><primary>Receiver Operating Characteristic</primary></indexterm>
<indexterm role="cp"><primary>Area under curve</primary></indexterm>

<literallayout>ROC     <replaceable>var_list</replaceable> BY <replaceable>state_var</replaceable> (<replaceable>state_value</replaceable>)
        /PLOT = { CURVE [(REFERENCE)], NONE }
        /PRINT = [ SE ] [ COORDINATES ]
        /CRITERIA = [ CUTOFF({INCLUDE,EXCLUDE}) ]
          [ TESTPOS ({LARGE,SMALL}) ]
          [ CI (<replaceable>confidence</replaceable>) ]
          [ DISTRIBUTION ({FREE, NEGEXPO }) ]
        /MISSING={EXCLUDE,INCLUDE}
</literallayout>

<para>The <literal>ROC</literal> command is used to plot the receiver operating characteristic curve 
of a dataset, and to estimate the area under the curve.
This is useful for analysing the efficacy of a variable as a predictor of a state of nature.
</para>
<para>The mandatory <replaceable>var_list</replaceable> is the list of predictor variables.
The variable <replaceable>state_var</replaceable> is the variable whose values represent the actual states, 
and <replaceable>state_value</replaceable> is the value of this variable which represents the positive state.
</para>
<para>The optional subcommand <literal>PLOT</literal> is used to determine if and how the <literal>ROC</literal> curve is drawn.
The keyword <literal>CURVE</literal> means that the <literal>ROC</literal> curve should be drawn, and the optional keyword <literal>REFERENCE</literal>,
which should be enclosed in parentheses, says that the diagonal reference line should be drawn.
If the keyword <literal>NONE</literal> is given, then no <literal>ROC</literal> curve is drawn.
By default, the curve is drawn with no reference line.
</para>
<para>The optional subcommand <literal>PRINT</literal> determines which additional tables should be printed.
Two additional tables are available. 
The <literal>SE</literal> keyword says that standard error of the area under the curve should be printed as well as
the area itself.
In addition, a p-value under the null hypothesis that the area under the curve equals 0.5 will be
printed.
The <literal>COORDINATES</literal> keyword says that a table of coordinates of the <literal>ROC</literal> curve should be printed.
</para>
<para>The <literal>CRITERIA</literal> subcommand has four optional parameters:
</para><itemizedlist><listitem><para>The <literal>TESTPOS</literal> parameter may be <literal>LARGE</literal> or <literal>SMALL</literal>.
<literal>LARGE</literal> is the default, and says that larger values in the predictor variables are to be 
considered positive.  <literal>SMALL</literal> indicates that smaller values should be considered positive.
</para>
</listitem><listitem><para>The <literal>CI</literal> parameter specifies the confidence interval that should be printed.
It has no effect if the <literal>SE</literal> keyword in the <literal>PRINT</literal> subcommand has not been given.
</para>
</listitem><listitem><para>The <literal>DISTRIBUTION</literal> parameter determines the method to be used when estimating the area
under the curve.  
There are two possibilities, <emphasis>viz</emphasis>: <literal>FREE</literal> and <literal>NEGEXPO</literal>.
The <literal>FREE</literal> method uses a non-parametric estimate, and the <literal>NEGEXPO</literal> method a bi-negative 
exponential distribution estimate.
The <literal>NEGEXPO</literal> method should only be used when the number of positive actual states is
equal to the number of negative actual states.
The default is <literal>FREE</literal>.
</para>
</listitem><listitem><para>The <literal>CUTOFF</literal> parameter is for compatibility and is ignored.
</para></listitem></itemizedlist>
<para>The <literal>MISSING</literal> subcommand determines whether user missing values are to 
be included or excluded in the analysis.  The default behaviour is to
exclude them.
Cases are excluded on a listwise basis; if any of the variables in <replaceable>var_list</replaceable> 
or if the variable <replaceable>state_var</replaceable> is missing, then the entire case will be 
excluded.
</para>
<!--  LocalWords:  subcmd subcommand -->
</sect1>
</chapter>
<chapter label="16" id="Utilities">
<title>Utilities</title>

<para>Commands that don&#8217;t fit any other category are placed here.
</para>
<para>Most of these commands are not affected by commands like <literal>IF</literal> and
<literal>LOOP</literal>:
they take effect only once, unconditionally, at the time that they are
encountered in the input.
</para>

<sect1 label="16.1" id="ADD-DOCUMENT">
<title>ADD DOCUMENT</title>
<indexterm role="vr"><primary>ADD DOCUMENT</primary></indexterm>

<literallayout>ADD DOCUMENT 
    &#8217;line one&#8217; &#8217;line two&#8217; &#8230; &#8217;last line&#8217; .
</literallayout>

<para><literal>ADD DOCUMENT</literal> adds one or more lines of descriptive commentary to 
the active dataset.  Documents added in this way are saved to system files.
They can be viewed using <literal>SYSFILE INFO</literal> or <literal>DISPLAY
DOCUMENTS</literal>.  They can be removed from the active dataset with <literal>DROP
DOCUMENTS</literal>.
</para>
<para>Each line of documentary text must be enclosed in quotation marks, and 
may not be more than 80 bytes long. See <link linkend="DOCUMENT">DOCUMENT</link>.
</para>
</sect1>
<sect1 label="16.2" id="CACHE">
<title>CACHE</title>
<indexterm role="vr"><primary>CACHE</primary></indexterm>

<literallayout>CACHE.
</literallayout>
<para>This command is accepted, for compatibility, but it has no effect.
</para>
</sect1>
<sect1 label="16.3" id="CD">
<title>CD</title>
<indexterm role="vr"><primary>CD</primary></indexterm>
<indexterm role="cp"><primary>directory</primary></indexterm>
<indexterm role="cp"><primary>changing directory</primary></indexterm>

<literallayout>CD &#8217;new directory&#8217; .
</literallayout>
<para><literal>CD</literal> changes the current directory.  The new directory will become that specified by the command.
</para>
</sect1>
<sect1 label="16.4" id="COMMENT">
<title>COMMENT</title>
<indexterm role="vr"><primary>COMMENT</primary></indexterm>
<indexterm role="vr"><primary>*</primary></indexterm>

<literallayout>Two possibles syntaxes:
        COMMENT comment text &#8230; .
        *comment text &#8230; .
</literallayout>
<para><literal>COMMENT</literal> is ignored.  It is used to provide information to
the author and other readers of the pspp syntax file.  
</para>
<para><literal>COMMENT</literal> can extend over any number of lines.  Don&#8217;t forget to
terminate it with a dot or a blank line.
</para>


</sect1>
<sect1 label="16.5" id="DOCUMENT">
<title>DOCUMENT</title>
<indexterm role="vr"><primary>DOCUMENT</primary></indexterm>

<literallayout>DOCUMENT <replaceable>documentary_text</replaceable>.
</literallayout>
<para><literal>DOCUMENT</literal> adds one or more lines of descriptive commentary to the
active dataset.  Documents added in this way are saved to system files.
They can be viewed using <literal>SYSFILE INFO</literal> or <literal>DISPLAY
DOCUMENTS</literal>.  They can be removed from the active dataset with <literal>DROP
DOCUMENTS</literal>.
</para>
<para>Specify the <replaceable>documentary text</replaceable> following the <literal>DOCUMENT</literal> keyword.  
It is interpreted literally &#8212; any quotes or other punctuation marks 
will be included in the file.
You can extend the documentary text over as many lines as necessary.  
Lines are truncated at 80 bytes.  Don&#8217;t forget to terminate
the command with a dot or a blank line. See <link linkend="ADD-DOCUMENT">ADD DOCUMENT</link>.
</para>
</sect1>
<sect1 label="16.6" id="DISPLAY-DOCUMENTS">
<title>DISPLAY DOCUMENTS</title>
<indexterm role="vr"><primary>DISPLAY DOCUMENTS</primary></indexterm>

<literallayout>DISPLAY DOCUMENTS.
</literallayout>
<para><literal>DISPLAY DOCUMENTS</literal> displays the documents in the active dataset.  Each
document is preceded by a line giving the time and date that it was
added.  See <link linkend="DOCUMENT">DOCUMENT</link>.
</para>
</sect1>
<sect1 label="16.7" id="DISPLAY-FILE-LABEL">
<title>DISPLAY FILE LABEL</title>
<indexterm role="vr"><primary>DISPLAY FILE LABEL</primary></indexterm>

<literallayout>DISPLAY FILE LABEL.
</literallayout>
<para><literal>DISPLAY FILE LABEL</literal> displays the file label contained in the
active dataset,
if any.  See <link linkend="FILE-LABEL">FILE LABEL</link>.
</para>
<para>This command is a pspp extension.
</para>
</sect1>
<sect1 label="16.8" id="DROP-DOCUMENTS">
<title>DROP DOCUMENTS</title>
<indexterm role="vr"><primary>DROP DOCUMENTS</primary></indexterm>

<literallayout>DROP DOCUMENTS.
</literallayout>
<para><literal>DROP DOCUMENTS</literal> removes all documents from the active dataset.
New documents can be added with <literal>DOCUMENT</literal> (see <link linkend="DOCUMENT">DOCUMENT</link>).
</para>
<para><literal>DROP DOCUMENTS</literal> changes only the active dataset.  It does not modify any
system files stored on disk.
</para>
</sect1>
<sect1 label="16.9" id="ECHO">
<title>ECHO</title>
<indexterm role="vr"><primary>ECHO</primary></indexterm>

<literallayout>ECHO &#8217;arbitrary text&#8217; .
</literallayout>
<para>Use <literal>ECHO</literal> to write arbitrary text to the output stream. The text should be enclosed in quotation marks following the normal rules for string tokens (see <link linkend="Tokens">Tokens</link>).
</para>
</sect1>
<sect1 label="16.10" id="ERASE">
<title>ERASE</title>
<indexterm role="vr"><primary>ERASE</primary></indexterm>

<literallayout>ERASE FILE <replaceable>file_name</replaceable>.
</literallayout>
<para><literal>ERASE FILE</literal> deletes a file from the local filesystem.
<replaceable>file_name</replaceable> must be quoted.
This command cannot be used if the SAFER (see <link linkend="SET">SET</link>) setting is active.
</para>

</sect1>
<sect1 label="16.11" id="EXECUTE">
<title>EXECUTE</title>
<indexterm role="vr"><primary>EXECUTE</primary></indexterm>

<literallayout>EXECUTE.
</literallayout>
<para><literal>EXECUTE</literal> causes the active dataset to be read and all pending
transformations to be executed.
</para>
</sect1>
<sect1 label="16.12" id="FILE-LABEL">
<title>FILE LABEL</title>
<indexterm role="vr"><primary>FILE LABEL</primary></indexterm>

<literallayout>FILE LABEL <replaceable>file_label</replaceable>.
</literallayout>
<para><literal>FILE LABEL</literal> provides a title for the active dataset.  This
title will be saved into system files and portable files that are
created during this pspp run.
</para>
<para><replaceable>file_label</replaceable> should not be quoted.
If quotes are included, they are literally interpreted and become part of the file label.
</para>
</sect1>
<sect1 label="16.13" id="FINISH">
<title>FINISH</title>
<indexterm role="vr"><primary>FINISH</primary></indexterm>

<literallayout>FINISH.
</literallayout>
<para><literal>FINISH</literal> terminates the current pspp session and returns
control to the operating system.
</para>
</sect1>
<sect1 label="16.14" id="HOST">
<title>HOST</title>
<indexterm role="vr"><primary>HOST</primary></indexterm>

<literallayout>HOST.
HOST COMMAND=[&#8217;<replaceable>command</replaceable>&#8217;...].
</literallayout>
<para><literal>HOST</literal> suspends the current pspp session and temporarily returns control 
to the operating system.
This command cannot be used if the SAFER (see <link linkend="SET">SET</link>) setting is active.
</para>
<para>If the <literal>COMMAND</literal> subcommand is specified, as a sequence of shell
commands as quoted strings within square brackets, then pspp executes
them together in a single subshell.
</para>
<para>If no subcommands are specified, then pspp invokes an interactive
subshell.
</para>
</sect1>
<sect1 label="16.15" id="INCLUDE">
<title>INCLUDE</title>
<indexterm role="vr"><primary>INCLUDE</primary></indexterm>

<literallayout>        INCLUDE [FILE=]&#8217;<replaceable>file_name</replaceable>&#8217; [ENCODING=&#8217;<replaceable>encoding</replaceable>&#8217;].
</literallayout>
<para><literal>INCLUDE</literal> causes the pspp command processor to read an
additional command file as if it were included bodily in the current
command file.
If errors are encountered in the included file, then command processing will 
stop and no more commands will be processed.
Include files may be nested to any depth, up to the limit of available
memory.
</para>
<para>The <literal>INSERT</literal> command (see <link linkend="INSERT">INSERT</link>) is a more flexible
alternative to <literal>INCLUDE</literal>.  An <literal>INCLUDE</literal> command acts the same as
<literal>INSERT</literal> with <literal>ERROR=STOP CD=NO SYNTAX=BATCH</literal> specified.
</para>
<para>The optional <literal>ENCODING</literal> subcommand has the same meaning as with <literal>INSERT</literal>.
</para>
</sect1>
<sect1 label="16.16" id="INSERT">
<title>INSERT</title>
<indexterm role="vr"><primary>INSERT</primary></indexterm>

<literallayout>     INSERT [FILE=]&#8217;<replaceable>file_name</replaceable>&#8217;
        [CD={NO,YES}]
        [ERROR={CONTINUE,STOP}]
        [SYNTAX={BATCH,INTERACTIVE}]
        [ENCODING={LOCALE, &#8217;<replaceable>charset_name</replaceable>&#8217;}].
</literallayout>
<para><literal>INSERT</literal> is similar to <literal>INCLUDE</literal> (see <link linkend="INCLUDE">INCLUDE</link>) 
but somewhat more flexible.
It causes the command processor to read a file as if it were embedded in the 
current command file.
</para>
<para>If <literal>CD=YES</literal> is specified, then before including the file, the
current directory  will be changed to the directory of the included
file.  
The default setting is &#8216;<literal>CD=NO</literal>&#8217;.
Note that this directory will remain current until it is
changed explicitly (with the <literal>CD</literal> command, or a subsequent
<literal>INSERT</literal> command with the &#8216;<literal>CD=YES</literal>&#8217; option).
It will not revert to its original setting even after the included
file is finished processing.
</para>
<para>If <literal>ERROR=STOP</literal> is specified, errors encountered in the
inserted file will cause processing to immediately cease.
Otherwise processing will continue at the next command.
The default setting is <literal>ERROR=CONTINUE</literal>.
</para>
<para>If <literal>SYNTAX=INTERACTIVE</literal> is specified then the syntax contained in
the included file must conform to interactive syntax
conventions. See <link linkend="Syntax-Variants">Syntax Variants</link>.
The default setting is <literal>SYNTAX=BATCH</literal>.
</para>
<para><literal>ENCODING</literal> optionally specifies the character set used by the included
file.  Its argument, which is not case-sensitive, must be in one of
the following forms:
</para>
<variablelist><varlistentry><term><literal>LOCALE</literal>
</term><listitem><para>The encoding used by the system locale, or as overridden by the 
<literal>SET</literal> command (see <link linkend="SET">SET</link>).  On GNU/Linux and other Unix-like systems,
environment variables, e.g. <envar>LANG</envar> or <envar>LC_ALL</envar>, determine the
system locale.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>charset_name</replaceable>
</term><listitem><para>One of the character set names listed by <acronym>IANA</acronym> at
<ulink url="http://www.iana.org/assignments/character-sets">http://www.iana.org/assignments/character-sets</ulink>.  Some examples
are <literal>ASCII</literal> (United States), <literal>ISO-8859-1</literal> (western Europe),
<literal>EUC-JP</literal> (Japan), and <literal>windows-1252</literal> (Windows).  Not all
systems support all character sets.
</para>
</listitem></varlistentry><varlistentry><term><literal>Auto,<replaceable>encoding</replaceable></literal>
</term><listitem><para>Automatically detects whether a syntax file is encoded in an Unicode
encoding such as UTF-8, UTF-16, or UTF-32.  If it is not, then pspp
generally assumes that the file is encoded in <replaceable>encoding</replaceable> (an <acronym>IANA</acronym>
character set name).  However, if <replaceable>encoding</replaceable> is UTF-8, and the
syntax file is not valid UTF-8, pspp instead assumes that the file
is encoded in <literal>windows-1252</literal>.
</para>
<para>For best results, <replaceable>encoding</replaceable> should be an <acronym>ASCII</acronym>-compatible
encoding (the most common locale encodings are all <acronym>ASCII</acronym>-compatible),
because encodings that are not <acronym>ASCII</acronym> compatible cannot be
automatically distinguished from UTF-8.
</para>
</listitem></varlistentry><varlistentry><term><literal>Auto</literal>
</term></varlistentry><varlistentry><term><literal>Auto,Locale</literal>
</term><listitem><para>Automatic detection, as above, with the default encoding taken from
the system locale or the setting on <literal>SET LOCALE</literal>.
</para></listitem></varlistentry></variablelist>
<para>When ENCODING is not specified, the default is taken from the
<option>--syntax-encoding</option> command option, if it was specified, and
otherwise it is <literal>Auto</literal>.
</para>
</sect1>
<sect1 label="16.17" id="OUTPUT">
<title>OUTPUT</title>
<indexterm role="vr"><primary>OUTPUT</primary></indexterm>
<indexterm role="cp"><primary>precision, of output</primary></indexterm>
<indexterm role="cp"><primary>decimal places</primary></indexterm>

<literallayout>OUTPUT MODIFY
       /SELECT TABLES
       /TABLECELLS SELECT = [ {SIGNIFICANCE, COUNT} ]
                   FORMAT = <replaceable>fmt_spec</replaceable>.
</literallayout><blockquote><para><emphasis role="bold">Please note:</emphasis> In the above synopsis the characters &#8216;<literal>[</literal>&#8217; and &#8216;<literal>]</literal>&#8217; are literals.
They must appear in the syntax to be interpreted.
</para></blockquote>
<para><literal>OUTPUT</literal> changes the appearance of the tables in which results are printed.
In particular, it can be used to set the format and precision to which results are displayed.
</para>
<para>After running this command, the default table appearance parameters will have been modified and  each 
new output table generated will use the new parameters.
</para>
<para>Following <literal>/TABLECELLS SELECT =</literal> a list of cell classes must appear, enclosed in square
brackets.  This list determines the classes of values should be selected for modification.
Each class can be:
</para>
<variablelist><varlistentry><term>SIGNIFICANCE
</term><listitem><para>Significance of tests (p-values).
</para>
</listitem></varlistentry><varlistentry><term>COUNT
</term><listitem><para>Counts or sums of weights.
</para></listitem></varlistentry></variablelist>
<para>The value of <replaceable>fmt_spec</replaceable> must be a valid output format (see <link linkend="Input-and-Output-Formats">Input and Output Formats</link>).
Note that not all possible formats are meaningful for all classes.
</para>
</sect1>
<sect1 label="16.18" id="PERMISSIONS">
<title>PERMISSIONS</title>
<indexterm role="vr"><primary>PERMISSIONS</primary></indexterm>
<indexterm role="cp"><primary>mode</primary></indexterm>
<indexterm role="cp"><primary>file mode</primary></indexterm>
<indexterm role="cp"><primary>changing file permissions</primary></indexterm>

<literallayout>PERMISSIONS
        FILE=&#8217;<replaceable>file_name</replaceable>&#8217;
        /PERMISSIONS = {READONLY,WRITEABLE}.
</literallayout>
<para><literal>PERMISSIONS</literal> changes the permissions of a file.  
There is one mandatory subcommand which specifies the permissions to
which the file should be changed.  
If you set a file&#8217;s  permission  to <literal>READONLY</literal>, then the file will become
unwritable either by you or anyone else on the system.
If you set the permission to <literal>WRITEABLE</literal>, then the file will become
writeable by you; the permissions afforded to others will be
unchanged.
This command cannot be used if the <literal>SAFER</literal> (see <link linkend="SET">SET</link>) setting is active.
</para>

</sect1>
<sect1 label="16.19" id="PRESERVE-and-RESTORE">
<title>PRESERVE and RESTORE</title>
<indexterm role="vr"><primary>PRESERVE</primary></indexterm>
<indexterm role="vr"><primary>RESTORE</primary></indexterm>

<literallayout>PRESERVE.
&#8230;
RESTORE.
</literallayout>
<para><literal>PRESERVE</literal> saves all of the settings that <literal>SET</literal> (see <link linkend="SET">SET</link>)
can adjust.  A later <literal>RESTORE</literal> command restores those settings.
</para>
<para><literal>PRESERVE</literal> can be nested up to five levels deep.
</para>
</sect1>
<sect1 label="16.20" id="SET">
<title>SET</title>
<indexterm role="vr"><primary>SET</primary></indexterm>

<literallayout>SET

(data input)
        /BLANKS={SYSMIS,&#8217;.&#8217;,number}
        /DECIMAL={DOT,COMMA}
        /FORMAT=<replaceable>fmt_spec</replaceable>
        /EPOCH={AUTOMATIC,<replaceable>year</replaceable>}
        /RIB={NATIVE,MSBFIRST,LSBFIRST,VAX}
        /RRB={NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL}

(interaction)
        /MXERRS=<replaceable>max_errs</replaceable>
        /MXWARNS=<replaceable>max_warnings</replaceable>
        /WORKSPACE=<replaceable>workspace_size</replaceable>

(syntax execution)
        /LOCALE=&#8217;<replaceable>locale</replaceable>&#8217;
        /MEXPAND={ON,OFF}
        /MITERATE=<replaceable>max_iterations</replaceable>
        /MNEST=<replaceable>max_nest</replaceable>
        /MPRINT={ON,OFF}
        /MXLOOPS=<replaceable>max_loops</replaceable>
        /SEED={RANDOM,<replaceable>seed_value</replaceable>}
        /UNDEFINED={WARN,NOWARN}
        /FUZZBITS=<replaceable>fuzzbits</replaceable>

(data output)
        /CC{A,B,C,D,E}={&#8217;<replaceable>npre</replaceable>,<replaceable>pre</replaceable>,<replaceable>suf</replaceable>,<replaceable>nsuf</replaceable>&#8217;,&#8217;<replaceable>npre</replaceable>.<replaceable>pre</replaceable>.<replaceable>suf</replaceable>.<replaceable>nsuf</replaceable>&#8217;}
        /DECIMAL={DOT,COMMA}
        /FORMAT=<replaceable>fmt_spec</replaceable>
        /WIB={NATIVE,MSBFIRST,LSBFIRST,VAX}
        /WRB={NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL}

(output routing)
        /ERRORS={ON,OFF,TERMINAL,LISTING,BOTH,NONE}
        /MESSAGES={ON,OFF,TERMINAL,LISTING,BOTH,NONE}
        /PRINTBACK={ON,OFF,TERMINAL,LISTING,BOTH,NONE}
        /RESULTS={ON,OFF,TERMINAL,LISTING,BOTH,NONE}

(output driver options)
        /HEADERS={NO,YES,BLANK}
        /LENGTH={NONE,<replaceable>n_lines</replaceable>}
        /MORE={ON,OFF}
        /WIDTH={NARROW,WIDTH,<replaceable>n_characters</replaceable>}
        /TNUMBERS={VALUES,LABELS,BOTH}
        /TVARS={NAMES,LABELS,BOTH}

(logging)
        /JOURNAL={ON,OFF} [&#8217;<replaceable>file_name</replaceable>&#8217;]

(system files)
        /COMPRESSION={ON,OFF}
        /SCOMPRESSION={ON,OFF}

(miscellaneous)
        /SAFER=ON
        /LOCALE=&#8217;<replaceable>string</replaceable>&#8217;


(obsolete settings accepted for compatibility, but ignored)
        /BOXSTRING={&#8217;<replaceable>xxx</replaceable>&#8217;,&#8217;<replaceable>xxxxxxxxxxx</replaceable>&#8217;}
        /CASE={UPPER,UPLOW}
        /CPI=cpi_value
        /HIGHRES={ON,OFF}
        /HISTOGRAM=&#8217;<replaceable>c</replaceable>&#8217;
        /LOWRES={AUTO,ON,OFF}
        /LPI=<replaceable>lpi_value</replaceable>
        /MENUS={STANDARD,EXTENDED}
        /MXMEMORY=<replaceable>max_memory</replaceable>
        /SCRIPTTAB=&#8217;c&#8217;
        /TB1={&#8217;<replaceable>xxx</replaceable>&#8217;,&#8217;<replaceable>xxxxxxxxxxx</replaceable>&#8217;}
        /TBFONTS=&#8217;<replaceable>string</replaceable>&#8217;
        /XSORT={YES,NO}
</literallayout>
<para><literal>SET</literal> allows the user to adjust several parameters relating to
pspp&#8217;s execution.  Since there are many subcommands to this command, its
subcommands will be examined in groups.
</para>
<para>For subcommands that take boolean values, <literal>ON</literal> and <literal>YES</literal> are synonymous, 
as are <literal>OFF</literal> and <literal>NO</literal>, when used as subcommand values.
</para>
<para>The data input subcommands affect the way that data is read from data
files.  The data input subcommands are
</para>
<variablelist><varlistentry><term>BLANKS
</term><listitem><anchor id="SET-BLANKS"/><para>This is the value assigned to an item data item that is empty or
contains only white space.  An argument of SYSMIS or &#8217;.&#8217; will cause the
system-missing value to be assigned to null items.  This is the
default.  Any real value may be assigned.
</para>
</listitem></varlistentry><varlistentry><term>DECIMAL
</term><listitem><anchor id="SET-DECIMAL"/><para>This value may be set to <literal>DOT</literal> or <literal>COMMA</literal>.
Setting it to <literal>DOT</literal> causes the decimal point character to be
&#8216;<literal>.</literal>&#8217; and the grouping character to be &#8216;<literal>,</literal>&#8217;.
Setting it to <literal>COMMA</literal>
causes the decimal point character to be &#8216;<literal>,</literal>&#8217; and the grouping
character to be &#8216;<literal>.</literal>&#8217;.
If the setting is <literal>COMMA</literal>, then &#8216;<literal>,</literal>&#8217; will not be treated
as a field separator in the <literal>DATA LIST</literal> command (see <link linkend="DATA-LIST">DATA LIST</link>).
The default value is determined from the system locale.
</para>
</listitem></varlistentry><varlistentry><term>FORMAT
</term><listitem><para>Allows the default numeric input/output format to be specified.  The
default is F8.2.  See <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.
</para>
</listitem></varlistentry><varlistentry><term>EPOCH
</term><listitem><anchor id="SET-EPOCH"/><para>Specifies the range of years used when a 2-digit year is read from a
data file or used in a date construction expression (see <link linkend="Date-Construction">Date
Construction</link>).  If a 4-digit year is specified for the epoch, then
2-digit years are interpreted starting from that year, known as the
epoch.  If <literal>AUTOMATIC</literal> (the default) is specified, then the epoch begins
69 years before the current date.
</para>
</listitem></varlistentry><varlistentry><term>RIB
</term><listitem><anchor id="SET-RIB"/>
<para>pspp extension to set the byte ordering (endianness) used for reading
data in IB or PIB format (see <link linkend="Binary-and-Hexadecimal-Numeric-Formats">Binary and Hexadecimal Numeric
Formats</link>).  In <literal>MSBFIRST</literal> ordering, the most-significant byte appears at
the left end of a IB or PIB field.  In <literal>LSBFIRST</literal> ordering, the
least-significant byte appears at the left end.  <literal>VAX</literal> ordering is like
<literal>MSBFIRST</literal>, except that each pair of bytes is in reverse order.  <literal>NATIVE</literal>,
the default, is equivalent to <literal>MSBFIRST</literal> or <literal>LSBFIRST</literal> depending on the
native format of the machine running pspp.
</para>
</listitem></varlistentry><varlistentry><term>RRB
</term><listitem><anchor id="SET-RRB"/>
<para>pspp extension to set the floating-point format used for reading data in
RB format (see <link linkend="Binary-and-Hexadecimal-Numeric-Formats">Binary and Hexadecimal Numeric Formats</link>).  The
possibilities are:
</para>
<variablelist><varlistentry><term>NATIVE
</term><listitem><para>The native format of the machine running pspp.  Equivalent to either IDL
or IDB.
</para>
</listitem></varlistentry><varlistentry><term>ISL
</term><listitem><para>32-bit IEEE 754 single-precision floating point, in little-endian byte
order.
</para>
</listitem></varlistentry><varlistentry><term>ISB
</term><listitem><para>32-bit IEEE 754 single-precision floating point, in big-endian byte
order.
</para>
</listitem></varlistentry><varlistentry><term>IDL
</term><listitem><para>64-bit IEEE 754 double-precision floating point, in little-endian byte
order.
</para>
</listitem></varlistentry><varlistentry><term>IDB
</term><listitem><para>64-bit IEEE 754 double-precision floating point, in big-endian byte
order.
</para>
</listitem></varlistentry><varlistentry><term>VF
</term><listitem><para>32-bit VAX F format, in VAX-endian byte order.
</para>
</listitem></varlistentry><varlistentry><term>VD
</term><listitem><para>64-bit VAX D format, in VAX-endian byte order.
</para>
</listitem></varlistentry><varlistentry><term>VG
</term><listitem><para>64-bit VAX G format, in VAX-endian byte order.
</para>
</listitem></varlistentry><varlistentry><term>ZS
</term><listitem><para>32-bit IBM Z architecture short format hexadecimal floating point, in
big-endian byte order.  
</para>
</listitem></varlistentry><varlistentry><term>ZL
</term><listitem><para>64-bit IBM Z architecture long format hexadecimal floating point, in
big-endian byte order.
</para>
<para>Z architecture also supports IEEE 754 floating point.  The ZS and ZL
formats are only for use with very old input files.
</para></listitem></varlistentry></variablelist><para>The default is NATIVE.
</para></listitem></varlistentry></variablelist>
<para>Interaction subcommands affect the way that pspp interacts with an
online user.  The interaction subcommands are
</para>
<variablelist><varlistentry><term>MXERRS
</term><listitem><para>The maximum number of errors before pspp halts processing of the current
command file.  The default is 50.
</para>
</listitem></varlistentry><varlistentry><term>MXWARNS
</term><listitem><para>The maximum number of warnings + errors before pspp halts processing the
current command file.  
The special value of zero means that all warning situations should be ignored.
No warnings will be issued, except a single initial warning advising the user
that warnings will not be given.
The default value is 100.
</para></listitem></varlistentry></variablelist>
<para>Syntax execution subcommands control the way that pspp commands
execute.  The syntax execution subcommands are
</para>
<variablelist><varlistentry><term>LOCALE
</term><listitem><para>Overrides the system locale for the purpose of reading and writing
syntax and data files.  The argument should be a locale name in the
general form <literal><replaceable>language</replaceable>_<replaceable>country</replaceable>.<replaceable>encoding</replaceable></literal>, where <replaceable>language</replaceable>
and <replaceable>country</replaceable> are 2-character language and country abbreviations,
respectively, and <replaceable>encoding</replaceable> is an <acronym>IANA</acronym> character set name.
Example locales are <literal>en_US.UTF-8</literal> (UTF-8 encoded English as
spoken in the United States) and <literal>ja_JP.EUC-JP</literal> (EUC-JP encoded
Japanese as spoken in Japan).
</para>
</listitem></varlistentry><varlistentry><term>MEXPAND
</term><term>MITERATE
</term><term>MNEST
</term><term>MPRINT
</term><listitem><para>Currently not used.
</para>
</listitem></varlistentry><varlistentry><term>MXLOOPS
</term><listitem><para>The maximum number of iterations for an uncontrolled loop (see <link linkend="LOOP">LOOP</link>).
The default <replaceable>max_loops</replaceable> is 40.
</para>
</listitem></varlistentry><varlistentry><term>SEED
</term><listitem><para>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.
</para>
</listitem></varlistentry><varlistentry><term>UNDEFINED
</term><listitem><para>Currently not used.
</para>
</listitem></varlistentry><varlistentry><term>FUZZBITS
</term><listitem><anchor id="SET-FUZZBITS"/><para>The maximum number of bits of errors in the least-significant places
to accept for rounding up a value that is almost halfway between two
possibilities for rounding with the RND operator (see <link linkend="Miscellaneous-Mathematics">Miscellaneous
Mathematics</link>).  The default <replaceable>fuzzbits</replaceable> is 6.
</para>
</listitem></varlistentry><varlistentry><term>WORKSPACE
</term><listitem><para>The maximum amount of memory (in kilobytes) that pspp will use to store data being processed.
If memory in excess of the workspace size is required, then pspp will start
to use temporary files to store the data.
Setting a higher value will, in general, mean procedures will run faster, 
but may cause other applications to run slower.
On platforms without virtual memory management, setting a very large workspace
may cause pspp to abort.
<indexterm role="cp"><primary>workspace</primary></indexterm>
<indexterm role="cp"><primary>memory, amount used to store cases</primary></indexterm>
</para></listitem></varlistentry></variablelist>
<para>Data output subcommands affect the format of output data.  These
subcommands are
</para>
<variablelist><varlistentry><term>CCA
</term><term>CCB
</term><term>CCC
</term><term>CCD
</term><term>CCE
</term><listitem><anchor id="CCx-Settings"/>
<para>Set up custom currency formats.  See <link linkend="Custom-Currency-Formats">Custom Currency Formats</link>, for
details.
</para>
</listitem></varlistentry><varlistentry><term>DECIMAL
</term><listitem><para>The default <literal>DOT</literal> setting causes the decimal point character to be
&#8216;<literal>.</literal>&#8217;.  A setting of <literal>COMMA</literal> causes the decimal point character to be
&#8216;<literal>,</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term>FORMAT
</term><listitem><para>Allows the default numeric input/output format to be specified.  The
default is F8.2.  See <link linkend="Input-and-Output-Formats">Input and Output Formats</link>.
</para>
</listitem></varlistentry><varlistentry><term>WIB
</term><listitem><anchor id="SET-WIB"/>
<para>pspp extension to set the byte ordering (endianness) used for writing
data in IB or PIB format (see <link linkend="Binary-and-Hexadecimal-Numeric-Formats">Binary and Hexadecimal Numeric
Formats</link>).  In <literal>MSBFIRST</literal> ordering, the most-significant byte appears at
the left end of a IB or PIB field.  In <literal>LSBFIRST</literal> ordering, the
least-significant byte appears at the left end.  <literal>VAX</literal> ordering is like
<literal>MSBFIRST</literal>, except that each pair of bytes is in reverse order.  <literal>NATIVE</literal>,
the default, is equivalent to <literal>MSBFIRST</literal> or <literal>LSBFIRST</literal> depending on the
native format of the machine running pspp.
</para>
</listitem></varlistentry><varlistentry><term>WRB
</term><listitem><anchor id="SET-WRB"/>
<para>pspp extension to set the floating-point format used for writing data in
RB format (see <link linkend="Binary-and-Hexadecimal-Numeric-Formats">Binary and Hexadecimal Numeric Formats</link>).  The choices
are the same as <literal>SET RIB</literal>.  The default is <literal>NATIVE</literal>.
</para></listitem></varlistentry></variablelist>
<para>In the pspp text-based interface, the output routing subcommands
affect where output is sent.  The following values are allowed for
each of these subcommands:
</para>
<variablelist><varlistentry><term>OFF
</term></varlistentry><varlistentry><term>NONE
</term><listitem><para>Discard this kind of output.
</para>
</listitem></varlistentry><varlistentry><term>TERMINAL
</term><listitem><para>Write this output to the terminal, but not to listing files and other
output devices.
</para>
</listitem></varlistentry><varlistentry><term>LISTING
</term><listitem><para>Write this output to listing files and other output devices, but not
to the terminal.
</para>
</listitem></varlistentry><varlistentry><term>ON
</term><term>BOTH
</term><listitem><para>Write this type of output to all output devices.
</para></listitem></varlistentry></variablelist>
<para>These output routing subcommands are:
</para>
<variablelist><varlistentry><term>ERRORS
</term><listitem><para>Applies to error and warning messages.  The default is <literal>BOTH</literal>.
</para>
</listitem></varlistentry><varlistentry><term>MESSAGES
</term><listitem><para>Applies to notes.  The default is <literal>BOTH</literal>.
</para>
</listitem></varlistentry><varlistentry><term>PRINTBACK
</term><listitem><para>Determines whether the syntax used for input is printed back as part
of the output.  The default is <literal>NONE</literal>.
</para>
</listitem></varlistentry><varlistentry><term>RESULTS
</term><listitem><para>Applies to everything not in one of the above categories, such as the
results of statistical procedures.  The default is <literal>BOTH</literal>.
</para></listitem></varlistentry></variablelist>
<para>These subcommands have no effect on output in the pspp GUI
environment.
</para>
<para>Output driver option subcommands affect output drivers&#8217; settings.  These
subcommands are
</para>
<variablelist><varlistentry><term>HEADERS
</term><term>LENGTH
</term><term>MORE
</term><term>WIDTH
</term><term>TNUMBERS
</term><listitem><para>The <literal>TNUMBERS</literal> option sets the way in which values are displayed in output tables.
The valid settings are <literal>VALUES</literal>, <literal>LABELS</literal> and <literal>BOTH</literal>.
If <literal>TNUMBERS</literal> is set to <literal>VALUES</literal>, then all values are displayed with their literal value 
(which for a numeric value is a number and for a string value an alphanumeric string).
If <literal>TNUMBERS</literal> is set to <literal>LABELS</literal>, then values are displayed using their assigned labels if any.
(See <link linkend="VALUE-LABELS">VALUE LABELS</link>.)
If the a value has no label, then it will be displayed using its literal value.
If <literal>TNUMBERS</literal> is set to <literal>BOTH</literal>, then values will be displayed with both their label
(if any) and their literal value in parentheses.
</para></listitem></varlistentry><varlistentry><term>TVARS
</term><listitem><para>The <literal>TVARS</literal> option sets the way in which variables are displayed in output tables.
The valid settings are <literal>NAMES</literal>, <literal>LABELS</literal> and <literal>BOTH</literal>.
If <literal>TVARS</literal> is set to <literal>NAMES</literal>, then all variables are displayed using their names.
If <literal>TVARS</literal> is set to <literal>LABELS</literal>, then variables are displayed using their label if one
has been set.  If no label has been set, then the name will be used.
(See <link linkend="VARIABLE-LABELS">VARIABLE LABELS</link>.)
If <literal>TVARS</literal> is set to <literal>BOTH</literal>, then variables will be displayed with both their label
(if any) and their name in parentheses.
</para></listitem></varlistentry></variablelist>
<indexterm role="cp"><primary>headers</primary></indexterm>
<indexterm role="cp"><primary>length</primary></indexterm>
<indexterm role="cp"><primary>more</primary></indexterm>
<indexterm role="cp"><primary>pager</primary></indexterm>
<indexterm role="cp"><primary>width</primary></indexterm>
<indexterm role="cp"><primary>tnumbers</primary></indexterm>


<para>Logging subcommands affect logging of commands executed to external
files.  These subcommands are
</para>
<variablelist><varlistentry><term>JOURNAL
</term><term>LOG
</term><listitem><para>These subcommands, which are synonyms, control the journal.  The
default is <literal>ON</literal>, which causes commands entered interactively to be
written to the journal file.  Commands included from syntax files that
are included interactively and error messages printed by pspp are also
written to the journal file, prefixed by &#8216;<literal>&gt;</literal>&#8217;.  <literal>OFF</literal> disables use
of the journal.
</para>
<para>The journal is named <filename>pspp.jnl</filename> by default.  A different name may
be specified.
</para></listitem></varlistentry></variablelist>
<para>System file subcommands affect the default format of system files
produced by pspp.  These subcommands are
</para>
<variablelist><varlistentry><term>COMPRESSION
</term><listitem><para>Not currently used.
</para>
</listitem></varlistentry><varlistentry><term>SCOMPRESSION
</term><listitem><para>Whether system files created by <literal>SAVE</literal> or <literal>XSAVE</literal> are
compressed by default.  The default is <literal>ON</literal>.
</para></listitem></varlistentry></variablelist>
<para>Security subcommands affect the operations that commands are allowed to
perform.  The security subcommands are
</para>
<variablelist><varlistentry><term>SAFER
</term><listitem><para>Setting this option disables the following operations:
</para>
<itemizedlist><listitem><para>The <literal>ERASE</literal> command.
</para></listitem><listitem><para>The <literal>HOST</literal> command.
</para></listitem><listitem><para>The <literal>PERMISSIONS</literal> command.
</para></listitem><listitem><para>Pipes (file names beginning or ending with &#8216;<literal>|</literal>&#8217;).
</para></listitem></itemizedlist>
<para>Be aware that this setting does not guarantee safety (commands can still
overwrite files, for instance) but it is an improvement.
When set, this setting cannot be reset during the same session, for
obvious security reasons.
</para>
</listitem></varlistentry><varlistentry><term>LOCALE
</term><listitem><indexterm role="cp"><primary>locale</primary></indexterm>
<indexterm role="cp"><primary>encoding, characters</primary></indexterm>
<para>This item is used to set the default character encoding.
The encoding may be specified either as an encoding name or alias
(see <ulink url="http://www.iana.org/assignments/character-sets">http://www.iana.org/assignments/character-sets</ulink>), or
as a locale name.
If given as a locale name, only the character encoding of the 
locale is relevant.
</para>
<para>System files written by pspp will use this encoding.
System files read by pspp, for which the encoding is unknown, will be
interpreted using this encoding.
</para>
<para>The full list of valid encodings and locale names/alias are operating system
dependent.
The following are all examples of acceptable syntax on common GNU/Linux
systems.
</para><screen>SET LOCALE='iso-8859-1'.

SET LOCALE='ru_RU.cp1251'.

SET LOCALE='japanese'.
</screen>
<para>Contrary to intuition, this command does not affect any aspect 
of the system&#8217;s locale.
</para></listitem></varlistentry></variablelist>
</sect1>
<sect1 label="16.21" id="SHOW">
<title>SHOW</title>
<indexterm role="vr"><primary>SHOW</primary></indexterm>

<literallayout>SHOW
        [ALL]
        [BLANKS]
        [CC]
        [CCA]
        [CCB]
        [CCC]
        [CCD]
        [CCE]
        [COPYING]
        [DECIMALS]
        [DIRECTORY]
        [ENVIRONMENT]
        [FORMAT]
        [FUZZBITS]
        [LENGTH]
        [MXERRS]
        [MXLOOPS]
        [MXWARNS]
        [N]
        [SCOMPRESSION]
        [TEMPDIR]
        [UNDEFINED]
        [VERSION]
        [WARRANTY]
        [WEIGHT]
        [WIDTH]
</literallayout>
<para><literal>SHOW</literal> can be used to display the current state of pspp&#8217;s execution
parameters.  Parameters that can be changed using <literal>SET</literal>
(see <link linkend="SET">SET</link>), can be examined using <literal>SHOW</literal> using the subcommand
with the same name.  <literal>SHOW</literal> supports the following additional
subcommands:
</para>
<variablelist><varlistentry><term><literal>ALL</literal>
</term><listitem><para>Show all settings.
</para></listitem></varlistentry><varlistentry><term><literal>CC</literal>
</term><listitem><para>Show all custom currency settings (<literal>CCA</literal> through <literal>CCE</literal>).
</para></listitem></varlistentry><varlistentry><term><literal>DIRECTORY</literal>
</term><listitem><para>Shows the current working directory.
</para></listitem></varlistentry><varlistentry><term><literal>ENVIRONMENT</literal>
</term><listitem><para>Shows the operating system details.
</para></listitem></varlistentry><varlistentry><term><literal>N</literal>
</term><listitem><para>Reports the number of cases in the active dataset.  The reported number is not
weighted.  If no dataset is defined, then &#8216;<literal>Unknown</literal>&#8217; will be reported.
</para></listitem></varlistentry><varlistentry><term><literal>TEMPDIR</literal>
</term><listitem><para>Shows the path of the directory where temporary files will be stored.
</para></listitem></varlistentry><varlistentry><term><literal>VERSION</literal>
</term><listitem><para>Shows the version of this installation of pspp.
</para></listitem></varlistentry><varlistentry><term><literal>WARRANTY</literal>
</term><listitem><para>Show details of the lack of warranty for pspp.
</para></listitem></varlistentry><varlistentry><term><literal>COPYING</literal> / <literal>LICENSE</literal>
</term><listitem><para>Display the terms of pspp&#8217;s copyright licence (see <link linkend="License">License</link>).
</para></listitem></varlistentry></variablelist>
<para>Specifying <literal>SHOW</literal> without any subcommands is equivalent to <literal>SHOW ALL</literal>.
</para>
</sect1>
<sect1 label="16.22" id="SUBTITLE">
<title>SUBTITLE</title>
<indexterm role="vr"><primary>SUBTITLE</primary></indexterm>

<literallayout>SUBTITLE &#8217;<replaceable>subtitle_string</replaceable>&#8217;.
  or
SUBTITLE <replaceable>subtitle_string</replaceable>.
</literallayout>
<para><literal>SUBTITLE</literal> 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.
</para>
<para>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.
</para>
</sect1>
<sect1 label="16.23" id="TITLE">
<title>TITLE</title>
<indexterm role="vr"><primary>TITLE</primary></indexterm>

<literallayout>TITLE &#8217;<replaceable>title_string</replaceable>&#8217;.
  or
TITLE <replaceable>title_string</replaceable>.
</literallayout>
<para><literal>TITLE</literal> 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.
</para>
<para>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.
</para>
</sect1>
</chapter>
<chapter label="17" id="Invoking-pspp_002dconvert">
<title>Invoking <command>pspp-convert</command></title>
<indexterm role="cp"><primary>Invocation</primary></indexterm>
<indexterm role="cp"><primary><command>pspp-convert</command></primary></indexterm>

<para><command>pspp-convert</command> is a command-line utility accompanying
pspp. It reads an SPSS or SPSS/PC+ system file or SPSS portable
file or encrypted SPSS syntax file <replaceable>input</replaceable> and
writes a copy of it to another <replaceable>output</replaceable> in a different format.
Synopsis:
</para>
<literallayout><literal>pspp-convert</literal> [<replaceable>options</replaceable>] <replaceable>input</replaceable> <replaceable>output</replaceable>

<literal>pspp-convert --<!-- /@w -->help</literal>

<literal>pspp-convert --<!-- /@w -->version</literal>
</literallayout>
<para>The format of <replaceable>input</replaceable> is automatically detected, when possible.
The character encoding of old SPSS system files cannot always be
guessed correctly, and SPSS/PC+ system files do not include any
indication of their encoding.  Use <literal>-e <replaceable>encoding</replaceable></literal> to specify
the encoding in this case.
</para>
<para>By default, the intended format for <replaceable>output</replaceable> is inferred based on its
extension:
</para>
<variablelist><varlistentry><term><literal>csv</literal>
</term><term><literal>txt</literal>
</term><listitem><para>Comma-separated value.  Each value is formatted according to its
variable&#8217;s print format.  The first line in the file contains variable
names.
</para>
</listitem></varlistentry><varlistentry><term><literal>sav</literal>
</term></varlistentry><varlistentry><term><literal>sys</literal>
</term><listitem><para>SPSS system file.
</para>
</listitem></varlistentry><varlistentry><term><literal>por</literal>
</term><listitem><para>SPSS portable file.
</para>
</listitem></varlistentry><varlistentry><term><literal>sps</literal>
</term><listitem><para>SPSS syntax file.  (Only encrypted syntax files may be converted to
this format.)
</para></listitem></varlistentry></variablelist>
<para><command>pspp-convert</command> can convert most input formats to most output
formats.  Encrypted system file and syntax files are exceptions: if
the input file is in an encrypted format, then the output file must be
the same format (decrypted).  To decrypt such a file, specify the
encrypted file as <replaceable>input</replaceable>.  The output will be the equivalent
plaintext file.  You will be prompted for the password (or use
<option>-p</option>, documented below).
</para>
<para>Use <literal>-O <replaceable>extension</replaceable></literal> to override the inferred format or to
specify the format for unrecognized extensions.
</para>
<para>The following options are accepted:
</para>
<variablelist><varlistentry><term><option>-O <replaceable>format</replaceable></option>
</term><term><option>--output-format=<replaceable>format</replaceable></option>
</term><listitem><para>Specifies the desired output format.  <replaceable>format</replaceable> must be one of the
extensions listed above, e.g. <literal>-O csv</literal> requests comma-separated
value output.
</para>
</listitem></varlistentry><varlistentry><term><option>-c <replaceable>maxcases</replaceable></option>
</term><term><option>--cases=<replaceable>maxcases</replaceable></option>
</term><listitem><para>By default, all cases are copied from <replaceable>input</replaceable> to <replaceable>output</replaceable>.
Specifying this option to limit the number of cases written to
<replaceable>output</replaceable> to <replaceable>maxcases</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><option>-e <replaceable>charset</replaceable></option>
</term><term><option>--encoding=<replaceable>charset</replaceable></option>
</term><listitem><para>Overrides the encoding in which character strings in <replaceable>input</replaceable> are
interpreted.  This option is necessary because old SPSS system files,
and SPSS/PC+ system files, do not self-identify their encoding.
</para>
</listitem></varlistentry><varlistentry><term><option>-p <replaceable>password</replaceable></option>
</term></varlistentry><varlistentry><term><option>--password=<replaceable>password</replaceable></option>
</term><listitem><para>Specifies the password to use to decrypt an encrypted SPSS system file
or syntax file.  If this option is not specified,
<command>pspp-convert</command> will prompt interactively for the password as
necessary.
</para>
<para>Be aware that command-line options, including passwords, may be
visible to other users on multiuser systems.
</para>
</listitem></varlistentry><varlistentry><term><option>-h</option>
</term><term><option>--help</option>
</term><listitem><para>Prints a usage message on stdout and exits.
</para>
</listitem></varlistentry><varlistentry><term><option>-v</option>
</term><term><option>--version</option>
</term><listitem><para>Prints version information on stdout and exits.
</para></listitem></varlistentry></variablelist></chapter>
<chapter label="18" id="Invoking-pspp_002ddump_002dsav">
<title>Invoking <command>pspp-dump-sav</command></title>
<indexterm role="cp"><primary>Invocation</primary></indexterm>
<indexterm role="cp"><primary><command>pspp-dump-sav</command></primary></indexterm>

<para><command>pspp-dump-sav</command> is a command-line utility accompanying
pspp.  It reads one or more SPSS system files and prints their
contents.  The output format is useful for debugging system file
readers and writers and for discovering how to interpret unknown or
poorly understood records.  End users may find the output useful for
providing the PSPP developers information about system files that PSPP
does not accurately read.
</para>
<para>Synopsis:
</para>
<literallayout><literal>pspp-dump-sav</literal> [<literal>-d</literal>[<replaceable>maxcases</replaceable>] | <literal>--<!-- /@w -->data</literal>[<literal>=</literal><replaceable>maxcases</replaceable>]] <replaceable>file</replaceable>&#8230;

<literal>pspp-dump-sav --<!-- /@w -->help</literal> | <literal>-h</literal>

<literal>pspp-dump-sav --<!-- /@w -->version</literal> | <literal>-v</literal>
</literallayout>
<para>The following options are accepted:
</para>
<variablelist><varlistentry><term><literal>-d</literal>[<replaceable>maxcases</replaceable>]
</term></varlistentry><varlistentry><term><literal>--<!-- /@w -->data</literal>[<literal>=</literal><replaceable>maxcases</replaceable>]
</term><listitem><para>By default, <command>pspp-dump-sav</command> does not print any of the data in a
system file, only the file headers.  Specify this option to print the
data as well.  If <replaceable>maxcases</replaceable> is specified, then it limits the
number of cases printed.
</para>
</listitem></varlistentry><varlistentry><term><literal>-h</literal>
</term><term><literal>--<!-- /@w -->help</literal>
</term><listitem><para>Prints a usage message on stdout and exits.
</para>
</listitem></varlistentry><varlistentry><term><literal>-v</literal>
</term><term><literal>--<!-- /@w -->version</literal>
</term><listitem><para>Prints version information on stdout and exits.
</para></listitem></varlistentry></variablelist>
<para>Some errors that prevent files from being interpreted successfully
cause <command>pspp-dump-sav</command> to exit without reading any additional
files given on the command line.
</para></chapter>
<chapter label="19" id="Not-Implemented">
<title>Not Implemented</title>

<para>This chapter lists parts of the pspp language that are not yet
implemented.
</para>
<indexterm role="cp"><primary>unimplemented commands</primary></indexterm>
<indexterm role="cp"><primary>commands, unimplemented</primary></indexterm>

<!-- Generated from ../src/language/command.def by get-commands.pl -->
<!-- Do not modify! -->

<variablelist><varlistentry><term><literal>2SLS</literal>
</term><listitem><para>Two stage least squares regression
</para>
</listitem></varlistentry><varlistentry><term><literal>ACF</literal>
</term><listitem><para>Autocorrelation function
</para>
</listitem></varlistentry><varlistentry><term><literal>ALSCAL</literal>
</term><listitem><para>Multidimensional scaling
</para>
</listitem></varlistentry><varlistentry><term><literal>ANACOR</literal>
</term><listitem><para>Correspondence analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>ANOVA</literal>
</term><listitem><para>Factorial analysis of variance
</para>
</listitem></varlistentry><varlistentry><term><literal>CASEPLOT</literal>
</term><listitem><para>Plot time series
</para>
</listitem></varlistentry><varlistentry><term><literal>CASESTOVARS</literal>
</term><listitem><para>Restructure complex data
</para>
</listitem></varlistentry><varlistentry><term><literal>CATPCA</literal>
</term><listitem><para>Categorical principle components analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>CATREG</literal>
</term><listitem><para>Categorical regression
</para>
</listitem></varlistentry><varlistentry><term><literal>CCF</literal>
</term><listitem><para>Time series cross correlation
</para>
</listitem></varlistentry><varlistentry><term><literal>CLEAR TRANSFORMATIONS</literal>
</term><listitem><para>Clears transformations from active dataset
</para>
</listitem></varlistentry><varlistentry><term><literal>CLUSTER</literal>
</term><listitem><para>Hierarchical clustering
</para>
</listitem></varlistentry><varlistentry><term><literal>CONJOINT</literal>
</term><listitem><para>Analyse full concept data
</para>
</listitem></varlistentry><varlistentry><term><literal>CORRESPONDENCE</literal>
</term><listitem><para>Show correspondence
</para>
</listitem></varlistentry><varlistentry><term><literal>COXREG</literal>
</term><listitem><para>Cox proportional hazards regression
</para>
</listitem></varlistentry><varlistentry><term><literal>CREATE</literal>
</term><listitem><para>Create time series data
</para>
</listitem></varlistentry><varlistentry><term><literal>CSDESCRIPTIVES</literal>
</term><listitem><para>Complex samples descriptives
</para>
</listitem></varlistentry><varlistentry><term><literal>CSGLM</literal>
</term><listitem><para>Complex samples GLM
</para>
</listitem></varlistentry><varlistentry><term><literal>CSLOGISTIC</literal>
</term><listitem><para>Complex samples logistic regression
</para>
</listitem></varlistentry><varlistentry><term><literal>CSPLAN</literal>
</term><listitem><para>Complex samples design
</para>
</listitem></varlistentry><varlistentry><term><literal>CSSELECT</literal>
</term><listitem><para>Select complex samples
</para>
</listitem></varlistentry><varlistentry><term><literal>CSTABULATE</literal>
</term><listitem><para>Tabulate complex samples
</para>
</listitem></varlistentry><varlistentry><term><literal>CTABLES</literal>
</term><listitem><para>Display complex samples
</para>
</listitem></varlistentry><varlistentry><term><literal>CURVEFIT</literal>
</term><listitem><para>Fit curve to line plot
</para>
</listitem></varlistentry><varlistentry><term><literal>DATE</literal>
</term><listitem><para>Create time series data
</para>
</listitem></varlistentry><varlistentry><term><literal>DEFINE</literal>
</term><listitem><para>Syntax macros
</para>
</listitem></varlistentry><varlistentry><term><literal>DETECTANOMALY</literal>
</term><listitem><para>Find unusual cases
</para>
</listitem></varlistentry><varlistentry><term><literal>DISCRIMINANT</literal>
</term><listitem><para>Linear discriminant analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>EDIT</literal>
</term><listitem><para>obsolete
</para>
</listitem></varlistentry><varlistentry><term><literal>END FILE TYPE</literal>
</term><listitem><para>Ends complex data input
</para>
</listitem></varlistentry><varlistentry><term><literal>FILE TYPE</literal>
</term><listitem><para>Complex data input
</para>
</listitem></varlistentry><varlistentry><term><literal>FIT</literal>
</term><listitem><para>Goodness of Fit
</para>
</listitem></varlistentry><varlistentry><term><literal>GENLOG</literal>
</term><listitem><para>Categorical model fitting
</para>
</listitem></varlistentry><varlistentry><term><literal>GET TRANSLATE</literal>
</term><listitem><para>Read other file formats
</para>
</listitem></varlistentry><varlistentry><term><literal>GGRAPH</literal>
</term><listitem><para>Custom defined graphs
</para>
</listitem></varlistentry><varlistentry><term><literal>HILOGLINEAR</literal>
</term><listitem><para>Hierarchical loglinear models
</para>
</listitem></varlistentry><varlistentry><term><literal>HOMALS</literal>
</term><listitem><para>Homogeneity analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>IGRAPH</literal>
</term><listitem><para>Interactive graphs
</para>
</listitem></varlistentry><varlistentry><term><literal>INFO</literal>
</term><listitem><para>Local Documentation
</para>
</listitem></varlistentry><varlistentry><term><literal>KEYED DATA LIST</literal>
</term><listitem><para>Read nonsequential data
</para>
</listitem></varlistentry><varlistentry><term><literal>KM</literal>
</term><listitem><para>Kaplan-Meier
</para>
</listitem></varlistentry><varlistentry><term><literal>LOGLINEAR</literal>
</term><listitem><para>General model fitting
</para>
</listitem></varlistentry><varlistentry><term><literal>MANOVA</literal>
</term><listitem><para>Multivariate analysis of variance
</para>
</listitem></varlistentry><varlistentry><term><literal>MAPS</literal>
</term><listitem><para>Geographical display
</para>
</listitem></varlistentry><varlistentry><term><literal>MATRIX</literal>
</term><listitem><para>Matrix processing
</para>
</listitem></varlistentry><varlistentry><term><literal>MATRIX DATA</literal>
</term><listitem><para>Matrix data input
</para>
</listitem></varlistentry><varlistentry><term><literal>MCONVERT</literal>
</term><listitem><para>Convert covariance/correlation matrices
</para>
</listitem></varlistentry><varlistentry><term><literal>MIXED</literal>
</term><listitem><para>Mixed linear models
</para>
</listitem></varlistentry><varlistentry><term><literal>MODEL CLOSE</literal>
</term><listitem><para>Close server connection
</para>
</listitem></varlistentry><varlistentry><term><literal>MODEL HANDLE</literal>
</term><listitem><para>Define server connection
</para>
</listitem></varlistentry><varlistentry><term><literal>MODEL LIST</literal>
</term><listitem><para>Show existing models
</para>
</listitem></varlistentry><varlistentry><term><literal>MODEL NAME</literal>
</term><listitem><para>Specify model label
</para>
</listitem></varlistentry><varlistentry><term><literal>MULTIPLE CORRESPONDENCE</literal>
</term><listitem><para>Multiple correspondence analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>MULT RESPONSE</literal>
</term><listitem><para>Multiple response analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>MVA</literal>
</term><listitem><para>Missing value analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>NAIVEBAYES</literal>
</term><listitem><para>Small sample bayesian prediction
</para>
</listitem></varlistentry><varlistentry><term><literal>NLR</literal>
</term><listitem><para>Non Linear Regression
</para>
</listitem></varlistentry><varlistentry><term><literal>NOMREG</literal>
</term><listitem><para>Multinomial logistic regression
</para>
</listitem></varlistentry><varlistentry><term><literal>NONPAR CORR</literal>
</term><listitem><para>Nonparametric correlation
</para>
</listitem></varlistentry><varlistentry><term><literal>NUMBERED</literal>
</term><listitem>

</listitem></varlistentry><varlistentry><term><literal>OLAP CUBES</literal>
</term><listitem><para>On-line analytical processing
</para>
</listitem></varlistentry><varlistentry><term><literal>OMS</literal>
</term><listitem><para>Output management
</para>
</listitem></varlistentry><varlistentry><term><literal>ORTHOPLAN</literal>
</term><listitem><para>Orthogonal effects design
</para>
</listitem></varlistentry><varlistentry><term><literal>OVERALS</literal>
</term><listitem><para>Nonlinear canonical correlation
</para>
</listitem></varlistentry><varlistentry><term><literal>PACF</literal>
</term><listitem><para>Partial autocorrelation
</para>
</listitem></varlistentry><varlistentry><term><literal>PARTIAL CORR</literal>
</term><listitem><para>Partial correlation
</para>
</listitem></varlistentry><varlistentry><term><literal>PLANCARDS</literal>
</term><listitem><para>Conjoint analysis planning
</para>
</listitem></varlistentry><varlistentry><term><literal>PLUM</literal>
</term><listitem><para>Estimate ordinal regression models
</para>
</listitem></varlistentry><varlistentry><term><literal>POINT</literal>
</term><listitem><para>Marker in keyed file
</para>
</listitem></varlistentry><varlistentry><term><literal>PPLOT</literal>
</term><listitem><para>Plot time series variables
</para>
</listitem></varlistentry><varlistentry><term><literal>PREDICT</literal>
</term><listitem><para>Specify forecast period
</para>
</listitem></varlistentry><varlistentry><term><literal>PREFSCAL</literal>
</term><listitem><para>Multidimensional unfolding
</para>
</listitem></varlistentry><varlistentry><term><literal>PRINCALS</literal>
</term><listitem><para>PCA by alternating least squares
</para>
</listitem></varlistentry><varlistentry><term><literal>PROBIT</literal>
</term><listitem><para>Probit analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>PROCEDURE OUTPUT</literal>
</term><listitem><para>Specify output file
</para>
</listitem></varlistentry><varlistentry><term><literal>PROXIMITIES</literal>
</term><listitem><para>Pairwise similarity
</para>
</listitem></varlistentry><varlistentry><term><literal>PROXSCAL</literal>
</term><listitem><para>Multidimensional scaling of proximity data
</para>
</listitem></varlistentry><varlistentry><term><literal>RATIO STATISTICS</literal>
</term><listitem><para>Descriptives of ratios
</para>
</listitem></varlistentry><varlistentry><term><literal>READ MODEL</literal>
</term><listitem><para>Read new model
</para>
</listitem></varlistentry><varlistentry><term><literal>RECORD TYPE</literal>
</term><listitem><para>Defines a type of record within FILE TYPE
</para>
</listitem></varlistentry><varlistentry><term><literal>REFORMAT</literal>
</term><listitem><para>Read obsolete files
</para>
</listitem></varlistentry><varlistentry><term><literal>REPEATING DATA</literal>
</term><listitem><para>Specify multiple cases per input record
</para>
</listitem></varlistentry><varlistentry><term><literal>REPORT</literal>
</term><listitem><para>Pretty print working file
</para>
</listitem></varlistentry><varlistentry><term><literal>RMV</literal>
</term><listitem><para>Replace missing values
</para>
</listitem></varlistentry><varlistentry><term><literal>SCRIPT</literal>
</term><listitem><para>Run script file
</para>
</listitem></varlistentry><varlistentry><term><literal>SEASON</literal>
</term><listitem><para>Estimate seasonal factors
</para>
</listitem></varlistentry><varlistentry><term><literal>SELECTPRED</literal>
</term><listitem><para>Select predictor variables
</para>
</listitem></varlistentry><varlistentry><term><literal>SPCHART</literal>
</term><listitem><para>Plot control charts
</para>
</listitem></varlistentry><varlistentry><term><literal>SPECTRA</literal>
</term><listitem><para>Plot spectral density
</para>
</listitem></varlistentry><varlistentry><term><literal>STEMLEAF</literal>
</term><listitem><para>Plot stem-and-leaf display
</para>
</listitem></varlistentry><varlistentry><term><literal>SUMMARIZE</literal>
</term><listitem><para>Univariate statistics
</para>
</listitem></varlistentry><varlistentry><term><literal>SURVIVAL</literal>
</term><listitem><para>Survival analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>TDISPLAY</literal>
</term><listitem><para>Display active models
</para>
</listitem></varlistentry><varlistentry><term><literal>TREE</literal>
</term><listitem><para>Create classification tree
</para>
</listitem></varlistentry><varlistentry><term><literal>TSAPPLY</literal>
</term><listitem><para>Apply time series model
</para>
</listitem></varlistentry><varlistentry><term><literal>TSET</literal>
</term><listitem><para>Set time sequence variables
</para>
</listitem></varlistentry><varlistentry><term><literal>TSHOW</literal>
</term><listitem><para>Show time sequence variables
</para>
</listitem></varlistentry><varlistentry><term><literal>TSMODEL</literal>
</term><listitem><para>Estimate time series model
</para>
</listitem></varlistentry><varlistentry><term><literal>TSPLOT</literal>
</term><listitem><para>Plot time sequence variables
</para>
</listitem></varlistentry><varlistentry><term><literal>TWOSTEP CLUSTER</literal>
</term><listitem><para>Cluster observations
</para>
</listitem></varlistentry><varlistentry><term><literal>UNIANOVA</literal>
</term><listitem><para>Univariate analysis
</para>
</listitem></varlistentry><varlistentry><term><literal>UNNUMBERED</literal>
</term><listitem><para>obsolete
</para>
</listitem></varlistentry><varlistentry><term><literal>VALIDATEDATA</literal>
</term><listitem><para>Identify suspicious cases
</para>
</listitem></varlistentry><varlistentry><term><literal>VARCOMP</literal>
</term><listitem><para>Estimate variance
</para>
</listitem></varlistentry><varlistentry><term><literal>VARSTOCASES</literal>
</term><listitem><para>Restructure complex data
</para>
</listitem></varlistentry><varlistentry><term><literal>VERIFY</literal>
</term><listitem><para>Report time series
</para>
</listitem></varlistentry><varlistentry><term><literal>WLS</literal>
</term><listitem><para>Weighted least squares regression
</para>
</listitem></varlistentry><varlistentry><term><literal>XGRAPH</literal>
</term><listitem><para>High resolution charts
</para>
</listitem></varlistentry></variablelist><!-- Local Variables: -->
<!-- buffer-read-only: t -->
<!-- End: -->

</chapter>
<chapter label="20" id="Bugs">
<title>Bugs</title>

<indexterm role="cp"><primary>bugs</primary></indexterm>
<indexterm role="cp"><primary>troubleshooting</primary></indexterm>

<para>Occasionally you may encounter a bug in pspp.
</para>
<sect1 label="20.1">
<title>When to report bugs</title>

<para>If you discover a bug, please first:
</para><itemizedlist><listitem><para>Make sure that it really is a bug.  Sometimes, what may appear
to be a bug, turns out to be a misunderstanding of how to use the program.
If you are unsure, ask for advice on the pspp-users mailing list.  
Information about the mailing list is at <ulink url="http://lists.gnu.org/mailman/listinfo/pspp-users">http://lists.gnu.org/mailman/listinfo/pspp-users</ulink>.
</para></listitem><listitem><para>Try an up to date version of pspp; the problem 
 may have been recently fixed. 
</para></listitem><listitem><para>If the problem persists in the up to date version, check to see
 if it has already been reported.  Reported issues are listed 
 at <ulink url="http://savannah.gnu.org/bugs/?group=pspp">http://savannah.gnu.org/bugs/?group=pspp</ulink>.
 For known issues in individual language features, see the relevant section in see <link linkend="Language">Language</link>.
</para></listitem><listitem><para>If the problem exists in a recent version and it has not already 
 been reported, then please report it.
</para></listitem></itemizedlist>

</sect1>
<sect1 label="20.2">
<title>How to report bugs</title>

<para>The best way to send a bug report is using the web page at
<ulink url="http://savannah.gnu.org/bugs/?group=pspp">http://savannah.gnu.org/bugs/?group=pspp</ulink>.
Alternatively, bug reports may be sent by email
to <email>bug-gnu-pspp@gnu.org</email>.
</para>
<para>In your bug report please include:
</para><itemizedlist><listitem><para>The version of pspp in which you encountered the problem.
That means the precise version number.  Do not simply say &#8220;the latest version&#8221; &#8212;
releases happen quickly, and bug reports are archived indefinitely.
</para></listitem><listitem><para>The operating system and type of computer on which it is running.  On a GNU 
or other unix-like system, the output from the <literal>uname</literal> command is helpful.
</para></listitem><listitem><para>A sample of the syntax which causes the problem or, if it is a user
 interface problem, the sequence of steps required to reproduce it.
 Screen shots are not usually helpful unless you are reporting a bug in
 the graphical user interface itself.
</para></listitem><listitem><para>A description of what you think is wrong: What happened that you 
  didn&#8217;t expect, and what did you expect to happen?
</para></listitem></itemizedlist>
<para>The following is an example of a useful bug report:
</para><screen>When I run PSPP 0.8.4 on the system:
&quot;Linux knut 3.5.3-gnu #1 PREEMPT Tue Aug 28 10:49:41 UTC 2012 mips64 GNU/Linux&quot;
Executing the following syntax:

 DATA LIST FREE /x *.
 BEGIN DATA.
 1 2 3
 END DATA.
 LIST.

results in:

 4
 5
 6

I think the output should be:

 1
 2
 3
</screen><para>Here, the developers have the necessary information to reproduce the circumstances of the bug report,
and they understand what the reporter expected.
</para>

<para>Conversely, the following is a useless bug report:
</para>
<screen>I downloaded the latest version of PSPP and entered a sequence of numbers, 
but when I analyse them it gives the wrong output.
</screen><para>In that example, it is impossible to reproduce, and there is no indication
of why the reporter thought what he saw was wrong.
</para>
<para>Note that the purpose of bug reports is to help improve the quality of pspp 
for the benefit of all users.
It is not a consultancy or support service.  If that is what you want, you are welcome to make
private arrangements.  Since pspp is free software, consultants have access to
the information they need to provide such support.
The pspp developers appreciate all users&#8217; feedback, but cannot promise an immediate response.
</para>
<para>Please do not use the bug reporting address for general enquiries or to seek 
help in using, installing or running the program.  
For that, use the pspp-users mailing list mentioned above.
</para>

</sect1>
</chapter>
<chapter label="21" id="Function-Index">
<title>Function Index</title>
<index role="fn"></index>
</chapter>
<chapter label="22" id="Command-Index">
<title>Command Index</title>
<index role="vr"></index>
</chapter>
<chapter label="23" id="Concept-Index">
<title>Concept Index</title>
<index role="cp"></index>

</chapter>
<appendix label="A" id="GNU-Free-Documentation-License">
<title>GNU Free Documentation License</title>

<!-- The GNU Free Documentation License. -->
Version 1.3, 3 November 2008

<!-- This file is intended to be included within another document, -->
<!-- hence no sectioning command or @node. -->

<literallayout>Copyright &#169; 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
<ulink url="http://fsf.org/">http://fsf.org/</ulink>

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
</literallayout>
<orderedlist numeration="arabic"><listitem><para>PREAMBLE
</para>
<para>The purpose of this License is to make a manual, textbook, or other
functional and useful document <firstterm>free</firstterm> in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
</para>
<para>This License is a kind of &#8220;copyleft&#8221;, which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft
license designed for free software.
</para>
<para>We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.
</para>
</listitem><listitem><para>APPLICABILITY AND DEFINITIONS
</para>
<para>This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License.  Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein.  The &#8220;Document&#8221;, below,
refers to any such manual or work.  Any member of the public is a
licensee, and is addressed as &#8220;you&#8221;.  You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
</para>
<para>A &#8220;Modified Version&#8221; of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
</para>
<para>A &#8220;Secondary Section&#8221; is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document&#8217;s overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject.  (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
</para>
<para>The &#8220;Invariant Sections&#8221; are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.  If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant.  The Document may contain zero
Invariant Sections.  If the Document does not identify any Invariant
Sections then there are none.
</para>
<para>The &#8220;Cover Texts&#8221; are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.  A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
</para>
<para>A &#8220;Transparent&#8221; copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters.  A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text.  A copy that is not &#8220;Transparent&#8221; is called &#8220;Opaque&#8221;.
</para>
<para>Examples of suitable formats for Transparent copies include plain
ascii without markup, Texinfo input format, La&tex; input
format, <acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly available
<acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym>,
PostScript or <acronym>PDF</acronym> designed for human modification.  Examples
of transparent image formats include <acronym>PNG</acronym>, <acronym>XCF</acronym> and
<acronym>JPG</acronym>.  Opaque formats include proprietary formats that can be
read and edited only by proprietary word processors, <acronym>SGML</acronym> or
<acronym>XML</acronym> for which the <acronym>DTD</acronym> and/or processing tools are
not generally available, and the machine-generated <acronym>HTML</acronym>,
PostScript or <acronym>PDF</acronym> produced by some word processors for
output purposes only.
</para>
<para>The &#8220;Title Page&#8221; means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, &#8220;Title Page&#8221; means
the text near the most prominent appearance of the work&#8217;s title,
preceding the beginning of the body of the text.
</para>
<para>The &#8220;publisher&#8221; means any person or entity that distributes copies
of the Document to the public.
</para>
<para>A section &#8220;Entitled XYZ&#8221; means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language.  (Here XYZ stands for a
specific section name mentioned below, such as &#8220;Acknowledgements&#8221;,
&#8220;Dedications&#8221;, &#8220;Endorsements&#8221;, or &#8220;History&#8221;.)  To &#8220;Preserve the Title&#8221;
of such a section when you modify the Document means that it remains a
section &#8220;Entitled XYZ&#8221; according to this definition.
</para>
<para>The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document.  These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
</para>
</listitem><listitem><para>VERBATIM COPYING
</para>
<para>You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.
</para>
<para>You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
</para>
</listitem><listitem><para>COPYING IN QUANTITY
</para>
<para>If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document&#8217;s license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present
the full title with all words of the title equally prominent and
visible.  You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
</para>
<para>If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
</para>
<para>If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
</para>
<para>It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
</para>
</listitem><listitem><para>MODIFICATIONS
</para>
<para>You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it.  In addition, you must do these things in the Modified Version:
</para>
<orderedlist numeration="upperalpha"><listitem><para>Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document).  You may use the same title as a previous version
if the original publisher of that version gives permission.
</para>
</listitem><listitem><para>List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
</para>
</listitem><listitem><para>State on the Title page the name of the publisher of the
Modified Version, as the publisher.
</para>
</listitem><listitem><para>Preserve all the copyright notices of the Document.
</para>
</listitem><listitem><para>Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
</para>
</listitem><listitem><para>Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
</para>
</listitem><listitem><para>Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document&#8217;s license notice.
</para>
</listitem><listitem><para>Include an unaltered copy of this License.
</para>
</listitem><listitem><para>Preserve the section Entitled &#8220;History&#8221;, Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page.  If
there is no section Entitled &#8220;History&#8221; in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
</para>
</listitem><listitem><para>Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on.  These may be placed in the &#8220;History&#8221; section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
</para>
</listitem><listitem><para>For any section Entitled &#8220;Acknowledgements&#8221; or &#8220;Dedications&#8221;, Preserve
the Title of the section, and preserve in the section all the
substance and tone of each of the contributor acknowledgements and/or
dedications given therein.
</para>
</listitem><listitem><para>Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles.  Section numbers
or the equivalent are not considered part of the section titles.
</para>
</listitem><listitem><para>Delete any section Entitled &#8220;Endorsements&#8221;.  Such a section
may not be included in the Modified Version.
</para>
</listitem><listitem><para>Do not retitle any existing section to be Entitled &#8220;Endorsements&#8221; or
to conflict in title with any Invariant Section.
</para>
</listitem><listitem><para>Preserve any Warranty Disclaimers.
</para></listitem></orderedlist>
<para>If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version&#8217;s license notice.
These titles must be distinct from any other section titles.
</para>
<para>You may add a section Entitled &#8220;Endorsements&#8221;, provided it contains
nothing but endorsements of your Modified Version by various
parties&#8212;for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
</para>
<para>You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity.  If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
</para>
<para>The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
</para>
</listitem><listitem><para>COMBINING DOCUMENTS
</para>
<para>You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
</para>
<para>The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
</para>
<para>In the combination, you must combine any sections Entitled &#8220;History&#8221;
in the various original documents, forming one section Entitled
&#8220;History&#8221;; likewise combine any sections Entitled &#8220;Acknowledgements&#8221;,
and any sections Entitled &#8220;Dedications&#8221;.  You must delete all
sections Entitled &#8220;Endorsements.&#8221;
</para>
</listitem><listitem><para>COLLECTIONS OF DOCUMENTS
</para>
<para>You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
</para>
<para>You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
</para>
</listitem><listitem><para>AGGREGATION WITH INDEPENDENT WORKS
</para>
<para>A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an &#8220;aggregate&#8221; if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation&#8217;s users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
</para>
<para>If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document&#8217;s Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
</para>
</listitem><listitem><para>TRANSLATION
</para>
<para>Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers.  In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
</para>
<para>If a section in the Document is Entitled &#8220;Acknowledgements&#8221;,
&#8220;Dedications&#8221;, or &#8220;History&#8221;, the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
</para>
</listitem><listitem><para>TERMINATION
</para>
<para>You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense, or distribute it is void, and
will automatically terminate your rights under this License.
</para>
<para>However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
</para>
<para>Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
</para>
<para>Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License.  If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.
</para>
</listitem><listitem><para>FUTURE REVISIONS OF THIS LICENSE
</para>
<para>The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time.  Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.  See
<ulink url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.
</para>
<para>Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License &#8220;or any later version&#8221; applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.  If the Document
specifies that a proxy can decide which future versions of this
License can be used, that proxy&#8217;s public statement of acceptance of a
version permanently authorizes you to choose that version for the
Document.
</para>
</listitem><listitem><para>RELICENSING
</para>
<para>&#8220;Massive Multiauthor Collaboration Site&#8221; (or &#8220;MMC Site&#8221;) means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works.  A
public wiki that anybody can edit is an example of such a server.  A
&#8220;Massive Multiauthor Collaboration&#8221; (or &#8220;MMC&#8221;) contained in the
site means any set of copyrightable works thus published on the MMC
site.
</para>
<para>&#8220;CC-BY-SA&#8221; means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
</para>
<para>&#8220;Incorporate&#8221; means to publish or republish a Document, in whole or
in part, as part of another Document.
</para>
<para>An MMC is &#8220;eligible for relicensing&#8221; if it is licensed under this
License, and if all works that were first published under this License
somewhere other than this MMC, and subsequently incorporated in whole
or in part into the MMC, (1) had no cover texts or invariant sections,
and (2) were thus incorporated prior to November 1, 2008.
</para>
<para>The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.
</para>
</listitem></orderedlist>
<bridgehead renderas="sect1">ADDENDUM: How to use this License for your documents</bridgehead>

<para>To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
</para>
<screen>  Copyright (C)  <replaceable>year</replaceable>  <replaceable>your name</replaceable>.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.
</screen>
<para>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the &#8220;with&#8230;Texts.&#8221; line with this:
</para>
<screen>    with the Invariant Sections being <replaceable>list their titles</replaceable>, with
    the Front-Cover Texts being <replaceable>list</replaceable>, and with the Back-Cover Texts
    being <replaceable>list</replaceable>.
</screen>
<para>If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
</para>
<para>If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
</para>
<!-- Local Variables: -->
<!-- ispell-local-pdict: "ispell-dict" -->
<!-- End: -->


</appendix>
</book>