1 \input texinfo @c -*- texinfo -*-
5 @set TIMESTAMP Time-stamp: Sat Dec 20 20:25:33 WST 2003 jmd
8 @c For double-sided printing, uncomment:
9 @c @setchapternewpage odd
22 * PSPP: (pspp). Statistical analysis package.
26 PSPP, for statistical analysis of sampled data, by Ben Pfaff.
28 This file documents PSPP, a statistical package for analysis of
29 sampled data that uses a command language compatible with SPSS.
31 Copyright (C) 1996-9, 2000 Free Software Foundation, Inc.
33 This version of the PSPP documentation is consistent with version 2 of
36 Permission is granted to make and distribute verbatim copies of this
37 manual provided the copyright notice and this permission notice are
38 preserved on all copies.
41 Permission is granted to process this file through TeX and print the
42 results, provided the printed document carries copying permission notice
43 identical to this one except for the removal of this paragraph (this
44 paragraph not being relevant to the printed manual).
47 Permission is granted to copy and distribute modified versions of this
48 manual under the conditions for verbatim copying, provided that the
49 entire resulting derived work is distributed under the terms of a
50 permission notice identical to this one.
52 Permission is granted to copy and distribute translations of this
53 manual into another language, under the above condition for modified
54 versions, except that this permission notice may be stated in a
55 translation approved by the Free Software Foundation.
60 @subtitle A System for Statistical Analysis
61 @subtitle Edition @value{EDITION}, for PSPP version @value{VERSION}
65 @vskip 0pt plus 1filll
67 PSPP Copyright @copyright{} 1997, 1998 Free Software Foundation, Inc.
69 Permission is granted to make and distribute verbatim copies of this
70 manual provided the copyright notice and this permission notice are
71 preserved on all copies.
73 Permission is granted to copy and distribute modified versions of this
74 manual under the conditions for verbatim copying, provided that the
75 entire derived work is distributed under the terms of a permission
76 notice identical to this one.
78 Permission is granted to copy and distribute translations of this manual
79 into another language, under the above conditions for modified versions,
80 except that this permission notice may be stated in a translation
81 approved by the Foundation.
84 @node Top, Introduction, (dir), (dir)
88 This file documents the PSPP package for statistical analysis of sampled
89 data. This is edition @value{EDITION}, for PSPP version
90 @value{VERSION}, last modified at @value{TIMESTAMP}.
95 * Introduction:: Description of the package.
96 * License:: Your rights and obligations.
97 * Credits:: Acknowledgement of authors.
99 * Installation:: How to compile and install PSPP.
100 * Configuration:: Configuring PSPP.
101 * Invocation:: Starting and running PSPP.
103 * Language:: Basics of the PSPP command language.
104 * Expressions:: Numeric and string expression syntax.
106 * Data Input and Output:: Reading data from user files.
107 * System and Portable Files:: Dealing with system & portable files.
108 * Variable Attributes:: Adjusting and examining variables.
109 * Data Manipulation:: Simple operations on data.
110 * Data Selection:: Select certain cases for analysis.
111 * Conditionals and Looping:: Doing things many times or not at all.
112 * Statistics:: Basic statistical procedures.
113 * Utilities:: Other commands.
114 * Not Implemented:: What's not here yet
116 * Data File Format:: Format of PSPP system files.
117 * Portable File Format:: Format of PSPP portable files.
118 * q2c Input Format:: Format of syntax accepted by q2c.
120 * Bugs:: Known problems; submitting bug reports.
122 * Function Index:: Index of PSPP functions for expressions.
123 * Concept Index:: Index of concepts.
124 * Command Index:: Index of PSPP procedures.
128 @node Introduction, License, Top, Top
129 @chapter Introduction
132 @cindex PSPP language
133 @cindex language, PSPP
134 PSPP is a tool for statistical analysis of sampled data. It reads a
135 syntax file and a data file, analyzes the data, and writes the results
136 to a listing file or to standard output.
138 The language accepted by PSPP is similar to those accepted by SPSS
139 statistical products. The details of PSPP's language are given
140 later in this manual.
147 @cindex Free Software Foundation
148 PSPP produces output in two forms: tables and charts. Both of these can
149 be written in several formats; currently, ASCII, PostScript, and HTML
150 are supported. In the future, more drivers, such as PCL and X Window
151 System drivers, may be developed. For now, Ghostscript, available from
152 the Free Software Foundation, may be used to convert PostScript chart
153 output to other formats.
155 The current version of PSPP, @value{VERSION}, is woefully incomplete in
156 terms of its statistical procedure support. PSPP is a work in progress.
157 The author hopes to support fully support all features in the products
158 that PSPP replaces, eventually. The author welcomes questions,
159 comments, donations, and code submissions. @xref{Bugs,,Submitting Bug
160 Reports}, for instructions on contacting the author.
162 @node License, Credits, Introduction, Top
163 @chapter Your rights and obligations
165 @cindex your rights and obligations
167 @cindex obligations, your
169 @cindex Free Software Foundation
170 @cindex GNU General Public License
171 @cindex General Public License
174 @cindex redistribution
175 Most of PSPP is distributed under the GNU General Public
176 License. The General Public License says, in effect, that you may
177 modify and distribute PSPP as you like, as long as you grant the
178 same rights to others. It also states that you must provide source code
179 when you distribute PSPP, or, if you obtained PSPP
180 source code from an anonymous ftp site, give out the name of that site.
182 The General Public License is given in full in the source distribution
183 as file @file{COPYING}. In Debian GNU/Linux, this file is also
184 available as file @file{/usr/share/common-licenses/GPL-2}.
186 To quote the GPL itself:
189 This program is free software; you can redistribute it and/or modify it
190 under the terms of the GNU General Public License as published by the
191 Free Software Foundation; either version 2 of the License, or (at your
192 option) any later version.
194 This program is distributed in the hope that it will be useful, but
195 WITHOUT ANY WARRANTY; without even the implied warranty of
196 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
197 General Public License for more details.
199 You should have received a copy of the GNU General Public License along
200 with this program; if not, write to the Free Software Foundation, Inc.,
201 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
204 @node Credits, Installation, License, Top
210 Most of PSPP, as well as this manual,
211 was written by Ben Pfaff. @xref{Contacting the Author}, for
212 instructions on contacting the author.
214 @cindex Covington, Michael A.
215 @cindex Van Zandt, James
216 @cindex @file{ftp.cdrom.com}
217 @cindex @file{/pub/algorithms/c/julcal10}
218 @cindex @file{julcal.c}
219 @cindex @file{julcal.h}
220 The PSPP source code incorporates @code{julcal10} originally
221 written by Michael A. Covington and translated into C by Jim Van Zandt.
222 The original package can be found in directory
223 @url{ftp://ftp.cdrom.com/pub/algorithms/c/julcal10}. The entire
224 contents of that directory constitute the package. The files actually
225 used in PSPP are @code{julcal.c} and @code{julcal.h}.
227 @node Installation, Configuration, Credits, Top
228 @chapter Installing PSPP
230 @cindex PSPP, installing
232 @cindex GNU C compiler
234 @cindex compiler, recommended
235 @cindex compiler, gcc
236 PSPP conforms to the GNU Coding Standards. PSPP is written in, and
237 requires for proper operation, ANSI/ISO C. You might want to
238 additionally note the following points:
242 The compiler and linker must allow for significance of several
243 characters in external identifiers. The exact number is unknown but at
244 least 31 is recommended.
247 The @code{int} type must be 32 bits or wider.
250 The recommended compiler is gcc 2.7.2.1 or later, but any ANSI compiler
251 will do if it fits the above criteria.
254 Many UNIX variants should work out-of-the-box, as PSPP uses GNU
255 autoconf to detect differences between environments. Please report any
256 problems with compilation of PSPP under UNIX and UNIX-like operating
257 systems---portability is a major concern of the author.
259 The pages below give specific instructions for installing PSPP
260 on each type of system mentioned above.
263 * UNIX installation:: Installing on UNIX-like environments.
266 @node UNIX installation, , Installation, Installation
267 @section UNIX installation
268 @cindex UNIX, installing PSPP under
269 @cindex installation, under UNIX
271 To install PSPP under a UNIX-like operating system, follow the steps
272 below in order. Some of the text below was taken directly from various
273 Free Software Foundation sources.
277 @code{cd} to the directory containing the PSPP source.
279 @cindex configure, GNU
280 @cindex GNU configure
282 Type @samp{./configure} to configure for your particular operating
283 system and compiler. Running @code{configure} takes a while. While
284 running, it displays some messages telling which features it is checking
287 You can optionally supply some options to @code{configure} to
288 give it hints about how to do its job. Type @code{./configure --help}
289 to see a list of options. One of the most useful options is
290 @samp{--with-checker}, which enables the use of the Checker memory
291 debugger under supported operating systems. Checker must already be
292 installed to use this option. Do not use @samp{--with-checker} if you
293 are not debugging PSPP itself.
295 @cindex @file{Makefile}
296 @cindex @file{config.h}
297 @cindex @file{pref.h}
300 (optional) Edit @file{Makefile}, @file{config.h}, and @file{pref.h}.
301 These files are produced by @code{configure}. Note that most PSPP
302 settings can be changed at runtime.
304 @file{pref.h} is only generated by @code{configure} if it does not
305 already exist. (It's copied from @file{prefh.orig}.)
309 Type @samp{make} to compile the package. If there are any errors during
310 compilation, try to fix them. If modifications are necessary to compile
311 correctly under your configuration, contact the author.
312 @xref{Bugs,,Submitting Bug Reports}, for details.
314 @cindex self-tests, running
316 Type @samp{make check} to run self-tests on the compiled PSPP package.
319 @cindex PSPP, installing
320 @cindex @file{/usr/local/share/pspp/}
321 @cindex @file{/usr/local/bin/}
322 @cindex @file{/usr/local/info/}
323 @cindex documentation, installing
325 Become the superuser and type @samp{make install} to install the
326 PSPP binaries, by default in @file{/usr/local/bin/}. The
327 directory @file{/usr/local/share/pspp/} is created and populated with
328 files needed by PSPP at runtime. This step will also cause the
329 PSPP documentation to be installed in @file{/usr/local/info/},
330 but only if that directory already exists.
333 (optional) Type @samp{make clean} to delete the PSPP binaries
334 from the source tree.
337 @node Configuration, Invocation, Installation, Top
338 @chapter Configuring PSPP
339 @cindex configuration
340 @cindex PSPP, configuring
342 PSPP has dozens of configuration possibilities and hundreds of
343 settings. This is both a bane and a blessing. On one hand, it's
344 possible to easily accommodate diverse ranges of setups. But, on the
345 other, the multitude of possibilities can overwhelm the casual user.
346 Fortunately, the configuration mechanisms are profusely described in the
347 sections below@enddots{}
350 * File locations:: How PSPP finds config files.
351 * Configuration techniques:: Many different methods of configuration@enddots{}
352 * Configuration files:: How configuration files are read.
353 * Environment variables:: All about environment variables.
354 * Output devices:: Describing your terminal(s) and printer(s).
355 * PostScript driver class:: Configuration of PostScript devices.
356 * ASCII driver class:: Configuration of character-code devices.
357 * HTML driver class:: Configuration for HTML output.
358 * Miscellaneous configuring:: Even more configuration variables.
359 * Improving output quality:: Hints for producing ever-more-lovely output.
362 @node File locations, Configuration techniques, Configuration, Configuration
363 @section Locating configuration files
365 PSPP uses the same method to find most of its configuration files:
369 The @dfn{base name} of the file being sought is determined.
372 The path to search is determined.
375 Each directory in the search path, from left to right, is searched for a
376 file with the name of the base name. The first occurrence is read
377 as the configuration file.
380 The first two steps are elaborated below for the sake of our pedantic
385 A @dfn{base name} is a file name lacking an absolute directory
386 reference. Some examples of base names are: @file{ps-encodings},
387 @file{devices}, @file{devps/DESC} (under UNIX), @file{devps\DESC} (under
390 Determining the base name is a two-step process:
394 If the appropriate environment variable is defined, the value of that
395 variable is used (@pxref{Environment variables}). For instance, when
396 searching for the output driver initialization file, the variable
397 examined is @code{STAT_OUTPUT_INIT_FILE}.
400 Otherwise, the compiled-in default is used. For example, when searching
401 for the output driver initialization file, the default base name is
405 @strong{Please note:} If a user-specified base name does contain an
406 absolute directory reference, as in a file name like
407 @file{/home/pfaff/fonts/TR}, no path is searched---the file name is used
408 exactly as given---and the algorithm terminates.
411 The path is the first of the following that is defined:
415 A variable definition for the path given in the user environment. This
416 is a PSPP-specific environment variable name; for instance,
417 @code{STAT_OUTPUT_INIT_PATH}.
420 In some cases, another, less-specific environment variable is checked.
421 For instance, when searching for font files, the PostScript driver first
422 checks for a variable with name @code{STAT_GROFF_FONT_PATH}, then for
423 one with name @code{GROFF_FONT_PATH}. (However, font searching has its
424 own list of esoteric search rules.)
427 The configuration file path, which is itself determined by the
432 If the command line contains an option of the form @samp{-B @var{path}}
433 or @samp{--config-dir=@var{path}}, then the value given on the
434 rightmost occurrence of such an option is used.
437 Otherwise, if the environment variable @code{STAT_CONFIG_PATH} is
438 defined, the value of that variable is used.
441 Otherwise, the compiled-in fallback default is used. On UNIX machines,
442 the default fallback path is
449 @file{/usr/local/lib/pspp}
455 On DOS machines, the default fallback path is:
459 All the paths from the DOS search path in the @samp{PATH} environment
460 variable, in left-to-right order.
463 @file{C:\PSPP}, as a last resort.
466 Note that the installer of PSPP can easily change this default
467 fallback path; thus the above should not be taken as gospel.
472 As a final note: Under DOS, directories given in paths are delimited by
473 semicolons (@samp{;}); under UNIX, directories are delimited by colons
474 (@samp{:}). This corresponds with the standard path delimiter under
477 @node Configuration techniques, Configuration files, File locations, Configuration
478 @section Configuration techniques
480 There are many ways that PSPP can be configured. These are
481 described in the list below. Values given by earlier items take
482 precedence over those given by later items.
486 Syntax commands that modify settings, such as @cmd{SET}. @xref{SET}.
489 Command-line options. @xref{Invocation}.
492 PSPP-specific environment variable contents. @xref{Environment
496 General environment variable contents. @xref{Environment variables}.
499 Configuration file contents. @xref{Configuration files}.
505 Some of the above may not apply to a particular setting. For instance,
506 the current pager (such as @samp{more}, @samp{most}, or @samp{less})
507 cannot be determined by configuration file contents because there is no
508 appropriate configuration file.
510 @node Configuration files, Environment variables, Configuration techniques, Configuration
511 @section Configuration files
513 Most configuration files have a common form:
517 Each line forms a separate command or directive. This means that lines
518 cannot be broken up, unless they are spliced together with a trailing
519 backslash, as described below.
522 Before anything else is done, trailing whitespace is removed.
525 When a line ends in a backslash (@samp{\}), the backslash is removed,
526 and the next line is read and appended to the current line.
530 Whitespace preceding the backslash is retained.
533 This rule continues to be applied until the line read does not end in a
537 It is an error if the last line in the file ends in a backslash.
541 Comments are introduced by an octothorpe (@samp{#}), and continue until the
546 An octothorpe inside balanced pairs of double quotation marks (@samp{"})
547 or single quotation marks (@samp{'}) does not introduce a comment.
550 The backslash character can be used inside balanced quotes of either
551 type to escape the following character as a literal character.
553 (This is distinct from the use of a backslash as a line-splicing
557 Line splicing takes place before comment removal.
561 Blank lines, and lines that contain only whitespace, are ignored.
564 @node Environment variables, Output devices, Configuration files, Configuration
565 @section Environment variables
567 You may think the concept of environment variables is a fairly simple
568 one. However, the author of PSPP has found a way to complicate
569 even something so simple. Environment variables are further described
570 in the sections below:
573 * Variable values:: Values of variables are determined this way.
574 * Environment substitutions:: How environment substitutions are made.
575 * Predefined variables:: A few variables are automatically defined.
578 @node Variable values, Environment substitutions, Environment variables, Environment variables
579 @subsection Values of environment variables
581 Values for environment variables are obtained by the following means,
582 which are arranged in order of decreasing precedence:
586 Command-line options. @xref{Invocation}.
589 The @file{environment} configuration file---more on this below.
592 Actual environment variables (defined in the shell or other parent
596 The @file{environment} configuration file is located through application
597 of the usual algorithm for configuration files (@pxref{File locations}),
598 except that its contents do not affect the search path used to find
599 @file{environment} itself. Use of @file{environment} is discouraged on
600 systems that allow an arbitrarily large environment; it is supported for
601 use on systems like MS-DOS that limit environment size.
603 @file{environment} is composed of lines having the form
604 @samp{@var{key}=@var{value}}, where @var{key} and the equals sign
605 (@samp{=}) are required, and @var{value} is optional. If @var{value} is
606 given, variable @var{key} is given that value; if @var{value} is absent,
607 variable @var{key} is undefined (deleted). Variables may not be defined
610 Environment substitutions are performed on each line in the file
611 (@pxref{Environment substitutions}).
613 See @ref{Configuration files}, for more details on formatting of the
614 environment configuration file.
617 @strong{Please note:} Support for @file{environment} is not yet
621 @node Environment substitutions, Predefined variables, Variable values, Environment variables
622 @subsection Environment substitutions
624 Much of the power of environment variables lies in the way that they may
625 be substituted into configuration files. Variable substitutions are
628 The line is scanned from left to right. In this scan, all characters
629 other than dollar signs (@samp{$}) are retained unmolested. Dollar
630 signs, however, introduce an environment variable reference. References
635 Replaced by the value of environment variable @var{var}, determined as
636 specified in @ref{Variable values}. @var{var} must be one of the
644 Exactly one nonalphabetic character. This may not be a left brace
649 Same as above, but @var{var} may contain any character (except
653 Replaced by a single dollar sign.
656 Undefined variables expand to a empty value.
658 @node Predefined variables, , Environment substitutions, Environment variables
659 @subsection Predefined environment variables
661 There are two environment variables predefined for use in environment
666 Defined as the version number of PSPP, as a string, in a format
667 something like @samp{0.9.4}.
670 Defined as the host architecture of PSPP, as a string, in standard
671 cpu-manufacturer-OS format. For instance, Debian GNU/Linux 1.1 on an
672 Intel machine defines this as @samp{i586-unknown-linux}. This is
673 somewhat dependent on the system used to compile PSPP.
676 Nothing prevents these values from being overridden, although it's a
677 good idea not to do so.
679 @node Output devices, PostScript driver class, Environment variables, Configuration
680 @section Output devices
682 Configuring output devices is the most complicated aspect of configuring
683 PSPP. The output device configuration file is named
684 @file{devices}. It is searched for using the usual algorithm for
685 finding configuration files (@pxref{File locations}). Each line in the
686 file is read in the usual manner for configuration files
687 (@pxref{Configuration files}).
689 Lines in @file{devices} are divided into three categories, described
690 briefly in the table below:
693 @item driver category definitions
694 Define a driver in terms of other drivers.
696 @item macro definitions
697 Define environment variables local to the the output driver
700 @item device definitions
701 Describe the configuration of an output device.
704 The following sections further elaborate the contents of the
708 * Driver categories:: How to organize the driver namespace.
709 * Macro definitions:: Environment variables local to @file{devices}.
710 * Device definitions:: Output device descriptions.
711 * Dimensions:: Lengths, widths, sizes, @enddots{}
712 * papersize:: Letter, legal, A4, envelope, @enddots{}
713 * Distinguishing line types:: Details on @file{devices} parsing.
714 * Tokenizing lines:: Dividing @file{devices} lines into tokens.
717 @node Driver categories, Macro definitions, Output devices, Output devices
718 @subsection Driver categories
720 Drivers can be divided into categories. Drivers are specified by their
721 names, or by the names of the categories that they are contained in.
722 Only certain drivers are enabled each time PSPP is run; by
723 default, these are the drivers in the category `default'. To enable a
724 different set of drivers, use the @samp{-o @var{device}} command-line
725 option (@pxref{Invocation}).
727 Categories are specified with a line of the form
728 @samp{@var{category}=@var{driver1} @var{driver2} @var{driver3} @var{@dots{}}
729 @var{driver@var{n}}}. This line specifies that the category
730 @var{category} is composed of drivers named @var{driver1},
731 @var{driver2}, and so on. There may be any number of drivers in the
732 category, from zero on up.
734 Categories may also be specified on the command line
735 (@pxref{Invocation}).
737 This is all you need to know about categories. If you're still curious,
740 First of all, the term `categories' is a bit of a misnomer. In fact,
741 the internal representation is nothing like the hierarchy that the term
742 seems to imply: a linear list is used to keep track of the enabled
745 When PSPP first begins reading @file{devices}, this list contains
746 the name of any drivers or categories specified on the command line, or
747 the single item `default' if none were specified.
749 Each time a category definition is specified, the list is searched for
750 an item with the value of @var{category}. If a matching item is found,
751 it is deleted. If there was a match, the list of drivers (@var{driver1}
752 through @var{driver@var{n}}) is then appended to the list.
754 Each time a driver definition line is encountered, the list is searched.
755 If the list contains an item with that driver's name, the driver is
756 enabled and the item is deleted from the list. Otherwise, the driver
759 It is an error if the list is not empty when the end of @file{devices}
762 @node Macro definitions, Device definitions, Driver categories, Output devices
763 @subsection Macro definitions
765 Macro definitions take the form @samp{define @var{macroname}
766 @var{definition}}. In such a macro definition, the environment variable
767 @var{macroname} is defined to expand to the value @var{definition}.
768 Before the definition is made, however, any macros used in
769 @var{definition} are expanded.
771 Please note the following nuances of macro usage:
775 For the purposes of this section, @dfn{macro} and @dfn{environment
776 variable} are synonyms.
779 Macros may not take arguments.
782 Macros may not recurse.
785 Macros are just environment variable definitions like other environment
786 variable definitions, with the exception that they are limited in scope
787 to the @file{devices} configuration file.
790 Macros override other all environment variables of the same name (within
791 the scope of @file{devices}).
794 Earlier macro definitions for a particular @var{key} override later
795 ones. In particular, macro definitions on the command line override
796 those in the device definition file. @xref{Non-option Arguments}.
799 There are two predefined macros, whose values are determined at runtime:
803 Defined as the width of the console screen, in columns of text.
806 Defined as the length of the console screen, in lines of text.
810 @node Device definitions, Dimensions, Macro definitions, Output devices
811 @subsection Driver definitions
813 Driver definitions are the ultimate purpose of the @file{devices}
814 configuration file. These are where the real action is. Driver
815 definitions tell PSPP where it should send its output.
817 Each driver definition line is divided into four fields. These fields
818 are delimited by colons (@samp{:}). Each line is subjected to
819 environment variable interpolation before it is processed further
820 (@pxref{Environment substitutions}). From left to right, the four
821 fields are, in brief:
825 A unique identifier, used to determine whether to enable the driver.
828 One of the predefined driver classes supported by PSPP. The
829 currently supported driver classes include `postscript' and `ascii'.
832 Zero or more of the following keywords, delimited by spaces:
837 Indicates that the device is a screen display. This may reduce the
838 amount of buffering done by the driver, to make interactive use more
843 Indicates that the device is a printer.
847 Indicates that the device is a listing file.
850 These options are just hints to PSPP and do not cause the output to be
851 directed to the screen, or to the printer, or to a listing file---those
852 must be set elsewhere in the options. They are used primarily to decide
853 which devices should be enabled at any given time. @xref{SET}, for more
857 An optional set of options to pass to the driver itself. The exact
858 format for the options varies among drivers.
861 The driver is enabled if:
865 Its driver name is specified on the command line, or
868 It's in a category specified on the command line, or
871 If no categories or driver names are specified on the command line, it
872 is in category @code{default}.
875 For more information on driver names, see @ref{Driver categories}.
877 The class name must be one of those supported by PSPP. The
878 classes supported depend on the options with which PSPP was
879 compiled. See later sections in this chapter for descriptions of the
880 available driver classes.
882 Options are dependent on the driver. See the driver descriptions for
885 @node Dimensions, papersize, Device definitions, Output devices
886 @subsection Dimensions
888 Quite often in configuration it is necessary to specify a length or a
889 size. PSPP uses a common syntax for all such, calling them
890 collectively by the name @dfn{dimensions}.
894 You can specify dimensions in decimal form (@samp{12.5}) or as
895 fractions, either as mixed numbers (@samp{12-1/2}) or raw fractions
899 A number of different units are available. These are suffixed to the
900 numeric part of the dimension. There must be no spaces between the
901 number and the unit. The available units are identical to those offered
902 by the popular typesetting system @TeX{}:
906 inch (1 @code{in} = 2.54 @code{cm})
909 inch (1 @code{in} = 2.54 @code{cm})
912 printer's point (1 @code{in} = 72.27 @code{pt})
915 pica (12 @code{pt} = 1 @code{pc})
918 PostScript point (1 @code{in} = 72 @code{bp})
924 millimeter (10 @code{mm} = 1 @code{cm})
927 didot point (1157 @code{dd} = 1238 @code{pt})
930 cicero (1 @code{cc} = 12 @code{dd})
933 scaled point (65536 @code{sp} = 1 @code{pt})
937 If no explicit unit is given, PSPP attempts to guess the best unit:
941 Numbers less than 50 are assumed to be in inches.
944 Numbers 50 or greater are assumed to be in millimeters.
948 @node papersize, Distinguishing line types, Dimensions, Output devices
949 @subsection Paper sizes
951 Output drivers usually deal with some sort of hardcopy media. This
952 media is called @dfn{paper} by the drivers, though in reality it could
953 be a transparency or film or thinly veiled sarcasm. To make it easier
954 for you to deal with paper, PSPP allows you to have (of course!) a
955 configuration file that gives symbolic names, like ``letter'' or
956 ``legal'' or ``a4'', to paper sizes, rather than forcing you to use
957 cryptic numbers like ``8-1/2 x 11'' or ``210 by 297''. Surprisingly
958 enough, this configuration file is named @file{papersize}.
959 @xref{Configuration files}.
961 When PSPP tries to connect a symbolic paper name to a paper size, it
962 reads and parses each non-comment line in the file, in order. The first
963 field on each line must be a symbolic paper name in double quotes.
964 Paper names may not contain double quotes. Paper names are not
965 case-sensitive: @samp{legal} and @samp{Legal} are equivalent.
967 If a match is found for the paper name, the rest of the line is parsed.
968 If it is found to be a pair of dimensions (@pxref{Dimensions}) separated
969 by either @samp{x} or @samp{by}, then those are taken to be the paper
970 size, in order of width followed by length. There @emph{must} be at
971 least one space on each side of @samp{x} or @samp{by}.
973 Otherwise the line must be of the form
974 @samp{"@var{paper-1}"="@var{paper-2}"}. In this case the target of the
975 search becomes paper name @var{paper-2} and the search through the file
978 @node Distinguishing line types, Tokenizing lines, papersize, Output devices
979 @subsection How lines are divided into types
981 The lines in @file{devices} are distinguished in the following manner:
985 Leading whitespace is removed.
988 If the resulting line begins with the exact string @code{define},
989 followed by one or more whitespace characters, the line is processed as
993 Otherwise, the line is scanned for the first instance of a colon
994 (@samp{:}) or an equals sign (@samp{=}).
997 If a colon is encountered first, the line is processed as a driver
1001 Otherwise, if an equals sign is encountered, the line is processed as a
1005 Otherwise, the line is ill-formed.
1008 @node Tokenizing lines, , Distinguishing line types, Output devices
1009 @subsection How lines are divided into tokens
1011 Each driver definition line is run through a simple tokenizer. This
1012 tokenizer recognizes two basic types of tokens.
1014 The first type is an equals sign (@samp{=}). Equals signs are both
1015 delimiters between tokens and tokens in themselves.
1017 The second type is an identifier or string token. Identifiers and
1018 strings are equivalent after tokenization, though they are written
1019 differently. An identifier is any string of characters other than
1020 whitespace or equals sign.
1022 A string is introduced by a single- or double-quote character (@samp{'}
1023 or @samp{"}) and, in general, continues until the next occurrence of
1024 that same character. The following standard C escapes can also be
1025 embedded within strings:
1029 A single-quote (@samp{'}).
1032 A double-quote (@samp{"}).
1035 A question mark (@samp{?}). Included for hysterical raisins.
1038 A backslash (@samp{\}).
1041 Audio bell (ASCII 7).
1044 Backspace (ASCII 8).
1047 Formfeed (ASCII 12).
1053 Carriage return (ASCII 13).
1059 Vertical tab (ASCII 11).
1061 @item \@var{o}@var{o}@var{o}
1062 Each @samp{o} must be an octal digit. The character is the one having
1063 the octal value specified. Any number of octal digits is read and
1064 interpreted; only the lower 8 bits are used.
1066 @item \x@var{h}@var{h}
1067 Each @samp{h} must be a hex digit. The character is the one having the
1068 hexadecimal value specified. Any number of hex digits is read and
1069 interpreted; only the lower 8 bits are used.
1072 Tokens, outside of quoted strings, are delimited by whitespace or equals
1075 @node PostScript driver class, ASCII driver class, Output devices, Configuration
1076 @section The PostScript driver class
1078 The @code{postscript} driver class is used to produce output that is
1079 acceptable to PostScript printers and to PC-based PostScript
1080 interpreters such as Ghostscript. Continuing a long tradition,
1081 PSPP's PostScript driver is configurable to the point of
1084 There are actually two PostScript drivers. The first one,
1085 @samp{postscript}, produces ordinary DSC-compliant PostScript output.
1086 The second one @samp{epsf}, produces an Encapsulated PostScript file.
1087 The two drivers are otherwise identical in configuration and in
1090 The PostScript driver is described in further detail below.
1093 * PS output options:: Output file options.
1094 * PS page options:: Paper, margins, scaling & rotation, more!
1095 * PS file options:: Configuration files.
1096 * PS font options:: Default fonts, font options.
1097 * PS line options:: Line widths, options.
1098 * Prologue:: Details on the PostScript prologue.
1099 * Encodings:: Details on PostScript font encodings.
1102 @node PS output options, PS page options, PostScript driver class, PostScript driver class
1103 @subsection PostScript output options
1105 These options deal with the form of the output and the output file
1109 @item output-file=@var{filename}
1111 File to which output should be sent. This can be an ordinary filename
1112 (i.e., @code{"pspp.ps"}), a pipe filename (i.e., @code{"|lpr"}), or
1113 stdout (@code{"-"}). Default: @code{"pspp.ps"}.
1115 @item color=@var{boolean}
1117 Most of the time black-and-white PostScript devices are smart enough to
1118 map colors to shades themselves. However, you can cause the PSPP
1119 output driver to do an ugly simulation of this in its own driver by
1120 turning @code{color} off. Default: @code{on}.
1122 This is a boolean setting, as are many settings in the PostScript
1123 driver. Valid positive boolean values are @samp{on}, @samp{true},
1124 @samp{yes}, and nonzero integers. Negative boolean values are
1125 @samp{off}, @samp{false}, @samp{no}, and zero.
1127 @item data=@var{data-type}
1129 One of @code{clean7bit}, @code{clean8bit}, or @code{binary}. This
1130 controls what characters will be written to the output file. PostScript
1131 produced with @code{clean7bit} can be transmitted over 7-bit
1132 transmission channels that use ASCII control characters for line
1133 control. @code{clean8bit} is similar but allows characters above 127 to
1134 be written to the output file. @code{binary} allows any character in
1135 the output file. Default: @code{clean7bit}.
1137 @item line-ends=@var{line-end-type}
1139 One of @code{cr}, @code{lf}, or @code{crlf}. This controls what is used
1140 for newline in the output file. Default: @code{cr}.
1142 @item optimize-line-size=@var{level}
1144 Either @code{0} or @code{1}. If @var{level} is @code{1}, then short
1145 line segments will be collected and merged into longer ones. This
1146 reduces output file size but requires more time and memory. A
1147 @var{level} of @code{0} has the advantage of being better for
1148 interactive environments. @code{1} is the default unless the
1149 @code{screen} flag is set; in that case, the default is @code{0}.
1151 @item optimize-text-size=@var{level}
1153 One of @code{0}, @code{1}, or @code{2}, each higher level representing
1154 correspondingly more aggressive space savings for text in the output
1155 file and requiring correspondingly more time and memory. Unfortunately
1156 the levels presently are all the same. @code{1} is the default unless
1157 the @code{screen} flag is set; in that case, the default is @code{0}.
1160 @node PS page options, PS file options, PS output options, PostScript driver class
1161 @subsection PostScript page options
1163 These options affect page setup:
1166 @item headers=@var{boolean}
1168 Controls whether the standard headers showing the time and date and
1169 title and subtitle are printed at the top of each page. Default:
1172 @item paper-size=@var{paper-size}
1174 Paper size, either as a symbolic name (i.e., @code{letter} or @code{a4})
1175 or specific measurements (i.e., @code{8-1/2x11} or @code{"210 x 297"}.
1176 @xref{papersize, , Paper sizes}. Default: @code{letter}.
1178 @item orientation=@var{orientation}
1180 Either @code{portrait} or @code{landscape}. Default: @code{portrait}.
1182 @item left-margin=@var{dimension}
1183 @itemx right-margin=@var{dimension}
1184 @itemx top-margin=@var{dimension}
1185 @itemx bottom-margin=@var{dimension}
1187 Sets the margins around the page. The headers, if enabled, are not
1188 included in the margins; they are in addition to the margins. For a
1189 description of dimensions, see @ref{Dimensions}. Default: @code{0.5in}.
1193 @node PS file options, PS font options, PS page options, PostScript driver class
1194 @subsection PostScript file options
1196 Oh, my. You don't really want to know about the way that the PostScript
1197 driver deals with files, do you? Well I suppose you're entitled, but I
1198 warn you right now: it's not pretty. Here goes@enddots{}
1200 First let's look at the options that are available:
1204 @item font-dir=@var{font-directory}
1206 Sets the font directory. Default: @code{devps}.
1208 @item prologue-file=@var{prologue-file-name}
1210 Sets the name of the PostScript prologue file. You can write your own
1211 prologue, though I have no idea why you'd want to: see @ref{Prologue}.
1212 Default: @code{ps-prologue}.
1214 @item device-file=@var{device-file-name}
1216 Sets the name of the Groff-format device description file. The
1217 PostScript driver reads this to know about the scaling of fonts
1218 and so on. The format of such files is described in groff_font(5),
1219 included with Groff. Default: @code{DESC}.
1221 @item encoding-file=@var{encoding-file-name}
1223 Sets the name of the encoding file. This file contains a list of all
1224 font encodings that will be needed so that the driver can put all of
1225 them at the top of the prologue. @xref{Encodings}. Default:
1226 @code{ps-encodings}.
1228 If the specified encoding file cannot be found, this error will be
1229 silently ignored, since most people do not need any encodings besides
1230 the ones that can be found using @code{auto-encodings}, described below.
1232 @item auto-encode=@var{boolean}
1234 When enabled, the font encodings needed by the default proportional- and
1235 fixed-pitch fonts will automatically be dumped to the PostScript
1236 output. Otherwise, it is assumed that the user has an encoding file
1237 and knows how to use it (@pxref{Encodings}). There is probably no good
1238 reason to turn off this convenient feature. Default: @code{on}.
1242 Next I suppose it's time to describe the search algorithm. When the
1243 PostScript driver needs a file, whether that file be a font, a
1244 PostScript prologue, or what you will, it searches in this manner:
1249 Constructs a path by taking the first of the following that is defined:
1254 Environment variable @code{STAT_GROFF_FONT_PATH}. @xref{Environment
1258 Environment variable @code{GROFF_FONT_PATH}.
1261 The compiled-in fallback default.
1265 Constructs a base name from concatenating, in order, the font directory,
1266 a path separator (@samp{/} or @samp{\}), and the file to be found. A
1267 typical base name would be something like @code{devps/ps-encodings}.
1270 Searches for the base name in the path constructed above. If the file
1271 is found, the algorithm terminates.
1274 Searches for the base name in the standard configuration path. See
1275 @ref{File locations}, for more details. If the file is found, the
1276 algorithm terminates.
1279 At this point we remove the font directory and path separator from the
1280 base name. Now the base name is simply the file to be found, i.e.,
1281 @code{ps-encodings}.
1284 Searches for the base name in the path constructed in the first step.
1285 If the file is found, the algorithm terminates.
1288 Searches for the base name in the standard configuration path. If the
1289 file is found, the algorithm terminates.
1292 The algorithm terminates unsuccessfully.
1295 So, as you see, there are several ways to configure the PostScript
1296 drivers. Careful selection of techniques can make the configuration
1297 very flexible indeed.
1299 @node PS font options, PS line options, PS file options, PostScript driver class
1300 @subsection PostScript font options
1302 The list of available font options is short and sweet:
1305 @item prop-font=@var{font-name}
1307 Sets the default proportional font. The name should be that of a
1308 PostScript font. Default: @code{"Helvetica"}.
1310 @item fixed-font=@var{font-name}
1312 Sets the default fixed-pitch font. The name should be that of a
1313 PostScript font. Default: @code{"Courier"}.
1315 @item font-size=@var{font-size}
1317 Sets the size of the default fonts, in thousandths of a point. Default:
1322 @node PS line options, Prologue, PS font options, PostScript driver class
1323 @subsection PostScript line options
1325 Most tables contain lines, or rules, between cells. Some features of
1326 the way that lines are drawn in PostScript tables are user-definable:
1330 @item line-style=@var{style}
1332 Sets the style used for lines used to divide tables into sections.
1333 @var{style} must be either @code{thick}, in which case thick lines are
1334 used, or @var{double}, in which case double lines are used. Default:
1337 @item line-gutter=@var{dimension}
1339 Sets the line gutter, which is the amount of whitespace on either side
1340 of lines that border text or graphics objects. @xref{Dimensions}.
1341 Default: @code{0.5pt}.
1343 @item line-spacing=@var{dimension}
1345 Sets the line spacing, which is the amount of whitespace that separates
1346 lines that are side by side, as in a double line. Default:
1349 @item line-width=@var{dimension}
1351 Sets the width of a typical line used in tables. Default: @code{0.5pt}.
1353 @item line-width-thick=@var{dimension}
1355 Sets the width of a thick line used in tables. Not used if
1356 @code{line-style} is set to @code{thick}. Default: @code{1.5pt}.
1360 @node Prologue, Encodings, PS line options, PostScript driver class
1361 @subsection The PostScript prologue
1363 Most PostScript files that are generated mechanically by programs
1364 consist of two parts: a prologue and a body. The prologue is generally
1365 a collection of boilerplate. Only the body differs greatly between
1366 two outputs from the same program.
1368 This is also the strategy used in the PSPP PostScript driver. In
1369 general, the prologue supplied with PSPP will be more than sufficient.
1370 In this case, you will not need to read the rest of this section.
1371 However, hackers might want to know more. Read on, if you fall into
1374 The prologue is dumped into the output stream essentially unmodified.
1375 However, two actions are performed on its lines. First, certain lines
1376 may be omitted as specified in the prologue file itself. Second,
1377 variables are substituted.
1379 The following lines are omitted:
1383 All lines that contain three bangs in a row (@code{!!!}).
1386 Lines that contain @code{!eps}, if the PostScript driver is producing
1387 ordinary PostScript output. Otherwise an EPS file is being produced,
1388 and the line is included in the output, although everything following
1389 @code{!eps} is deleted.
1392 Lines that contain @code{!ps}, if the PostScript driver is producing EPS
1393 output. Otherwise, ordinary PostScript is being produced, and the line
1394 is included in the output, although everything following @code{!ps} is
1398 The following are the variables that are substituted. Only the
1399 variables listed are substituted; environment variables are not.
1400 @xref{Environment substitutions}.
1405 The page bounding box, in points, as four space-separated numbers. For
1406 U.S. letter size paper, this is @samp{0 0 612 792}.
1410 PSPP version as a string: @samp{GNU PSPP 0.1b}, for example.
1414 Date the file was created. Example: @samp{Tue May 21 13:46:22 1991}.
1418 Value of the @code{data} PostScript driver option, as one of the strings
1419 @samp{Clean7Bit}, @samp{Clean8Bit}, or @samp{Binary}.
1423 Page orientation, as one of the strings @code{Portrait} or
1428 Under multiuser OSes, the user's login name, taken either from the
1429 environment variable @code{LOGNAME} or, if that fails, the result of the
1430 C library function @code{getlogin()}. Defaults to @samp{nobody}.
1434 System hostname as reported by @code{gethostname()}. Defaults to
1439 Name of the default proportional font, prefixed by the word
1440 @samp{font} and a space. Example: @samp{font Times-Roman}.
1444 Name of the default fixed-pitch font, prefixed by the word @samp{font}
1449 The page scaling factor as a floating-point number. Example:
1450 @code{1.0}. Note that this is also passed as an argument to the BP
1456 The paper length and paper width, respectively, in thousandths of a
1457 point. Note that these are also passed as arguments to the BP macro.
1462 The left margin and top margin, respectively, in thousandths of a
1463 point. Note that these are also passed as arguments to the BP macro.
1467 Document title as a string. This is not the title specified in the
1468 PSPP syntax file. A typical title is the word @samp{PSPP} followed
1469 by the syntax file name in parentheses. Example: @samp{PSPP
1474 PSPP syntax file name. Example: @samp{mary96/first.stat}.
1478 Any other questions about the PostScript prologue can best be answered
1479 by examining the default prologue or the PSPP source.
1481 @node Encodings, , Prologue, PostScript driver class
1482 @subsection PostScript encodings
1484 PostScript fonts often contain many more than 256 characters, in order
1485 to accommodate foreign language characters and special symbols.
1486 PostScript uses @dfn{encodings} to map these onto single-byte symbol
1487 sets. Each font can have many different encodings applied to it.
1489 PSPP's PostScript driver needs to know which encoding to apply to each
1490 font. It can determine this from the information encapsulated in the
1491 Groff font description that it reads. However, there is an additional
1492 problem---for efficiency, the PostScript driver needs to have a complete
1493 list of all encodings that will be used in the entire session @emph{when
1494 it opens the output file}. For this reason, it can't use the
1495 information built into the fonts because it doesn't know which fonts
1498 As a stopgap solution, there are two mechanisms for specifying which
1499 encodings will be used. The first mechanism is automatic and it is the
1500 only one that most PSPP users will ever need. The second mechanism is
1501 manual, but it is more flexible. Either mechanism or both may be used
1504 The first mechanism is activated by the @samp{auto-encode} driver option
1505 (@pxref{PS file options}). When enabled, @samp{auto-encode} causes the
1506 PostScript driver to include the encodings used by the default
1507 proportional and fixed-pitch fonts (@pxref{PS font options}). Many
1508 PSPP output files will only need these encodings.
1510 The second mechanism is the file specified by the @samp{encoding-file}
1511 option (@pxref{PS file options}). If it exists, this file must consist
1512 of lines in PSPP configuration-file format (@pxref{Configuration
1513 files}). Each line that is not a comment should name a PostScript
1514 encoding to include in the output.
1516 It is not an error if an encoding is included more than once, by either
1517 mechanism. It will appear only once in the output. It is also not an
1518 error if an encoding is included in the output but never used. It
1519 @emph{is} an error if an encoding is used but not included by one of
1520 these mechanisms. In this case, the built-in PostScript encoding
1521 @samp{ISOLatin1Encoding} is substituted.
1523 @node ASCII driver class, HTML driver class, PostScript driver class, Configuration
1524 @section The ASCII driver class
1526 The ASCII driver class produces output that can be displayed on a
1527 terminal or output to printers. All of its options are highly
1528 configurable. The ASCII driver has class name @samp{ascii}.
1530 The ASCII driver is described in further detail below.
1533 * ASCII output options:: Output file options.
1534 * ASCII page options:: Page size, margins, more.
1535 * ASCII font options:: Box character, bold & italics.
1538 @node ASCII output options, ASCII page options, ASCII driver class, ASCII driver class
1539 @subsection ASCII output options
1542 @item output-file=@var{filename}
1544 File to which output should be sent. This can be an ordinary filename
1545 (e.g., @code{"pspp.txt"}), a pipe filename (e.g., @code{"|lpr"}), or
1546 stdout (@code{"-"}). Default: @code{"pspp.list"}.
1548 @item char-set=@var{char-set-type}
1550 One of @samp{ascii} or @samp{latin1}. This has no effect on output at
1551 the present time. Default: @code{ascii}.
1553 @item form-feed-string=@var{form-feed-value}
1555 The string written to the output to cause a formfeed. See also
1556 @code{paginate}, described below, for a related setting. Default:
1559 @item newline-string=@var{newline-value}
1561 The string written to the output to cause a newline (carriage return
1562 plus linefeed). The default, which can be specified explicitly with
1563 @code{newline-string=default}, is to use the system-dependent newline
1564 sequence by opening the output file in text mode. This is usually the
1567 However, @code{newline-string} can be set to any string. When this is
1568 done, the output file is opened in binary mode.
1570 @item paginate=@var{boolean}
1572 If set, a formfeed (as set in @code{form-feed-string}, described above)
1573 will be written to the device after every page. Default: @code{on}.
1575 @item tab-width=@var{tab-width-value}
1577 The distance between tab stops for this device. If set to 0, tabs will
1578 not be used in the output. Default: @code{8}.
1580 @item init=@var{initialization-string}.
1582 String written to the device before anything else, at the beginning of
1583 the output. Default: @code{""} (the empty string).
1585 @item done=@var{finalization-string}.
1587 String written to the device after everything else, at the end of the
1588 output. Default: @code{""} (the empty string).
1591 @node ASCII page options, ASCII font options, ASCII output options, ASCII driver class
1592 @subsection ASCII page options
1594 These options affect page setup:
1597 @item headers=@var{boolean}
1599 If enabled, two lines of header information giving title and subtitle,
1600 page number, date and time, and PSPP version are printed at the top of
1601 every page. These two lines are in addition to any top margin
1602 requested. Default: @code{on}.
1604 @item length=@var{line-count}
1606 Physical length of a page, in lines. Headers and margins are subtracted
1607 from this value. Default: @code{66}.
1609 @item width=@var{character-count}
1611 Physical width of a page, in characters. Margins are subtracted from
1612 this value. Default: @code{130}.
1614 @item lpi=@var{lines-per-inch}
1616 Number of lines per vertical inch. Not currently used. Default: @code{6}.
1618 @item cpi=@var{characters-per-inch}
1620 Number of characters per horizontal inch. Not currently used. Default:
1623 @item left-margin=@var{left-margin-width}
1625 Width of the left margin, in characters. PSPP subtracts this value
1626 from the page width. Default: @code{0}.
1628 @item right-margin=@var{right-margin-width}
1630 Width of the right margin, in characters. PSPP subtracts this value
1631 from the page width. Default: @code{0}.
1633 @item top-margin=@var{top-margin-lines}
1635 Length of the top margin, in lines. PSPP subtracts this value from
1636 the page length. Default: @code{2}.
1638 @item bottom-margin=@var{bottom-margin-lines}
1640 Length of the bottom margin, in lines. PSPP subtracts this value from
1641 the page length. Default: @code{2}.
1645 @node ASCII font options, , ASCII page options, ASCII driver class
1646 @subsection ASCII font options
1648 These are the ASCII font options:
1651 @item box[@var{line-type}]=@var{box-chars}
1653 The characters used for lines in tables produced by the ASCII driver can
1654 be changed using this option. @var{line-type} is used to indicate which
1655 type of line to change; @var{box-chars} is the character or string of
1656 characters to use for this type of line.
1658 @var{line-type} must be a 4-digit number in base 4. The digits are in
1659 the order `right', `bottom', `left', `top'. The four possibilities for
1673 Special device-defined line, if one is available; otherwise, a double
1682 Sets @samp{|} as the character to use for a single-width line with
1683 bottom and top components.
1687 Sets @samp{#} as the character to use for the intersection of four
1688 double-width lines, one each from the top, bottom, left and right.
1690 @item box[1100]="\xda"
1692 Sets @samp{"\xda"}, which under MS-DOS is a box character suitable for
1693 the top-left corner of a box, as the character for the intersection of
1694 two single-width lines, one each from the right and bottom.
1702 @code{box[0000]=" "}
1705 @code{box[1000]="-"}
1706 @*@code{box[0010]="-"}
1707 @*@code{box[1010]="-"}
1710 @code{box[0100]="|"}
1711 @*@code{box[0001]="|"}
1712 @*@code{box[0101]="|"}
1715 @code{box[2000]="="}
1716 @*@code{box[0020]="="}
1717 @*@code{box[2020]="="}
1720 @code{box[0200]="#"}
1721 @*@code{box[0002]="#"}
1722 @*@code{box[0202]="#"}
1725 @code{box[3000]="="}
1726 @*@code{box[0030]="="}
1727 @*@code{box[3030]="="}
1730 @code{box[0300]="#"}
1731 @*@code{box[0003]="#"}
1732 @*@code{box[0303]="#"}
1735 For all others, @samp{+} is used unless there are double lines or
1736 special lines, in which case @samp{#} is used.
1739 @item italic-on=@var{italic-on-string}
1741 Character sequence written to turn on italics or underline printing. If
1742 this is set to @code{overstrike}, then the driver will simulate
1743 underlining by overstriking with underscore characters (@samp{_}) in the
1744 manner described by @code{overstrike-style} and
1745 @code{carriage-return-style}. Default: @code{overstrike}.
1747 @item italic-off=@var{italic-off-string}
1749 Character sequence to turn off italics or underline printing. Default:
1750 @code{""} (the empty string).
1752 @item bold-on=@var{bold-on-string}
1754 Character sequence written to turn on bold or emphasized printing. If
1755 set to @code{overstrike}, then the driver will simulated bold printing
1756 by overstriking characters in the manner described by
1757 @code{overstrike-style} and @code{carriage-return-style}. Default:
1760 @item bold-off=@var{bold-off-string}
1762 Character sequence to turn off bold or emphasized printing. Default:
1763 @code{""} (the empty string).
1765 @item bold-italic-on=@var{bold-italic-on-string}
1767 Character sequence written to turn on bold-italic printing. If set to
1768 @code{overstrike}, then the driver will simulate bold-italics by
1769 overstriking twice, once with the character, a second time with an
1770 underscore (@samp{_}) character, in the manner described by
1771 @code{overstrike-style} and @code{carriage-return-style}. Default:
1774 @item bold-italic-off=@var{bold-italic-off-string}
1776 Character sequence to turn off bold-italic printing. Default: @code{""}
1779 @item overstrike-style=@var{overstrike-option}
1781 Either @code{single} or @code{line}:
1785 If @code{single} is selected, then, to overstrike a line of text, the
1786 output driver will output a character, backspace, overstrike, output a
1787 character, backspace, overstrike, and so on along a line.
1790 If @code{line} is selected then the output driver will output an entire
1791 line, then backspace or emit a carriage return (as indicated by
1792 @code{carriage-return-style}), then overstrike the entire line at once.
1795 @code{single} is recommended for use with ttys and programs that
1796 understand overstriking in text files, such as the pager @code{less}.
1797 @code{single} will also work with printer devices but results in rapid
1798 back-and-forth motions of the printhead that can cause the printer to
1799 physically overheat!
1801 @code{line} is recommended for use with printer devices. Most programs
1802 that understand overstriking in text files will not properly deal with
1805 Default: @code{single}.
1807 @item carriage-return-style=@var{carriage-return-type}
1809 Either @code{bs} or @code{cr}. This option applies only when one or
1810 more of the font commands is set to @code{overstrike} and, at the same
1811 time, @code{overstrike-style} is set to @code{line}.
1815 If @code{bs} is selected then the driver will return to the beginning of
1816 a line by emitting a sequence of backspace characters (ASCII 8).
1819 If @code{cr} is selected then the driver will return to the beginning of
1820 a line by emitting a single carriage-return character (ASCII 13).
1823 Although @code{cr} is preferred as being more compact, @code{bs} is more
1824 general since some devices do not interpret carriage returns in the
1825 desired manner. Default: @code{bs}.
1828 @node HTML driver class, Miscellaneous configuring, ASCII driver class, Configuration
1829 @section The HTML driver class
1831 The @code{html} driver class is used to produce output for viewing in
1832 tables-capable web browsers such as Emacs' w3-mode. Its configuration
1833 is very simple. Currently, the output has a very plain format. In the
1834 future, further work may be done on improving the output appearance.
1836 There are few options for use with the @code{html} driver class:
1839 @item output-file=@var{filename}
1841 File to which output should be sent. This can be an ordinary filename
1842 (i.e., @code{"pspp.ps"}), a pipe filename (i.e., @code{"|lpr"}), or
1843 stdout (@code{"-"}). Default: @code{"pspp.html"}.
1845 @item prologue-file=@var{prologue-file-name}
1847 Sets the name of the PostScript prologue file. You can write your own
1848 prologue if you want to customize colors or other settings: see
1849 @ref{HTML Prologue}. Default: @code{html-prologue}.
1853 * HTML Prologue:: Format of the HTML prologue file.
1856 @node HTML Prologue, , HTML driver class, HTML driver class
1857 @subsection The HTML prologue
1859 HTML files that are generated by PSPP consist of two parts: a prologue
1860 and a body. The prologue is a collection of boilerplate. Only the body
1861 differs greatly between two outputs. You can tune the colors and other
1862 attributes of the output by editing the prologue.
1864 The prologue is dumped into the output stream essentially unmodified.
1865 However, two actions are performed on its lines. First, certain lines
1866 may be omitted as specified in the prologue file itself. Second,
1867 variables are substituted.
1869 The following lines are omitted:
1873 All lines that contain three bangs in a row (@code{!!!}).
1876 Lines that contain @code{!title}, if no title is set for the output. If
1877 a title is set, then the characters @code{!title} are removed before the
1881 Lines that contain @code{!subtitle}, if no subtitle is set for the
1882 output. If a subtitle is set, then the characters @code{!subtitle} are
1883 removed before the line is output.
1886 The following are the variables that are substituted. Only the
1887 variables listed are substituted; environment variables are not.
1888 @xref{Environment substitutions}.
1893 PSPP version as a string: @samp{GNU PSPP 0.1b}, for example.
1897 Date the file was created. Example: @samp{Tue May 21 13:46:22 1991}.
1901 Under multiuser OSes, the user's login name, taken either from the
1902 environment variable @code{LOGNAME} or, if that fails, the result of the
1903 C library function @code{getlogin()}. Defaults to @samp{nobody}.
1907 System hostname as reported by @code{gethostname()}. Defaults to
1912 Document title as a string. This is the title specified in the PSPP
1917 Document subtitle as a string.
1921 PSPP syntax file name. Example: @samp{mary96/first.stat}.
1924 @node Miscellaneous configuring, Improving output quality, HTML driver class, Configuration
1925 @section Miscellaneous configuration
1927 The following environment variables can be used to further configure
1933 Used to determine the user's home directory. No default value.
1935 @item STAT_INCLUDE_PATH
1937 Path used to find include files in PSPP syntax files. Defaults vary
1938 across operating systems:
1948 @file{~/.pspp/include}
1951 @file{/usr/local/lib/pspp/include}
1954 @file{/usr/lib/pspp/include}
1957 @file{/usr/local/share/pspp/include}
1960 @file{/usr/share/pspp/include}
1970 @file{C:\PSPP\INCLUDE}
1983 When PSPP invokes an external pager, it uses the first of these that
1984 is defined. There is a default pager only if the person who compiled
1989 The terminal type @code{termcap} or @code{ncurses} will use, if such
1990 support was compiled into PSPP.
1992 @item STAT_OUTPUT_INIT_FILE
1994 The basename used to search for the driver definition file.
1995 @xref{Output devices}. @xref{File locations}. Default: @code{devices}.
1997 @item STAT_OUTPUT_PAPERSIZE_FILE
1999 The basename used to search for the papersize file. @xref{papersize}.
2000 @xref{File locations}. Default: @code{papersize}.
2002 @item STAT_OUTPUT_INIT_PATH
2004 The path used to search for the driver definition file and the papersize
2005 file. @xref{File locations}. Default: the standard configuration path.
2009 The @code{sort} procedure stores its temporary files in this directory.
2010 Default: (UNIX) @file{/tmp}, (MS-DOS) @file{\}, (other OSes) empty string.
2015 Under MS-DOS only, these variables are consulted after TMPDIR, in this
2019 @node Improving output quality, , Miscellaneous configuring, Configuration
2020 @section Improving output quality
2022 When its drivers are set up properly, PSPP can produce output that
2023 looks very good indeed. The PostScript driver, suitably configured, can
2024 produce presentation-quality output. Here are a few guidelines for
2025 producing better-looking output, regardless of output driver. Your
2026 mileage may vary, of course, and everyone has different esthetic
2031 Width is important in PSPP output. Greater output width leads to more
2032 readable output, to a point. Try the following to increase the output
2037 If you're using the ASCII driver with a dot-matrix printer, figure out
2038 what you need to do to put the printer into compressed mode. Put that
2039 string into the @code{init-string} setting. Try to get 132 columns; 160
2040 might be better, but you might find that print that tiny is difficult to
2044 With the PostScript driver, try these ideas:
2051 Legal-size (8.5" x 14") paper in landscape mode.
2054 Reducing font sizes. If you're using 12-point fonts, try 10 point; if
2055 you're using 10-point fonts, try 8 point. Some fonts are more readable
2056 than others at small sizes.
2060 Try to strike a balance between character size and page width.
2063 Use high-quality fonts. Many public domain fonts are poor in quality.
2064 Recently, URW made some high-quality fonts available under the GPL.
2065 These are probably suitable.
2068 Be sure you're using the proper font metrics. The font metrics provided
2069 with PSPP may not correspond to the fonts actually being printed.
2070 This can cause bizarre-looking output.
2073 Make sure that you're using good ink/ribbon/toner. Darker print is
2077 Use plain fonts with serifs, such as Times-Roman or Palatino. Avoid
2078 choosing italic or bold fonts as document base fonts.
2081 @node Invocation, Language, Configuration, Top
2082 @chapter Invoking PSPP
2084 @cindex PSPP, invoking
2086 @cindex command line, options
2087 @cindex options, command-line
2089 pspp [ -B @var{dir} | --config-dir=@var{dir} ] [ -o @var{device} | --device=@var{device} ]
2090 [ -d @var{var}[=@var{value}] | --define=@var{var}[=@var{value}] ] [-u @var{var} | --undef=@var{var} ]
2091 [ -f @var{file} | --out-file=@var{file} ] [ -p | --pipe ] [ -I- | --no-include ]
2092 [ -I @var{dir} | --include=@var{dir} ] [ -i | --interactive ]
2093 [ -n | --edit | --dry-run | --just-print | --recon ]
2094 [ -r | --no-statrc ] [ -h | --help ] [ -l | --list ]
2095 [ -c @var{command} | --command @var{command} ] [ -s | --safer ]
2096 [ --testing-mode ] [ -V | --version ] [ -v | --verbose ]
2097 [ @var{key}=@var{value} ] @var{file}@enddots{}
2101 * Non-option Arguments:: Specifying syntax files and output devices.
2102 * Configuration Options:: Change the configuration for the current run.
2103 * Input and output options:: Controlling input and output files.
2104 * Language control options:: Language variants.
2105 * Informational options:: Helpful information about PSPP.
2108 @node Non-option Arguments, Configuration Options, Invocation, Invocation
2109 @section Non-option Arguments
2111 Syntax files and output device substitutions can be specified on
2112 PSPP's command line:
2117 A file by itself on the command line will be executed as a syntax file.
2118 PSPP terminates after the syntax file runs, unless the @code{-i} or
2119 @code{--interactive} option is given (@pxref{Language control options}).
2121 @item @var{file1} @var{file2}
2123 When two or more filenames are given on the command line, the first
2124 syntax file is executed, then PSPP's dictionary is cleared, then the second
2125 syntax file is executed.
2127 @item @var{file1} + @var{file2}
2129 If syntax files' names are delimited by a plus sign (@samp{+}), then the
2130 dictionary is not cleared between their executions, as if they were
2131 concatenated together into a single file.
2133 @item @var{key}=@var{value}
2135 Defines an output device macro @var{key} to expand to @var{value},
2136 overriding any macro having the same @var{key} defined in the device
2137 configuration file. @xref{Macro definitions}.
2141 There is one other way to specify a syntax file, if your operating
2142 system supports it. If you have a syntax file @file{foobar.stat}, put
2146 #! /usr/local/bin/pspp
2149 at the top, and mark the file as executable with @code{chmod +x
2150 foobar.stat}. (If PSPP is not installed in @file{/usr/local/bin},
2151 then insert its actual installation directory into the syntax file
2152 instead.) Now you should be able to invoke the syntax file just by
2153 typing its name. You can include any options on the command line as
2154 usual. PSPP entirely ignores any lines beginning with @samp{#!}.
2156 @node Configuration Options, Input and output options, Non-option Arguments, Invocation
2157 @section Configuration Options
2159 Configuration options are used to change PSPP's configuration for the
2160 current run. The configuration options are:
2164 @itemx --config-dir=@var{dir}
2166 Sets the configuration directory to @var{dir}. @xref{File locations}.
2168 @item -o @var{device}
2169 @itemx --device=@var{device}
2171 Selects the output device with name @var{device}. If this option is
2172 given more than once, then all devices mentioned are selected. This
2173 option disables all devices besides those mentioned on the command line.
2175 @item -d @var{var}[=@var{value}]
2176 @itemx --define=@var{var}[=@var{value}]
2178 Defines an `environment variable' named @var{var} having the optional
2179 value @var{value} specified. @xref{Variable values}.
2182 @itemx --undef=@var{var}
2184 Undefines the `environment variable' named @var{var}. @xref{Variable
2188 @node Input and output options, Language control options, Configuration Options, Invocation
2189 @section Input and output options
2191 Input and output options affect how PSPP reads input and writes
2192 output. These are the input and output options:
2196 @itemx --out-file=@var{file}
2198 This overrides the output file name for devices designated as listing
2199 devices. If a file named @var{file} already exists, it is overwritten.
2204 Allows PSPP to be used as a filter by causing the syntax file to be
2205 read from stdin and output to be written to stdout. Conflicts with the
2206 @code{-f @var{file}} and @code{--file=@var{file}} options.
2211 Clears all directories from the include path. This includes all
2212 directories put in the include path by default. @xref{Miscellaneous
2216 @itemx --include=@var{dir}
2218 Appends directory @var{dir} to the path that is searched for include
2219 files in PSPP syntax files.
2221 @item -c @var{command}
2222 @itemx --command=@var{command}
2224 Execute literal command @var{command}. The command is executed before
2225 startup syntax files, if any.
2227 @item --testing-mode
2229 Invoke heuristics to assist with testing PSPP. For use by @code{make
2230 check} and similar scripts.
2233 @node Language control options, Informational options, Input and output options, Invocation
2234 @section Language control options
2236 Language control options control how PSPP syntax files are parsed and
2237 interpreted. The available language control options are:
2241 @itemx --interactive
2243 When a syntax file is specified on the command line, PSPP normally
2244 terminates after processing it. Giving this option will cause PSPP to
2245 bring up a command prompt after processing the syntax file.
2247 In addition, this forces syntax files to be interpreted in interactive
2248 mode, rather than the default batch mode. @xref{Tokenizing lines}, for
2249 information on the differences between batch mode and interactive mode
2250 command interpretation.
2258 Only the syntax of any syntax file specified or of commands entered at
2259 the command line is checked. Transformations are not performed and
2260 procedures are not executed. Not yet implemented.
2265 Prevents the execution of the PSPP startup syntax file. Not yet
2266 implemented, as startup syntax files aren't, either.
2271 Disables certain unsafe operations. This includes the ERASE and
2272 HOST commands, as well as use of pipes as input and output files.
2275 @node Informational options, , Language control options, Invocation
2276 @section Informational options
2278 Informational options cause information about PSPP to be written to
2279 the terminal. Here are the available options:
2285 Prints a message describing PSPP command-line syntax and the available
2286 device driver classes, then terminates.
2291 Lists the available device driver classes, then terminates.
2296 Prints a brief message listing PSPP's version, warranties you don't
2297 have, copying conditions and copyright, and e-mail address for bug
2298 reports, then terminates.
2303 Increments PSPP's verbosity level. Higher verbosity levels cause
2304 PSPP to display greater amounts of information about what it is
2305 doing. Often useful for debugging PSPP's configuration.
2307 This option can be given multiple times to set the verbosity level to
2308 that value. The default verbosity level is 0, in which no informational
2309 messages will be displayed.
2311 Higher verbosity levels cause messages to be displayed when the
2312 corresponding events take place.
2317 Driver and subsystem initializations.
2321 Completion of driver initializations. Beginning of driver closings.
2325 Completion of driver closings.
2329 Files searched for; success of searches.
2333 Individual directories included in file searches.
2336 Each verbosity level also includes messages from lower verbosity levels.
2340 @node Language, Expressions, Invocation, Top
2341 @chapter The PSPP language
2342 @cindex language, PSPP
2343 @cindex PSPP, language
2346 @strong{Please note:} PSPP is not even close to completion.
2347 Only a few actual statistical procedures are implemented. PSPP
2348 is a work in progress.
2351 This chapter discusses elements common to many PSPP commands.
2352 Later chapters will describe individual commands in detail.
2355 * Tokens:: Characters combine to form tokens.
2356 * Commands:: Tokens combine to form commands.
2357 * Types of Commands:: Commands come in several flavors.
2358 * Order of Commands:: Commands combine to form syntax files.
2359 * Missing Observations:: Handling missing observations.
2360 * Variables:: The unit of data storage.
2361 * Files:: Files used by PSPP.
2362 * BNF:: How command syntax is described.
2365 @node Tokens, Commands, Language, Language
2367 @cindex language, lexical analysis
2368 @cindex language, tokens
2370 @cindex lexical analysis
2373 PSPP divides most syntax file lines into series of short chunks
2374 called @dfn{tokens}, @dfn{lexical elements}, or @dfn{lexemes}. These
2375 tokens are then grouped to form commands, each of which tells
2376 PSPP to take some action---read in data, write out data, perform
2377 a statistical procedure, etc. The process of dividing input into tokens
2378 is @dfn{tokenization}, or @dfn{lexical analysis}. Each type of token is
2383 Tokens must be separated from each other by @dfn{delimiters}.
2384 Delimiters include whitespace (spaces, tabs, carriage returns, line
2385 feeds, vertical tabs), punctuation (commas, forward slashes, etc.), and
2386 operators (plus, minus, times, divide, etc.) Note that while whitespace
2387 only separates tokens, other delimiters are tokens in themselves.
2392 Identifiers are names that specify variable names, commands, or command
2397 The first character in an identifier must be a letter, @samp{#}, or
2398 @samp{@@}. Some system identifiers begin with @samp{$}, but
2399 user-defined variables' names may not begin with @samp{$}.
2402 The remaining characters in the identifier must be letters, digits, or
2403 one of the following special characters:
2410 @cindex variable names
2411 @cindex names, variable
2412 Variable names may be any length, but only the first 8 characters are
2416 @cindex case-sensitivity
2417 Identifiers are not case-sensitive: @code{foobar}, @code{Foobar},
2418 @code{FooBar}, @code{FOOBAR}, and @code{FoObaR} are different
2419 representations of the same identifier.
2423 Identifiers other than variable names may be abbreviated to their first
2424 3 characters if this abbreviation is unambiguous. These identifiers are
2425 often called @dfn{keywords}. (Unique abbreviations of 3 or more
2426 characters are also accepted: @samp{FRE}, @samp{FREQ}, and
2427 @samp{FREQUENCIES} are equivalent when the last is a keyword.)
2430 Whether an identifier is a keyword depends on the context.
2433 @cindex keywords, reserved
2434 @cindex reserved keywords
2435 Some keywords are reserved. These keywords may not be used in any
2436 context besides those explicitly described in this manual. The reserved
2440 ALL AND BY EQ GE GT LE LT NE NOT OR TO WITH
2444 Since keywords are identifiers, all the rules for identifiers apply.
2445 Specifically, they must be delimited as are other identifiers:
2446 @code{WITH} is a reserved keyword, but @code{WITHOUT} is a valid
2452 @cindex variable names, ending with period
2453 @strong{Caution:} It is legal to end a variable name with a period, but
2454 @emph{don't do it!} The variable name will be misinterpreted when it is
2455 the final token on a line: @code{FOO.} will be divided into two separate
2456 tokens, @samp{FOO} and @samp{.}, the @dfn{terminal dot}.
2457 @xref{Commands, , Forming commands of tokens}.
2463 Numbers may be specified as integers or reals. Integers are internally
2464 converted into reals. Scientific notation is not supported. Here are
2465 some examples of valid numbers:
2468 1234 3.14159265359 .707106781185 8945.
2471 @strong{Caution:} The last example will be interpreted as two tokens,
2472 @samp{8945} and @samp{.}, if it is the last token on a line.
2478 @cindex case-sensitivity
2479 Strings are literal sequences of characters enclosed in pairs of single
2480 quotes (@samp{'}) or double quotes (@samp{"}).
2484 Whitespace and case of letters @emph{are} significant inside strings.
2486 Whitespace characters inside a string are not delimiters.
2488 To include single-quote characters in a string, enclose the string in
2491 To include double-quote characters in a string, enclose the string in
2494 It is not possible to put both single- and double-quote characters
2500 Hexstrings are string variants that use hex digits to specify
2505 A hexstring may be used anywhere that an ordinary string is allowed.
2510 A hexstring begins with @samp{X'} or @samp{x'}, and ends with @samp{'}.
2514 No whitespace is allowed between the initial @samp{X} and @samp{'}.
2517 Double quotes @samp{"} may be used in place of single quotes @samp{'} if
2518 done in both places.
2521 Each pair of hex digits is internally changed into a single character
2522 with the given value.
2525 If there is an odd number of hex digits, the missing last digit is
2526 assumed to be @samp{0}.
2530 @strong{Please note:} Use of hexstrings is nonportable because the same
2531 numeric values are associated with different glyphs by different
2532 operating systems. Therefore, their use should be confined to syntax
2533 files that will not be widely distributed.
2536 @cindex characters, reserved
2539 @strong{Please note also:} The character with value 00 is reserved for
2540 internal use by PSPP. Its use in strings causes an error and
2541 replacement with a blank space (in ASCII, hex 20, decimal 32).
2546 Punctuation separates tokens; punctuators are delimiters. These are the
2547 punctuation characters:
2555 Operators describe mathematical operations. Some operators are delimiters:
2561 Many of the above operators are also punctuators. Punctuators are
2562 distinguished from operators by context.
2564 The other operators are all reserved keywords. None of these are
2568 AND EQ GE GT LE LT NE OR
2572 @cindex terminal dot
2573 @cindex dot, terminal
2576 A period (@samp{.}) at the end of a line (except for whitespace) is one
2577 type of a @dfn{terminal dot}, although not every terminal dot is a
2578 period at the end of a line. @xref{Commands, , Forming commands of
2579 tokens}. A period is a terminal dot @emph{only}
2580 when it is at the end of a line; otherwise it is part of a
2581 floating-point number. (A period outside a number in the middle of a
2585 @cindex terminal dot, changing
2586 @cindex dot, terminal, changing
2587 @strong{Please note:} The character used for the @dfn{terminal dot}
2588 can be changed with @cmd{SET}'s ENDCMD subcommand (@pxref{SET}). This
2589 is strongly discouraged, and throughout all the remainder of this
2590 manual it will be assumed that the default setting is in effect.
2595 @node Commands, Types of Commands, Tokens, Language
2596 @section Forming commands of tokens
2598 @cindex PSPP, command structure
2599 @cindex language, command structure
2600 @cindex commands, structure
2602 Most PSPP commands share a common structure, diagrammed below:
2605 @var{cmd}@dots{} [@var{sbc}[=][@var{spec} [[,]@var{spec}]@dots{}]] [[/[=][@var{spec} [[,]@var{spec}]@dots{}]]@dots{}].
2609 In the above, rather daunting, expression, pairs of square brackets
2610 (@samp{[ ]}) indicate optional elements, and names such as @var{cmd}
2611 indicate parts of the syntax that vary from command to command.
2612 Ellipses (@samp{...}) indicate that the preceding part may be repeated
2613 an arbitrary number of times. Let's pick apart what it says above:
2616 @cindex commands, names
2618 A command begins with a command name of one or more keywords, such as
2619 @cmd{FREQUENCIES}, @cmd{DATA LIST}, or @cmd{N OF CASES}. @var{cmd}
2620 may be abbreviated to its first word if that is unambiguous; each word
2621 in @var{cmd} may be abbreviated to a unique prefix of three or more
2622 characters as described above.
2626 The command name may be followed by one or more @dfn{subcommands}:
2630 Each subcommand begins with a unique keyword, indicated by @var{sbc}
2631 above. This is analogous to the command name.
2634 The subcommand name is optionally followed by an equals sign (@samp{=}).
2637 Some subcommands accept a series of one or more specifications
2638 (@var{spec}), optionally separated by commas.
2641 Each subcommand must be separated from the next (if any) by a forward
2645 @cindex dot, terminal
2646 @cindex terminal dot
2648 Each command must be terminated with a @dfn{terminal dot}.
2649 The terminal dot may be given one of three ways:
2653 (most commonly) A period character at the very end of a line, as
2657 (only if NULLINE is on: @xref{SET, , Setting user preferences}, for more
2658 details.) A completely blank line.
2661 (in batch mode only) Any line that is not indented from the left side of
2662 the page causes a terminal dot to be inserted before that line.
2663 Therefore, each command begins with a line that is flush left, followed
2664 by zero or more lines that are indented one or more characters from the
2667 In batch mode, PSPP will ignore a plus sign, minus sign, or period
2668 (@samp{+}, @samp{@minus{}}, or @samp{.}) as the first character in a
2669 line. Any of these characters as the first character on a line will
2670 begin a new command. This allows for visual indentation of a command
2671 without that command being considered part of the previous command.
2673 PSPP is in batch mode when it is reading input from a file, rather
2674 than from an interactive user. Note that the other forms of the
2675 terminal dot may also be used in batch mode.
2677 Sometimes, one encounters syntax files that are intended to be
2678 interpreted in interactive mode rather than batch mode (for instance,
2679 this can happen if a session log file is used directly as a syntax
2680 file). When this occurs, use the @samp{-i} command line option to force
2681 interpretation in interactive mode (@pxref{Language control options}).
2685 PSPP ignores empty commands when they are generated by the above
2686 rules. Note that, as a consequence of these rules, each command must
2687 begin on a new line.
2689 @node Types of Commands, Order of Commands, Commands, Language
2690 @section Types of Commands
2692 Commands in PSPP are divided roughly into six categories:
2695 @item Utility commands
2696 @cindex utility commands
2697 Set or display various global options that affect PSPP operations.
2698 May appear anywhere in a syntax file. @xref{Utilities, , Utility
2701 @item File definition commands
2702 @cindex file definition commands
2703 Give instructions for reading data from text files or from special
2704 binary ``system files''. Most of these commands discard any previous
2705 data or variables to replace it with the new data and
2706 variables. At least one must appear before the first command in any of
2707 the categories below. @xref{Data Input and Output}.
2709 @item Input program commands
2710 @cindex input program commands
2711 Though rarely used, these provide powerful tools for reading data files
2712 in arbitrary textual or binary formats. @xref{INPUT PROGRAM}.
2714 @item Transformations
2715 @cindex transformations
2716 Perform operations on data and write data to output files. Transformations
2717 are not carried out until a procedure is executed.
2719 @item Restricted transformations
2720 @cindex restricted transformations
2721 Same as transformations for most purposes. @xref{Order of Commands}, for a
2722 detailed description of the differences.
2726 Analyze data, writing results of analyses to the listing file. Cause
2727 transformations specified earlier in the file to be performed. In a
2728 more general sense, a @dfn{procedure} is any command that causes the
2729 active file (the data) to be read.
2732 @node Order of Commands, Missing Observations, Types of Commands, Language
2733 @section Order of Commands
2734 @cindex commands, ordering
2735 @cindex order of commands
2737 PSPP does not place many restrictions on ordering of commands.
2738 The main restriction is that variables must be defined with one of the
2739 file-definition commands before they are otherwise referred to.
2741 Of course, there are specific rules, for those who are interested.
2742 PSPP possesses five internal states, called initial, INPUT PROGRAM,
2743 FILE TYPE, transformation, and procedure states. (Please note the
2744 distinction between the @cmd{INPUT PROGRAM} and @cmd{FILE TYPE}
2745 @emph{commands} and the INPUT PROGRAM and FILE TYPE @emph{states}.)
2747 PSPP starts up in the initial state. Each successful completion
2748 of a command may cause a state transition. Each type of command has its
2749 own rules for state transitions:
2752 @item Utility commands
2755 Legal in all states.
2757 Do not cause state transitions. Exception: when @cmd{N OF CASES}
2758 is executed in the procedure state, it causes a transition to the
2759 transformation state.
2762 @item @cmd{DATA LIST}
2765 Legal in all states.
2767 When executed in the initial or procedure state, causes a transition to
2768 the transformation state.
2770 Clears the active file if executed in the procedure or transformation
2774 @item @cmd{INPUT PROGRAM}
2777 Invalid in INPUT PROGRAM and FILE TYPE states.
2779 Causes a transition to the INPUT PROGRAM state.
2781 Clears the active file.
2784 @item @cmd{FILE TYPE}
2787 Invalid in INPUT PROGRAM and FILE TYPE states.
2789 Causes a transition to the FILE TYPE state.
2791 Clears the active file.
2794 @item Other file definition commands
2797 Invalid in INPUT PROGRAM and FILE TYPE states.
2799 Cause a transition to the transformation state.
2801 Clear the active file, except for @cmd{ADD FILES}, @cmd{MATCH FILES},
2805 @item Transformations
2808 Invalid in initial and FILE TYPE states.
2810 Cause a transition to the transformation state.
2813 @item Restricted transformations
2816 Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
2818 Cause a transition to the transformation state.
2824 Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
2826 Cause a transition to the procedure state.
2830 @node Missing Observations, Variables, Order of Commands, Language
2831 @section Handling missing observations
2832 @cindex missing values
2833 @cindex values, missing
2835 PSPP includes special support for unknown numeric data values.
2836 Missing observations are assigned a special value, called the
2837 @dfn{system-missing value}. This ``value'' actually indicates the
2838 absence of value; it means that the actual value is unknown. Procedures
2839 automatically exclude from analyses those observations or cases that
2840 have missing values. Whether single observations or entire cases are
2841 excluded depends on the procedure.
2843 The system-missing value exists only for numeric variables. String
2844 variables always have a defined value, even if it is only a string of
2847 Variables, whether numeric or string, can have designated
2848 @dfn{user-missing values}. Every user-missing value is an actual value
2849 for that variable. However, most of the time user-missing values are
2850 treated in the same way as the system-missing value. String variables
2851 that are wider than a certain width, usually 8 characters (depending on
2852 computer architecture), cannot have user-missing values.
2854 For more information on missing values, see the following sections:
2855 @ref{Variables}, @ref{MISSING VALUES}, @ref{Expressions}. See also the
2856 documentation on individual procedures for information on how they
2857 handle missing values.
2859 @node Variables, Files, Missing Observations, Language
2864 Variables are the basic unit of data storage in PSPP. All the
2865 variables in a file taken together, apart from any associated data, are
2866 said to form a @dfn{dictionary}.
2867 Some details of variables are described in the sections below.
2870 * Attributes:: Attributes of variables.
2871 * System Variables:: Variables automatically defined by PSPP.
2872 * Sets of Variables:: Lists of variable names.
2873 * Input/Output Formats:: Input and output formats.
2874 * Scratch Variables:: Variables deleted by procedures.
2877 @node Attributes, System Variables, Variables, Variables
2878 @subsection Attributes of Variables
2879 @cindex variables, attributes of
2880 @cindex attributes of variables
2881 Each variable has a number of attributes, including:
2885 This is an identifier. Each variable must have a different name.
2888 @cindex variables, type
2889 @cindex type of variables
2893 @cindex variables, width
2894 @cindex width of variables
2896 (string variables only) String variables with a width of 8 characters or
2897 fewer are called @dfn{short string variables}. Short string variables
2898 can be used in many procedures where @dfn{long string variables} (those
2899 with widths greater than 8) are not allowed.
2902 @strong{Please note:} Certain systems may consider strings longer than 8
2903 characters to be short strings. Eight characters represents a minimum
2904 figure for the maximum length of a short string.
2908 Variables in the dictionary are arranged in a specific order.
2909 @cmd{DISPLAY} can be used to show this order: see @ref{DISPLAY}.
2911 @item Initialization
2912 Either reinitialized to 0 or spaces for each case, or left at its
2913 existing value. @xref{LEAVE}.
2915 @cindex missing values
2916 @cindex values, missing
2917 @item Missing values
2918 Optionally, up to three values, or a range of values, or a specific
2919 value plus a range, can be specified as @dfn{user-missing values}.
2920 There is also a @dfn{system-missing value} that is assigned to an
2921 observation when there is no other obvious value for that observation.
2922 Observations with missing values are automatically excluded from
2923 analyses. User-missing values are actual data values, while the
2924 system-missing value is not a value at all. @xref{Missing Observations}.
2926 @cindex variable labels
2927 @cindex labels, variable
2928 @item Variable label
2929 A string that describes the variable. @xref{VARIABLE LABELS}.
2931 @cindex value labels
2932 @cindex labels, value
2934 Optionally, these associate each possible value of the variable with a
2935 string. @xref{VALUE LABELS}.
2937 @cindex print format
2939 Display width, format, and (for numeric variables) number of decimal
2940 places. This attribute does not affect how data are stored, just how
2941 they are displayed. Example: a width of 8, with 2 decimal places.
2942 @xref{PRINT FORMATS}.
2944 @cindex write format
2946 Similar to print format, but used by certain commands that are
2947 designed to write to binary files. @xref{WRITE FORMATS}.
2950 @node System Variables, Sets of Variables, Attributes, Variables
2951 @subsection Variables Automatically Defined by PSPP
2952 @cindex system variables
2953 @cindex variables, system
2955 There are seven system variables. These are not like ordinary
2956 variables, as they are not stored in each case. They can only be used
2957 in expressions. These system variables, whose values and output formats
2958 cannot be modified, are described below.
2961 @cindex @code{$CASENUM}
2963 Case number of the case at the moment. This changes as cases are
2966 @cindex @code{$DATE}
2968 Date the PSPP process was started, in format A9, following the
2969 pattern @code{DD MMM YY}.
2971 @cindex @code{$JDATE}
2973 Number of days between 15 Oct 1582 and the time the PSPP process
2976 @cindex @code{$LENGTH}
2978 Page length, in lines, in format F11.
2980 @cindex @code{$SYSMIS}
2982 System missing value, in format F1.
2984 @cindex @code{$TIME}
2986 Number of seconds between midnight 14 Oct 1582 and the time the active file
2987 was read, in format F20.
2989 @cindex @code{$WIDTH}
2991 Page width, in characters, in format F3.
2994 @node Sets of Variables, Input/Output Formats, System Variables, Variables
2995 @subsection Lists of variable names
2996 @cindex TO convention
2997 @cindex convention, TO
2999 There are several ways to specify a set of variables:
3003 (Most commonly.) List the variable names one after another, optionally
3004 separating them by commas.
3008 (This method cannot be used on commands that define the dictionary, such
3009 as @cmd{DATA LIST}.) The syntax is the names of two existing variables,
3010 separated by the reserved keyword @code{TO}. The meaning is to include
3011 every variable in the dictionary between and including the variables
3012 specified. For instance, if the dictionary contains six variables with
3013 the names @code{ID}, @code{X1}, @code{X2}, @code{GOAL}, @code{MET}, and
3014 @code{NEXTGOAL}, in that order, then @code{X2 TO MET} would include
3015 variables @code{X2}, @code{GOAL}, and @code{MET}.
3018 (This method can be used only on commands that define the dictionary,
3019 such as @cmd{DATA LIST}.) It is used to define sequences of variables
3020 that end in consecutive integers. The syntax is two identifiers that
3021 end in numbers. This method is best illustrated with examples:
3025 The syntax @code{X1 TO X5} defines 5 variables:
3041 The syntax @code{ITEM0008 TO ITEM0013} defines 6 variables:
3059 Each of the syntaxes @code{QUES001 TO QUES9} and @code{QUES6 TO QUES3}
3060 are invalid, although for different reasons, which should be evident.
3063 Note that after a set of variables has been defined with @cmd{DATA LIST}
3064 or another command with this method, the same set can be referenced on
3065 later commands using the same syntax.
3068 The above methods can be combined, either one after another or delimited
3069 by commas. For instance, the combined syntax @code{A Q5 TO Q8 X TO Z}
3070 is legal as long as each part @code{A}, @code{Q5 TO Q8}, @code{X TO Z}
3071 is individually legal.
3074 @node Input/Output Formats, Scratch Variables, Sets of Variables, Variables
3075 @subsection Input and Output Formats
3077 Data that PSPP inputs and outputs must have one of a number of formats.
3078 These formats are described, in general, by a format specification of
3079 the form @code{NAMEw.d}, where @var{name} is the
3080 format name and @var{w} is a field width. @var{d} is the optional
3081 desired number of decimal places, if appropriate. If @var{d} is not
3082 included then it is assumed to be 0. Some formats do not allow @var{d}
3085 When an input format is specified on @cmd{DATA LIST} or another
3087 it is converted to an output format for the purposes of @cmd{PRINT}
3089 data output commands. For most purposes, input and output formats are
3090 the same; the salient differences are described below.
3092 Below are listed the input and output formats supported by PSPP. If an
3093 input format is mapped to a different output format by default, then
3094 that mapping is indicated with @result{}. Each format has the listed
3095 bounds on input width (iw) and output width (ow).
3097 The standard numeric input and output formats are given in the following
3101 @item Fw.d: 1 <= iw,ow <= 40
3102 Standard decimal format with @var{d} decimal places. If the number is
3103 too large to fit within the field width, it is expressed in scientific
3104 notation (@code{1.2+34}) if w >= 6, with always at least two digits in
3105 the exponent. When used as an input format, scientific notation is
3106 allowed but an E or an F must be used to introduce the exponent.
3108 The default output format is the same as the input format, except if
3109 @var{d} > 1. In that case the output @var{w} is always made to be at
3112 @item Ew.d: 1 <= iw <= 40; 6 <= ow <= 40
3113 For input this is equivalent to F format except that no E or F is
3114 require to introduce the exponent. For output, produces scientific
3115 notation in the form @code{1.2+34}. There are always at least two
3116 digits given in the exponent.
3118 The default output @var{w} is the largest of the input @var{w}, the
3119 input @var{d} + 7, and 10. The default output @var{d} is the input
3120 @var{d}, but at least 3.
3122 @item COMMAw.d: 1 <= iw,ow <= 40
3123 Equivalent to F format, except that groups of three digits are
3124 comma-separated on output. If the number is too large to express in the
3125 field width, then first commas are eliminated, then if there is still
3126 not enough space the number is expressed in scientific notation given
3127 that w >= 6. Commas are allowed and ignored when this is used as an
3130 @item DOTw.d: 1 <= iw,ow <= 40
3131 Equivalent to COMMA format except that the roles of comma and decimal
3132 point are interchanged. However: If SET /DECIMAL=DOT is in effect, then
3133 COMMA uses @samp{,} for a decimal point and DOT uses @samp{.} for a
3136 @item DOLLARw.d: 1 <= iw <= 40; 2 <= ow <= 40
3137 Equivalent to COMMA format, except that the number is prefixed by a
3138 dollar sign (@samp{$}) if there is room. On input the value is allowed
3139 to be prefixed by a dollar sign, which is ignored.
3141 The default output @var{w} is the input @var{w}, but at least 2.
3143 @item PCTw.d: 2 <= iw,ow <= 40
3144 Equivalent to F format, except that the number is suffixed by a percent
3145 sign (@samp{%}) if there is room. On input the value is allowed to be
3146 suffixed by a percent sign, which is ignored.
3148 The default output @var{w} is the input @var{w}, but at least 2.
3150 @item Nw.d: 1 <= iw,ow <= 40
3151 Only digits are allowed within the field width. The decimal point is
3152 assumed to be @var{d} digits from the right margin.
3154 The default output format is F with the same @var{w} and @var{d}, except
3155 if @var{d} > 1. In that case the output @var{w} is always made to be at
3158 @item Zw.d @result{} F: 1 <= iw,ow <= 40
3159 Zoned decimal input. If you need to use this then you know how.
3161 @item IBw.d @result{} F: 1 <= iw,ow <= 8
3162 Integer binary format. The field is interpreted as a fixed-point
3163 positive or negative binary number in two's-complement notation. The
3164 location of the decimal point is implied. Endianness is the same as the
3167 The default output format is F8.2 if @var{d} is 0. Otherwise it is F,
3168 with output @var{w} as 9 + input @var{d} and output @var{d} as input
3171 @item PIB @result{} F: 1 <= iw,ow <= 8
3172 Positive integer binary format. The field is interpreted as a
3173 fixed-point positive binary number. The location of the decimal point
3174 is implied. Endianness is teh same as the host machine.
3176 The default output format follows the rules for IB format.
3178 @item Pw.d @result{} F: 1 <= iw,ow <= 16
3179 Binary coded decimal format. Each byte from left to right, except the
3180 rightmost, represents two digits. The upper nibble of each byte is more
3181 significant. The upper nibble of the final byte is the least
3182 significant digit. The lower nibble of the final byte is the sign; a
3183 value of D represents a negative sign and all other values are
3184 considered positive. The decimal point is implied.
3186 The default output format follows the rules for IB format.
3188 @item PKw.d @result{} F: 1 <= iw,ow <= 16
3189 Positive binary code decimal format. Same as P but the last byte is the
3192 The default output format follows the rules for IB format.
3194 @item RBw @result{} F: 2 <= iw,ow <= 8
3196 Binary C architecture-dependent ``double'' format. For a standard
3197 IEEE754 implementation @var{w} should be 8.
3199 The default output format follows the rules for IB format.
3201 @item PIBHEXw.d @result{} F: 2 <= iw,ow <= 16
3202 PIB format encoded as textual hex digit pairs. @var{w} must be even.
3204 The input width is mapped to a default output width as follows:
3205 2@result{}4, 4@result{}6, 6@result{}9, 8@result{}11, 10@result{}14,
3206 12@result{}16, 14@result{}18, 16@result{}21. No allowances are made for
3209 @item RBHEXw @result{} F: 4 <= iw,ow <= 16
3211 RB format encoded as textual hex digits pairs. @var{w} must be even.
3213 The default output format is F8.2.
3215 @item CCAw.d: 1 <= ow <= 40
3216 @itemx CCBw.d: 1 <= ow <= 40
3217 @itemx CCCw.d: 1 <= ow <= 40
3218 @itemx CCDw.d: 1 <= ow <= 40
3219 @itemx CCEw.d: 1 <= ow <= 40
3221 User-defined custom currency formats. May not be used as an input
3222 format. @xref{SET}, for more details.
3225 The date and time numeric input and output formats accept a number of
3226 possible formats. Before describing the formats themselves, some
3227 definitions of the elements that make up their formats will be helpful:
3231 All formats accept an optional whitespace leader.
3234 An integer between 1 and 31 representing the day of month.
3237 An integer representing a number of days.
3239 @item date-delimiter
3240 One or more characters of whitespace or the following characters:
3244 A month name in one of the following forms:
3247 An integer between 1 and 12.
3249 Roman numerals representing an integer between 1 and 12.
3251 At least the first three characters of an English month name (January,
3256 An integer year number between 1582 and 19999, or between 1 and 199.
3257 Years between 1 and 199 will have 1900 added.
3260 A single number with a year number in the first 2, 3, or 4 digits (as
3261 above) and the day number within the year in the last 3 digits.
3264 An integer between 1 and 4 representing a quarter.
3267 The letter @samp{Q} or @samp{q}.
3270 An integer between 1 and 53 representing a week within a year.
3273 The letters @samp{wk} in any case.
3275 @item time-delimiter
3276 At least one characters of whitespace or @samp{:} or @samp{.}.
3279 An integer greater than 0 representing an hour.
3282 An integer between 0 and 59 representing a minute within an hour.
3285 Optionally, a time-delimiter followed by a real number representing a
3289 An integer between 0 and 23 representing an hour within a day.
3292 At least the first two characters of an English day word.
3295 Any amount or no amount of whitespace.
3298 An optional positive or negative sign.
3301 All formats accept an optional whitespace trailer.
3304 The date input formats are strung together from the above pieces. On
3305 output, the date formats are always printed in a single canonical
3306 manner, based on field width. The date input and output formats are
3310 @item DATEw: 9 <= iw,ow <= 40
3311 Date format. Input format: leader + day + date-delimiter +
3312 month + date-delimiter + year + trailer. Output format: DD-MMM-YY for
3313 @var{w} < 11, DD-MMM-YYYY otherwise.
3315 @item EDATEw: 8 <= iw,ow <= 40
3316 European date format. Input format same as DATE. Output format:
3317 DD.MM.YY for @var{w} < 10, DD.MM.YYYY otherwise.
3319 @item SDATEw: 8 <= iw,ow <= 40
3320 Standard date format. Input format: leader + year + date-delimiter +
3321 month + date-delimiter + day + trailer. Output format: YY/MM/DD for
3322 @var{w} < 10, YYYY/MM/DD otherwise.
3324 @item ADATEw: 8 <= iw,ow <= 40
3325 American date format. Input format: leader + month + date-delimiter +
3326 day + date-delimiter + year + trailer. Output format: MM/DD/YY for
3327 @var{w} < 10, MM/DD/YYYY otherwise.
3329 @item JDATEw: 5 <= iw,ow <= 40
3330 Julian date format. Input format: leader + julian + trailer. Output
3331 format: YYDDD for @var{w} < 7, YYYYDDD otherwise.
3333 @item QYRw: 4 <= iw <= 40, 6 <= ow <= 40
3334 Quarter/year format. Input format: leader + quarter + q-delimiter +
3335 year + trailer. Output format: @samp{Q Q YY}, where the first
3336 @samp{Q} is one of the digits 1, 2, 3, 4, if @var{w} < 8, @code{Q Q
3339 @item MOYRw: 6 <= iw,ow <= 40
3340 Month/year format. Input format: leader + month + date-delimiter + year
3341 + trailer. Output format: @samp{MMM YY} for @var{w} < 8, @samp{MMM
3344 @item WKYRw: 6 <= iw <= 40, 8 <= ow <= 40
3345 Week/year format. Input format: leader + week + wk-delimiter + year +
3346 trailer. Output format: @samp{WW WK YY} for @var{w} < 10, @samp{WW WK
3349 @item DATETIMEw.d: 17 <= iw,ow <= 40
3350 Date and time format. Input format: leader + day + date-delimiter +
3351 month + date-delimiter + yaer + time-delimiter + hour24 + time-delimiter
3352 + minute + opt-second. Output format: @samp{DD-MMM-YYYY HH:MM}. If
3353 @var{w} > 19 then seconds @samp{:SS} is added. If @var{w} > 22 and
3354 @var{d} > 0 then fractional seconds @samp{.SS} are added.
3356 @item TIMEw.d: 5 <= iw,ow <= 40
3357 Time format. Input format: leader + sign + spaces + hour +
3358 time-delimiter + minute + opt-second. Output format: @samp{HH:MM}.
3359 Seconds and fractional seconds are available with @var{w} of at least 8
3360 and 10, respectively.
3362 @item DTIMEw.d: 1 <= iw <= 40, 8 <= ow <= 40
3363 Time format with day count. Input format: leader + sign + spaces +
3364 day-count + time-delimiter + hour + time-delimiter + minute +
3365 opt-second. Output format: @samp{DD HH:MM}. Seconds and fractional
3366 seconds are available with @var{w} of at least 8 and 10, respectively.
3368 @item WKDAYw: 2 <= iw,ow <= 40
3369 A weekday as a number between 1 and 7, where 1 is Sunday. Input format:
3370 leader + weekday + trailer. Output format: as many characters, in all
3371 capital letters, of the English name of the weekday as will fit in the
3374 @item MONTHw: 3 <= iw,ow <= 40
3375 A month as a number between 1 and 12, where 1 is January. Input format:
3376 leader + month + trailer. Output format: as many character, in all
3377 capital letters, of the English name of the month as will fit in the
3381 There are only two formats that may be used with string variables:
3384 @item Aw: 1 <= iw <= 255, 1 <= ow <= 254
3385 The entire field is treated as a string value.
3387 @item AHEXw @result{} A: 2 <= iw <= 254; 2 <= ow <= 510
3388 The field is composed of characters in a string encoded as textual hex
3391 The default output @var{w} is half the input @var{w}.
3394 @node Scratch Variables, , Input/Output Formats, Variables
3395 @subsection Scratch Variables
3397 Most of the time, variables don't retain their values between cases.
3398 Instead, either they're being read from a data file or the active file,
3399 in which case they assume the value read, or, if created with
3401 another transformation, they're initialized to the system-missing value
3402 or to blanks, depending on type.
3404 However, sometimes it's useful to have a variable that keeps its value
3405 between cases. You can do this with @cmd{LEAVE} (@pxref{LEAVE}), or you can
3406 use a @dfn{scratch variable}. Scratch variables are variables whose
3407 names begin with an octothorpe (@samp{#}).
3409 Scratch variables have the same properties as variables left with
3411 they retain their values between cases, and for the first case they are
3412 initialized to 0 or blanks. They have the additional property that they
3413 are deleted before the execution of any procedure. For this reason,
3414 scratch variables can't be used for analysis. To obtain the same
3415 effect, use @cmd{COMPUTE} (@pxref{COMPUTE}) to copy the scratch variable's
3416 value into an ordinary variable, then analysis that variable.
3418 @node Files, BNF, Variables, Language
3419 @section Files Used by PSPP
3421 PSPP makes use of many files each time it runs. Some of these it
3422 reads, some it writes, some it creates. Here is a table listing the
3423 most important of these files:
3426 @cindex file, command
3427 @cindex file, syntax file
3428 @cindex command file
3432 These names (synonyms) refer to the file that contains instructions to
3433 PSPP that tell it what to do. The syntax file's name is specified on
3434 the PSPP command line. Syntax files can also be pulled in with
3435 @cmd{INCLUDE} (@pxref{INCLUDE}).
3440 Data files contain raw data in ASCII format suitable for being read in
3441 by @cmd{DATA LIST}. Data can be embedded in the syntax
3442 file with @cmd{BEGIN DATA} and @cmd{END DATA}: this makes the
3443 syntax file a data file too.
3445 @cindex file, output
3448 One or more output files are created by PSPP each time it is
3449 run. The output files receive the tables and charts produced by
3450 statistical procedures. The output files may be in any number of formats,
3451 depending on how PSPP is configured.
3454 @cindex file, active
3456 The active file is the ``file'' on which all PSPP procedures
3457 are performed. The active file contains variable definitions and
3458 cases. The active file is not necessarily a disk file: it is stored
3459 in memory if there is room.
3462 @node BNF, , Files, Language
3463 @section Backus-Naur Form
3465 @cindex Backus-Naur Form
3466 @cindex command syntax, description of
3467 @cindex description of command syntax
3469 The syntax of some parts of the PSPP language is presented in this
3470 manual using the formalism known as @dfn{Backus-Naur Form}, or BNF. The
3471 following table describes BNF:
3477 Words in all-uppercase are PSPP keyword tokens. In BNF, these are
3478 often called @dfn{terminals}. There are some special terminals, which
3479 are actually written in lowercase for clarity:
3482 @cindex @code{number}
3486 @cindex @code{integer}
3487 @item @code{integer}
3490 @cindex @code{string}
3494 @cindex @code{var-name}
3495 @item @code{var-name}
3496 A single variable name.
3500 @item @code{=}, @code{/}, @code{+}, @code{-}, etc.
3501 Operators and punctuators.
3504 @cindex terminal dot
3505 @cindex dot, terminal
3507 The terminal dot. This is not necessarily an actual dot in the syntax
3508 file: @xref{Commands}, for more details.
3513 @cindex nonterminals
3514 Other words in all lowercase refer to BNF definitions, called
3515 @dfn{productions}. These productions are also known as
3516 @dfn{nonterminals}. Some nonterminals are very common, so they are
3517 defined here in English for clarity:
3520 @cindex @code{var-list}
3522 A list of one or more variable names or the keyword @code{ALL}.
3524 @cindex @code{expression}
3526 An expression. @xref{Expressions}, for details.
3531 @cindex ``is defined as''
3533 @samp{::=} means ``is defined as''. The left side of @samp{::=} gives
3534 the name of the nonterminal being defined. The right side of @samp{::=}
3535 gives the definition of that nonterminal. If the right side is empty,
3536 then one possible expansion of that nonterminal is nothing. A BNF
3537 definition is called a @dfn{production}.
3540 @cindex terminals and nonterminals, differences
3541 So, the key difference between a terminal and a nonterminal is that a
3542 terminal cannot be broken into smaller parts---in fact, every terminal
3543 is a single token (@pxref{Tokens}). On the other hand, nonterminals are
3544 composed of a (possibly empty) sequence of terminals and nonterminals.
3545 Thus, terminals indicate the deepest level of syntax description. (In
3546 parsing theory, terminals are the leaves of the parse tree; nonterminals
3550 @cindex start symbol
3551 @cindex symbol, start
3552 The first nonterminal defined in a set of productions is called the
3553 @dfn{start symbol}. The start symbol defines the entire syntax for
3557 @node Expressions, Data Input and Output, Language, Top
3558 @chapter Mathematical Expressions
3559 @cindex expressions, mathematical
3560 @cindex mathematical expressions
3562 Some PSPP commands use expressions, which share a common syntax
3563 among all PSPP commands. Expressions are made up of
3564 @dfn{operands}, which can be numbers, strings, or variable names,
3565 separated by @dfn{operators}. There are five types of operators:
3566 grouping, arithmetic, logical, relational, and functions.
3568 Every operator takes one or more @dfn{arguments} as input and produces
3569 or @dfn{returns} exactly one result as output. Both strings and numeric
3570 values can be used as arguments and are produced as results, but each
3571 operator accepts only specific combinations of numeric and string values
3572 as arguments. With few exceptions, operator arguments may be
3573 full-fledged expressions in themselves.
3576 * Booleans:: Boolean values.
3577 * Missing Values in Expressions:: Using missing values in expressions.
3578 * Grouping Operators:: ( )
3579 * Arithmetic Operators:: + - * / **
3580 * Logical Operators:: AND NOT OR
3581 * Relational Operators:: EQ GE GT LE LT NE
3582 * Functions:: More-sophisticated operators.
3583 * Order of Operations:: Operator precedence.
3586 @node Booleans, Missing Values in Expressions, Expressions, Expressions
3587 @section Boolean values
3589 @cindex values, Boolean
3591 There is a third type for arguments and results, the @dfn{Boolean} type,
3592 which is used to represent true/false conditions. Booleans have only
3593 three possible values: 0 (false), 1 (true), and system-missing.
3594 System-missing is neither true nor false.
3598 A numeric expression that has value 0, 1, or system-missing may be used
3599 in place of a Boolean. Thus, the expression @code{0 AND 1} is valid
3600 (although it is always false).
3603 A numeric expression with any other value will cause an error if it is
3604 used as a Boolean. So, @code{2 OR 3} is invalid.
3607 A Boolean expression may not be used in place of a numeric expression.
3608 Thus, @code{(1>2) + (3<4)} is invalid.
3611 Strings and Booleans are not compatible, and neither may be used in
3615 @node Missing Values in Expressions, Grouping Operators, Booleans, Expressions
3616 @section Missing Values in Expressions
3618 String missing values are not treated specially in expressions. Most
3619 numeric operators return system-missing when given system-missing
3620 arguments. Exceptions are listed under particular operator
3623 User-missing values for numeric variables are always transformed into
3624 the system-missing value, except inside the arguments to the
3625 @code{VALUE}, @code{SYSMIS}, and @code{MISSING} functions.
3627 The missing-value functions can be used to precisely control how missing
3628 values are treated in expressions. @xref{Missing Value Functions}, for
3631 @node Grouping Operators, Arithmetic Operators, Missing Values in Expressions, Expressions
3632 @section Grouping Operators
3635 @cindex grouping operators
3636 @cindex operators, grouping
3638 Parentheses (@samp{()}) are the grouping operators. Surround an
3639 expression with parentheses to force early evaluation.
3641 Parentheses also surround the arguments to functions, but in that
3642 situation they act as punctuators, not as operators.
3644 @node Arithmetic Operators, Logical Operators, Grouping Operators, Expressions
3645 @section Arithmetic Operators
3646 @cindex operators, arithmetic
3647 @cindex arithmetic operators
3649 The arithmetic operators take numeric arguments and produce numeric
3655 @item @var{a} + @var{b}
3656 Adds @var{a} and @var{b}, returning the sum.
3660 @item @var{a} - @var{b}
3661 Subtracts @var{b} from @var{a}, returning the difference.
3664 @cindex multiplication
3665 @item @var{a} * @var{b}
3666 Multiplies @var{a} and @var{b}, returning the product.
3670 @item @var{a} / @var{b}
3671 Divides @var{a} by @var{b}, returning the quotient. If @var{b} is
3672 zero, the result is system-missing.
3675 @cindex exponentiation
3676 @item @var{a} ** @var{b}
3677 Returns the result of raising @var{a} to the power @var{b}. If
3678 @var{a} is negative and @var{b} is not an integer, the result is
3679 system-missing. The result of @code{0**0} is system-missing as well.
3684 Reverses the sign of @var{a}.
3687 @node Logical Operators, Relational Operators, Arithmetic Operators, Expressions
3688 @section Logical Operators
3689 @cindex logical operators
3690 @cindex operators, logical
3695 @cindex values, system-missing
3696 @cindex system-missing
3697 The logical operators take logical arguments and produce logical
3698 results, meaning ``true or false''. PSPP logical operators are
3699 not true Boolean operators because they may also result in a
3700 system-missing value.
3705 @cindex intersection, logical
3706 @cindex logical intersection
3707 @item @var{a} AND @var{b}
3708 @itemx @var{a} & @var{b}
3709 True if both @var{a} and @var{b} are true. However, if one argument is
3710 false and the other is missing, the result is false, not missing. If
3711 both arguments are missing, the result is missing.
3715 @cindex union, logical
3716 @cindex logical union
3717 @item @var{a} OR @var{b}
3718 @itemx @var{a} | @var{b}
3719 True if at least one of @var{a} and @var{b} is true. If one argument is
3720 true and the other is missing, the result is true, not missing. If both
3721 arguments are missing, the result is missing.
3725 @cindex inversion, logical
3726 @cindex logical inversion
3729 True if @var{a} is false.
3732 @node Relational Operators, Functions, Logical Operators, Expressions
3733 @section Relational Operators
3735 The relational operators take numeric or string arguments and produce Boolean
3738 Note that, with numeric arguments, PSPP does not make exact
3739 relational tests. Instead, two numbers are considered to be equal even
3740 if they differ by a small amount. This amount, @dfn{epsilon}, is
3741 dependent on the PSPP configuration and determined at compile
3742 time. (The default value is 0.000000001, or
3749 Use of epsilon allows for round-off errors. Use of epsilon is also
3750 idiotic, but the author is not a numeric analyst.
3752 Strings cannot be compared to numbers. When strings of different
3753 lengths are compared, the shorter string is right-padded with spaces
3754 to match the length of the longer string.
3756 The results of string comparisons, other than tests for equality or
3757 inequality, are dependent on the character set in use. String
3758 comparisons are case-sensitive.
3761 @cindex equality, testing
3762 @cindex testing for equality
3765 @item @var{a} EQ @var{b}
3766 @itemx @var{a} = @var{b}
3767 True if @var{a} is equal to @var{b}.
3769 @cindex less than or equal to
3772 @item @var{a} LE @var{b}
3773 @itemx @var{a} <= @var{b}
3774 True if @var{a} is less than or equal to @var{b}.
3779 @item @var{a} LT @var{b}
3780 @itemx @var{a} < @var{b}
3781 True if @var{a} is less than @var{b}.
3783 @cindex greater than or equal to
3786 @item @var{a} GE @var{b}
3787 @itemx @var{a} >= @var{b}
3788 True if @var{a} is greater than or equal to @var{b}.
3790 @cindex greater than
3793 @item @var{a} GT @var{b}
3794 @itemx @var{a} > @var{b}
3795 True if @var{a} is greater than @var{b}.
3797 @cindex inequality, testing
3798 @cindex testing for inequality
3802 @item @var{a} NE @var{b}
3803 @itemx @var{a} ~= @var{b}
3804 @itemx @var{a} <> @var{b}
3805 True is @var{a} is not equal to @var{b}.
3808 @node Functions, Order of Operations, Relational Operators, Expressions
3817 @cindex names, of functions
3818 PSPP functions provide mathematical abilities above and beyond
3819 those possible using simple operators. Functions have a common
3820 syntax: each is composed of a function name followed by a left
3821 parenthesis, one or more arguments, and a right parenthesis. Function
3822 names are @strong{not} reserved; their names are specially treated
3823 only when followed by a left parenthesis: @code{EXP(10)} refers to the
3824 constant value @code{e} raised to the 10th power, but @code{EXP} by
3825 itself refers to the value of variable EXP.
3827 The sections below describe each function in detail.
3830 * Advanced Mathematics:: EXP LG10 LN SQRT
3831 * Miscellaneous Mathematics:: ABS MOD MOD10 RND TRUNC
3832 * Trigonometry:: ACOS ARCOS ARSIN ARTAN ASIN ATAN COS SIN TAN
3833 * Missing Value Functions:: MISSING NMISS NVALID SYSMIS VALUE
3834 * Pseudo-Random Numbers:: NORMAL UNIFORM
3835 * Set Membership:: ANY RANGE
3836 * Statistical Functions:: CFVAR MAX MEAN MIN SD SUM VARIANCE
3837 * String Functions:: CONCAT INDEX LENGTH LOWER LPAD LTRIM NUMBER
3838 RINDEX RPAD RTRIM STRING SUBSTR UPCASE
3839 * Time & Date:: CTIME.xxx DATE.xxx TIME.xxx XDATE.xxx
3840 * Miscellaneous Functions:: LAG YRMODA
3841 * Functions Not Implemented:: CDF.xxx CDFNORM IDF.xxx NCDF.xxx PROBIT RV.xxx
3844 @node Advanced Mathematics, Miscellaneous Mathematics, Functions, Functions
3845 @subsection Advanced Mathematical Functions
3846 @cindex mathematics, advanced
3848 Advanced mathematical functions take numeric arguments and produce
3851 @deftypefn {Function} {} EXP (@var{exponent})
3852 Returns @i{e} (approximately 2.71828) raised to power @var{exponent}.
3856 @deftypefn {Function} {} LG10 (@var{number})
3857 Takes the base-10 logarithm of @var{number}. If @var{number} is
3858 not positive, the result is system-missing.
3861 @deftypefn {Function} {} LN (@var{number})
3862 Takes the base-@i{e} logarithm of @var{number}. If @var{number} is
3863 not positive, the result is system-missing.
3866 @cindex square roots
3867 @deftypefn {Function} {} SQRT (@var{number})
3868 Takes the square root of @var{number}. If @var{number} is negative,
3869 the result is system-missing.
3872 @node Miscellaneous Mathematics, Trigonometry, Advanced Mathematics, Functions
3873 @subsection Miscellaneous Mathematical Functions
3874 @cindex mathematics, miscellaneous
3876 Miscellaneous mathematical functions take numeric arguments and produce
3879 @cindex absolute value
3880 @deftypefn {Function} {} ABS (@var{number})
3881 Results in the absolute value of @var{number}.
3885 @deftypefn {Function} {} MOD (@var{numerator}, @var{denominator})
3886 Returns the remainder (modulus) of @var{numerator} divided by
3887 @var{denominator}. If @var{denominator} is 0, the result is
3888 system-missing. However, if @var{numerator} is 0 and
3889 @var{denominator} is system-missing, the result is 0.
3892 @cindex modulus, by 10
3893 @deftypefn {Function} {} MOD10 (@var{number})
3894 Returns the remainder when @var{number} is divided by 10. If
3895 @var{number} is negative, MOD10(@var{number}) is negative or zero.
3899 @deftypefn {Function} {} RND (@var{number})
3900 Takes the absolute value of @var{number} and rounds it to an integer.
3901 Then, if @var{number} was negative originally, negates the result.
3905 @deftypefn {Function} {} TRUNC (@var{number})
3906 Discards the fractional part of @var{number}; that is, rounds
3907 @var{number} towards zero.
3910 @node Trigonometry, Missing Value Functions, Miscellaneous Mathematics, Functions
3911 @subsection Trigonometric Functions
3912 @cindex trigonometry
3914 Trigonometric functions take numeric arguments and produce numeric
3918 @cindex inverse cosine
3919 @deftypefn {Function} {} ACOS (@var{number})
3920 @deftypefnx {Function} {} ARCOS (@var{number})
3921 Takes the arccosine, in radians, of @var{number}. Results in
3922 system-missing if @var{number} is not between -1 and 1. Portability:
3927 @cindex inverse sine
3928 @deftypefn {Function} {} ARSIN (@var{number})
3929 Takes the arcsine, in radians, of @var{number}. Results in
3930 system-missing if @var{number} is not between -1 and 1 inclusive.
3934 @cindex inverse tangent
3935 @deftypefn {Function} {} ARTAN (@var{number})
3936 Takes the arctangent, in radians, of @var{number}.
3940 @cindex inverse sine
3941 @deftypefn {Function} {} ASIN (@var{number})
3942 Takes the arcsine, in radians, of @var{number}. Results in
3943 system-missing if @var{number} is not between -1 and 1 inclusive.
3948 @cindex inverse tangent
3949 @deftypefn {Function} {} ATAN (@var{number})
3950 Takes the arctangent, in radians, of @var{number}.
3954 @strong{Please note:} Use of the AR* group of inverse trigonometric
3955 functions is recommended over the A* group because they are more
3960 @deftypefn {Function} {} COS (@var{angle})
3961 Takes the cosine of @var{angle} which should be in radians.
3965 @deftypefn {Function} {} SIN (@var{angle})
3966 Takes the sine of @var{angle} which should be in radians.
3970 @deftypefn {Function} {} TAN (@var{angle})
3971 Takes the tangent of @var{angle} which should be in radians.
3972 Results in system-missing at values
3973 of @var{angle} that are too close to odd multiples of pi/2.
3977 @node Missing Value Functions, Pseudo-Random Numbers, Trigonometry, Functions
3978 @subsection Missing-Value Functions
3979 @cindex missing values
3980 @cindex values, missing
3981 @cindex functions, missing-value
3983 Missing-value functions take various types as arguments, returning
3984 various types of results.
3986 @deftypefn {Function} {} MISSING (@var{variable or expression})
3987 @var{num} may be a single variable name or an expression. If it is a
3988 variable name, results in 1 if the variable has a user-missing or
3989 system-missing value for the current case, 0 otherwise. If it is an
3990 expression, results in 1 if the expression has the system-missing value,
3994 @strong{Please note:} If the argument is a string expression other than
3995 a variable name, MISSING is guaranteed to return 0, because strings do
3996 not have a system-missing value. Also, when using a numeric expression
3997 argument, remember that user-missing values are converted to the
3998 system-missing value in most contexts. Thus, the expressions
3999 @code{MISSING(VAR1 @var{op} VAR2)} and @code{MISSING(VAR1) OR
4000 MISSING(VAR2)} are often equivalent, depending on the specific operator
4005 @deftypefn {Function} {} NMISS (@var{expr} [, @var{expr}]@dots{})
4006 Each argument must be a numeric expression. Returns the number of
4007 user- or system-missing values in the list. As a special extension,
4008 the syntax @code{@var{var1} TO @var{var2}} may be used to refer to a
4009 range of variables; see @ref{Sets of Variables}, for more details.
4012 @deftypefn {Function} {} NVALID (@var{expr} [, @var{expr}]@dots{})
4013 Each argument must be a numeric expression. Returns the number of
4014 values in the list that are not user- or system-missing. As a special extension,
4015 the syntax @code{@var{var1} TO @var{var2}} may be used to refer to a
4016 range of variables; see @ref{Sets of Variables}, for more details.
4019 @deftypefn {Function} {} SYSMIS (@var{variable or expression})
4020 When given the name of a numeric variable, returns 1 if the value of
4021 that variable is system-missing. Otherwise, if the value is not
4022 missing or if it is user-missing, returns 0. If given the name of a
4023 string variable, always returns 1. If given an expression other than
4024 a single variable name, results in 1 if the value is system- or
4025 user-missing, 0 otherwise.
4028 @deftypefn {Function} {} VALUE (@var{variable})
4029 Prevents the user-missing values of @var{variable} from being
4030 transformed into system-missing values: If @var{variable} is not
4031 system- or user-missing, results in the value of @var{variable}. If
4032 @var{variable} is user-missing, results in the value of @var{variable}
4033 anyway. If @var{variable} is system-missing, results in system-missing.
4036 @node Pseudo-Random Numbers, Set Membership, Missing Value Functions, Functions
4037 @subsection Pseudo-Random Number Generation Functions
4038 @cindex random numbers
4039 @cindex pseudo-random numbers (see random numbers)
4041 Pseudo-random number generation functions take numeric arguments and
4042 produce numeric results.
4044 PSPP uses the alleged RC4 cipher as a pseudo-random number generator
4045 (PRNG). The bytes output by this PRNG are system-independent for a
4046 given random seed, but differences in endianness and floating-point
4047 formats will make PRNG results differ from system to system. RC4
4048 should produce high-quality random numbers for simulation purposes.
4049 (If you're concerned about the quality of the random number generator,
4050 well, you're using a statistical processing package---analyze it!)
4052 PSPP's implementation of RC4 has not undergone any security auditing.
4053 Furthermore, various precautions that would be necessary for secure
4054 operation, such as secure seeding and discarding the first several
4055 bytes of output, have not been taken. Therefore, PSPP's
4056 implementation of RC4 should not be used for security purposes.
4058 @cindex random numbers, normally-distributed
4059 @deftypefn {Function} {} NORMAL (@var{number})
4060 Results in a random number. Results from @code{NORMAL} are normally
4061 distributed with a mean of 0 and a standard deviation of @var{number}.
4064 @cindex random numbers, uniformly-distributed
4065 @deftypefn {Function} {} UNIFORM (@var{number})
4066 Results in a random number between 0 and @var{number}. Results from
4067 @code{UNIFORM} are evenly distributed across its entire range. There
4068 may be a maximum on the largest random number ever generated---this is
4076 (2,147,483,647), but it may be orders of magnitude
4080 @node Set Membership, Statistical Functions, Pseudo-Random Numbers, Functions
4081 @subsection Set-Membership Functions
4082 @cindex set membership
4083 @cindex membership, of set
4085 Set membership functions determine whether a value is a member of a set.
4086 They take a set of numeric arguments or a set of string arguments, and
4087 produce Boolean results.
4089 String comparisons are performed according to the rules given in
4090 @ref{Relational Operators}.
4092 @deftypefn {Function} {} ANY (@var{value}, @var{set} [, @var{set}]@dots{})
4093 Results in true if @var{value} is equal to any of the @var{set}
4094 values. Otherwise, results in false. If @var{value} is
4095 system-missing, returns system-missing. System-missing values in
4096 @var{set} do not cause ANY to return system-missing.
4099 @deftypefn {Function} {} RANGE (@var{value}, @var{low}, @var{high} [, @var{low}, @var{high}]@dots{})
4100 Results in true if @var{value} is in any of the intervals bounded by
4101 @var{low} and @var{high} inclusive. Otherwise, results in false.
4102 Each @var{low} must be less than or equal to its corresponding
4103 @var{high} value. @var{low} and @var{high} must be given in pairs.
4104 If @var{value} is system-missing, returns system-missing.
4105 System-missing values in @var{set} do not cause RANGE to return
4109 @node Statistical Functions, String Functions, Set Membership, Functions
4110 @subsection Statistical Functions
4111 @cindex functions, statistical
4114 Statistical functions compute descriptive statistics on a list of
4115 values. Some statistics can be computed on numeric or string values;
4116 other can only be computed on numeric values. Their results have the
4117 same type as their arguments. The current case's weighting factor
4118 (@pxref{WEIGHT}) has no effect on statistical functions.
4120 @cindex arguments, minimum valid
4121 @cindex minimum valid number of arguments
4122 With statistical functions it is possible to specify a minimum number of
4123 non-missing arguments for the function to be evaluated. To do so,
4124 append a dot and the number to the function name. For instance, to
4125 specify a minimum of three valid arguments to the MEAN function, use the
4128 @cindex coefficient of variation
4129 @cindex variation, coefficient of
4130 @deftypefn {Function} {} CFVAR (@var{number}, @var{number}[, @dots{}])
4131 Results in the coefficient of variation of the values of @var{number}.
4132 This function requires at least two valid arguments to give a
4133 non-missing result. (The coefficient of variation is the standard
4134 deviation divided by the mean.)
4138 @deftypefn {Function} {} MAX (@var{value}, @var{value}[, @dots{}])
4139 Results in the value of the greatest @var{value}. The @var{value}s may
4140 be numeric or string. Although at least two arguments must be given,
4141 only one need be valid for MAX to give a non-missing result.
4145 @deftypefn {Function} {} MEAN (@var{number}, @var{number}[, @dots{}])
4146 Results in the mean of the values of @var{number}. Although at least
4147 two arguments must be given, only one need be valid for MEAN to give a
4152 @deftypefn {Function} {} MIN (@var{number}, @var{number}[, @dots{}])
4153 Results in the value of the least @var{value}. The @var{value}s may
4154 be numeric or string. Although at least two arguments must be given,
4155 only one need be valid for MAX to give a non-missing result.
4158 @cindex standard deviation
4159 @cindex deviation, standard
4160 @deftypefn {Function} {} SD (@var{number}, @var{number}[, @dots{}])
4161 Results in the standard deviation of the values of @var{number}.
4162 This function requires at least two valid arguments to give a
4167 @deftypefn {Function} {} SUM (@var{number}, @var{number}[, @dots{}])
4168 Results in the sum of the values of @var{number}. Although at least two
4169 arguments must be given, only one need by valid for SUM to give a
4174 @deftypefn {Function} {} VAR (@var{number}, @var{number}[, @dots{}])
4175 Results in the variance of the values of @var{number}. This function
4176 requires at least two valid arguments to give a non-missing result.
4179 @deftypefn {Function} {} VARIANCE (@var{number}, @var{number}[, @dots{}])
4180 Results in the variance of the values of @var{number}. This function
4181 requires at least two valid arguments to give a non-missing result.
4182 (Use VAR in preference to VARIANCE for reasons of portability.)
4185 @node String Functions, Time & Date, Statistical Functions, Functions
4186 @subsection String Functions
4187 @cindex functions, string
4188 @cindex string functions
4190 String functions take various arguments and return various results.
4192 @cindex concatenation
4193 @cindex strings, concatenation of
4194 @deftypefn {Function} {} CONCAT (@var{string}, @var{string}[, @dots{}])
4195 Returns a string consisting of each @var{string} in sequence.
4196 @code{CONCAT("abc", "def", "ghi")} has a value of @code{"abcdefghi"}.
4197 The resultant string is truncated to a maximum of 255 characters.
4200 @cindex searching strings
4201 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needle})
4202 Returns a positive integer indicating the position of the first
4203 occurrence @var{needle} in @var{haystack}. Returns 0 if @var{haystack}
4204 does not contain @var{needle}. Returns system-missing if @var{needle}
4208 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needle}, @var{divisor})
4209 Divides @var{needle} into parts, each with length @var{divisor}.
4210 Searches @var{haystack} for the first occurrence of each part, and
4211 returns the smallest value. Returns 0 if @var{haystack} does not
4212 contain any part in @var{needle}. It is an error if @var{divisor}
4213 cannot be evenly divided into the length of @var{needle}. Returns
4214 system-missing if @var{needle} is an empty string.
4217 @cindex strings, finding length of
4218 @deftypefn {Function} {} LENGTH (@var{string})
4219 Returns the number of characters in @var{string}.
4222 @cindex strings, case of
4223 @deftypefn {Function} {} LOWER (@var{string})
4224 Returns a string identical to @var{string} except that all uppercase
4225 letters are changed to lowercase letters. The definitions of
4226 ``uppercase'' and ``lowercase'' are system-dependent.
4229 @cindex strings, padding
4230 @deftypefn {Function} {} LPAD (@var{string}, @var{length})
4231 If @var{string} is at least @var{length} characters in length, returns
4232 @var{string} unchanged. Otherwise, returns @var{string} padded with
4233 spaces on the left side to length @var{length}. Returns an empty string
4234 if @var{length} is system-missing, negative, or greater than 255.
4237 @deftypefn {Function} {} LPAD (@var{string}, @var{length}, @var{padding})
4238 If @var{string} is at least @var{length} characters in length, returns
4239 @var{string} unchanged. Otherwise, returns @var{string} padded with
4240 @var{padding} on the left side to length @var{length}. Returns an empty
4241 string if @var{length} is system-missing, negative, or greater than 255, or
4242 if @var{padding} does not contain exactly one character.
4245 @cindex strings, trimming
4246 @cindex whitespace, trimming
4247 @deftypefn {Function} {} LTRIM (@var{string})
4248 Returns @var{string}, after removing leading spaces. Other whitespace,
4249 such as tabs, carriage returns, line feeds, and vertical tabs, is not
4253 @deftypefn {Function} {} LTRIM (@var{string}, @var{padding})
4254 Returns @var{string}, after removing leading @var{padding} characters.
4255 If @var{padding} does not contain exactly one character, returns an
4259 @cindex numbers, converting from strings
4260 @cindex strings, converting to numbers
4261 @deftypefn {Function} {} NUMBER (@var{string})
4262 Returns the number produced when @var{string} is interpreted according
4263 to format F@var{x}.0, where @var{x} is the number of characters in
4264 @var{string}. If @var{string} does not form a proper number,
4265 system-missing is returned without an error message. Portability: none.
4268 @deftypefn {Function} {} NUMBER (@var{string}, @var{format})
4269 Returns the number produced when @var{string} is interpreted according
4270 to format specifier @var{format}. Only the number of characters in
4271 @var{string} specified by @var{format} are examined. For example,
4272 @code{NUMBER("123", F3.0)} and @code{NUMBER("1234", F3.0)} both have
4273 value 123. If @var{string} does not form a proper number,
4274 system-missing is returned without an error message.
4277 @cindex strings, searching backwards
4278 @deftypefn {Function} {} RINDEX (@var{string}, @var{format})
4279 Returns a positive integer indicating the position of the last
4280 occurrence of @var{needle} in @var{haystack}. Returns 0 if
4281 @var{haystack} does not contain @var{needle}. Returns system-missing if
4282 @var{needle} is an empty string.
4285 @deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle}, @var{divisor})
4286 Divides @var{needle} into parts, each with length @var{divisor}.
4287 Searches @var{haystack} for the last occurrence of each part, and
4288 returns the largest value. Returns 0 if @var{haystack} does not contain
4289 any part in @var{needle}. It is an error if @var{divisor} cannot be
4290 evenly divided into the length of @var{needle}. Returns system-missing
4291 if @var{needle} is an empty string.
4294 @cindex padding strings
4295 @cindex strings, padding
4296 @deftypefn {Function} {} RPAD (@var{string}, @var{length})
4297 If @var{string} is at least @var{length} characters in length, returns
4298 @var{string} unchanged. Otherwise, returns @var{string} padded with
4299 spaces on the right to length @var{length}. Returns an empty string if
4300 @var{length} is system-missing, negative, or greater than 255.
4303 @deftypefn {Function} {} RPAD (@var{string}, @var{length}, @var{padding})
4304 If @var{string} is at least @var{length} characters in length, returns
4305 @var{string} unchanged. Otherwise, returns @var{string} padded with
4306 @var{padding} on the right to length @var{length}. Returns an empty
4307 string if @var{length} is system-missing, negative, or greater than 255,
4308 or if @var{padding} does not contain exactly one character.
4311 @cindex strings, trimming
4312 @cindex whitespace, trimming
4313 @deftypefn {Function} {} RTRIM (@var{string})
4314 Returns @var{string}, after removing trailing spaces. Other types of
4315 whitespace are not removed.
4318 @deftypefn {Function} {} RTRIM (@var{string}, @var{padding})
4319 Returns @var{string}, after removing trailing @var{padding} characters.
4320 If @var{padding} does not contain exactly one character, returns an
4324 @cindex strings, converting from numbers
4325 @cindex numbers, converting to strings
4326 @deftypefn {Function} {} STRING (@var{number}, @var{format})
4327 Returns a string corresponding to @var{number} in the format given by
4328 format specifier @var{format}. For example, @code{STRING(123.56, F5.1)}
4329 has the value @code{"123.6"}.
4333 @cindex strings, taking substrings of
4334 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start})
4335 Returns a string consisting of the value of @var{string} from position
4336 @var{start} onward. Returns an empty string if @var{start} is system-missing
4337 or has a value less than 1 or greater than the number of characters in
4341 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start}, @var{count})
4342 Returns a string consisting of the first @var{count} characters from
4343 @var{string} beginning at position @var{start}. Returns an empty string
4344 if @var{start} or @var{count} is system-missing, if @var{start} is less
4345 than 1 or greater than the number of characters in @var{string}, or if
4346 @var{count} is less than 1. Returns a string shorter than @var{count}
4347 characters if @var{start} + @var{count} - 1 is greater than the number
4348 of characters in @var{string}. Examples: @code{SUBSTR("abcdefg", 3, 2)}
4349 has value @code{"cd"}; @code{SUBSTR("Ben Pfaff", 5, 10)} has the value
4353 @cindex case conversion
4354 @cindex strings, case of
4355 @deftypefn {Function} {} UPCASE (@var{string})
4356 Returns @var{string}, changing lowercase letters to uppercase letters.
4359 @node Time & Date, Miscellaneous Functions, String Functions, Functions
4360 @subsection Time & Date Functions
4361 @cindex functions, time & date
4365 @cindex dates, legal range of
4366 The legal range of dates for use in PSPP is 15 Oct 1582
4367 through 31 Dec 19999.
4369 @cindex arguments, invalid
4370 @cindex invalid arguments
4372 @strong{Please note:} Most time & date extraction functions will accept
4377 Negative numbers in PSPP time format.
4379 Numbers less than 86,400 in PSPP date format.
4382 However, sensible results are not guaranteed for these invalid values.
4383 The given equivalents for these functions are definitely not guaranteed
4388 @strong{Please note also:} The time & date construction
4389 functions @strong{do} produce reasonable and useful results for
4390 out-of-range values; these are not considered invalid.
4394 * Time & Date Concepts:: How times & dates are defined and represented
4395 * Time Construction:: TIME.@{DAYS HMS@}
4396 * Time Extraction:: CTIME.@{DAYS HOURS MINUTES SECONDS@}
4397 * Date Construction:: DATE.@{DMY MDY MOYR QYR WKYR YRDAY@}
4398 * Date Extraction:: XDATE.@{DATE HOUR JDAY MDAY MINUTE MONTH
4399 QUARTER SECOND TDAY TIME WEEK
4403 @node Time & Date Concepts, Time Construction, Time & Date, Time & Date
4404 @subsubsection How times & dates are defined and represented
4406 @cindex time, concepts
4407 @cindex time, intervals
4408 Times and dates are handled by PSPP as single numbers. A
4409 @dfn{time} is an interval. PSPP measures times in seconds.
4410 Thus, the following intervals correspond with the numeric values given:
4415 1 day, 3 hours, 10 seconds 97,210
4417 10010 d, 14 min, 24 s 864,864,864
4420 @cindex dates, concepts
4421 @cindex time, instants of
4422 A @dfn{date}, on the other hand, is a particular instant in the past or
4423 the future. PSPP represents a date as a number of seconds after the
4424 midnight that separated 8 Oct 1582 and 9 Oct 1582. (Please note that 15
4425 Oct 1582 immediately followed 9 Oct 1582.) Thus, the midnights before
4426 the dates given below correspond with the numeric PSPP dates given:
4430 4 Jul 1776 6,113,318,400
4431 1 Jan 1900 10,010,390,400
4432 1 Oct 1978 12,495,427,200
4433 24 Aug 1995 13,028,601,600
4436 @cindex time, mathematical properties of
4437 @cindex mathematics, applied to times & dates
4438 @cindex dates, mathematical properties of
4444 A time may be added to, or subtracted from, a date, resulting in a date.
4447 The difference of two dates may be taken, resulting in a time.
4450 Two times may be added to, or subtracted from, each other, resulting in
4454 (Adding two dates does not produce a useful result.)
4456 Since times and dates are merely numbers, the ordinary addition and
4457 subtraction operators are employed for these purposes.
4460 @strong{Please note:} Many dates and times have extremely large
4461 values---just look at the values above. Thus, it is not a good idea to
4462 take powers of these values; also, the accuracy of some procedures may
4463 be affected. If necessary, convert times or dates in seconds to some
4464 other unit, like days or years, before performing analysis.
4467 @node Time Construction, Time Extraction, Time & Date Concepts, Time & Date
4468 @subsubsection Functions that Produce Times
4469 @cindex times, constructing
4470 @cindex constructing times
4472 These functions take numeric arguments and produce numeric results in
4476 @cindex time, in days
4477 @deftypefn {Function} {} TIME.DAYS (@var{ndays})
4478 Results in a time value corresponding to @var{ndays} days.
4479 (@code{TIME.DAYS(@var{x})} is equivalent to @code{@var{x} * 60 * 60 *
4483 @cindex hours-minutes-seconds
4484 @cindex time, in hours-minutes-seconds
4485 @deftypefn {Function} {} TIME.HMS (@var{nhours}, @var{nmins}, @var{nsecs})
4486 Results in a time value corresponding to @var{nhours} hours, @var{nmins}
4487 minutes, and @var{nsecs} seconds. (@code{TIME.HMS(@var{h}, @var{m},
4488 @var{s})} is equivalent to @code{@var{h}*60*60 + @var{m}*60 +
4492 @node Time Extraction, Date Construction, Time Construction, Time & Date
4493 @subsubsection Functions that Examine Times
4494 @cindex extraction, of time
4495 @cindex time examination
4496 @cindex examination, of times
4497 @cindex time, lengths of
4499 These functions take numeric arguments in PSPP time format and
4500 give numeric results.
4503 @cindex time, in days
4504 @deftypefn {Function} {} CTIME.DAYS (@var{time})
4505 Results in the number of days and fractional days in @var{time}.
4506 (@code{CTIME.DAYS(@var{x})} is equivalent to @code{@var{x}/60/60/24}.)
4510 @cindex time, in hours
4511 @deftypefn {Function} {} CTIME.HOURS (@var{time})
4512 Results in the number of hours and fractional hours in @var{time}.
4513 (@code{CTIME.HOURS(@var{x})} is equivalent to @code{@var{x}/60/60}.)
4517 @cindex time, in minutes
4518 @deftypefn {Function} {} CTIME.MINUTES (@var{time})
4519 Results in the number of minutes and fractional minutes in @var{time}.
4520 (@code{CTIME.MINUTES(@var{x})} is equivalent to @code{@var{x}/60}.)
4524 @cindex time, in seconds
4525 @deftypefn {Function} {} CTIME.SECONDS (@var{time})
4526 Results in the number of seconds and fractional seconds in @var{time}.
4527 (@code{CTIME.SECONDS} does nothing; @code{CTIME.SECONDS(@var{x})} is
4528 equivalent to @code{@var{x}}.)
4531 @node Date Construction, Date Extraction, Time Extraction, Time & Date
4532 @subsubsection Functions that Produce Dates
4533 @cindex dates, constructing
4534 @cindex constructing dates
4536 @cindex arguments, of date construction functions
4537 These functions take numeric arguments and give numeric results in the
4538 PSPP date format. Arguments taken by these functions are:
4542 Refers to a day of the month between 1 and 31.
4545 Refers to a month of the year between 1 and 12.
4548 Refers to a quarter of the year between 1 and 4. The quarters of the
4549 year begin on the first days of months 1, 4, 7, and 10.
4552 Refers to a week of the year between 1 and 53.
4555 Refers to a day of the year between 1 and 366.
4558 Refers to a year between 1582 and 19999.
4561 @cindex arguments, invalid
4562 If these functions' arguments are out-of-range, they are correctly
4563 normalized before conversion to date format. Non-integers are rounded
4566 @cindex day-month-year
4567 @cindex dates, day-month-year
4568 @deftypefn {Function} {} DATE.DMY (@var{day}, @var{month}, @var{year})
4569 @deftypefnx {Function} {} DATE.MDY (@var{month}, @var{day}, @var{year})
4570 Results in a date value corresponding to the midnight before day
4571 @var{day} of month @var{month} of year @var{year}.
4575 @cindex dates, month-year
4576 @deftypefn {Function} {} DATE.MOYR (@var{month}, @var{year})
4577 Results in a date value corresponding to the midnight before the first
4578 day of month @var{month} of year @var{year}.
4581 @cindex quarter-year
4582 @cindex dates, quarter-year
4583 @deftypefn {Function} {} DATE.QYR (@var{quarter}, @var{year})
4584 Results in a date value corresponding to the midnight before the first
4585 day of quarter @var{quarter} of year @var{year}.
4589 @cindex dates, week-year
4590 @deftypefn {Function} {} DATE.WKYR (@var{week}, @var{year})
4591 Results in a date value corresponding to the midnight before the first
4592 day of week @var{week} of year @var{year}.
4596 @cindex dates, year-day
4597 @deftypefn {Function} {} DATE.YRDAY (@var{year}, @var{yday})
4598 Results in a date value corresponding to the midnight before day
4599 @var{yday} of year @var{year}.
4602 @node Date Extraction, , Date Construction, Time & Date
4603 @subsubsection Functions that Examine Dates
4604 @cindex extraction, of dates
4605 @cindex date examination
4607 @cindex arguments, of date extraction functions
4608 These functions take numeric arguments in PSPP date or time
4609 format and give numeric results. These names are used for arguments:
4613 A numeric value in PSPP date format.
4616 A numeric value in PSPP time format.
4619 A numeric value in PSPP time or date format.
4623 @cindex dates, in days
4624 @cindex time, in days
4625 @deftypefn {Function} {} XDATE.DATE (@var{time-or-date})
4626 For a time, results in the time corresponding to the number of whole
4627 days @var{date-or-time} includes. For a date, results in the date
4628 corresponding to the latest midnight at or before @var{date-or-time};
4629 that is, gives the date that @var{date-or-time} is in.
4630 (XDATE.DATE(@var{x}) is equivalent to TRUNC(@var{x}/86400)*86400.)
4631 Applying this function to a time is a non-portable feature.
4635 @cindex dates, in hours
4636 @cindex time, in hours
4637 @deftypefn {Function} {} XDATE.HOUR (@var{time-or-date})
4638 For a time, results in the number of whole hours beyond the number of
4639 whole days represented by @var{date-or-time}. For a date, results in
4640 the hour (as an integer between 0 and 23) corresponding to
4641 @var{date-or-time}. (XDATE.HOUR(@var{x}) is equivalent to
4642 MOD(TRUNC(@var{x}/3600),24)) Applying this function to a time is a
4643 non-portable feature.
4646 @cindex day of the year
4647 @cindex dates, day of the year
4648 @deftypefn {Function} {} XDATE.JDAY (@var{date})
4649 Results in the day of the year (as an integer between 1 and 366)
4650 corresponding to @var{date}.
4653 @cindex day of the month
4654 @cindex dates, day of the month
4655 @deftypefn {Function} {} XDATE.MDAY (@var{date})
4656 Results in the day of the month (as an integer between 1 and 31)
4657 corresponding to @var{date}.
4661 @cindex dates, in minutes
4662 @cindex time, in minutes
4663 @deftypefn {Function} {} XDATE.MINUTE (@var{time-or-date})
4664 Results in the number of minutes (as an integer between 0 and 59) after
4665 the last hour in @var{time-or-date}. (XDATE.MINUTE(@var{x}) is
4666 equivalent to MOD(TRUNC(@var{x}/60),60)) Applying this function to a
4667 time is a non-portable feature.
4671 @cindex dates, in months
4672 @deftypefn {Function} {} XDATE.MONTH (@var{date})
4673 Results in the month of the year (as an integer between 1 and 12)
4674 corresponding to @var{date}.
4678 @cindex dates, in quarters
4679 @deftypefn {Function} {} XDATE.QUARTER (@var{date})
4680 Results in the quarter of the year (as an integer between 1 and 4)
4681 corresponding to @var{date}.
4685 @cindex dates, in seconds
4686 @cindex time, in seconds
4687 @deftypefn {Function} {} XDATE.SECOND (@var{time-or-date})
4688 Results in the number of whole seconds after the last whole minute (as
4689 an integer between 0 and 59) in @var{time-or-date}.
4690 (XDATE.SECOND(@var{x}) is equivalent to MOD(@var{x}, 60).) Applying
4691 this function to a time is a non-portable feature.
4695 @cindex times, in days
4696 @deftypefn {Function} {} XDATE.TDAY (@var{time})
4697 Results in the number of whole days (as an integer) in @var{time}.
4698 (XDATE.TDAY(@var{x}) is equivalent to TRUNC(@var{x}/86400).)
4702 @cindex dates, time of day
4703 @deftypefn {Function} {} XDATE.TIME (@var{date})
4704 Results in the time of day at the instant corresponding to @var{date},
4705 in PSPP time format. This is the number of seconds since
4706 midnight on the day corresponding to @var{date}. (XDATE.TIME(@var{x}) is
4707 equivalent to TRUNC(@var{x}/86400)*86400.)
4711 @cindex dates, in weeks
4712 @deftypefn {Function} {} XDATE.WEEK (@var{date})
4713 Results in the week of the year (as an integer between 1 and 53)
4714 corresponding to @var{date}.
4717 @cindex day of the week
4719 @cindex dates, day of the week
4720 @cindex dates, in weekdays
4721 @deftypefn {Function} {} XDATE.WKDAY (@var{date})
4722 Results in the day of week (as an integer between 1 and 7) corresponding
4723 to @var{date}. The days of the week are:
4744 @cindex dates, in years
4745 @deftypefn {Function} {} XDATE.YEAR (@var{date})
4746 Returns the year (as an integer between 1582 and 19999) corresponding to
4750 @node Miscellaneous Functions, Functions Not Implemented, Time & Date, Functions
4751 @subsection Miscellaneous Functions
4752 @cindex functions, miscellaneous
4754 Miscellaneous functions take various arguments and produce various
4757 @cindex cross-case function
4758 @cindex function, cross-case
4759 @deftypefn {Function} {} LAG (@var{variable})
4760 @var{variable} must be a numeric or string variable name. @code{LAG}
4761 results in the value of that variable for the case before the current
4762 one. In case-selection procedures, @code{LAG} results in the value of
4763 the variable for the last case selected. Results in system-missing (for
4764 numeric variables) or blanks (for string variables) for the first case
4765 or before any cases are selected.
4768 @deftypefn {Function} {} LAG (@var{variable}, @var{ncases})
4769 @var{variable} must be a numeric or string variable name. @var{ncases}
4770 must be a small positive constant integer, although there is no explicit
4771 limit. (Use of a large value for @var{ncases} will increase memory
4772 consumption, since PSPP must keep @var{ncases} cases in memory.)
4773 @code{LAG (@var{variable}, @var{ncases}} results in the value of
4774 @var{variable} that is @var{ncases} before the case currently being
4775 processed. See @code{LAG (@var{variable})} above for more details.
4778 @cindex date, Julian
4780 @deftypefn {Function} {} YRMODA (@var{year}, @var{month}, @var{day})
4781 @var{year} is a year between 0 and 199 or 1582 and 19999. @var{month} is
4782 a month between 1 and 12. @var{day} is a day between 1 and 31. If
4783 @var{month} or @var{day} is out-of-range, it changes the next higher
4784 unit. For instance, a @var{day} of 0 refers to the last day of the
4785 previous month, and a @var{month} of 13 refers to the first month of the
4786 next year. @var{year} must be in range. If @var{year} is between 0 and
4787 199, 1900 is added. @var{year}, @var{month}, and @var{day} must all be
4790 @code{YRMODA} results in the number of days between 15 Oct 1582 and
4791 the date specified, plus one. The date passed to @code{YRMODA} must be
4792 on or after 15 Oct 1582. 15 Oct 1582 has a value of 1.
4795 @node Functions Not Implemented, , Miscellaneous Functions, Functions
4796 @subsection Functions Not Implemented
4797 @cindex functions, not implemented
4798 @cindex not implemented
4799 @cindex features, not implemented
4801 These functions are not yet implemented and thus not yet documented,
4802 since it's a hassle.
4826 @node Order of Operations, , Functions, Expressions
4827 @section Operator Precedence
4828 @cindex operator precedence
4829 @cindex precedence, operator
4830 @cindex order of operations
4831 @cindex operations, order of
4833 The following table describes operator precedence. Smaller-numbered
4834 levels in the table have higher precedence. Within a level, operations
4835 are performed from left to right, except for level 2 (exponentiation),
4836 where operations are performed from right to left. If an operator
4837 appears in the table in two places (@code{-}), the first occurrence is
4838 unary, the second is binary.
4852 @code{EQ GE GT LE LT NE}
4857 @node Data Input and Output, System and Portable Files, Expressions, Top
4858 @chapter Data Input and Output
4863 @cindex observations
4865 Data are the focus of the PSPP language.
4866 Each datum belongs to a @dfn{case} (also called an @dfn{observation}).
4867 Each case represents an individual or `experimental unit'.
4868 For example, in the results of a survey, the names of the respondents,
4869 their sex, age @i{etc}. and their responses are all data and the data
4870 pertaining to single respondent is a case.
4871 This chapter examines
4872 the PSPP commands for defining variables and reading and writing data.
4875 @strong{Please note:} Data is not actually read until a procedure is
4876 executed. These commands tell PSPP how to read data, but they
4877 do not @emph{cause} PSPP to read data.
4881 * BEGIN DATA:: Embed data within a syntax file.
4882 * CLEAR TRANSFORMATIONS:: Clear pending transformations.
4883 * DATA LIST:: Fundamental data reading command.
4884 * END CASE:: Output the current case.
4885 * END FILE:: Terminate the current input program.
4886 * FILE HANDLE:: Support for fixed-length records.
4887 * INPUT PROGRAM:: Support for complex input programs.
4888 * LIST:: List cases in the active file.
4889 * MATRIX DATA:: Read matrices in text format.
4890 * NEW FILE:: Clear the active file and dictionary.
4891 * PRINT:: Display values in print formats.
4892 * PRINT EJECT:: Eject the current page then print.
4893 * PRINT SPACE:: Print blank lines.
4894 * REREAD:: Take another look at the previous input line.
4895 * REPEATING DATA:: Multiple cases on a single line.
4896 * WRITE:: Display values in write formats.
4899 @node BEGIN DATA, CLEAR TRANSFORMATIONS, Data Input and Output, Data Input and Output
4903 @cindex Embedding data in syntax files
4904 @cindex Data, embedding in syntax files
4912 @cmd{BEGIN DATA} and @cmd{END DATA} can be used to embed raw ASCII
4913 data in a PSPP syntax file. @cmd{DATA LIST} or another input
4914 procedure must be used before @cmd{BEGIN DATA} (@pxref{DATA LIST}).
4915 @cmd{BEGIN DATA} and @cmd{END DATA} must be used together. @cmd{END
4916 DATA} must appear by itself on a single line, with no leading
4917 whitespace and exactly one space between the words @code{END} and
4918 @code{DATA}, followed immediately by the terminal dot, like this:
4924 @node CLEAR TRANSFORMATIONS, DATA LIST, BEGIN DATA, Data Input and Output
4925 @section CLEAR TRANSFORMATIONS
4926 @vindex CLEAR TRANSFORMATIONS
4929 CLEAR TRANSFORMATIONS.
4932 @cmd{CLEAR TRANSFORMATIONS} clears out all pending
4933 transformations. It does not cancel the current input program. It is
4934 valid only when PSPP is interactive, not in syntax files.
4936 @node DATA LIST, END CASE, CLEAR TRANSFORMATIONS, Data Input and Output
4939 @cindex reading data from a file
4940 @cindex data, reading from a file
4941 @cindex data, embedding in syntax files
4942 @cindex embedding data in syntax files
4944 Used to read text or binary data, @cmd{DATA LIST} is the most
4945 fundamental data-reading command. Even the more sophisticated input
4946 methods use @cmd{DATA LIST} commands as a building block.
4947 Understanding @cmd{DATA LIST} is important to understanding how to use
4948 PSPP to read your data files.
4950 There are two major variants of @cmd{DATA LIST}, which are fixed
4951 format and free format. In addition, free format has a minor variant,
4952 list format, which is discussed in terms of its differences from vanilla
4955 Each form of @cmd{DATA LIST} is described in detail below.
4958 * DATA LIST FIXED:: Fixed columnar locations for data.
4959 * DATA LIST FREE:: Any spacing you like.
4960 * DATA LIST LIST:: Each case must be on a single line.
4963 @node DATA LIST FIXED, DATA LIST FREE, DATA LIST, DATA LIST
4964 @subsection DATA LIST FIXED
4965 @vindex DATA LIST FIXED
4966 @cindex reading fixed-format data
4967 @cindex fixed-format data, reading
4968 @cindex data, fixed-format, reading
4969 @cindex embedding fixed-format data
4975 RECORDS=record_count
4977 /[line_no] var_spec@dots{}
4979 where each var_spec takes one of the forms
4980 var_list start-end [type_spec]
4981 var_list (fortran_spec)
4984 @cmd{DATA LIST FIXED} is used to read data files that have values at fixed
4985 positions on each line of single-line or multiline records. The
4986 keyword FIXED is optional.
4988 The FILE subcommand must be used if input is to be taken from an
4989 external file. It may be used to specify a filename as a string or a
4990 file handle (@pxref{FILE HANDLE}). If the FILE subcommand is not used,
4991 then input is assumed to be specified within the command file using
4992 @cmd{BEGIN DATA}@dots{}@cmd{END DATA} (@pxref{BEGIN DATA}).
4994 The optional RECORDS subcommand, which takes a single integer as an
4995 argument, is used to specify the number of lines per record. If RECORDS
4996 is not specified, then the number of lines per record is calculated from
4997 the list of variable specifications later in @cmd{DATA LIST}.
4999 The END subcommand is only useful in conjunction with @cmd{INPUT
5000 PROGRAM}. @xref{INPUT PROGRAM}, for details.
5002 @cmd{DATA LIST} can optionally output a table describing how the data file
5003 will be read. The TABLE subcommand enables this output, and NOTABLE
5004 disables it. The default is to output the table.
5006 The list of variables to be read from the data list must come last.
5007 Each line in the data record is introduced by a slash (@samp{/}).
5008 Optionally, a line number may follow the slash. Following, any number
5009 of variable specifications may be present.
5011 Each variable specification consists of a list of variable names
5012 followed by a description of their location on the input line. Sets of
5013 variables may specified using the @code{DATA LIST} TO convention
5015 Variables}). There are two ways to specify the location of the variable
5016 on the line: PSPP style and FORTRAN style.
5018 With PSPP style, the starting column and ending column for the field
5019 are specified after the variable name, separated by a dash (@samp{-}).
5020 For instance, the third through fifth columns on a line would be
5021 specified @samp{3-5}. By default, variables are considered to be in
5022 @samp{F} format (@pxref{Input/Output Formats}). (This default can be
5023 changed; see @ref{SET} for more information.)
5025 When using PSPP style, to use a variable format other than the default,
5026 specify the format type in parentheses after the column numbers. For
5027 instance, for alphanumeric @samp{A} format, use @samp{(A)}.
5029 In addition, implied decimal places can be specified in parentheses
5030 after the column numbers. As an example, suppose that a data file has a
5031 field in which the characters @samp{1234} should be interpreted as
5032 having the value 12.34. Then this field has two implied decimal places,
5033 and the corresponding specification would be @samp{(2)}. If a field
5034 that has implied decimal places contains a decimal point, then the
5035 implied decimal places are not applied.
5037 Changing the variable format and adding implied decimal places can be
5038 done together; for instance, @samp{(N,5)}.
5040 When using PSPP style, the input and output width of each variable is
5041 computed from the field width. The field width must be evenly divisible
5042 into the number of variables specified.
5044 FORTRAN style is an altogether different approach to specifying field
5045 locations. With this approach, a list of variable input format
5046 specifications, separated by commas, are placed after the variable names
5047 inside parentheses. Each format specifier advances as many characters
5048 into the input line as it uses.
5050 In addition to the standard format specifiers (@pxref{Input/Output
5051 Formats}), FORTRAN style defines some extensions:
5055 Advance the current column on this line by one character position.
5057 @item @code{T}@var{x}
5058 Set the current column on this line to column @var{x}, with column
5059 numbers considered to begin with 1 at the left margin.
5061 @item @code{NEWREC}@var{x}
5062 Skip forward @var{x} lines in the current record, resetting the active
5063 column to the left margin.
5066 Any format specifier may be preceded by a number. This causes the
5067 action of that format specifier to be repeated the specified number of
5070 @item (@var{spec1}, @dots{}, @var{specN})
5071 Group the given specifiers together. This is most useful when preceded
5072 by a repeat count. Groups may be nested arbitrarily.
5075 FORTRAN and PSPP styles may be freely intermixed. PSPP style leaves the
5076 active column immediately after the ending column specified. Record
5077 motion using @code{NEWREC} in FORTRAN style also applies to later
5078 FORTRAN and PSPP specifiers.
5081 * DATA LIST FIXED Examples:: Examples of DATA LIST FIXED.
5084 @node DATA LIST FIXED Examples, , DATA LIST FIXED, DATA LIST FIXED
5085 @unnumberedsubsubsec Examples
5090 DATA LIST TABLE /NAME 1-10 (A) INFO1 TO INFO3 12-17 (1).
5099 Defines the following variables:
5103 @code{NAME}, a 10-character-wide long string variable, in columns 1
5107 @code{INFO1}, a numeric variable, in columns 12 through 13.
5110 @code{INFO2}, a numeric variable, in columns 14 through 15.
5113 @code{INFO3}, a numeric variable, in columns 16 through 17.
5116 The @code{BEGIN DATA}/@code{END DATA} commands cause three cases to be
5120 Case NAME INFO1 INFO2 INFO3
5121 1 John Smith 10 23 11
5122 2 Bob Arnold 12 20 15
5126 The @code{TABLE} keyword causes PSPP to print out a table
5127 describing the four variables defined.
5131 DAT LIS FIL="survey.dat"
5132 /ID 1-5 NAME 7-36 (A) SURNAME 38-67 (A) MINITIAL 69 (A)
5137 Defines the following variables:
5141 @code{ID}, a numeric variable, in columns 1-5 of the first record.
5144 @code{NAME}, a 30-character long string variable, in columns 7-36 of the
5148 @code{SURNAME}, a 30-character long string variable, in columns 38-67 of
5152 @code{MINITIAL}, a 1-character short string variable, in column 69 of
5156 Fifty variables @code{Q01}, @code{Q02}, @code{Q03}, @dots{}, @code{Q49},
5157 @code{Q50}, all numeric, @code{Q01} in column 7, @code{Q02} in column 8,
5158 @dots{}, @code{Q49} in column 55, @code{Q50} in column 56, all in the second
5162 Cases are separated by a blank record.
5164 Data is read from file @file{survey.dat} in the current directory.
5166 This example shows keywords abbreviated to their first 3 letters.
5170 @node DATA LIST FREE, DATA LIST LIST, DATA LIST FIXED, DATA LIST
5171 @subsection DATA LIST FREE
5172 @vindex DATA LIST FREE
5181 where each var_spec takes one of the forms
5182 var_list [(type_spec)]
5186 In free format, the input data is structured as a series of comma- or
5187 whitespace-delimited fields (end of line is one form of whitespace; it
5188 is not treated specially). Field contents may be surrounded by matched
5189 pairs of apostrophes (@samp{'}) or quotes (@samp{"}), or they may be
5190 unenclosed. For any type of field leading white space (up to the
5191 apostrophe or quote, if any) is not included in the field.
5193 Multiple consecutive delimiters are equivalent to a single delimiter.
5194 To specify an empty field, write an empty set of single or double
5195 quotes; for instance, @samp{""}.
5197 The NOTABLE and TABLE subcommands are as in @cmd{DATA LIST FIXED} above.
5198 NOTABLE is the default.
5200 The FILE and END subcommands are as in @cmd{DATA LIST FIXED} above.
5202 The variables to be parsed are given as a single list of variable names.
5203 This list must be introduced by a single slash (@samp{/}). The set of
5204 variable names may contain format specifications in parentheses
5205 (@pxref{Input/Output Formats}). Format specifications apply to all
5206 variables back to the previous parenthesized format specification.
5208 In addition, an asterisk may be used to indicate that all variables
5209 preceding it are to have input/output format @samp{F8.0}.
5211 Specified field widths are ignored on input, although all normal limits
5212 on field width apply, but they are honored on output.
5214 @node DATA LIST LIST, , DATA LIST FREE, DATA LIST
5215 @subsection DATA LIST LIST
5216 @vindex DATA LIST LIST
5225 where each var_spec takes one of the forms
5226 var_list [(type_spec)]
5230 With one exception, @cmd{DATA LIST LIST} is syntactically and
5231 semantically equivalent to @cmd{DATA LIST FREE}. The exception is
5232 that each input line is expected to correspond to exactly one input
5233 record. If more or fewer fields are found on an input line than
5234 expected, an appropriate diagnostic is issued.
5236 @node END CASE, END FILE, DATA LIST, Data Input and Output
5244 @cmd{END CASE} is used only within @cmd{INPUT PROGRAM} to output the
5245 current case. @xref{INPUT PROGRAM}, for details.
5247 @node END FILE, FILE HANDLE, END CASE, Data Input and Output
5255 @cmd{END FILE} is used only within @cmd{INPUT PROGRAM} to terminate
5256 the current input program. @xref{INPUT PROGRAM}.
5258 @node FILE HANDLE, INPUT PROGRAM, END FILE, Data Input and Output
5259 @section FILE HANDLE
5263 FILE HANDLE handle_name
5265 /RECFORM=@{VARIABLE,FIXED,SPANNED@}
5267 /MODE=@{CHARACTER,IMAGE,BINARY,MULTIPUNCH,360@}
5270 Use @cmd{FILE HANDLE} to define the attributes of a file that does
5271 not use conventional variable-length records terminated by newline
5274 Specify the file handle name as an identifier. Any given identifier may
5275 only appear once in a PSPP run. File handles may not be reassigned to a
5276 different file. The file handle name must immediately follow the @cmd{FILE
5277 HANDLE} command name.
5279 The NAME subcommand specifies the name of the file associated with the
5280 handle. It is the only required subcommand.
5282 The RECFORM subcommand specifies how the file is laid out. VARIABLE
5283 specifies variable-length lines terminated with newlines, and it is the
5284 default. FIXED specifies fixed-length records. SPANNED is not
5287 LRECL specifies the length of fixed-length records. It is required if
5288 @code{/RECFORM FIXED} is specified.
5290 MODE specifies a file mode. CHARACTER, the default, causes the data
5291 file to be opened in ANSI C text mode. BINARY causes the data file to
5292 be opened in ANSI C binary mode. The other possibilities are not
5295 @node INPUT PROGRAM, LIST, FILE HANDLE, Data Input and Output
5296 @section INPUT PROGRAM
5297 @vindex INPUT PROGRAM
5301 @dots{} input commands @dots{}
5305 @cmd{INPUT PROGRAM}@dots{}@cmd{END INPUT PROGRAM} specifies a
5306 complex input program. By placing data input commands within @cmd{INPUT
5307 PROGRAM}, PSPP programs can take advantage of more complex file
5308 structures than available with only @cmd{DATA LIST}.
5310 The first sort of extended input program is to simply put multiple @cmd{DATA
5311 LIST} commands within the @cmd{INPUT PROGRAM}. This will cause all of
5313 files to be read in parallel. Input will stop when end of file is
5314 reached on any of the data files.
5316 Transformations, such as conditional and looping constructs, can also be
5317 included within @cmd{INPUT PROGRAM}. These can be used to combine input
5318 from several data files in more complex ways. However, input will still
5319 stop when end of file is reached on any of the data files.
5321 To prevent @cmd{INPUT PROGRAM} from terminating at the first end of
5323 the END subcommand on @cmd{DATA LIST}. This subcommand takes a
5325 which should be a numeric scratch variable (@pxref{Scratch Variables}).
5326 (It need not be a scratch variable but otherwise the results can be
5327 surprising.) The value of this variable is set to 0 when reading the
5328 data file, or 1 when end of file is encountered.
5330 Two additional commands are useful in conjunction with @cmd{INPUT PROGRAM}.
5331 @cmd{END CASE} is the first. Normally each loop through the
5333 structure produces one case. @cmd{END CASE} controls exactly
5334 when cases are output. When @cmd{END CASE} is used, looping from the end of
5335 @cmd{INPUT PROGRAM} to the beginning does not cause a case to be output.
5337 @cmd{END FILE} is the second. When the END subcommand is used on @cmd{DATA
5338 LIST}, there is no way for the @cmd{INPUT PROGRAM} construct to stop
5340 so an infinite loop results. @cmd{END FILE}, when executed,
5341 stops the flow of input data and passes out of the @cmd{INPUT PROGRAM}
5344 All this is very confusing. A few examples should help to clarify.
5348 DATA LIST NOTABLE FILE='a.data'/X 1-10.
5349 DATA LIST NOTABLE FILE='b.data'/Y 1-10.
5354 The example above reads variable X from file @file{a.data} and variable
5355 Y from file @file{b.data}. If one file is shorter than the other then
5356 the extra data in the longer file is ignored.
5363 DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
5366 DATA LIST NOTABLE END=#B FILE='b.data'/Y 1-10.
5376 The above example reads variable X from @file{a.data} and variable Y from
5377 @file{b.data}. If one file is shorter than the other then the missing
5378 field is set to the system-missing value alongside the present value for
5379 the remaining length of the longer file.
5386 DATA LIST NOTABLE END=#B FILE='b.data'/X 1-10.
5393 DATA LIST NOTABLE END=#A FILE='a.data'/X 1-10.
5402 The above example reads data from file @file{a.data}, then from
5403 @file{b.data}, and concatenates them into a single active file.
5410 DATA LIST NOTABLE END=#EOF FILE='a.data'/X 1-10.
5418 DATA LIST NOTABLE END=#EOF FILE='b.data'/X 1-10.
5429 The above example does the same thing as the previous example, in a
5435 COMPUTE X=UNIFORM(10).
5440 LIST/FORMAT=NUMBERED.
5443 The above example causes an active file to be created consisting of 50
5444 random variates between 0 and 10.
5446 @node LIST, MATRIX DATA, INPUT PROGRAM, Data Input and Output
5453 /CASES=FROM start_index TO end_index BY incr_index
5454 /FORMAT=@{UNNUMBERED,NUMBERED@} @{WRAP,SINGLE@}
5458 The @cmd{LIST} procedure prints the values of specified variables to the
5461 The VARIABLES subcommand specifies the variables whose values are to be
5462 printed. Keyword VARIABLES is optional. If VARIABLES subcommand is not
5463 specified then all variables in the active file are printed.
5465 The CASES subcommand can be used to specify a subset of cases to be
5466 printed. Specify FROM and the case number of the first case to print,
5467 TO and the case number of the last case to print, and BY and the number
5468 of cases to advance between printing cases, or any subset of those
5469 settings. If CASES is not specified then all cases are printed.
5471 The FORMAT subcommand can be used to change the output format. NUMBERED
5472 will print case numbers along with each case; UNNUMBERED, the default,
5473 causes the case numbers to be omitted. The WRAP and SINGLE settings are
5474 currently not used. WEIGHT will cause case weights to be printed along
5475 with variable values; NOWEIGHT, the default, causes case weights to be
5476 omitted from the output.
5478 Case numbers start from 1. They are counted after all transformations
5479 have been considered.
5481 @cmd{LIST} attempts to fit all the values on a single line. If needed
5482 to make them fit, variable names are displayed vertically. If values
5483 cannot fit on a single line, then a multi-line format will be used.
5485 @cmd{LIST} is a procedure. It causes the data to be read.
5487 @node MATRIX DATA, NEW FILE, LIST, Data Input and Output
5488 @section MATRIX DATA
5495 /FORMAT=@{LIST,FREE@} @{LOWER,UPPER,FULL@} @{DIAGONAL,NODIAGONAL@}
5496 /SPLIT=@{new_var,var_list@}
5500 /CONTENTS=@{N_VECTOR,N_SCALAR,N_MATRIX,MEAN,STDDEV,COUNT,MSE,
5501 DFE,MAT,COV,CORR,PROX@}
5504 @cmd{MATRIX DATA} command reads square matrices in one of several textual
5505 formats. @cmd{MATRIX DATA} clears the dictionary and replaces it and
5509 Use VARIABLES to specify the variables that form the rows and columns of
5510 the matrices. You may not specify a variable named @code{VARNAME_}. You
5511 should specify VARIABLES first.
5513 Specify the file to read on FILE, either as a file name string or a file
5514 handle (@pxref{FILE HANDLE}). If FILE is not specified then matrix data
5515 must immediately follow @cmd{MATRIX DATA} with a @cmd{BEGIN
5516 DATA}@dots{}@cmd{END DATA}
5517 construct (@pxref{BEGIN DATA}).
5519 The FORMAT subcommand specifies how the matrices are formatted. LIST,
5520 the default, indicates that there is one line per row of matrix data;
5521 FREE allows single matrix rows to be broken across multiple lines. This
5522 is analogous to the difference between @cmd{DATA LIST FREE} and
5523 @cmd{DATA LIST LIST}
5524 (@pxref{DATA LIST}). LOWER, the default, indicates that the lower
5525 triangle of the matrix is given; UPPER indicates the upper triangle; and
5526 FULL indicates that the entire matrix is given. DIAGONAL, the default,
5527 indicates that the diagonal is part of the data; NODIAGONAL indicates
5528 that it is omitted. DIAGONAL/NODIAGONAL have no effect when FULL is
5531 The SPLIT subcommand is used to specify @cmd{SPLIT FILE} variables for the
5532 input matrices (@pxref{SPLIT FILE}). Specify either a single variable
5533 not specified on VARIABLES, or one or more variables that are specified
5534 on VARIABLES. In the former case, the SPLIT values are not present in
5535 the data and ROWTYPE_ may not be specified on VARIABLES. In the latter
5536 case, the SPLIT values are present in the data.
5538 Specify a list of factor variables on FACTORS. Factor variables must
5539 also be listed on VARIABLES. Factor variables are used when there are
5540 some variables where, for each possible combination of their values,
5541 statistics on the matrix variables are included in the data.
5543 If FACTORS is specified and ROWTYPE_ is not specified on VARIABLES, the
5544 CELLS subcommand is required. Specify the number of factor variable
5545 combinations that are given. For instance, if factor variable A has 2
5546 values and factor variable B has 3 values, specify 6.
5548 The N subcommand specifies a population number of observations. When N
5549 is specified, one N record is output for each @cmd{SPLIT FILE}.
5551 Use CONTENTS to specify what sort of information the matrices include.
5552 Each possible option is described in more detail below. When ROWTYPE_
5553 is specified on VARIABLES, CONTENTS is optional; otherwise, if CONTENTS
5554 is not specified then /CONTENTS=CORR is assumed.
5559 Number of observations as a vector, one value for each variable.
5561 Number of observations as a single value.
5567 Vector of standard deviations.
5571 Vector of mean squared errors.
5573 Vector of degrees of freedom.
5584 The exact semantics of the matrices read by @cmd{MATRIX DATA} are complex.
5585 Right now @cmd{MATRIX DATA} isn't too useful due to a lack of procedures
5586 accepting or producing related data, so these semantics aren't
5587 documented. Later, they'll be described here in detail.
5589 @node NEW FILE, PRINT, MATRIX DATA, Data Input and Output
5597 @cmd{NEW FILE} command clears the current active file.
5599 @node PRINT, PRINT EJECT, NEW FILE, Data Input and Output
5608 /[line_no] arg@dots{}
5610 arg takes one of the following forms:
5611 'string' [start-end]
5612 var_list start-end [type_spec]
5613 var_list (fortran_spec)
5617 The @cmd{PRINT} transformation writes variable data to an output file.
5618 @cmd{PRINT} is executed when a procedure causes the data to be read.
5619 Follow @cmd{PRINT} by @cmd{EXECUTE} to print variable data without
5620 invoking a procedure (@pxref{EXECUTE}).
5622 All @cmd{PRINT} subcommands are optional.
5624 The OUTFILE subcommand specifies the file to receive the output. The
5625 file may be a file name as a string or a file handle (@pxref{FILE
5626 HANDLE}). If OUTFILE is not present then output will be sent to PSPP's
5627 output listing file.
5629 The RECORDS subcommand specifies the number of lines to be output. The
5630 number of lines may optionally be surrounded by parentheses.
5632 TABLE will cause the PRINT command to output a table to the listing file
5633 that describes what it will print to the output file. NOTABLE, the
5634 default, suppresses this output table.
5636 Introduce the strings and variables to be printed with a slash
5637 (@samp{/}). Optionally, the slash may be followed by a number
5638 indicating which output line will be specified. In the absence of this
5639 line number, the next line number will be specified. Multiple lines may
5640 be specified using multiple slashes with the intended output for a line
5641 following its respective slash.
5643 Literal strings may be printed. Specify the string itself. Optionally
5644 the string may be followed by a column number or range of column
5645 numbers, specifying the location on the line for the string to be
5646 printed. Otherwise, the string will be printed at the current position
5649 Variables to be printed can be specified in the same ways as available
5650 for @cmd{DATA LIST FIXED} (@pxref{DATA LIST FIXED}). In addition, a
5652 list may be followed by an asterisk (@samp{*}), which indicates that the
5653 variables should be printed in their dictionary print formats, separated
5654 by spaces. A variable list followed by a slash or the end of command
5655 will be interpreted the same way.
5657 If a FORTRAN type specification is used to move backwards on the current
5658 line, then text is written at that point on the line, the line will be
5659 truncated to that length, although additional text being added will
5660 again extend the line to that length.
5662 @node PRINT EJECT, PRINT SPACE, PRINT, Data Input and Output
5663 @section PRINT EJECT
5671 /[line_no] arg@dots{}
5673 arg takes one of the following forms:
5674 'string' [start-end]
5675 var_list start-end [type_spec]
5676 var_list (fortran_spec)
5680 @cmd{PRINT EJECT} writes data to an output file. Before the data is
5681 written, the current page in the listing file is ejected.
5683 @xref{PRINT}, for more information on syntax and usage.
5685 @node PRINT SPACE, REREAD, PRINT EJECT, Data Input and Output
5686 @section PRINT SPACE
5690 PRINT SPACE OUTFILE='filename' n_lines.
5693 @cmd{PRINT SPACE} prints one or more blank lines to an output file.
5695 The OUTFILE subcommand is optional. It may be used to direct output to
5696 a file specified by file name as a string or file handle (@pxref{FILE
5697 HANDLE}). If OUTFILE is not specified then output will be directed to
5700 n_lines is also optional. If present, it is an expression
5701 (@pxref{Expressions}) specifying the number of blank lines to be
5702 printed. The expression must evaluate to a nonnegative value.
5704 @node REREAD, REPEATING DATA, PRINT SPACE, Data Input and Output
5709 REREAD FILE=handle COLUMN=column.
5712 The @cmd{REREAD} transformation allows the previous input line in a
5714 already processed by @cmd{DATA LIST} or another input command to be re-read
5715 for further processing.
5717 The FILE subcommand, which is optional, is used to specify the file to
5718 have its line re-read. The file must be specified in the form of a file
5719 handle (@pxref{FILE HANDLE}). If FILE is not specified then the last
5720 file specified on @cmd{DATA LIST} will be assumed (last file specified
5721 lexically, not in terms of flow-of-control).
5723 By default, the line re-read is re-read in its entirety. With the
5724 COLUMN subcommand, a prefix of the line can be exempted from
5725 re-reading. Specify an expression (@pxref{Expressions}) evaluating to
5726 the first column that should be included in the re-read line. Columns
5727 are numbered from 1 at the left margin.
5729 Issuing @code{REREAD} multiple times will not back up in the data
5730 file. Instead, it will re-read the same line multiple times.
5732 @node REPEATING DATA, WRITE, REREAD, Data Input and Output
5733 @section REPEATING DATA
5734 @vindex REPEATING DATA
5742 /CONTINUED[=cont_start-cont_end]
5743 /ID=id_start-id_end=id_var
5745 /DATA=var_spec@dots{}
5747 where each var_spec takes one of the forms
5748 var_list start-end [type_spec]
5749 var_list (fortran_spec)
5752 @cmd{REPEATING DATA} parses groups of data repeating in
5753 a uniform format, possibly with several groups on a single line. Each
5754 group of data corresponds with one case. @cmd{REPEATING DATA} may only be
5755 used within an @cmd{INPUT PROGRAM} structure (@pxref{INPUT PROGRAM}).
5756 When used with @cmd{DATA LIST}, it
5757 can be used to parse groups of cases that share a subset of variables
5758 but differ in their other data.
5760 The STARTS subcommand is required. Specify a range of columns, using
5761 literal numbers or numeric variable names. This range specifies the
5762 columns on the first line that are used to contain groups of data. The
5763 ending column is optional. If it is not specified, then the record
5764 width of the input file is used. For the inline file (@pxref{BEGIN
5765 DATA}) this is 80 columns; for a file with fixed record widths it is the
5766 record width; for other files it is 1024 characters by default.
5768 The OCCURS subcommand is required. It must be a number or the name of a
5769 numeric variable. Its value is the number of groups present in the
5772 The DATA subcommand is required. It must be the last subcommand
5773 specified. It is used to specify the data present within each repeating
5774 group. Column numbers are specified relative to the beginning of a
5775 group at column 1. Data is specified in the same way as with @cmd{DATA LIST
5776 FIXED} (@pxref{DATA LIST FIXED}).
5778 All other subcommands are optional.
5780 FILE specifies the file to read, either a file name as a string or a
5781 file handle (@pxref{FILE HANDLE}). If FILE is not present then the
5782 default is the last file handle used on @cmd{DATA LIST} (lexically, not in
5783 terms of flow of control).
5785 By default @cmd{REPEATING DATA} will output a table describing how it will
5786 parse the input data. Specifying NOTABLE will disable this behavior;
5787 specifying TABLE will explicitly enable it.
5789 The LENGTH subcommand specifies the length in characters of each group.
5790 If it is not present then length is inferred from the DATA subcommand.
5791 LENGTH can be a number or a variable name.
5793 Normally all the data groups are expected to be present on a single
5794 line. Use the CONTINUED command to indicate that data can be continued
5795 onto additional lines. If data on continuation lines starts at the left
5796 margin and continues through the entire field width, no column
5797 specifications are necessary on CONTINUED. Otherwise, specify the
5798 possible range of columns in the same way as on STARTS.
5800 When data groups are continued from line to line, it is easy
5801 for cases to get out of sync through careless hand editing. The
5802 ID subcommand allows a case identifier to be present on each line of
5803 repeating data groups. @cmd{REPEATING DATA} will check for the same
5804 identifier on each line and report mismatches. Specify the range of
5805 columns that the identifier will occupy, followed by an equals sign
5806 (@samp{=}) and the identifier variable name. The variable must already
5807 have been declared with @cmd{NUMERIC} or another command.
5809 @node WRITE, , REPEATING DATA, Data Input and Output
5818 /[line_no] arg@dots{}
5820 arg takes one of the following forms:
5821 'string' [start-end]
5822 var_list start-end [type_spec]
5823 var_list (fortran_spec)
5827 @code{WRITE} writes text or binary data to an output file.
5829 @xref{PRINT}, for more information on syntax and usage. The main
5830 difference between @code{PRINT} and @code{WRITE} is that @cmd{WRITE}
5831 uses write formats by default, where PRINT uses print formats.
5833 The sole additional difference is that if @cmd{WRITE} is used to send output
5834 to a binary file, carriage control characters will not be output.
5835 @xref{FILE HANDLE}, for information on how to declare a file as binary.
5837 @node System and Portable Files, Variable Attributes, Data Input and Output, Top
5838 @chapter System Files and Portable Files
5840 The commands in this chapter read, write, and examine system files and
5844 * APPLY DICTIONARY:: Apply system file dictionary to active file.
5845 * EXPORT:: Write to a portable file.
5846 * GET:: Read from a system file.
5847 * IMPORT:: Read from a portable file.
5848 * MATCH FILES:: Merge system files.
5849 * SAVE:: Write to a system file.
5850 * SYSFILE INFO:: Display system file dictionary.
5851 * XSAVE:: Write to a system file, as a transform.
5854 @node APPLY DICTIONARY, EXPORT, System and Portable Files, System and Portable Files
5855 @section APPLY DICTIONARY
5856 @vindex APPLY DICTIONARY
5859 APPLY DICTIONARY FROM='filename'.
5862 @cmd{APPLY DICTIONARY} applies the variable labels, value labels,
5863 and missing values from variables in a system file to corresponding
5864 variables in the active file. In some cases it also updates the
5867 Specify a system file with a file name string or as a file handle
5868 (@pxref{FILE HANDLE}). The dictionary in the system file will be read,
5869 but it will not replace the active file dictionary. The system file's
5870 data will not be read.
5872 Only variables with names that exist in both the active file and the
5873 system file are considered. Variables with the same name but different
5874 types (numeric, string) will cause an error message. Otherwise, the
5875 system file variables' attributes will replace those in their matching
5876 active file variables, as described below.
5878 If a system file variable has a variable label, then it will replace the
5879 active file variable's variable label. If the system file variable does
5880 not have a variable label, then the active file variable's variable
5881 label, if any, will be retained.
5883 If the active file variable is numeric or short string, then value
5884 labels and missing values, if any, will be copied to the active file
5885 variable. If the system file variable does not have value labels or
5886 missing values, then those in the active file variable, if any, will not
5889 Finally, weighting of the active file is updated (@pxref{WEIGHT}). If
5890 the active file has a weighting variable, and the system file does not,
5891 or if the weighting variable in the system file does not exist in the
5892 active file, then the active file weighting variable, if any, is
5893 retained. Otherwise, the weighting variable in the system file becomes
5894 the active file weighting variable.
5896 @cmd{APPLY DICTIONARY} takes effect immediately. It does not read the
5898 file. The system file is not modified.
5900 @node EXPORT, GET, APPLY DICTIONARY, System and Portable Files
5909 /RENAME=(src_names=target_names)@dots{}
5912 The @cmd{EXPORT} procedure writes the active file dictionary and data to a
5913 specified portable file.
5915 The OUTFILE subcommand, which is the only required subcommand, specifies
5916 the portable file to be written as a file name string or a file handle
5917 (@pxref{FILE HANDLE}).
5919 DROP, KEEP, and RENAME follow the same format as the SAVE procedure
5922 @cmd{EXPORT} is a procedure. It causes the active file to be read.
5924 @node GET, IMPORT, EXPORT, System and Portable Files
5933 /RENAME=(src_names=target_names)@dots{}
5936 @cmd{GET} clears the current dictionary and active file and
5937 replaces them with the dictionary and data from a specified system file.
5939 The FILE subcommand is the only required subcommand. Specify the system
5940 file to be read as a string file name or a file handle (@pxref{FILE
5943 By default, all the variables in a system file are read. The DROP
5944 subcommand can be used to specify a list of variables that are not to be
5945 read. By contrast, the KEEP subcommand can be used to specify variable
5946 that are to be read, with all other variables not read.
5948 Normally variables in a system file retain the names that they were
5949 saved under. Use the RENAME subcommand to change these names. Specify,
5950 within parentheses, a list of variable names followed by an equals sign
5951 (@samp{=}) and the names that they should be renamed to. Multiple
5952 parenthesized groups of variable names can be included on a single
5953 RENAME subcommand. Variables' names may be swapped using a RENAME
5954 subcommand of the form @samp{/RENAME=(A B=B A)}.
5956 Alternate syntax for the RENAME subcommand allows the parentheses to be
5957 eliminated. When this is done, only a single variable may be renamed at
5958 once. For instance, @samp{/RENAME=A=B}. This alternate syntax is
5961 DROP, KEEP, and RENAME are performed in left-to-right order. They
5962 each may be present any number of times. @cmd{GET} never modifies a
5963 system file on disk. Only the active file read from the system file
5964 is affected by these subcommands.
5966 @cmd{GET} does not cause the data to be read, only the dictionary. The data
5967 is read later, when a procedure is executed.
5969 @node IMPORT, MATCH FILES, GET, System and Portable Files
5979 /RENAME=(src_names=target_names)@dots{}
5982 The @cmd{IMPORT} transformation clears the active file dictionary and
5984 replaces them with a dictionary and data from a portable file on disk.
5986 The FILE subcommand, which is the only required subcommand, specifies
5987 the portable file to be read as a file name string or a file handle
5988 (@pxref{FILE HANDLE}).
5990 The TYPE subcommand is currently not used.
5992 DROP, KEEP, and RENAME follow the syntax used by @cmd{GET} (@pxref{GET}).
5994 @cmd{IMPORT} does not cause the data to be read, only the dictionary. The
5995 data is read later, when a procedure is executed.
5997 @node MATCH FILES, SAVE, IMPORT, System and Portable Files
5998 @section MATCH FILES
6004 /@{FILE,TABLE@}=@{*,'filename'@}
6007 /RENAME=(src_names=target_names)@dots{}
6014 @cmd{MATCH FILES} merges one or more system files, optionally
6015 including the active file. Records with the same values for BY
6016 variables are combined into a single record. Records with different
6017 values are output in order. Thus, multiple sorted system files are
6018 combined into a single sorted system file based on the value of the BY
6021 The BY subcommand specifies a list of variables that are used to match
6022 records from each of the system files. Variables specified must exist
6023 in all the files specified on FILE and TABLE. BY should usually be
6024 specified. If TABLE is used then BY is required.
6026 Specify FILE with a system file as a file name string or file handle
6027 (@pxref{FILE HANDLE}), or with an asterisk (@samp{*}) to
6028 indicate the current active file. The files specified on FILE are
6029 merged together based on the BY variables, or combined case-by-case if
6030 BY is not specified. Normally at least two FILE subcommands should be
6033 Specify TABLE with a system file to use it as a @dfn{table
6034 lookup file}. Records in table lookup files are not used up after
6035 they've been used once. This means that data in table lookup files can
6036 correspond to any number of records in FILE files. Table lookup files
6037 correspond to lookup tables in traditional relational database systems.
6038 It is incorrect to have records with duplicate BY values in table lookup
6041 Any number of FILE and TABLE subcommands may be specified. Each
6042 instance of FILE or TABLE can be followed by DROP, KEEP, and/or RENAME
6043 subcommands. These take the same form as the corresponding subcommands
6044 of @cmd{GET} (@pxref{GET}), and perform the same functions.
6046 Variables belonging to files that are not present for the current case
6047 are set to the system-missing value for numeric variables or spaces for
6050 IN, FIRST, LAST, and MAP are currently not used.
6052 @node SAVE, SYSFILE INFO, MATCH FILES, System and Portable Files
6059 /@{COMPRESSED,UNCOMPRESSED@}
6062 /RENAME=(src_names=target_names)@dots{}
6065 The @cmd{SAVE} procedure causes the dictionary and data in the active
6067 be written to a system file.
6069 FILE is the only required subcommand. Specify the system
6070 file to be written as a string file name or a file handle (@pxref{FILE
6073 The COMPRESS and UNCOMPRESS subcommand determine whether the saved
6074 system file is compressed. By default, system files are compressed.
6075 This default can be changed with the SET command (@pxref{SET}).
6077 By default, all the variables in the active file dictionary are written
6078 to the system file. The DROP subcommand can be used to specify a list
6079 of variables not to be written. In contrast, KEEP specifies variables
6080 to be written, with all variables not specified not written.
6082 Normally variables are saved to a system file under the same names they
6083 have in the active file. Use the RENAME subcommand to change these names.
6084 Specify, within parentheses, a list of variable names followed by an
6085 equals sign (@samp{=}) and the names that they should be renamed to.
6086 Multiple parenthesized groups of variable names can be included on a
6087 single RENAME subcommand. Variables' names may be swapped using a
6088 RENAME subcommand of the form @samp{/RENAME=(A B=B A)}.
6090 Alternate syntax for the RENAME subcommand allows the parentheses to be
6091 eliminated. When this is done, only a single variable may be renamed at
6092 once. For instance, @samp{/RENAME=A=B}. This alternate syntax is
6095 DROP, KEEP, and RENAME are performed in left-to-right order. They
6096 each may be present any number of times. @cmd{SAVE} never modifies
6097 the active file. DROP, KEEP, and RENAME only affect the system file
6100 @cmd{SAVE} causes the data to be read. It is a procedure.
6102 @node SYSFILE INFO, XSAVE, SAVE, System and Portable Files
6103 @section SYSFILE INFO
6104 @vindex SYSFILE INFO
6107 SYSFILE INFO FILE='filename'.
6110 @cmd{SYSFILE INFO} reads the dictionary in a system file and
6111 displays the information in its dictionary.
6113 Specify a file name or file handle. @cmd{SYSFILE INFO} reads that file as
6114 a system file and displays information on its dictionary.
6116 @cmd{SYSFILE INFO} does not affect the current active file.
6118 @node XSAVE, , SYSFILE INFO, System and Portable Files
6125 /@{COMPRESSED,UNCOMPRESSED@}
6128 /RENAME=(src_names=target_names)@dots{}
6131 The @cmd{XSAVE} transformation writes the active file dictionary and
6133 system file stored on disk.
6135 @cmd{XSAVE} is a transformation, not a procedure. It is executed when the
6136 data is read by a procedure or procedure-like command. In all other
6137 respects, @cmd{XSAVE} is identical to @cmd{SAVE}. @xref{SAVE}, for
6139 on syntax and usage.
6141 @node Variable Attributes, Data Manipulation, System and Portable Files, Top
6142 @chapter Manipulating variables
6144 The variables in the active file dictionary are important. There are
6145 several utility functions for examining and adjusting them.
6148 * ADD VALUE LABELS:: Add value labels to variables.
6149 * DISPLAY:: Display variable names & descriptions.
6150 * DISPLAY VECTORS:: Display a list of vectors.
6151 * FORMATS:: Set print and write formats.
6152 * LEAVE:: Don't clear variables between cases.
6153 * MISSING VALUES:: Set missing values for variables.
6154 * MODIFY VARS:: Rename, reorder, and drop variables.
6155 * NUMERIC:: Create new numeric variables.
6156 * PRINT FORMATS:: Set variable print formats.
6157 * RENAME VARIABLES:: Rename variables.
6158 * VALUE LABELS:: Set value labels for variables.
6159 * STRING:: Create new string variables.
6160 * VARIABLE LABELS:: Set variable labels for variables.
6161 * VECTOR:: Declare an array of variables.
6162 * WRITE FORMATS:: Set variable write formats.
6165 @node ADD VALUE LABELS, DISPLAY, Variable Attributes, Variable Attributes
6166 @section ADD VALUE LABELS
6167 @vindex ADD VALUE LABELS
6171 /var_list value 'label' [value 'label']@dots{}
6174 @cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
6175 LABELS} (@pxref{VALUE LABELS}), but it does not clear value
6176 labels from the variables before adding the ones specified.
6178 @node DISPLAY, DISPLAY VECTORS, ADD VALUE LABELS, Variable Attributes
6183 DISPLAY @{NAMES,INDEX,LABELS,VARIABLES,DICTIONARY,SCRATCH@}
6187 @cmd{DISPLAY} displays requested information on variables. Variables can
6188 optionally be sorted alphabetically. The entire dictionary or just
6189 specified variables can be described.
6191 One of the following keywords can be present:
6195 The variables' names are displayed.
6198 The variables' names are displayed along with a value describing their
6199 position within the active file dictionary.
6202 Variable names, positions, and variable labels are displayed.
6205 Variable names, positions, print and write formats, and missing values
6209 Variable names, positions, print and write formats, missing values,
6210 variable labels, and value labels are displayed.
6213 Varible names are displayed, for scratch variables only (@pxref{Scratch
6217 If SORTED is specified, then the variables are displayed in ascending
6218 order based on their names; otherwise, they are displayed in the order
6219 that they occur in the active file dictionary.
6221 @node DISPLAY VECTORS, FORMATS, DISPLAY, Variable Attributes
6222 @section DISPLAY VECTORS
6223 @vindex DISPLAY VECTORS
6229 @cmd{DISPLAY VECTORS} lists all the currently declared vectors.
6231 @node FORMATS, LEAVE, DISPLAY VECTORS, Variable Attributes
6236 FORMATS var_list (fmt_spec).
6239 @cmd{FORMATS} set both print and write formats for the specified
6240 variables to the specified format specification. @xref{Input/Output
6243 Specify a list of variables followed by a format specification in
6244 parentheses. The print and write formats of the specified variables
6247 Additional lists of variables and formats may be included if they are
6248 delimited by a slash (@samp{/}).
6250 @cmd{FORMATS} takes effect immediately. It is not affected by
6251 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
6253 @node LEAVE, MISSING VALUES, FORMATS, Variable Attributes
6261 @cmd{LEAVE} prevents the specified variables from being
6262 reinitialized whenever a new case is processed.
6264 Normally, when a data file is processed, every variable in the active
6265 file is initialized to the system-missing value or spaces at the
6266 beginning of processing for each case. When a variable has been
6267 specified on @cmd{LEAVE}, this is not the case. Instead, that variable is
6268 initialized to 0 (not system-missing) or spaces for the first case.
6269 After that, it retains its value between cases.
6271 This becomes useful for counters. For instance, in the example below
6272 the variable SUM maintains a running total of the values in the ITEM
6276 DATA LIST /ITEM 1-3.
6277 COMPUTE SUM=SUM+ITEM.
6288 @noindent Partial output from this example:
6297 It is best to use @cmd{LEAVE} command immediately before invoking a
6298 procedure command, because the left status of variables is reset by
6299 certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
6300 Left status is also reset by all procedure invocations.
6302 @node MISSING VALUES, MODIFY VARS, LEAVE, Variable Attributes
6303 @section MISSING VALUES
6304 @vindex MISSING VALUES
6307 MISSING VALUES var_list (missing_values).
6309 missing_values takes one of the following forms:
6314 num1 THRU num2, num3
6317 string1, string2, string3
6318 As part of a range, LO or LOWEST may take the place of num1;
6319 HI or HIGHEST may take the place of num2.
6322 @cmd{MISSING VALUES} sets user-missing values for numeric and
6323 short string variables. Long string variables may not have missing
6326 Specify a list of variables, followed by a list of their user-missing
6327 values in parentheses. Up to three discrete values may be given, or,
6328 for numeric variables only, a range of values optionally accompanied by
6329 a single discrete value. Ranges may be open-ended on one end, indicated
6330 through the use of the keyword LO or LOWEST or HI or HIGHEST.
6332 The @cmd{MISSING VALUES} command takes effect immediately. It is not
6333 affected by conditional and looping constructs such as @cmd{DO IF} or
6336 @node MODIFY VARS, NUMERIC, MISSING VALUES, Variable Attributes
6337 @section MODIFY VARS
6342 /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
6343 /RENAME=(old_names=new_names)@dots{}
6344 /@{DROP,KEEP@}=var_list
6348 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
6351 At least one subcommand must be specified, and no subcommand may be
6352 specified more than once. DROP and KEEP may not both be specified.
6354 The REORDER subcommand changes the order of variables in the active
6355 file. Specify one or more lists of variable names in parentheses. By
6356 default, each list of variables is rearranged into the specified order.
6357 To put the variables into the reverse of the specified order, put
6358 keyword BACKWARD before the parentheses. To put them into alphabetical
6359 order in the dictionary, specify keyword ALPHA before the parentheses.
6360 BACKWARD and ALPHA may also be combined.
6362 To rename variables in the active file, specify RENAME, an equals sign
6363 (@samp{=}), and lists of the old variable names and new variable names
6364 separated by another equals sign within parentheses. There must be the
6365 same number of old and new variable names. Each old variable is renamed to
6366 the corresponding new variable name. Multiple parenthesized groups of
6367 variables may be specified.
6369 The DROP subcommand deletes a specified list of variables from the
6372 The KEEP subcommand keeps the specified list of variables in the active
6373 file. Any unlisted variables are deleted from the active file.
6375 MAP is currently ignored.
6377 If either DROP or KEEP is specified, the data is read; otherwise it is
6380 @node NUMERIC, PRINT FORMATS, MODIFY VARS, Variable Attributes
6385 NUMERIC /var_list [(fmt_spec)].
6388 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
6389 setting their output formats.
6391 Specify a slash (@samp{/}), followed by the names of the new numeric
6392 variables. If you wish to set their output formats, follow their names
6393 by an output format specification in parentheses (@pxref{Input/Output
6394 Formats}); otherwise, the default is F8.2.
6396 Variables created with @cmd{NUMERIC} are initialized to the
6397 system-missing value.
6399 @node PRINT FORMATS, RENAME VARIABLES, NUMERIC, Variable Attributes
6400 @section PRINT FORMATS
6401 @vindex PRINT FORMATS
6404 PRINT FORMATS var_list (fmt_spec).
6407 @cmd{PRINT FORMATS} sets the print formats for the specified
6408 variables to the specified format specification.
6410 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
6411 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
6413 @node RENAME VARIABLES, VALUE LABELS, PRINT FORMATS, Variable Attributes
6414 @section RENAME VARIABLES
6415 @vindex RENAME VARIABLES
6418 RENAME VARIABLES (old_names=new_names)@dots{} .
6421 @cmd{RENAME VARIABLES} changes the names of variables in the active
6422 file. Specify lists of the old variable names and new
6423 variable names, separated by an equals sign (@samp{=}), within
6424 parentheses. There must be the same number of old and new variable
6425 names. Each old variable is renamed to the corresponding new variable
6426 name. Multiple parenthesized groups of variables may be specified.
6428 @cmd{RENAME VARIABLES} takes effect immediately. It does not cause the data
6431 @node VALUE LABELS, STRING, RENAME VARIABLES, Variable Attributes
6432 @section VALUE LABELS
6433 @vindex VALUE LABELS
6437 /var_list value 'label' [value 'label']@dots{}
6440 @cmd{VALUE LABELS} allows values of numeric and short string
6441 variables to be associated with labels. In this way, a short value can
6442 stand for a long value.
6444 To set up value labels for a set of variables, specify the
6445 variable names after a slash (@samp{/}), followed by a list of values
6446 and their associated labels, separated by spaces. Long string
6447 variables may not be specified.
6449 Before @cmd{VALUE LABELS} is executed, any existing value labels
6450 are cleared from the variables specified. Use @cmd{ADD VALUE LABELS}
6451 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
6454 @node STRING, VARIABLE LABELS, VALUE LABELS, Variable Attributes
6459 STRING /var_list (fmt_spec).
6462 @cmd{STRING} creates new string variables for use in
6465 Specify a slash (@samp{/}), followed by the names of the string
6466 variables to create and the desired output format specification in
6467 parentheses (@pxref{Input/Output Formats}). Variable widths are
6468 implicitly derived from the specified output formats.
6470 Created variables are initialized to spaces.
6472 @node VARIABLE LABELS, VECTOR, STRING, Variable Attributes
6473 @section VARIABLE LABELS
6474 @vindex VARIABLE LABELS
6478 /var_list 'var_label'.
6481 @cmd{VARIABLE LABELS} associates explanatory names
6482 with variables. This name, called a @dfn{variable label}, is displayed by
6483 statistical procedures.
6485 To assign a variable label to a group of variables, specify a slash
6486 (@samp{/}), followed by the list of variable names and the variable
6489 @node VECTOR, WRITE FORMATS, VARIABLE LABELS, Variable Attributes
6494 Two possible syntaxes:
6495 VECTOR vec_name=var_list.
6496 VECTOR vec_name_list(count).
6499 @cmd{VECTOR} allows a group of variables to be accessed as if they
6500 were consecutive members of an array with a vector(index) notation.
6502 To make a vector out of a set of existing variables, specify a name for
6503 the vector followed by an equals sign (@samp{=}) and the variables that
6504 belong in the vector.
6506 To make a vector and create variables at the same time, specify one or
6507 more vector names followed by a count in parentheses. This will cause
6508 variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
6509 to be created as numeric variables with print and write format F8.2.
6510 Variable names including numeric suffixes may not exceed 8 characters
6511 in length, and none of the variables may exist prior to @cmd{VECTOR}.
6513 All the variables in a vector must be the same type.
6515 Vectors created with @cmd{VECTOR} disappear after any procedure or
6516 procedure-like command is executed. The variables contained in the
6517 vectors remain, unless they are scratch variables (@pxref{Scratch
6520 Variables within a vector may be references in expressions using
6521 @code{vector(index)} syntax.
6523 @node WRITE FORMATS, , VECTOR, Variable Attributes
6524 @section WRITE FORMATS
6525 @vindex WRITE FORMATS
6528 WRITE FORMATS var_list (fmt_spec).
6531 @cmd{WRITE FORMATS} sets the write formats for the specified variables
6532 to the specified format specification. Its syntax is identical to
6533 that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
6534 write formats, not print formats.
6536 @node Data Manipulation, Data Selection, Variable Attributes, Top
6537 @chapter Data transformations
6538 @cindex transformations
6540 The PSPP procedures examined in this chapter manipulate data and
6541 prepare the active file for later analyses. They do not produce output,
6545 * AGGREGATE:: Summarize multiple cases into a single case.
6546 * AUTORECODE:: Automatic recoding of variables.
6547 * COMPUTE:: Assigning a variable a calculated value.
6548 * COUNT:: Counting variables with particular values.
6549 * FLIP:: Exchange variables with cases.
6550 * IF:: Conditionally assigning a calculated value.
6551 * RECODE:: Mapping values from one set to another.
6552 * SORT CASES:: Sort the active file.
6555 @node AGGREGATE, AUTORECODE, Data Manipulation, Data Manipulation
6563 /OUTFILE=@{*,'filename'@}
6566 /dest_vars=agr_func(src_vars, args@dots{})@dots{}
6569 @cmd{AGGREGATE} summarizes groups of cases into single cases.
6570 Cases are divided into groups that have the same values for one or more
6571 variables called @dfn{break variables}. Several functions are available
6572 for summarizing case contents.
6574 At least one break variable must be specified on BREAK, the only
6575 required subcommand. The values of these variables are used to divide
6576 the active file into groups to be summarized. In addition, at least
6577 one @var{dest_var} must be specified.
6579 By default, the active file is sorted based on the break variables
6580 before aggregation takes place. If the active file is already sorted
6581 or otherwise grouped in terms of the break variables, specify
6582 PRESORTED to save time.
6584 The OUTFILE subcommand specifies a system file by file name string or
6585 file handle (@pxref{FILE HANDLE}). The aggregated cases are written to
6586 this file. If OUTFILE is not specified, or if @samp{*} is specified,
6587 then the aggregated cases replace the active file.
6589 Specify DOCUMENT to copy the documents from the active file into the
6590 aggregate file (@pxref{DOCUMENT}). Otherwise, the aggregate file will
6591 not contain any documents, even if the aggregate file replaces the
6594 One or more sets of aggregation variables must be specified. Each set
6595 comprises a list of aggregation variables, an equals sign (@samp{=}),
6596 the name of an aggregation function (see the list below), and a list
6597 of source variables in parentheses. Some aggregation functions expect
6598 additional arguments following the source variable names.
6600 Each set must have exactly as many source variables as aggregation
6601 variables. Each aggregation variable receives the results of applying
6602 the specified aggregation function to the corresponding source
6603 variable. Most aggregation functions may be applied to numeric and
6604 short and long string variables. Others, marked below, are restricted
6607 The available aggregation functions are as follows:
6611 Sum. Limited to numeric values.
6612 @item MEAN(var_name)
6613 Arithmetic mean. Limited to numeric values.
6615 Standard deviation of the mean. Limited to numeric values.
6620 @item FGT(var_name, value)
6621 @itemx PGT(var_name, value)
6622 Fraction between 0 and 1, or percentage between 0 and 100, respectively,
6623 of values greater than the specified constant.
6624 @item FLT(var_name, value)
6625 @itemx PLT(var_name, value)
6626 Fraction or percentage, respectively, of values less than the specified
6628 @item FIN(var_name, low, high)
6629 @itemx PIN(var_name, low, high)
6630 Fraction or percentage, respectively, of values within the specified
6631 inclusive range of constants.
6632 @item FOUT(var_name, low, high)
6633 @itemx POUT(var_name, low, high)
6634 Fraction or percentage, respectively, of values strictly outside the
6635 specified range of constants.
6637 Number of non-missing values.
6639 Number of cases aggregated to form this group. Don't supply a source
6640 variable for this aggregation function.
6642 Number of non-missing values. Each case is considered to have a weight
6643 of 1, regardless of the current weighting variable (@pxref{WEIGHT}).
6645 Number of cases aggregated to form this group. Each case is considered
6646 to have a weight of 1, regardless of the current weighting variable.
6647 @item NMISS(var_name)
6648 Number of missing values.
6649 @item NUMISS(var_name)
6650 Number of missing values. Each case is considered to have a weight of
6651 1, regardless of the current weighting variable.
6652 @item FIRST(var_name)
6653 First value in this group.
6654 @item LAST(var_name)
6655 Last value in this group.
6658 Aggregation functions compare string values in terms of internal
6659 character codes. On most modern computers, this is a form of ASCII.
6661 The aggregation functions listed above exclude all user-missing values
6662 from calculations. To include user-missing values, insert a period
6663 (@samp{.}) between the function name and left parenthesis
6666 Normally, only a single case (for SD and SD., two cases) need be
6667 non-missing in each group for the aggregate variable to be
6668 non-missing. Specifying /MISSING=COLUMNWISE inverts this behavior, so
6669 that the aggregate variable becomes missing if any aggregated value is
6672 @cmd{AGGREGATE} both ignores and cancels the current @cmd{SPLIT FILE}
6673 settings (@pxref{SPLIT FILE}).
6675 @node AUTORECODE, COMPUTE, AGGREGATE, Data Manipulation
6680 AUTORECODE VARIABLES=src_vars INTO dest_vars
6685 The @cmd{AUTORECODE} procedure considers the @var{n} values that a variable
6686 takes on and maps them onto values 1@dots{}@var{n} on a new numeric
6689 Subcommand VARIABLES is the only required subcommand and must come
6690 first. Specify VARIABLES, an equals sign (@samp{=}), a list of source
6691 variables, INTO, and a list of target variables. There must the same
6692 number of source and target variables. The target variables must not
6695 By default, increasing values of a source variable (for a string, this
6696 is based on character code comparisons) are recoded to increasing values
6697 of its target variable. To cause increasing values of a source variable
6698 to be recoded to decreasing values of its target variable (@var{n} down
6699 to 1), specify DESCENDING.
6701 PRINT is currently ignored.
6703 @cmd{AUTORECODE} is a procedure. It causes the data to be read.
6705 @node COMPUTE, COUNT, AUTORECODE, Data Manipulation
6710 COMPUTE variable = expression.
6712 COMPUTE vector(index) = expression.
6715 @cmd{COMPUTE} assigns the value of an expression to a target
6716 variable. For each case, the expression is evaluated and its value
6717 assigned to the target variable. Numeric and short and long string
6718 variables may be assigned. When a string expression's width differs
6719 from the target variable's width, the string result of the expression
6720 is truncated or padded with spaces on the right as necessary. The
6721 expression and variable types must match.
6723 For numeric variables only, the target variable need not already
6724 exist. Numeric variables created by @cmd{COMPUTE} are assigned an
6725 @code{F8.2} output format. String variables must be declared before
6726 they can be used as targets for @cmd{COMPUTE}.
6728 The target variable may be specified as an element of a vector
6729 (@pxref{VECTOR}). In this case, a vector index expression must be
6730 specified in parentheses following the vector name. The index
6731 expression must evaluate to a numeric value that, after rounding down
6732 to the nearest integer, is a valid index for the named vector.
6734 Using @cmd{COMPUTE} to assign to a variable specified on @cmd{LEAVE}
6735 (@pxref{LEAVE}) resets the variable's left state. Therefore,
6736 @code{LEAVE} should be specified following @cmd{COMPUTE}, not before.
6738 COMPUTE is a transformation. It does not cause the active file to be
6741 @node COUNT, FLIP, COMPUTE, Data Manipulation
6746 COUNT var_name = var@dots{} (value@dots{}).
6748 Each value takes one of the following forms:
6754 In addition, num1 and num2 can be LO or LOWEST, or HI or HIGHEST,
6758 @cmd{COUNT} creates or replaces a numeric @dfn{target} variable that
6759 counts the occurrence of a @dfn{criterion} value or set of values over
6760 one or more @dfn{test} variables for each case.
6762 The target variable values are always nonnegative integers. They are
6763 never missing. The target variable is assigned an F8.2 output format.
6764 @xref{Input/Output Formats}. Any variables, including long and short
6765 string variables, may be test variables.
6767 User-missing values of test variables are treated just like any other
6768 values. They are @strong{not} treated as system-missing values.
6769 User-missing values that are criterion values or inside ranges of
6770 criterion values are counted as any other values. However (for numeric
6771 variables), keyword MISSING may be used to refer to all system-
6772 and user-missing values.
6774 @cmd{COUNT} target variables are assigned values in the order
6775 specified. In the command @code{COUNT A=A B(1) /B=A B(2).}, the
6776 following actions occur:
6780 The number of occurrences of 1 between @code{A} and @code{B} is counted.
6783 @code{A} is assigned this value.
6786 The number of occurrences of 1 between @code{B} and the @strong{new}
6787 value of @code{A} is counted.
6790 @code{B} is assigned this value.
6793 Despite this ordering, all @cmd{COUNT} criterion variables must exist
6794 before the procedure is executed---they may not be created as target
6795 variables earlier in the command! Break such a command into two
6798 The examples below may help to clarify.
6802 Assuming @code{Q0}, @code{Q2}, @dots{}, @code{Q9} are numeric variables,
6803 the following commands:
6807 Count the number of times the value 1 occurs through these variables
6808 for each case and assigns the count to variable @code{QCOUNT}.
6811 Print out the total number of times the value 1 occurs throughout
6812 @emph{all} cases using @cmd{DESCRIPTIVES}. @xref{DESCRIPTIVES}, for
6817 COUNT QCOUNT=Q0 TO Q9(1).
6818 DESCRIPTIVES QCOUNT /STATISTICS=SUM.
6822 Given these same variables, the following commands:
6826 Count the number of valid values of these variables for each case and
6827 assigns the count to variable @code{QVALID}.
6830 Multiplies each value of @code{QVALID} by 10 to obtain a percentage of
6831 valid values, using @cmd{COMPUTE}. @xref{COMPUTE}, for details.
6834 Print out the percentage of valid values across all cases, using
6835 @cmd{DESCRIPTIVES}. @xref{DESCRIPTIVES}, for details.
6839 COUNT QVALID=Q0 TO Q9 (LO THRU HI).
6840 COMPUTE QVALID=QVALID*10.
6841 DESCRIPTIVES QVALID /STATISTICS=MEAN.
6845 @node FLIP, IF, COUNT, Data Manipulation
6850 FLIP /VARIABLES=var_list /NEWNAMES=var_name.
6853 @cmd{FLIP} transposes rows and columns in the active file. It
6854 causes cases to be swapped with variables, and vice versa.
6856 No subcommands are required. The VARIABLES subcommand specifies
6857 variables that will be transformed into cases. Variables not specified
6858 are discarded. By default, all variables are selected for
6861 The variables specified by NEWNAMES, which must be a string variable, is
6862 used to give names to the variables created by @cmd{FLIP}. If
6864 specified then the default is a variable named CASE_LBL, if it exists.
6865 If it does not then the variables created by FLIP are named VAR000
6866 through VAR999, then VAR1000, VAR1001, and so on.
6868 When a NEWNAMES variable is available, the names must be canonicalized
6869 before becoming variable names. Invalid characters are replaced by
6870 letter @samp{V} in the first position, or by @samp{_} in subsequent
6871 positions. If the name thus generated is not unique, then numeric
6872 extensions are added, starting with 1, until a unique name is found or
6873 there are no remaining possibilities. If the latter occurs then the
6874 FLIP operation aborts.
6876 The resultant dictionary contains a CASE_LBL variable, which stores the
6877 names of the variables in the dictionary before the transposition. If
6878 the active file is subsequently transposed using @cmd{FLIP}, this
6880 be used to recreate the original variable names.
6882 @node IF, RECODE, FLIP, Data Manipulation
6887 IF condition variable=expression.
6889 IF condition vector(index)=expression.
6892 The @cmd{IF} transformation conditionally assigns the value of a target
6893 expression to a target variable, based on the truth of a test
6896 Specify a boolean-valued expression (@pxref{Expressions}) to be tested
6897 following the IF keyword. This expression is evaluated for each case.
6898 If the value is true, then the value of the expression is computed and
6899 assigned to the specified variable. If the value is false or missing,
6900 nothing is done. Numeric and short and long string variables may be
6901 assigned. When a string expression's width differs from the target
6902 variable's width, the string result of the expression is truncated or
6903 padded with spaces on the right as necessary. The expression and
6904 variable types must match.
6906 The target variable may be specified as an element of a vector
6907 (@pxref{VECTOR}). In this case, a vector index expression must be
6908 specified in parentheses following the vector name. The index
6909 expression must evaluate to a numeric value that, after rounding down
6910 to the nearest integer, is a valid index for the named vector.
6912 Using @cmd{IF} to assign to a variable specified on @cmd{LEAVE}
6913 (@pxref{LEAVE}) resets the variable's left state. Therefore,
6914 @code{LEAVE} should be specified following @cmd{IF}, not before.
6916 @node RECODE, SORT CASES, IF, Data Manipulation
6921 RECODE var_list (src_value@dots{}=dest_value)@dots{} [INTO var_list].
6923 src_value may take the following forms:
6930 Open-ended ranges may be specified using LO or LOWEST for num1
6931 or HI or HIGHEST for num2.
6933 dest_value may take the following forms:
6940 @cmd{RECODE} translates data from one range of values to
6941 another, via flexible user-specified mappings. Data may be remapped
6942 in-place or copied to new variables. Numeric, short string, and long
6943 string data can be recoded.
6945 Specify the list of source variables, followed by one or more mapping
6946 specifications each enclosed in parentheses. If the data is to be
6947 copied to new variables, specify INTO, then the list of target
6948 variables. String target variables must already have been declared
6949 using @cmd{STRING} or another transformation, but numeric target
6951 be created on the fly. There must be exactly as many target variables
6952 as source variables. Each source variable is remapped into its
6953 corresponding target variable.
6955 When INTO is not used, the input and output variables must be of the
6956 same type. Otherwise, string values can be recoded into numeric values,
6957 and vice versa. When this is done and there is no mapping for a
6958 particular value, either a value consisting of all spaces or the
6959 system-missing value is assigned, depending on variable type.
6961 Mappings are considered from left to right. The first src_value that
6962 matches the value of the source variable causes the target variable to
6963 receive the value indicated by the dest_value. Literal number, string,
6964 and range src_value's should be self-explanatory. MISSING as a
6965 src_value matches any user- or system-missing value. SYSMIS matches the
6966 system missing value only. ELSE is a catch-all that matches anything.
6967 It should be the last src_value specified.
6969 Numeric and string dest_value's should also be self-explanatory. COPY
6970 causes the input values to be copied to the output. This is only value
6971 if the source and target variables are of the same type. SYSMIS
6972 indicates the system-missing value.
6974 If the source variables are strings and the target variables are
6975 numeric, then there is one additional mapping available: (CONVERT),
6976 which must be the last specified mapping. CONVERT causes a number
6977 specified as a string to be converted to a numeric value. If the string
6978 cannot be parsed as a number, then the system-missing value is assigned.
6980 Multiple recodings can be specified on a single @cmd{RECODE} invocation.
6981 Introduce additional recodings with a slash (@samp{/}) to
6982 separate them from the previous recodings.
6984 @node SORT CASES, , RECODE, Data Manipulation
6989 SORT CASES BY var_list.
6992 @cmd{SORT CASES} sorts the active file by the values of one or more
6995 Specify BY and a list of variables to sort by. By default, variables
6996 are sorted in ascending order. To override sort order, specify (D) or
6997 (DOWN) after a list of variables to get descending order, or (A) or (UP)
6998 for ascending order. These apply to the entire list of variables
7001 @cmd{SORT CASES} is a procedure. It causes the data to be read.
7003 @cmd{SORT CASES} attempts to sort the entire active file in main memory.
7004 If main memory is exhausted, it falls back to a merge sort algorithm that
7005 involves writing and reading numerous temporary files. Environment
7006 variables determine the temporary files' location. The first of
7007 SPSSTMPDIR, SPSSXTMPDIR, or TMPDIR that is set determines the location.
7008 Otherwise, if the compiler environment defined P_tmpdir, that is used.
7009 Otherwise, under Unix-like OSes /tmp is used; under MS-DOS, the first of
7010 TEMP, TMP, or root on the current drive is used; under other OSes, the
7013 @node Data Selection, Conditionals and Looping, Data Manipulation, Top
7014 @chapter Selecting data for analysis
7016 This chapter documents PSPP commands that temporarily or permanently
7017 select data records from the active file for analysis.
7020 * FILTER:: Exclude cases based on a variable.
7021 * N OF CASES:: Limit the size of the active file.
7022 * PROCESS IF:: Temporarily excluding cases.
7023 * SAMPLE:: Select a specified proportion of cases.
7024 * SELECT IF:: Permanently delete selected cases.
7025 * SPLIT FILE:: Do multiple analyses with one command.
7026 * TEMPORARY:: Make transformations' effects temporary.
7027 * WEIGHT:: Weight cases by a variable.
7030 @node FILTER, N OF CASES, Data Selection, Data Selection
7039 @cmd{FILTER} allows a boolean-valued variable to be used to select
7040 cases from the data stream for processing.
7042 To set up filtering, specify BY and a variable name. Keyword
7043 BY is optional but recommended. Cases which have a zero or system- or
7044 user-missing value are excluded from analysis, but not deleted from the
7045 data stream. Cases with other values are analyzed.
7047 @code{FILTER OFF} turns off case filtering.
7049 Filtering takes place immediately before cases pass to a procedure for
7050 analysis. Only one filter variable may be active at a time. Normally,
7051 case filtering continues until it is explicitly turned off with @code{FILTER
7052 OFF}. However, if @cmd{FILTER} is placed after TEMPORARY, filtering stops
7053 after execution of the next procedure or procedure-like command.
7055 @node N OF CASES, PROCESS IF, FILTER, Data Selection
7060 N [OF CASES] num_of_cases [ESTIMATED].
7063 Sometimes you may want to disregard cases of your input. @cmd{N} can
7064 do this. @code{N 100} tells PSPP to disregard all cases after the
7067 If the value specified for @cmd{N} is greater than the number of cases
7068 read in, the value is ignored.
7070 @cmd{N} does not discard cases or prevent them from being read. It
7071 just causes cases beyond the last one specified to be ignored by data
7074 A later @cmd{N} command can increase or decrease the number of cases
7075 selected. (To select all the cases without knowing how many there are,
7076 specify a very high number: 100000 or whatever you think is large enough.)
7078 Transformation procedures performed after @cmd{N} is executed
7079 @emph{do} cause cases to be discarded.
7081 @cmd{SAMPLE}, @cmd{PROCESS IF}, and @cmd{SELECT IF} have
7082 precedence over @cmd{N}---the same results are obtained by both of the
7083 following fragments, given the same random number seeds:
7086 @i{@dots{}set up, read in data@dots{}}
7089 @i{@dots{}analyze data@dots{}}
7091 @i{@dots{}set up, read in data@dots{}}
7094 @i{@dots{}analyze data@dots{}}
7097 Both fragments above first randomly sample approximately half of the
7098 cases, then select the first 100 of those sampled.
7100 @cmd{N} with the @code{ESTIMATED} keyword gives an
7101 estimated number of cases before @cmd{DATA LIST} or another command to
7102 read in data. @code{ESTIMATED} never limits the number of cases
7103 processed by procedures. PSPP currently does not make use of
7104 case count estimates.
7106 @node PROCESS IF, SAMPLE, N OF CASES, Data Selection
7111 PROCESS IF expression.
7114 @cmd{PROCESS IF} temporarily eliminates cases from the
7115 data stream. Its effects are active only through the execution of the
7116 next procedure or procedure-like command.
7118 Specify a boolean expression (@pxref{Expressions}). If the value of the
7119 expression is true for a particular case, the case will be analyzed. If
7120 the expression has a false or missing value, then the case will be
7121 deleted from the data stream for this procedure only.
7123 Regardless of its placement relative to other commands, @cmd{PROCESS IF}
7124 always takes effect immediately before data passes to the procedure.
7125 Only one @cmd{PROCESS IF} command may be in effect at any given time.
7127 The effects of @cmd{PROCESS IF} are similar, but not identical, to the
7128 effects of executing @cmd{TEMPORARY}, then @cmd{SELECT IF}
7129 (@pxref{SELECT IF}).
7131 @cmd{PROCESS IF} is deprecated. It is included for compatibility with
7132 old command files. New syntax files should use @cmd{SELECT IF} or
7133 @cmd{FILTER} instead.
7135 @node SAMPLE, SELECT IF, PROCESS IF, Data Selection
7140 SAMPLE num1 [FROM num2].
7143 @cmd{SAMPLE} is used to randomly sample a proportion of the cases in
7144 the active file. @cmd{SAMPLE} is temporary, affecting only the next
7145 procedure, unless that is a data transformation, such as @cmd{SELECT IF}
7148 The proportion to sample can be expressed as a single number between 0
7149 and 1. If @code{k} is the number specified, and @code{N} is the number
7150 of currently-selected cases in the active file, then after
7151 @code{SAMPLE @var{k}.}, approximately @code{k*N} cases will be
7154 The proportion to sample can also be specified in the style @code{SAMPLE
7155 @var{m} FROM @var{N}}. With this style, cases are selected as follows:
7159 If @var{N} is equal to the number of currently-selected cases in the
7160 active file, exactly @var{m} cases will be selected.
7163 If @var{N} is greater than the number of currently-selected cases in the
7164 active file, an equivalent proportion of cases will be selected.
7167 If @var{N} is less than the number of currently-selected cases in the
7168 active, exactly @var{m} cases will be selected @emph{from the first
7169 @var{N} cases in the active file.}
7172 @cmd{SAMPLE}, @cmd{SELECT IF}, and @code{PROCESS IF} are performed in
7173 the order specified by the syntax file.
7175 @cmd{SAMPLE} is ignored before @code{SORT CASES}.
7177 @cmd{SAMPLE} is always performed before @code{N OF CASES}, regardless
7178 of ordering in the syntax file. @xref{N OF CASES}.
7180 The same values for @cmd{SAMPLE} may result in different samples. To
7181 obtain the same sample, use the @code{SET} command to set the random
7182 number seed to the same value before each @cmd{SAMPLE}. Different
7183 samples may still result when the file is processed on systems with
7184 differing endianness or floating-point formats. By default, the
7185 random number seed is based on the system time.
7187 @node SELECT IF, SPLIT FILE, SAMPLE, Data Selection
7192 SELECT IF expression.
7195 @cmd{SELECT IF} selects cases for analysis based on the value of a
7196 boolean expression. Cases not selected are permanently eliminated
7197 from the active file, unless @cmd{TEMPORARY} is in effect
7198 (@pxref{TEMPORARY}).
7200 Specify a boolean expression (@pxref{Expressions}). If the value of the
7201 expression is true for a particular case, the case will be analyzed. If
7202 the expression has a false or missing value, then the case will be
7203 deleted from the data stream.
7205 Place @cmd{SELECT IF} as early in the command file as
7206 possible. Cases that are deleted early can be processed more
7207 efficiently in time and space.
7209 @node SPLIT FILE, TEMPORARY, SELECT IF, Data Selection
7214 Two possible syntaxes:
7215 SPLIT FILE BY var_list.
7219 @cmd{SPLIT FILE} allows multiple sets of data present in one data
7220 file to be analyzed separately using single statistical procedure
7223 Specify a list of variable names to analyze multiple sets of
7224 data separately. Groups of cases having the same values for these
7225 variables are analyzed by statistical procedure commands as one group.
7226 An independent analysis is carried out for each group of cases, and the
7227 variable values for the group are printed along with the analysis.
7229 Specify OFF to disable @cmd{SPLIT FILE} and resume analysis of the
7230 entire active file as a single group of data.
7232 @node TEMPORARY, WEIGHT, SPLIT FILE, Data Selection
7240 @cmd{TEMPORARY} is used to make the effects of transformations
7241 following its execution temporary. These transformations will
7242 affect only the execution of the next procedure or procedure-like
7243 command. Their effects will not be saved to the active file.
7245 The only specification is the command name.
7247 @cmd{TEMPORARY} may not appear within a @cmd{DO IF} or @cmd{LOOP}
7249 appear only once between procedures and procedure-like commands.
7251 An example may help to clarify:
7270 The data read by the first @cmd{DESCRIPTIVES} are 4, 5, 8,
7271 10.5, 13, 15. The data read by the first @cmd{DESCRIPTIVES} are 1, 2,
7274 @node WEIGHT, , TEMPORARY, Data Selection
7283 @cmd{WEIGHT} assigns cases varying weights,
7284 changing the frequency distribution of the active file. Execution of
7285 @cmd{WEIGHT} is delayed until data have been read.
7287 If a variable name is specified, @cmd{WEIGHT} causes the values of that
7288 variable to be used as weighting factors for subsequent statistical
7289 procedures. Use of keyword BY is optional but recommended. Weighting
7290 variables must be numeric. Scratch variables may not be used for
7291 weighting (@pxref{Scratch Variables}).
7293 When OFF is specified, subsequent statistical procedures will weight all
7296 A positive integer weighting factor @var{w} on a case will yield the
7297 same statistical output as would replicating the case @var{w} times.
7298 A weighting factor of 0 is treated for statistical purposes as if the
7299 case did not exist in the input. Weighting values need not be
7300 integers, but negative and system-missing values for the weighting
7301 variable are interpreted as weighting factors of 0. User-missing
7302 values are not treated specially.
7304 @cmd{WEIGHT} does not cause cases in the active file to be replicated in
7307 @node Conditionals and Looping, Statistics, Data Selection, Top
7308 @chapter Conditional and Looping Constructs
7309 @cindex conditionals
7311 @cindex flow of control
7312 @cindex control flow
7314 This chapter documents PSPP commands used for conditional execution,
7315 looping, and flow of control.
7318 * BREAK:: Exit a loop.
7319 * DO IF:: Conditionally execute a block of code.
7320 * DO REPEAT:: Textually repeat a code block.
7321 * LOOP:: Repeat a block of code.
7324 @node BREAK, DO IF, Conditionals and Looping, Conditionals and Looping
7332 @cmd{BREAK} terminates execution of the innermost currently executing
7333 @cmd{LOOP} construct.
7335 @cmd{BREAK} is allowed only inside @cmd{LOOP}@dots{}@cmd{END LOOP}.
7336 @xref{LOOP}, for more details.
7338 @node DO IF, DO REPEAT, BREAK, Conditionals and Looping
7353 @cmd{DO IF} allows one of several sets of transformations to be
7354 executed, depending on user-specified conditions.
7356 If the specified boolean expression evaluates as true, then the block
7357 of code following @cmd{DO IF} is executed. If it evaluates as
7359 none of the code blocks is executed. If it is false, then
7360 the boolean expression on the first @cmd{ELSE IF}, if present, is tested in
7361 turn, with the same rules applied. If all expressions evaluate to
7362 false, then the @cmd{ELSE} code block is executed, if it is present.
7364 @node DO REPEAT, LOOP, DO IF, Conditionals and Looping
7369 DO REPEAT repvar_name=expansion@dots{}.
7373 expansion takes one of the following forms:
7378 num_or_range takes one of the following forms:
7383 @cmd{DO REPEAT} repeats a block of code, textually substituting
7384 different variables, numbers, or strings into the block with each
7387 Specify a repeat variable name followed by an equals sign (@samp{=}) and
7388 the list of replacements. Replacements can be a list of variables
7389 (which may be existing variables or new variables or a combination
7390 thereof), of numbers, or of strings. When new variable names are
7391 specified, @cmd{DO REPEAT} creates them as numeric variables. When numbers
7392 are specified, runs of integers may be indicated with TO notation, for
7393 instance @samp{1 TO 5} and @samp{1 2 3 4 5} would be equivalent. There
7394 is no equivalent notation for string values.
7396 Multiple repeat variables can be specified. When this is done, each
7397 variable must have the same number of replacements.
7399 The code within @cmd{DO REPEAT} is repeated as many times as there are
7400 replacements for each variable. The first time, the first value for
7401 each repeat variable is substituted; the second time, the second value
7402 for each repeat variable is substituted; and so on.
7404 Repeat variable substitutions work like macros. They take place
7405 anywhere in a line that the repeat variable name occurs as a token,
7406 including command and subcommand names. For this reason it is not a
7407 good idea to select words commonly used in command and subcommand names
7408 as repeat variable identifiers.
7410 If PRINT is specified on @cmd{END REPEAT}, the commands after substitutions
7411 are made are printed to the listing file, prefixed by a plus sign
7414 @node LOOP, , DO REPEAT, Conditionals and Looping
7419 LOOP [index_var=start TO end [BY incr]] [IF condition].
7421 END LOOP [IF condition].
7424 @cmd{LOOP} iterates a group of commands. A number of
7425 termination options are offered.
7427 Specify index_var to make that variable count from one value to
7428 another by a particular increment. index_var must be a pre-existing
7429 numeric variable. start, end, and incr are numeric expressions
7430 (@pxref{Expressions}.)
7432 During the first iteration, index_var is set to the value of start.
7433 During each successive iteration, index_var is increased by the value of
7434 incr. If end > start, then the loop terminates when index_var > end;
7435 otherwise it terminates when index_var < end. If incr is not specified
7436 then it defaults to +1 or -1 as appropriate.
7438 If end > start and incr < 0, or if end < start and incr > 0, then the
7439 loop is never executed. index_var is nevertheless set to the value of
7442 Modifying index_var within the loop is allowed, but it has no effect on
7443 the value of index_var in the next iteration.
7445 Specify a boolean expression for the condition on @cmd{LOOP} to
7446 cause the loop to be executed only if the condition is true. If the
7447 condition is false or missing before the loop contents are executed the
7448 first time, the loop contents are not executed at all.
7450 If index and condition clauses are both present on @cmd{LOOP}, the index
7451 clause is always evaluated first.
7453 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
7454 the loop to terminate if the condition is not true after the enclosed
7455 code block is executed. The condition is evaluated at the end of the
7456 loop, not at the beginning.
7458 If the index clause and both condition clauses are not present, then the
7459 loop is executed MXLOOPS (@pxref{SET}) times.
7461 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
7463 @node Statistics, Utilities, Conditionals and Looping, Top
7466 This chapter documents the statistical procedures that PSPP supports so
7470 * DESCRIPTIVES:: Descriptive statistics.
7471 * FREQUENCIES:: Frequency tables.
7472 * CROSSTABS:: Crosstabulation tables.
7473 * T-TEST:: Test Hypotheses about means.
7476 @node DESCRIPTIVES, FREQUENCIES, Statistics, Statistics
7477 @section DESCRIPTIVES
7482 /MISSING=@{VARIABLE,LISTWISE@} @{INCLUDE,NOINCLUDE@}
7483 /FORMAT=@{LABELS,NOLABELS@} @{NOINDEX,INDEX@} @{LINE,SERIAL@}
7485 /STATISTICS=@{ALL,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,
7486 SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,DEFAULT,
7487 SESKEWNESS,SEKURTOSIS@}
7488 /SORT=@{NONE,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,SKEWNESS,
7489 RANGE,MINIMUM,MAXIMUM,SUM,SESKEWNESS,SEKURTOSIS,NAME@}
7493 The @cmd{DESCRIPTIVES} procedure reads the active file and outputs
7495 statistics requested by the user. In addition, it can optionally
7498 The VARIABLES subcommand, which is required, specifies the list of
7499 variables to be analyzed. Keyword VARIABLES is optional.
7501 All other subcommands are optional:
7503 The MISSING subcommand determines the handling of missing variables. If
7504 INCLUDE is set, then user-missing values are included in the
7505 calculations. If NOINCLUDE is set, which is the default, user-missing
7506 values are excluded. If VARIABLE is set, then missing values are
7507 excluded on a variable by variable basis; if LISTWISE is set, then
7508 the entire case is excluded whenever any value in that case has a
7509 system-missing or, if INCLUDE is set, user-missing value.
7511 The FORMAT subcommand affects the output format. Currently the
7512 LABELS/NOLABELS and NOINDEX/INDEX settings are not used. When SERIAL is
7513 set, both valid and missing number of cases are listed in the output;
7514 when NOSERIAL is set, only valid cases are listed.
7516 The SAVE subcommand causes @cmd{DESCRIPTIVES} to calculate Z scores for all
7517 the specified variables. The Z scores are saved to new variables.
7518 Variable names are generated by trying first the original variable name
7519 with Z prepended and truncated to a maximum of 8 characters, then the
7520 names ZSC000 through ZSC999, STDZ00 through STDZ09, ZZZZ00 through
7521 ZZZZ09, ZQZQ00 through ZQZQ09, in that sequence. In addition, Z score
7522 variable names can be specified explicitly on VARIABLES in the variable
7523 list by enclosing them in parentheses after each variable.
7525 The STATISTICS subcommand specifies the statistics to be displayed:
7529 All of the statistics below.
7533 Standard error of the mean.
7539 Kurtosis and standard error of the kurtosis.
7541 Skewness and standard error of the skewness.
7551 Mean, standard deviation of the mean, minimum, maximum.
7553 Standard error of the kurtosis.
7555 Standard error of the skewness.
7558 The SORT subcommand specifies how the statistics should be sorted. Most
7559 of the possible values should be self-explanatory. NAME causes the
7560 statistics to be sorted by name. By default, the statistics are listed
7561 in the order that they are specified on the VARIABLES subcommand. The A
7562 and D settings request an ascending or descending sort order,
7565 @node FREQUENCIES, CROSSTABS, DESCRIPTIVES, Statistics
7566 @section FREQUENCIES
7571 /FORMAT=@{TABLE,NOTABLE,LIMIT(limit)@}
7572 @{STANDARD,CONDENSE,ONEPAGE[(onepage_limit)]@}
7574 @{AVALUE,DVALUE,AFREQ,DFREQ@}
7577 /MISSING=@{EXCLUDE,INCLUDE@}
7578 /STATISTICS=@{DEFAULT,MEAN,SEMEAN,MEDIAN,MODE,STDDEV,VARIANCE,
7579 KURTOSIS,SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,
7580 SESKEWNESS,SEKURTOSIS,ALL,NONE@}
7582 /PERCENTILES=percent@dots{}
7584 (These options are not currently implemented.)
7591 /VARIABLES=var_list (low,high)@dots{}
7594 The @cmd{FREQUENCIES} procedure outputs frequency tables for specified
7596 @cmd{FREQUENCIES} can also calculate and display descriptive statistics
7597 (including median and mode) and percentiles.
7599 In the future, @cmd{FREQUENCIES} will also support graphical output in the
7600 form of bar charts and histograms. In addition, it will be able to
7601 support percentiles for grouped data.
7603 The VARIABLES subcommand is the only required subcommand. Specify the
7604 variables to be analyzed. In most cases, this is all that is required.
7605 This is known as @dfn{general mode}.
7607 Occasionally, one may want to invoke a special mode called @dfn{integer
7608 mode}. Normally, in general mode, PSPP will automatically determine
7609 what values occur in the data. In integer mode, the user specifies the
7610 range of values that the data assumes. To invoke this mode, specify a
7611 range of data values in parentheses, separated by a comma. Data values
7612 inside the range are truncated to the nearest integer, then assigned to
7613 that value. If values occur outside this range, they are discarded.
7615 The FORMAT subcommand controls the output format. It has several
7620 TABLE, the default, causes a frequency table to be output for every
7621 variable specified. NOTABLE prevents them from being output. LIMIT
7622 with a numeric argument causes them to be output except when there are
7623 more than the specified number of values in the table.
7626 STANDARD frequency tables contain more complete information, but also to
7627 take up more space on the printed page. CONDENSE frequency tables are
7628 less informative but take up less space. ONEPAGE with a numeric
7629 argument will output standard frequency tables if there are the
7630 specified number of values or less, condensed tables otherwise. ONEPAGE
7631 without an argument defaults to a threshold of 50 values.
7634 LABELS causes value labels to be displayed in STANDARD frequency
7635 tables. NOLABLES prevents this.
7638 Normally frequency tables are sorted in ascending order by value. This
7639 is AVALUE. DVALUE tables are sorted in descending order by value.
7640 AFREQ and DFREQ tables are sorted in ascending and descending order,
7641 respectively, by frequency count.
7644 SINGLE spaced frequency tables are closely spaced. DOUBLE spaced
7645 frequency tables have wider spacing.
7648 OLDPAGE and NEWPAGE are not currently used.
7651 The MISSING subcommand controls the handling of user-missing values.
7652 When EXCLUDE, the default, is set, user-missing values are not included
7653 in frequency tables or statistics. When INCLUDE is set, user-missing
7654 are included. System-missing values are never included in statistics,
7655 but are listed in frequency tables.
7657 The available STATISTICS are the same as available in @cmd{DESCRIPTIVES}
7658 (@pxref{DESCRIPTIVES}), with the addition of MEDIAN, the data's median
7659 value, and MODE, the mode. (If there are multiple modes, the smallest
7660 value is reported.) By default, the mean, standard deviation of the
7661 mean, minimum, and maximum are reported for each variable.
7663 NTILES causes the specified quartiles to be reported. For instance,
7664 @code{/NTILES=4} would cause quartiles to be reported. In addition,
7665 particular percentiles can be requested with the PERCENTILES subcommand.
7667 @node CROSSTABS, T-TEST, FREQUENCIES, Statistics
7672 /TABLES=var_list BY var_list [BY var_list]@dots{}
7673 /MISSING=@{TABLE,INCLUDE,REPORT@}
7674 /WRITE=@{NONE,CELLS,ALL@}
7675 /FORMAT=@{TABLES,NOTABLES@}
7676 @{LABELS,NOLABELS,NOVALLABS@}
7681 /CELLS=@{COUNT,ROW,COLUMN,TOTAL,EXPECTED,RESIDUAL,SRESIDUAL,
7682 ASRESIDUAL,ALL,NONE@}
7683 /STATISTICS=@{CHISQ,PHI,CC,LAMBDA,UC,BTAU,CTAU,RISK,GAMMA,D,
7684 KAPPA,ETA,CORR,ALL,NONE@}
7687 /VARIABLES=var_list (low,high)@dots{}
7690 The @cmd{CROSSTABS} procedure displays crosstabulation
7691 tables requested by the user. It can calculate several statistics for
7692 each cell in the crosstabulation tables. In addition, a number of
7693 statistics can be calculated for each table itself.
7695 The TABLES subcommand is used to specify the tables to be reported. Any
7696 number of dimensions is permitted, and any number of variables per
7697 dimension is allowed. The TABLES subcommand may be repeated as many
7698 times as needed. This is the only required subcommand in @dfn{general
7701 Occasionally, one may want to invoke a special mode called @dfn{integer
7702 mode}. Normally, in general mode, PSPP will automatically determine
7703 what values occur in the data. In integer mode, the user specifies the
7704 range of values that the data assumes. To invoke this mode, specify the
7705 VARIABLES subcommand, giving a range of data values in parentheses for
7706 each variable to be used on the TABLES subcommand. Data values inside
7707 the range are truncated to the nearest integer, then assigned to that
7708 value. If values occur outside this range, they are discarded. When it
7709 is present, the VARIABLES subcommand must precede the TABLES subcommand.
7711 The MISSING subcommand determines the handling of user-missing values.
7712 When set to TABLE, the default, missing values are dropped on a table by
7713 table basis. When set to INCLUDE, user-missing values are included in
7714 tables and statistics. When set to REPORT, which is allowed only in
7715 integer mode, user-missing values are included in tables but marked with
7716 an @samp{M} (for ``missing'') and excluded from statistical
7719 Currently the WRITE subcommand is not used.
7721 The FORMAT subcommand controls the characteristics of the
7722 crosstabulation tables to be displayed. It has a number of possible
7727 TABLES, the default, causes crosstabulation tables to be output.
7728 NOTABLES suppresses them.
7731 LABELS, the default, allows variable labels and value labels to appear
7732 in the output. NOLABELS suppresses them. NOVALLABS displays variable
7733 labels but suppresses value labels.
7736 PIVOT, the default, causes each TABLES subcommand to be displayed in a
7737 pivot table format. NOPIVOT causes the old-style crosstabulation format
7741 AVALUE, the default, causes values to be sorted in ascending order.
7742 DVALUE asserts a descending sort order.
7745 INDEX/NOINDEX is currently ignored.
7748 BOX/NOBOX is currently ignored.
7751 The CELLS subcommand controls the contents of each cell in the displayed
7752 crosstabulation table. The possible settings are:
7768 Standardized residual.
7770 Adjusted standardized residual.
7774 Suppress cells entirely.
7777 @samp{/CELLS} without any settings specified requests COUNT, ROW,
7778 COLUMN, and TOTAL. If CELLS is not specified at all then only COUNT
7781 The STATISTICS subcommand selects statistics for computation:
7785 Pearson chi-square, likelihood ratio, Fisher's exact test, continuity
7786 correction, linear-by-linear association.
7790 Contingency coefficient.
7794 Uncertainty coefficient.
7810 Spearman correlation, Pearson's r.
7817 Selected statistics are only calculated when appropriate for the
7818 statistic. Certain statistics require tables of a particular size, and
7819 some statistics are calculated only in integer mode.
7821 @samp{/STATISTICS} without any settings selects CHISQ. If the
7822 STATISTICS subcommand is not given, no statistics are calculated.
7824 @strong{Please note:} Currently the implementation of CROSSTABS has the
7829 Pearson's R (but not Spearman) is off a little.
7831 T values for Spearman's R and Pearson's R are wrong.
7833 Significance of symmetric and directional measures is not calculated.
7835 Asymmetric ASEs and T values for lambda are wrong.
7837 ASE of Goodman and Kruskal's tau is not calculated.
7839 ASE of symmetric somers' d is wrong.
7841 Approximate T of uncertainty coefficient is wrong.
7844 Fixes for any of these deficiencies would be welcomed.
7846 @node T-TEST, , CROSSTABS, Statistics
7847 @comment node-name, next, previous, up
7853 /MISSING=@{ANALYSIS,LISTWISE@} @{EXCLUDE,INCLUDE@}
7854 /CRITERIA=CIN(confidence)
7862 (Independent Samples mode.)
7863 GROUPS=var(value1 [, value2])
7867 (Paired Samples mode.)
7868 PAIRS=var_list [WITH var_list [(PAIRED)] ]
7873 The @cmd{T-TEST} procedure outputs tables used in testing hypotheses about
7875 It operates in one of three modes:
7877 @item One Sample mode.
7878 @item Independent Groups mode.
7883 Each of these modes are described in more detail below.
7884 There are two optional subcommands which are common to all modes.
7886 The @cmd{/CRITERIA} subcommand tells PSPP the confidence interval used
7887 in the tests. The default value is 0.95.
7890 The @cmd{MISSING} subcommand determines the handling of missing
7892 If INCLUDE is set, then user-missing values are included in the
7894 If EXCLUDE is set, which is the default, user-missing
7895 values are excluded.
7896 If LISTWISE is set, then
7897 the entire case is excluded whenever any value in that case has a
7898 system-missing or, if INCLUDE is set, user-missing value.
7899 If ANALYSIS is set, then cases are excluded only where a value used in
7900 the analysis has a system-missing or, if INCLUDE is set, user-missing value.
7904 * One Sample Mode:: Testing against a hypothesised mean
7905 * Independent Samples Mode:: Testing two independent groups for the same mean
7906 * Paired Samples Mode:: Testing two interdependet groups for the same mean
7909 @node One Sample Mode, Independent Samples Mode, T-TEST, T-TEST
7910 @comment node-name, next, previous, up
7912 @subsection One Sample Mode
7914 The @cmd{TESTVAL} subcommand invokes the One Sample mode.
7915 This mode is used to test a population mean against a hypothesised
7917 The value given to the @cmd{TESTVAL} subcommand is the value against
7918 which you wish to test.
7919 In this mode, you must also use the @cmd{/VARIABLES} subcommand to
7920 tell PSPP which variables you wish to test.
7922 @node Independent Samples Mode, Paired Samples Mode, One Sample Mode, T-TEST
7923 @comment node-name, next, previous, up
7924 @subsection Independent Samples Mode
7926 The @cmd{GROUPS} subcommand invokes Independent Samples mode or
7928 This mode is used to test whether two groups of values have the
7929 same population mean.
7930 The variable given in the @cmd{GROUPS} subcommand is the independent
7931 variable which determines to which group the samples belong.
7932 The values in parentheses are the specific values of the independent
7933 variable for each group.
7934 In this mode, you must also use the @cmd{/VARIABLES} subcommand to
7935 tell PSPP the dependent variables you wish to test.
7937 @node Paired Samples Mode, , Independent Samples Mode, T-TEST
7938 @comment node-name, next, previous, up
7939 @subsection Paired Samples Mode
7941 The @cmd{PAIRS} subcommand introduces Paired Samples mode.
7942 Use this mode when repeated measures have been taken from the same
7944 If the the @code{WITH} keyword is omitted, then tables for all
7945 combinations of variables given in the @cmd{PAIRS} subcommand are
7947 If the @code{WITH} keyword is given, and the @code{(PAIRED)} keyword
7948 is also given, then the number of variables preceding @code{WITH}
7949 must be the same as the number following it.
7950 In this case, tables for each respective pair of variables are
7952 In the event that the @code{WITH} keyword is given, but the
7953 @code{(PAIRED)} keyword is omitted, then tables for each combination
7954 of variable preceding @code{WITH} against variable following
7955 @code{WITH} are generated.
7958 @node Utilities, Not Implemented, Statistics, Top
7961 Commands that don't fit any other category are placed here.
7963 Most of these commands are not affected by commands like @cmd{IF} and
7965 they take effect only once, unconditionally, at the time that they are
7966 encountered in the input.
7969 * COMMENT:: Document your syntax file.
7970 * DOCUMENT:: Document the active file.
7971 * DISPLAY DOCUMENTS:: Display active file documents.
7972 * DISPLAY FILE LABEL:: Display the active file label.
7973 * DROP DOCUMENTS:: Remove documents from the active file.
7974 * ERASE:: Erase a file.
7975 * EXECUTE:: Execute pending transformations.
7976 * FILE LABEL:: Set the active file's label.
7977 * FINISH:: Terminate the PSPP session.
7978 * HOST:: Temporarily return to the operating system.
7979 * INCLUDE:: Include a file within the current one.
7980 * QUIT:: Terminate the PSPP session.
7981 * SET:: Adjust PSPP runtime parameters.
7982 * SUBTITLE:: Provide a document subtitle.
7983 * TITLE:: Provide a document title.
7986 @node COMMENT, DOCUMENT, Utilities, Utilities
7992 Two possibles syntaxes:
7993 COMMENT comment text @dots{} .
7994 *comment text @dots{} .
7997 @cmd{COMMENT} is ignored. It is used to provide information to
7998 the author and other readers of the PSPP syntax file.
8000 @cmd{COMMENT} can extend over any number of lines. Don't forget to
8001 terminate it with a dot or a blank line.
8003 @node DOCUMENT, DISPLAY DOCUMENTS, COMMENT, Utilities
8008 DOCUMENT documentary_text.
8011 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
8012 active file. Documents added in this way are saved to system files.
8013 They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
8014 DOCUMENTS}. They can be removed from the active file with @cmd{DROP
8017 Specify the documentary text following the DOCUMENT keyword. You can
8018 extend the documentary text over as many lines as necessary. Lines are
8019 truncated at 80 characters width. Don't forget to terminate
8020 the command with a dot or a blank line.
8022 @node DISPLAY DOCUMENTS, DISPLAY FILE LABEL, DOCUMENT, Utilities
8023 @section DISPLAY DOCUMENTS
8024 @vindex DISPLAY DOCUMENTS
8030 @cmd{DISPLAY DOCUMENTS} displays the documents in the active file. Each
8031 document is preceded by a line giving the time and date that it was
8032 added. @xref{DOCUMENT}.
8034 @node DISPLAY FILE LABEL, DROP DOCUMENTS, DISPLAY DOCUMENTS, Utilities
8035 @section DISPLAY FILE LABEL
8036 @vindex DISPLAY FILE LABEL
8042 @cmd{DISPLAY FILE LABEL} displays the file label contained in the
8044 if any. @xref{FILE LABEL}.
8046 @node DROP DOCUMENTS, ERASE, DISPLAY FILE LABEL, Utilities
8047 @section DROP DOCUMENTS
8048 @vindex DROP DOCUMENTS
8054 @cmd{DROP DOCUMENTS} removes all documents from the active file.
8055 New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
8057 @cmd{DROP DOCUMENTS} changes only the active file. It does not modify any
8058 system files stored on disk.
8061 @node ERASE, EXECUTE, DROP DOCUMENTS, Utilities
8062 @comment node-name, next, previous, up
8067 ERASE FILE file_name.
8070 @cmd{ERASE FILE} deletes a file from the local filesystem.
8071 file_name must be quoted.
8072 This command cannot be used if the SAFER setting is active.
8075 @node EXECUTE, FILE LABEL, ERASE, Utilities
8083 @cmd{EXECUTE} causes the active file to be read and all pending
8084 transformations to be executed.
8086 @node FILE LABEL, FINISH, EXECUTE, Utilities
8091 FILE LABEL file_label.
8094 @cmd{FILE LABEL} provides a title for the active file. This
8095 title will be saved into system files and portable files that are
8096 created during this PSPP run.
8098 file_label need not be quoted. If quotes are
8099 included, they become part of the file label.
8101 @node FINISH, HOST, FILE LABEL, Utilities
8109 @cmd{FINISH} terminates the current PSPP session and returns
8110 control to the operating system.
8112 This command is not valid in interactive mode.
8114 @node HOST, INCLUDE, FINISH, Utilities
8115 @comment node-name, next, previous, up
8123 @cmd{HOST} suspends the current PSPP session and temporarily returns control
8124 to the operating system.
8125 This command cannot be used if the SAFER setting is active.
8128 @node INCLUDE, QUIT, HOST, Utilities
8134 Two possible syntaxes:
8139 @cmd{INCLUDE} causes the PSPP command processor to read an
8140 additional command file as if it were included bodily in the current
8143 Include files may be nested to any depth, up to the limit of available
8146 @node QUIT, SET, INCLUDE, Utilities
8151 Two possible syntaxes:
8156 @cmd{QUIT} terminates the current PSPP session and returns control
8157 to the operating system.
8159 This command is not valid within a command file.
8161 @node SET, SUBTITLE, QUIT, Utilities
8169 /BLANKS=@{SYSMIS,'.',number@}
8170 /DECIMAL=@{DOT,COMMA@}
8178 /CPROMPT='cprompt_string'
8179 /DPROMPT='dprompt_string'
8180 /ERRORBREAK=@{OFF,ON@}
8182 /MXWARNS=max_warnings
8184 /VIEWLENGTH=@{MINIMUM,MEDIAN,MAXIMUM,n_lines@}
8185 /VIEWWIDTH=n_characters
8189 /MITERATE=max_iterations
8193 /SEED=@{RANDOM,seed_value@}
8194 /UNDEFINED=@{WARN,NOWARN@}
8197 /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
8198 /DECIMAL=@{DOT,COMMA@}
8203 /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
8205 /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
8206 /PRINTBACK=@{ON,OFF@}
8207 /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@}
8214 (output driver options)
8215 /HEADERS=@{NO,YES,BLANK@}
8216 /LENGTH=@{NONE,length_in_lines@}
8219 /PAGER=@{OFF,"pager_name"@}
8220 /WIDTH=@{NARROW,WIDTH,n_characters@}
8223 /JOURNAL=@{ON,OFF@} [filename]
8224 /LOG=@{ON,OFF@} [filename]
8227 /COMPRESSION=@{ON,OFF@}
8228 /SCOMPRESSION=@{ON,OFF@}
8233 (obsolete settings accepted for compatibility, but ignored)
8234 /AUTOMENU=@{ON,OFF@}
8237 /BOXSTRING=@{'xxx','xxxxxxxxxxx'@}
8238 /CASE=@{UPPER,UPLOW@}
8243 /HELPWINDOWS=@{ON,OFF@}
8246 /LOWRES=@{AUTO,ON,OFF@}
8248 /MENUS=@{STANDARD,EXTENDED@}
8249 /MXMEMORY=max_memory
8250 /PTRANSLATE=@{ON,OFF@}
8252 /RUNREVIEW=@{AUTO,MANUAL@}
8254 /TB1=@{'xxx','xxxxxxxxxxx'@}
8256 /WORKDEV=drive_letter
8257 /WORKSPACE=workspace_size
8261 @cmd{SET} allows the user to adjust several parameters relating to
8262 PSPP's execution. Since there are many subcommands to this command, its
8263 subcommands will be examined in groups.
8265 On subcommands that take boolean values, ON and YES are synonym, and
8266 as are OFF and NO, when used as subcommand values.
8268 The data input subcommands affect the way that data is read from data
8269 files. The data input subcommands are
8273 This is the value assigned to an item data item that is empty or
8274 contains only whitespace. An argument of SYSMIS or '.' will cause the
8275 system-missing value to be assigned to null items. This is the
8276 default. Any real value may be assigned.
8279 The default DOT setting causes the decimal point character to be
8280 @samp{.}. A setting of COMMA causes the decimal point character to be
8284 Allows the default numeric input/output format to be specified. The
8285 default is F8.2. @xref{Input/Output Formats}.
8288 Program input subcommands affect the way that programs are parsed when
8289 they are typed interactively or run from a script. They are
8293 This is a single character indicating the end of a command. The default
8294 is @samp{.}. Don't change this.
8297 Whether a blank line is interpreted as ending the current command. The
8301 Interaction subcommands affect the way that PSPP interacts with an
8302 online user. The interaction subcommands are
8306 The command continuation prompt. The default is @samp{ > }.
8309 Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN
8310 DATA}). The default is @samp{data> }.
8313 Whether an error causes PSPP to stop processing the current command
8314 file after finishing the current command. The default is OFF.
8317 The maximum number of errors before PSPP halts processing of the current
8318 command file. The default is 50.
8321 The maximum number of warnings + errors before PSPP halts processing the
8322 current command file. The default is 100.
8325 The command prompt. The default is @samp{PSPP> }.
8328 The length of the screen in lines. MINIMUM means 25 lines, MEDIAN and
8329 MAXIMUM mean 43 lines. Otherwise specify the number of lines. Normally
8330 PSPP should auto-detect your screen size so this shouldn't have to be
8334 The width of the screen in characters. Normally 80 or 132.
8337 Program execution subcommands control the way that PSPP commands
8338 execute. The program execution subcommands are
8348 The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}).
8351 The initial pseudo-random number seed. Set to a real number or to
8352 RANDOM, which will obtain an initial seed from the current time of day.
8358 Data output subcommands affect the format of output data. These
8367 Set up custom currency formats. The argument is a string which must
8368 contain exactly three commas or exactly three periods. If commas, then
8369 the grouping character for the currency format is @samp{,}, and the
8370 decimal point character is @samp{.}; if periods, then the situation is
8373 The commas or periods divide the string into four fields, which are, in
8374 order, the negative prefix, prefix, suffix, and negative suffix. When a
8375 value is formatted using the custom currency format, the prefix precedes
8376 the value formatted and the suffix follows it. In addition, if the
8377 value is negative, the negative prefix precedes the prefix and the
8378 negative suffix follows the suffix.
8381 The default DOT setting causes the decimal point character to be
8382 @samp{.}. A setting of COMMA causes the decimal point character to be
8386 Allows the default numeric input/output format to be specified. The
8387 default is F8.2. @xref{Input/Output Formats}.
8390 Output routing subcommands affect where the output of transformations
8391 and procedures is sent. These subcommands are
8396 If turned on, commands are written to the listing file as they are read
8397 from command files. The default is OFF.
8407 Output activation subcommands affect whether output devices of
8408 particular types are enabled. These subcommands are
8412 Enable or disable listing devices.
8415 Enable or disable printer devices.
8418 Enable or disable screen devices.
8421 Output driver option subcommands affect output drivers' settings. These
8434 Logging subcommands affect logging of commands executed to external
8435 files. These subcommands are
8443 System file subcommands affect the default format of system files
8444 produced by PSPP. These subcommands are
8451 Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are
8452 compressed by default. The default is ON.
8455 Security subcommands affect the operations that commands are allowed to
8456 perform. The security subcommands are
8460 When set, this setting cannot ever be reset, for obvious security
8461 reasons. Setting this option disables the following operations:
8469 Pipe filenames (filenames beginning or ending with @samp{|}).
8472 Be aware that this setting does not guarantee safety (commands can still
8473 overwrite files, for instance) but it is an improvement.
8476 @node SUBTITLE, TITLE, SET, Utilities
8481 SUBTITLE 'subtitle_string'.
8483 SUBTITLE subtitle_string.
8486 @cmd{SUBTITLE} provides a subtitle to a particular PSPP
8487 run. This subtitle appears at the top of each output page below the
8488 title, if headers are enabled on the output device.
8490 Specify a subtitle as a string in quotes. The alternate syntax that did
8491 not require quotes is now obsolete. If it is used then the subtitle is
8492 converted to all uppercase.
8494 @node TITLE, , SUBTITLE, Utilities
8499 TITLE 'title_string'.
8504 @cmd{TITLE} provides a title to a particular PSPP run.
8505 This title appears at the top of each output page, if headers are enabled
8506 on the output device.
8508 Specify a title as a string in quotes. The alternate syntax that did
8509 not require quotes is now obsolete. If it is used then the title is
8510 converted to all uppercase.
8512 @node Not Implemented, Data File Format, Utilities, Top
8513 @chapter Not Implemented
8515 This chapter lists parts of the PSPP language that are not yet
8518 The following transformations and utilities are not yet implemented, but
8519 they will be supported in a later release.
8552 The following transformations and utilities are not implemented. There
8553 are no plans to support them in future releases. Contributions to
8554 implement them will still be accepted.
8576 NUMBERED and UNNUMBERED
8589 @node Data File Format, Portable File Format, Not Implemented, Top
8590 @chapter Data File Format
8592 PSPP necessarily uses the same format for system files as do the
8593 products with which it is compatible. This chapter is a description of
8596 There are three data types used in system files: 32-bit integers, 64-bit
8597 floating points, and 1-byte characters. In this document these will
8598 simply be referred to as @code{int32}, @code{flt64}, and @code{char},
8599 the names that are used in the PSPP source code. Every field of type
8600 @code{int32} or @code{flt64} is aligned on a 32-bit boundary.
8602 The endianness of data in PSPP system files is not specified. System
8603 files output on a computer of a particular endianness will have the
8604 endianness of that computer. However, PSPP can read files of either
8605 endianness, regardless of its host computer's endianness. PSPP
8606 translates endianness for both integer and floating point numbers.
8608 Floating point formats are also not specified. PSPP does not
8609 translate between floating point formats. This is unlikely to be a
8610 problem as all modern computer architectures use IEEE 754 format for
8611 floating point representation.
8613 The PSPP system-missing value is represented by the largest possible
8614 negative number in the floating point format; in C, this is most likely
8615 @code{-DBL_MAX}. There are two other important values used in missing
8616 values: @code{HIGHEST} and @code{LOWEST}. These are represented by the
8617 largest possible positive number (probably @code{DBL_MAX}) and the
8618 second-largest negative number. The latter must be determined in a
8619 system-dependent manner; in IEEE 754 format it is represented by value
8620 @code{0xffeffffffffffffe}.
8622 System files are divided into records. Each record begins with an
8623 @code{int32} giving a numeric record type. Individual record types are
8627 * File Header Record::
8629 * Value Label Record::
8630 * Value Label Variable Record::
8632 * Machine int32 Info Record::
8633 * Machine flt64 Info Record::
8634 * Miscellaneous Informational Records::
8635 * Dictionary Termination Record::
8639 @node File Header Record, Variable Record, Data File Format, Data File Format
8640 @section File Header Record
8642 The file header is always the first record in the file.
8645 struct sysfile_header
8655 char creation_date[9];
8656 char creation_time[8];
8657 char file_label[64];
8663 @item char rec_type[4];
8664 Record type code. Always set to @samp{$FL2}. This is the only record
8665 for which the record type is not of type @code{int32}.
8667 @item char prod_name[60];
8668 Product identification string. This always begins with the characters
8669 @samp{@@(#) SPSS DATA FILE}. PSPP uses the remaining characters to
8670 give its version and the operating system name; for example, @samp{GNU
8671 pspp 0.1.4 - sparc-sun-solaris2.5.2}. The string is truncated if it
8672 would be longer than 60 characters; otherwise it is padded on the right
8675 @item int32 layout_code;
8676 Always set to 2. PSPP reads this value to determine the
8679 @item int32 case_size;
8680 Number of data elements per case. This is the number of variables,
8681 except that long string variables add extra data elements (one for every
8682 8 characters after the first 8).
8684 @item int32 compressed;
8685 Set to 1 if the data in the file is compressed, 0 otherwise.
8687 @item int32 weight_index;
8688 If one of the variables in the data set is used as a weighting variable,
8689 set to the index of that variable. Otherwise, set to 0.
8692 Set to the number of cases in the file if it is known, or -1 otherwise.
8694 In the general case it is not possible to determine the number of cases
8695 that will be output to a system file at the time that the header is
8696 written. The way that this is dealt with is by writing the entire
8697 system file, including the header, then seeking back to the beginning of
8698 the file and writing just the @code{ncases} field. For `files' in which
8699 this is not valid, the seek operation fails. In this case,
8700 @code{ncases} remains -1.
8703 Compression bias. Always set to 100. The significance of this value is
8704 that only numbers between @code{(1 - bias)} and @code{(251 - bias)} can
8707 @item char creation_date[9];
8708 Set to the date of creation of the system file, in @samp{dd mmm yy}
8709 format, with the month as standard English abbreviations, using an
8710 initial capital letter and following with lowercase. If the date is not
8711 available then this field is arbitrarily set to @samp{01 Jan 70}.
8713 @item char creation_time[8];
8714 Set to the time of creation of the system file, in @samp{hh:mm:ss}
8715 format and using 24-hour time. If the time is not available then this
8716 field is arbitrarily set to @samp{00:00:00}.
8718 @item char file_label[64];
8719 Set the the file label declared by the user, if any. Padded on the
8722 @item char padding[3];
8723 Ignored padding bytes to make the structure a multiple of 32 bits in
8724 length. Set to zeros.
8727 @node Variable Record, Value Label Record, File Header Record, Data File Format
8728 @section Variable Record
8730 Immediately following the header must come the variable records. There
8731 must be one variable record for every variable and every 8 characters in
8732 a long string beyond the first 8; i.e., there must be exactly as many
8733 variable records as the value specified for @code{case_size} in the file
8737 struct sysfile_variable
8741 int32 has_var_label;
8742 int32 n_missing_values;
8747 /* The following two fields are present
8748 only if has_var_label is 1. */
8750 char label[/* variable length */];
8752 /* The following field is present only
8753 if n_missing_values is not 0. */
8754 flt64 missing_values[/* variable length*/];
8759 @item int32 rec_type;
8760 Record type code. Always set to 2.
8763 Variable type code. Set to 0 for a numeric variable. For a short
8764 string variable or the first part of a long string variable, this is set
8765 to the width of the string. For the second and subsequent parts of a
8766 long string variable, set to -1, and the remaining fields in the
8767 structure are ignored.
8769 @item int32 has_var_label;
8770 If this variable has a variable label, set to 1; otherwise, set to 0.
8772 @item int32 n_missing_values;
8773 If the variable has no missing values, set to 0. If the variable has
8774 one, two, or three discrete missing values, set to 1, 2, or 3,
8775 respectively. If the variable has a range for missing variables, set to
8776 -2; if the variable has a range for missing variables plus a single
8777 discrete value, set to -3.
8780 Print format for this variable. See below.
8783 Write format for this variable. See below.
8786 Variable name. The variable name must begin with a capital letter or
8787 the at-sign (@samp{@@}). Subsequent characters may also be octothorpes
8788 (@samp{#}), dollar signs (@samp{$}), underscores (@samp{_}), or full
8789 stops (@samp{.}). The variable name is padded on the right with spaces.
8791 @item int32 label_len;
8792 This field is present only if @code{has_var_label} is set to 1. It is
8793 set to the length, in characters, of the variable label, which must be a
8794 number between 0 and 120.
8796 @item char label[/* variable length */];
8797 This field is present only if @code{has_var_label} is set to 1. It has
8798 length @code{label_len}, rounded up to the nearest multiple of 32 bits.
8799 The first @code{label_len} characters are the variable's variable label.
8801 @item flt64 missing_values[/* variable length */];
8802 This field is present only if @code{n_missing_values} is not 0. It has
8803 the same number of elements as the absolute value of
8804 @code{n_missing_values}. For discrete missing values, each element
8805 represents one missing value. When a range is present, the first
8806 element denotes the minimum value in the range, and the second element
8807 denotes the maximum value in the range. When a range plus a value are
8808 present, the third element denotes the additional discrete missing
8809 value. HIGHEST and LOWEST are indicated as described in the chapter
8813 The @code{print} and @code{write} members of sysfile_variable are output
8814 formats coded into @code{int32} types. The LSB (least-significant byte)
8815 of the @code{int32} represents the number of decimal places, and the
8816 next two bytes in order of increasing significance represent field width
8817 and format type, respectively. The MSB (most-significant byte) is not
8818 used and should be set to zero.
8820 Format types are defined as follows:
8904 @node Value Label Record, Value Label Variable Record, Variable Record, Data File Format
8905 @section Value Label Record
8907 Value label records must follow the variable records and must precede
8908 the header termination record. Other than this, they may appear
8909 anywhere in the system file. Every value label record must be
8910 immediately followed by a label variable record, described below.
8912 Value label records begin with @code{rec_type}, an @code{int32} value
8913 set to the record type of 3. This is followed by @code{count}, an
8914 @code{int32} value set to the number of value labels present in this
8917 These two fields are followed by a series of @code{count} tuples. Each
8918 tuple is divided into two fields, the value and the label. The first of
8919 these, the value, is composed of a 64-bit value, which is either a
8920 @code{flt64} value or up to 8 characters (padded on the right to 8
8921 bytes) denoting a short string value. Whether the value is a
8922 @code{flt64} or a character string is not defined inside the value label
8925 The second field in the tuple, the label, has variable length. The
8926 first @code{char} is a count of the number of characters in the value
8927 label. The remainder of the field is the label itself. The field is
8928 padded on the right to a multiple of 64 bits in length.
8930 @node Value Label Variable Record, Document Record, Value Label Record, Data File Format
8931 @section Value Label Variable Record
8933 Every value label variable record must be immediately preceded by a
8934 value label record, described above.
8937 struct sysfile_value_label_variable
8941 int32 vars[/* variable length */];
8946 @item int32 rec_type;
8947 Record type. Always set to 4.
8950 Number of variables that the associated value labels from the value
8951 label record are to be applied.
8953 @item int32 vars[/* variable length];
8954 A list of variables to which to apply the value labels. There are
8955 @code{count} elements.
8958 @node Document Record, Machine int32 Info Record, Value Label Variable Record, Data File Format
8959 @section Document Record
8961 There must be no more than one document record per system file.
8962 Document records must follow the variable records and precede the
8963 dictionary termination record.
8966 struct sysfile_document
8970 char lines[/* variable length */][80];
8975 @item int32 rec_type;
8976 Record type. Always set to 6.
8978 @item int32 n_lines;
8979 Number of lines of documents present.
8981 @item char lines[/* variable length */][80];
8982 Document lines. The number of elements is defined by @code{n_lines}.
8983 Lines shorter than 80 characters are padded on the right with spaces.
8986 @node Machine int32 Info Record, Machine flt64 Info Record, Document Record, Data File Format
8987 @section Machine @code{int32} Info Record
8989 There must be no more than one machine @code{int32} info record per
8990 system file. Machine @code{int32} info records must follow the variable
8991 records and precede the dictionary termination record.
8994 struct sysfile_machine_int32_info
9003 int32 version_major;
9004 int32 version_minor;
9005 int32 version_revision;
9007 int32 floating_point_rep;
9008 int32 compression_code;
9010 int32 character_code;
9015 @item int32 rec_type;
9016 Record type. Always set to 7.
9018 @item int32 subtype;
9019 Record subtype. Always set to 3.
9022 Size of each piece of data in the data part, in bytes. Always set to 4.
9025 Number of pieces of data in the data part. Always set to 8.
9027 @item int32 version_major;
9028 PSPP major version number. In version @var{x}.@var{y}.@var{z}, this
9031 @item int32 version_minor;
9032 PSPP minor version number. In version @var{x}.@var{y}.@var{z}, this
9035 @item int32 version_revision;
9036 PSPP version revision number. In version @var{x}.@var{y}.@var{z},
9039 @item int32 machine_code;
9040 Machine code. PSPP always set this field to value to -1, but other
9043 @item int32 floating_point_rep;
9044 Floating point representation code. For IEEE 754 systems this is 1.
9045 IBM 370 sets this to 2, and DEC VAX E to 3.
9047 @item int32 compression_code;
9048 Compression code. Always set to 1.
9050 @item int32 endianness;
9051 Machine endianness. 1 indicates big-endian, 2 indicates little-endian.
9053 @item int32 character_code;
9054 Character code. 1 indicates EBCDIC, 2 indicates 7-bit ASCII, 3
9055 indicates 8-bit ASCII, 4 indicates DEC Kanji.
9058 @node Machine flt64 Info Record, Miscellaneous Informational Records, Machine int32 Info Record, Data File Format
9059 @section Machine @code{flt64} Info Record
9061 There must be no more than one machine @code{flt64} info record per
9062 system file. Machine @code{flt64} info records must follow the variable
9063 records and precede the dictionary termination record.
9066 struct sysfile_machine_flt64_info
9082 @item int32 rec_type;
9083 Record type. Always set to 3.
9085 @item int32 subtype;
9086 Record subtype. Always set to 4.
9089 Size of each piece of data in the data part, in bytes. Always set to 4.
9092 Number of pieces of data in the data part. Always set to 3.
9095 The system missing value.
9097 @item flt64 highest;
9098 The value used for HIGHEST in missing values.
9101 The value used for LOWEST in missing values.
9104 @node Miscellaneous Informational Records, Dictionary Termination Record, Machine flt64 Info Record, Data File Format
9105 @section Miscellaneous Informational Records
9107 Miscellaneous informational records must follow the variable records and
9108 precede the dictionary termination record.
9110 Miscellaneous informational records are ignored by PSPP when reading
9111 system files. They are not written by PSPP when writing system files.
9114 struct sysfile_misc_info
9123 char data[/* variable length */];
9128 @item int32 rec_type;
9129 Record type. Always set to 3.
9131 @item int32 subtype;
9132 Record subtype. May take any value.
9135 Size of each piece of data in the data part. Should have the value 4 or
9136 8, for @code{int32} and @code{flt64}, respectively.
9139 Number of pieces of data in the data part.
9141 @item char data[/* variable length */];
9142 Arbitrary data. There must be @code{size} times @code{count} bytes of
9146 @node Dictionary Termination Record, Data Record, Miscellaneous Informational Records, Data File Format
9147 @section Dictionary Termination Record
9149 The dictionary termination record must follow all other records, except
9150 for the actual cases, which it must precede. There must be exactly one
9151 dictionary termination record in every system file.
9154 struct sysfile_dict_term
9162 @item int32 rec_type;
9163 Record type. Always set to 999.
9166 Ignored padding. Should be set to 0.
9169 @node Data Record, , Dictionary Termination Record, Data File Format
9170 @section Data Record
9172 Data records must follow all other records in the data file. There must
9173 be at least one data record in every system file.
9175 The format of data records varies depending on whether the data is
9176 compressed. Regardless, the data is arranged in a series of 8-byte
9179 When data is not compressed, Every case is composed of @code{case_size}
9180 of these 8-byte elements, where @code{case_size} comes from the file
9181 header record (@pxref{File Header Record}). Each element corresponds to
9182 the variable declared in the respective variable record (@pxref{Variable
9183 Record}). Numeric values are given in @code{flt64} format; string
9184 values are literal characters string, padded on the right when
9187 Compressed data is arranged in the following manner: the first 8-byte
9188 element in the data section is divided into a series of 1-byte command
9189 codes. These codes have meanings as described below:
9193 Ignored. If the program writing the system file accumulates compressed
9194 data in blocks of fixed length, 0 bytes can be used to pad out extra
9195 bytes remaining at the end of a fixed-size block.
9198 These values indicate that the corresponding numeric variable has the
9199 value @code{(@var{code} - @var{bias})} for the case being read, where
9200 @var{code} is the value of the compression code and @var{bias} is the
9201 variable @code{compression_bias} from the file header. For example,
9202 code 105 with bias 100.0 (the normal value) indicates a numeric variable
9206 End of file. This code may or may not appear at the end of the data
9207 stream. PSPP always outputs this code but its use is not required.
9210 This value indicates that the numeric or string value is not
9211 compressible. The value is stored in the 8-byte element following the
9212 current block of command bytes. If this value appears twice in a block
9213 of command bytes, then it indicates the second element following the
9214 command bytes, and so on.
9217 Used to indicate a string value that is all spaces.
9220 Used to indicate the system-missing value.
9223 When the end of the first 8-byte element of command bytes is reached,
9224 any blocks of non-compressible values are skipped, and the next element
9225 of command bytes is read and interpreted, until the end of the file is
9228 @node Portable File Format, q2c Input Format, Data File Format, Top
9229 @chapter Portable File Format
9231 These days, most computers use the same internal data formats for
9232 integer and floating-point data, if one ignores little differences like
9233 big- versus little-endian byte ordering. However, occasionally it is
9234 necessary to exchange data between systems with incompatible data
9235 formats. This is what portable files are designed to do.
9237 @strong{Please note:} Although all of the following information is
9238 correct, as far as the author has been able to ascertain, it is gleaned
9239 from examination of ASCII-formatted portable files only, so some of it
9240 may be incorrect in the general case.
9243 * Portable File Characters::
9244 * Portable File Structure::
9245 * Portable File Header::
9246 * Version and Date Info Record::
9247 * Identification Records::
9248 * Variable Count Record::
9249 * Variable Records::
9250 * Value Label Records::
9251 * Portable File Data::
9254 @node Portable File Characters, Portable File Structure, Portable File Format, Portable File Format
9255 @section Portable File Characters
9257 Portable files are arranged as a series of lines of exactly 80
9258 characters each. Each line is terminated by a carriage-return,
9259 line-feed sequence (henceforth, ``newline''). Newlines are not
9260 delimiters: they are only used to avoid line-length limitations existing
9261 on some operating systems.
9263 The file must be terminated with a @samp{Z} character. In addition, if
9264 the final line in the file does not have exactly 80 characters, then it
9265 is padded on the right with @samp{Z} characters. (The file contents may
9266 be in any character set; the file contains a description of its own
9267 character set, as explained in the next section. Therefore, the
9268 @samp{Z} character is not necessarily an ASCII @samp{Z}.)
9270 For the rest of the description of the portable file format, newlines
9271 and the trailing @samp{Z}s will be ignored, as if they did not exist,
9272 because they are not an important part of understanding the file
9275 @node Portable File Structure, Portable File Header, Portable File Characters, Portable File Format
9276 @section Portable File Structure
9278 Every portable file consists of the following records, in sequence:
9286 Version and date info.
9289 Product identification.
9292 Subproduct identification (optional).
9298 Variables. Each variable record may optionally be followed by a
9299 missing value record and a variable label record.
9302 Value labels (optional).
9308 Most records are identified by a single-character tag code. The file
9309 header and version info record do not have a tag.
9311 Other than these single-character codes, there are three types of fields
9312 in a portable file: floating-point, integer, and string. Floating-point
9313 fields have the following format:
9318 Zero or more leading spaces.
9321 Optional asterisk (@samp{*}), which indicates a missing value. The
9322 asterisk must be followed by a single character, generally a period
9323 (@samp{.}), but it appears that other characters may also be possible.
9324 This completes the specification of a missing value.
9327 Optional minus sign (@samp{-}) to indicate a negative number.
9330 A whole number, consisting of one or more base-30 digits: @samp{0}
9331 through @samp{9} plus capital letters @samp{A} through @samp{T}.
9334 A fraction, consisting of a radix point (@samp{.}) followed by one or
9335 more base-30 digits (optional).
9338 An exponent, consisting of a plus or minus sign (@samp{+} or @samp{-})
9339 followed by one or more base-30 digits (optional).
9342 A forward slash (@samp{/}).
9345 Integer fields take form identical to floating-point fields, but they
9346 may not contain a fraction.
9348 String fields take the form of a integer field having value @var{n},
9349 followed by exactly @var{n} characters, which are the string content.
9351 @node Portable File Header, Version and Date Info Record, Portable File Structure, Portable File Format
9352 @section Portable File Header
9354 Every portable file begins with a 464-byte header, consisting of a
9355 200-byte collection of vanity splash strings, followed by a 256-byte
9356 character set translation table, followed by an 8-byte tag string.
9358 The 200-byte segment is divided into five 40-byte sections, each of
9359 which represents the string @code{ASCII SPSS PORT FILE} in a different
9360 character set encoding. (If the file is encoded in EBCDIC then the
9361 string is actually @code{EBCDIC SPSS PORT FILE}, and so on.) These
9362 strings are padded on the right with spaces in their own character set.
9364 It appears that these strings exist only to inform those who might view
9365 the file on a screen, and that they are not parsed by SPSS products.
9366 Thus, they can be safely ignored. For those interested, the strings are
9367 supposed to be in the following character sets, in the specified order:
9368 EBCDIC, 7-bit ASCII, CDC 6-bit ASCII, 6-bit ASCII, Honeywell 6-bit
9371 The 256-byte segment describes a mapping from the character set used in
9372 the portable file to an arbitrary character set having characters at the
9373 following positions:
9378 Control characters. Not important enough to describe in full here.
9386 Digits @samp{0} through @samp{9}.
9390 Capital letters @samp{A} through @samp{Z}.
9394 Lowercase letters @samp{a} through @samp{z}.
9406 Solid vertical pipe.
9410 Symbols @code{&[]!$*);^-/}
9414 Broken vertical pipe.
9418 Symbols @code{,%_>}?@code{`:} @c @code{?} is an inverted question mark
9422 British pound symbol.
9426 Symbols @code{@@'="}.
9430 Less than or equal symbol.
9462 Lower left corner box draw.
9466 Upper left corner box draw.
9470 Greater than or equal symbol.
9474 Superscript @samp{0} through @samp{9}.
9478 Lower right corner box draw.
9482 Upper right corner box draw.
9494 Superscript @samp{(}.
9498 Superscript @samp{)}.
9502 Horizontal dagger (?).
9506 Symbols @samp{@{@}\}.
9513 Centered dot, or bullet.
9520 Symbols that are not defined in a particular character set are set to
9521 the same value as symbol 64; i.e., to @samp{0}.
9523 The 8-byte tag string consists of the exact characters @code{SPSSPORT}
9524 in the portable file's character set, which can be used to verify that
9525 the file is indeed a portable file.
9527 @node Version and Date Info Record, Identification Records, Portable File Header, Portable File Format
9528 @section Version and Date Info Record
9530 This record does not have a tag code. It has the following structure:
9534 A single character identifying the file format version. The letter A
9535 represents version 0, and so on.
9538 An 8-character string field giving the file creation date in the format
9542 A 6-character string field giving the file creation time in the format
9546 @node Identification Records, Variable Count Record, Version and Date Info Record, Portable File Format
9547 @section Identification Records
9549 The product identification record has tag code @samp{1}. It consists of
9550 a single string field giving the name of the product that wrote the
9553 The subproduct identification record has tag code @samp{3}. It
9554 consists of a single string field giving additional information on the
9555 product that wrote the portable file.
9557 @node Variable Count Record, Variable Records, Identification Records, Portable File Format
9558 @section Variable Count Record
9560 The variable count record has tag code @samp{4}. It consists of two
9561 integer fields. The first contains the number of variables in the file
9562 dictionary. The purpose of the second is unknown; it contains the value
9563 161 in all portable files examined so far.
9565 @node Variable Records, Value Label Records, Variable Count Record, Portable File Format
9566 @section Variable Records
9568 Each variable record represents a single variable. Variable records
9569 have tag code @samp{7}. They have the following structure:
9574 Width (integer). This is 0 for a numeric variable, and a number between 1
9575 and 255 for a string variable.
9578 Name (string). 1--8 characters long. Must be in all capitals.
9581 Print format. This is a set of three integer fields:
9586 Format type (@pxref{Variable Record}).
9589 Format width. 1--40.
9592 Number of decimal places. 1--40.
9596 Write format. Same structure as the print format described above.
9599 Each variable record can optionally be followed by a missing value
9600 record, which has tag code @samp{8}. A missing value record has one
9601 field, the missing value itself (a floating-point or string, as
9602 appropriate). Up to three of these missing value records can be used.
9604 There is also a record for missing value ranges, which has tag code
9605 @samp{B}. It is followed by two fields representing the range, which
9606 are floating-point or string as appropriate. If a missing value range
9607 is present, it may be followed by a single missing value record.
9609 Tag codes @samp{9} and @samp{A} represent @code{LO THRU @var{x}} and
9610 @code{@var{x} THRU HI} ranges, respectively. Each is followed by a
9611 single field representing @var{x}. If one of the ranges is present, it
9612 may be followed by a single missing value record.
9614 In addition, each variable record can optionally be followed by a
9615 variable label record, which has tag code @samp{C}. A variable label
9616 record has one field, the variable label itself (string).
9618 @node Value Label Records, Portable File Data, Variable Records, Portable File Format
9619 @section Value Label Records
9621 Value label records have tag code @samp{D}. They have the following
9626 Variable count (integer).
9629 List of variables (strings). The variable count specifies the number in
9630 the list. Variables are specified by their names. All variables must
9631 be of the same type (numeric or string).
9634 Label count (integer).
9637 List of (value, label) tuples. The label count specifies the number of
9638 tuples. Each tuple consists of a value, which is numeric or string as
9639 appropriate to the variables, followed by a label (string).
9642 @node Portable File Data, , Value Label Records, Portable File Format
9643 @section Portable File Data
9645 The data record has tag code @samp{F}. There is only one tag for all
9646 the data; thus, all the data must follow the dictionary. The data is
9647 terminated by the end-of-file marker @samp{Z}, which is not valid as the
9648 beginning of a data element.
9650 Data elements are output in the same order as the variable records
9651 describing them. String variables are output as string fields, and
9652 numeric variables are output as floating-point fields.
9654 @node q2c Input Format, Bugs, Portable File Format, Top
9655 @chapter @code{q2c} Input Format
9657 PSPP statistical procedures have a bizarre and somewhat irregular
9658 syntax. Despite this, a parser generator has been written that
9659 adequately addresses many of the possibilities and tries to provide
9660 hooks for the exceptional cases. This parser generator is named
9664 * Invoking q2c:: q2c command-line syntax.
9665 * q2c Input Structure:: High-level layout of the input file.
9666 * Grammar Rules:: Syntax of the grammar rules.
9669 @node Invoking q2c, q2c Input Structure, q2c Input Format, q2c Input Format
9670 @section Invoking q2c
9673 q2c @var{input.q} @var{output.c}
9676 @code{q2c} translates a @samp{.q} file into a @samp{.c} file. It takes
9677 exactly two command-line arguments, which are the input file name and
9678 output file name, respectively. @code{q2c} does not accept any
9679 command-line options.
9681 @node q2c Input Structure, Grammar Rules, Invoking q2c, q2c Input Format
9682 @section @code{q2c} Input Structure
9684 @code{q2c} input files are divided into two sections: the grammar rules
9685 and the supporting code. The @dfn{grammar rules}, which make up the
9686 first part of the input, are used to define the syntax of the
9687 statistical procedure to be parsed. The @dfn{supporting code},
9688 following the grammar rules, are copied largely unchanged to the output
9689 file, except for certain escapes.
9691 The most important lines in the grammar rules are used for defining
9692 procedure syntax. These lines can be prefixed with a dollar sign
9693 (@samp{$}), which prevents Emacs' CC-mode from munging them. Besides
9694 this, a bang (@samp{!}) at the beginning of a line causes the line,
9695 minus the bang, to be written verbatim to the output file (useful for
9696 comments). As a third special case, any line that begins with the exact
9697 characters @code{/* *INDENT} is ignored and not written to the output.
9698 This allows @code{.q} files to be processed through @code{indent}
9699 without being munged.
9701 The syntax of the grammar rules themselves is given in the following
9704 The supporting code is passed into the output file largely unchanged.
9705 However, the following escapes are supported. Each escape must appear
9706 on a line by itself.
9709 @item /* (header) */
9711 Expands to a series of C @code{#include} directives which include the
9712 headers that are required for the parser generated by @code{q2c}.
9714 @item /* (decls @var{scope}) */
9716 Expands to C variable and data type declarations for the variables and
9717 @code{enum}s input and output by the @code{q2c} parser. @var{scope}
9718 must be either @code{local} or @code{global}. @code{local} causes the
9719 declarations to be output as function locals. @code{global} causes them
9720 to be declared as @code{static} module variables; thus, @code{global} is
9721 a bit of a misnomer.
9723 @item /* (parser) */
9725 Expands to the entire parser. Must be enclosed within a C function.
9729 Expands to a set of calls to the @code{free} function for variables
9730 declared by the parser. Only needs to be invoked if subcommands of type
9731 @code{string} are used in the grammar rules.
9734 @node Grammar Rules, , q2c Input Structure, q2c Input Format
9735 @section Grammar Rules
9737 The grammar rules describe the format of the syntax that the parser
9738 generated by @code{q2c} will understand. The way that the grammar rules
9739 are included in @code{q2c} input file are described above.
9741 The grammar rules are divided into tokens of the following types:
9744 @item Identifier (@code{ID})
9746 An identifier token is a sequence of letters, digits, and underscores
9747 (@samp{_}). Identifiers are @emph{not} case-sensitive.
9749 @item String (@code{STRING})
9751 String tokens are initiated by a double-quote character (@samp{"}) and
9752 consist of all the characters between that double quote and the next
9753 double quote, which must be on the same line as the first. Within a
9754 string, a backslash can be used as a ``literal escape''. The only
9755 reasons to use a literal escape are to include a double quote or a
9756 backslash within a string.
9758 @item Special character
9760 Other characters, other than whitespace, constitute tokens in
9765 The syntax of the grammar rules is as follows:
9768 grammar-rules ::= ID : subcommands .
9769 subcommands ::= subcommand
9770 ::= subcommands ; subcommand
9773 The syntax begins with an ID or STRING token that gives the name of the
9774 procedure to be parsed. The rest of the syntax consists of subcommands
9775 separated by semicolons (@samp{;}) and terminated with a full stop
9779 subcommand ::= sbc-options ID sbc-defn
9782 ::= sbc-options sbc-options
9785 sbc-defn ::= opt-prefix = specifiers
9786 ::= [ ID ] = array-sbc
9787 ::= opt-prefix = sbc-special-form
9792 Each subcommand can be prefixed with one or more option characters. An
9793 asterisk (@samp{*}) is used to indicate the default subcommand; the
9794 keyword used for the default subcommand can be omitted in the PSPP
9795 syntax file. A plus sign (@samp{+}) is used to indicate that a
9796 subcommand can appear more than once; if it is not present then that
9797 subcommand can appear no more than once.
9799 The subcommand name appears after the option characters.
9801 There are three forms of subcommands. The first and most common form
9802 simply gives an equals sign (@samp{=}) and a list of specifiers, which
9803 can each be set to a single setting. The second form declares an array,
9804 which is a set of flags that can be individually turned on by the user.
9805 There are also several special forms that do not take a list of
9808 Arrays require an additional @code{ID} argument. This is used as a
9809 prefix, prepended to the variable names constructed from the
9810 specifiers. The other forms also allow an optional prefix to be
9814 array-sbc ::= alternatives
9815 ::= array-sbc , alternatives
9817 ::= alternatives | ID
9820 An array subcommand is a set of Boolean values that can independently be
9821 turned on by the user, listed separated by commas (@samp{,}). If an value has more
9822 than one name then these names are separated by pipes (@samp{|}).
9825 specifiers ::= specifier
9826 ::= specifiers , specifier
9827 specifier ::= opt-id : settings
9832 Ordinary subcommands (other than arrays and special forms) require a
9833 list of specifiers. Each specifier has an optional name and a list of
9834 settings. If the name is given then a correspondingly named variable
9835 will be used to store the user's choice of setting. If no name is given
9836 then there is no way to tell which setting the user picked; in this case
9837 the settings should probably have values attached.
9840 settings ::= setting
9841 ::= settings / setting
9842 setting ::= setting-options ID setting-value
9849 Individual settings are separated by forward slashes (@samp{/}). Each
9850 setting can be as little as an @code{ID} token, but options and values
9851 can optionally be included. The @samp{*} option means that, for this
9852 setting, the @code{ID} can be omitted. The @samp{!} option means that
9853 this option is the default for its specifier.
9857 ::= ( setting-value-2 )
9859 setting-value-2 ::= setting-value-options setting-value-type : ID
9860 setting-value-restriction
9861 setting-value-options ::=
9863 setting-value-type ::= N
9865 setting-value-restriction ::=
9869 Settings may have values. If the value must be enclosed in parentheses,
9870 then enclose the value declaration in parentheses. Declare the setting
9871 type as @samp{n} or @samp{d} for integer or floating point type,
9872 respectively. The given @code{ID} is used to construct a variable name.
9873 If option @samp{*} is given, then the value is optional; otherwise it
9874 must be specified whenever the corresponding setting is specified. A
9875 ``restriction'' can also be specified which is a string giving a C
9876 expression limiting the valid range of the value. The special escape
9877 @code{%s} should be used within the restriction to refer to the
9878 setting's value variable.
9881 sbc-special-form ::= VAR
9882 ::= VARLIST varlist-options
9883 ::= INTEGER opt-list
9886 ::= STRING @r{(the literal word STRING)} string-options
9893 ::= ( STRING STRING )
9896 The special forms are of the following types:
9901 A single variable name.
9905 A list of variables. If given, the string can be used to provide
9906 @code{PV_@var{*}} options to the call to @code{parse_variables}.
9910 A single integer value.
9914 A list of integers separated by spaces or commas.
9918 A single floating-point value.
9922 A list of floating-point values.
9926 A single positive integer value.
9930 A string value. If the options are given then the first string is an
9931 expression giving a restriction on the value of the string; the second
9932 string is an error message to display when the restriction is violated.
9936 A custom function is used to parse this subcommand. The function must
9937 have prototype @code{int custom_@var{name} (void)}. It should return 0
9938 on failure (when it has already issued an appropriate diagnostic), 1 on
9939 success, or 2 if it fails and the calling function should issue a syntax
9940 error on behalf of the custom handler.
9944 @node Bugs, Function Index, q2c Input Format, Top
9948 * Known bugs:: Pointers to other files.
9949 * Contacting the Author:: Where to send the bug reports.
9952 @node Known bugs, Contacting the Author, Bugs, Bugs
9955 This is the list of known bugs in PSPP. In addition, @xref{Not
9956 Implemented}, and @xref{Functions Not Implemented}, for lists of bugs
9957 due to features not implemented. For known bugs in individual language
9958 features, see the documentation for that feature.
9962 Nothing has yet been tested exhaustively. Be cautious using PSPP to
9963 make important decisions.
9966 @code{make check} fails on some systems that don't like the syntax. I'm
9967 not sure why. If someone could make an attempt to track this down, it
9968 would be appreciated.
9971 PostScript driver bugs:
9975 Does not support driver arguments `max-fonts-simult' or
9976 `optimize-text-size'.
9979 Minor problems with font-encodings.
9982 Fails to align fonts along their baselines.
9985 Does not support certain bizarre line intersections--should
9986 never crop up in practice.
9989 Does not gracefully substitute for existing fonts whose
9990 encodings are missing.
9993 Does not perform italic correction or left italic correction
9997 Encapsulated PostScript is unimplemented.
10004 Does not support `infinite length' or `infinite width' paper.
10008 See below for information on reporting bugs not listed here.
10010 @node Contacting the Author, , Known bugs, Bugs
10011 @section Contacting the Author
10013 The author can be contacted at e-mail address
10018 @code{<blp@@gnu.org>}.
10021 PSPP bug reports should be sent to
10023 <bug-gnu-pspp@@gnu.org>.
10026 @code{<bug-gnu-pspp@@gnu.org>}.
10029 @node Function Index, Concept Index, Bugs, Top
10030 @chapter Function Index
10033 @node Concept Index, Command Index, Function Index, Top
10034 @chapter Concept Index
10037 @node Command Index, , Concept Index, Top
10038 @chapter Command Index
10044 @c Local Variables:
10045 @c compile-command: "makeinfo pspp.texi"